Documentación Técnica de la API & Integraciones
Conectá Noctra con tus terminales de cobro, molinetes de acceso QR, lectores fiscales y sistemas contables externos mediante endpoints REST seguros y Webhooks en tiempo real con tolerancia total a fallos de internet.
Autenticación por Roles
API Keys con granularidad estricta para cajas, tótems de autoservicio y accesos. Tokens Bearer JWT efímeros firmados con SHA-256.
Sync Batch Idempotente
Sincronización en ráfaga de tickets generados offline. Los identificadores UUID impiden cobros duplicados aunque se reintenten 100 veces.
Webhooks en Tiempo Real
Notificaciones instantáneas de eventos a tus servidores (validación de QR en molinetes, roturas de stock o alerta de merma crítica).
Endpoints Principales de la API v2
Base URL: https://api.noctra.vercel.app/v2Endpoints de Ingesta & Operación
curl -X POST https://api.noctra.vercel.app/v2/sales/sync-batch \
-H "Authorization: Bearer sp_live_sk_89f3a8b2..." \
-H "Content-Type: application/json" \
-d '{
"terminal_id": "BARRA_PRINCIPAL_POS_02",
"shift_id": "SHIFT-2026-0906-01",
"transactions": [
{
"idempotency_key": "tx_908f234-a1",
"timestamp": "2026-09-06T03:14:22Z",
"items": [
{ "sku": "FERNET-BRANCA-750", "ml_dispensed": 150, "qty": 2, "price_ars": 9000 },
{ "sku": "COCA-COLA-500", "ml_dispensed": 350, "qty": 2, "price_ars": 3000 }
],
"payment_method": "MERCADOPAGO_QR",
"total_ars": 12000
}
]
}'Seguridad y Resiliencia en Ambientes Nocturnos
Tolerancia a microcortes de red
La API implementa un protocolo de almacenamiento previo en el cliente POS para que las barras sigan despachando a máxima velocidad sin esperar respuesta de red en horario pico (02:00 a 04:30 AM).
Encriptación TLS 1.3 & Tokens con Scope
Toda la comunicación transita bajo túneles TLS 1.3. Las API Keys para tótems de entrada solo pueden verificar accesos, sin permisos de lectura sobre balances ni recaudación.
Preguntas Frecuentes sobre la API
¿Cómo se maneja la autenticación y rotación de tokens en cajas locales?
Cada terminal POS o iPad de barra se autentica mediante una API Key de terminal asociada a una clave Bearer efímera (JWT) con permisos específicos limitados al rol asignado (cajero, supervisor o bartender). La rotación es configurable por turno o cada 24 horas.
¿Qué sucede si una barra pierde conexión durante el envío de transacciones?
El cliente local almacena las ventas en una cola local encriptada (IndexedDB / SQLite local). En cuanto detecta red mediante el healthcheck de la API, ejecuta un endpoint de sincronización en lote (/v2/sales/sync-batch) con idempotencia garantizada mediante UUIDs únicos por ticket.
¿Es posible integrar lectores fiscales, pasarelas de pago y molinetes QR externos?
Sí. Los Webhooks de Noctra despachan eventos instantáneos (event: "ticket.scanned", "sale.created", "inventory.low_stock") para disparar relays de molinetes de acceso en menos de 300ms y sincronizar con software contable o ERPs externos.
¿Qué límites de tasa (Rate Limiting) aplican a los endpoints de la API?
Para terminales locales en horario nocturno (22:00 a 08:00 AM) no existen restricciones de rate limit en la red interna autorizada. Los endpoints públicos y webhooks manejan hasta 1.200 requests/minuto por cliente comercial.
¿Necesitás integrar hardware o sistemas existentes?
Nuestro equipo técnico realiza la configuración y sincronización inicial de tu boliche sin costo en el Programa Piloto 2026.