API

Nantli tiene una API para que tus propios sistemas lean y escriban los datos de tu casa: tu contabilidad puede leer las ventas del día, tu sistema de nómina puede leer el equipo y los horarios, tu BI puede jalar reportes. Todo con llaves que tú creas y revocas desde esta página.

Llaves y permisos

Cada llave tiene un nombre y una lista de permisos. Dale a cada sistema su propia llave con los permisos mínimos: al sistema contable, solo lectura de órdenes y reportes; al de nómina, equipo y horarios.

Selecciona Nueva llave, ponle nombre, elige permisos y selecciona Crear. La llave completa (nk_live_…) se muestra una sola vez — guárdala en tu sistema en ese momento. Si se pierde, revócala y crea otra; Nantli no la puede recuperar.

Los permisos de escritura solo funcionan si tu casa tiene el producto correspondiente activo: órdenes y catálogo van con el punto de venta, equipo y horarios con Equipo, reportes con el POS.

Usar la API

Cada petición lleva la llave en el encabezado Authorization:

curl https://app.nantli.ai/api/v1/me \
  -H "Authorization: Bearer nk_live_…"

/me te dice a qué casa pertenece la llave, con su zona horaria, moneda e idioma — úsalo para no codificar ninguno de los tres. Los recursos principales:

• GET /api/v1/orders — órdenes, con ?updated_after= para sincronizar solo lo que cambió.
• GET /api/v1/orders/{id} — una orden con partidas, pagos y reembolsos.
• POST /api/v1/orders — crea una orden; los precios siempre salen de tu catálogo.
• POST /api/v1/orders/{id}/payments — registra un cobro.
• GET /api/v1/catalog/products — tu carta con precios.
• GET /api/v1/reports/sales?from=&to= — ventas agregadas, en la zona horaria de tu casa.
• GET /api/v1/staff, GET /api/v1/schedules/entries, GET /api/v1/absences — equipo y horarios.

Las listas grandes se paginan con next_cursor; pásalo de vuelta como ?cursor=. Los POST que mueven dinero requieren un encabezado Idempotency-Key: si reintentas con la misma clave, la operación no se duplica.

Los errores llegan como { "error": { "code", "message", "request_id" } } con códigos estables (invalid_api_key, insufficient_scope, validation_failed…). Hay límites de uso por llave; si recibes rate_limited, espera y reintenta.

Webhooks

En lugar de preguntar cada minuto, tu sistema puede recibir avisos: registra un destino con Nuevo destino, elige los eventos (orden cobrada, empleado actualizado, turno cambiado…) y Nantli hará un POST firmado a tu URL cada vez que pasen.

Cada entrega va firmada con el estándar Standard Webhooks: verifica la firma con el secreto del destino (visible con Ver secreto) y descarta duplicados por el encabezado webhook-id — las entregas son al menos una vez. Si tu destino falla, Nantli reintenta con esperas crecientes hasta por un día; si falla de forma sostenida, el destino se pausa solo y aquí mismo lo puedes reactivar.

Buenas prácticas

• Una llave por sistema, con los permisos mínimos. Revocar una no toca las demás.
• Guarda la llave como secreto en tu sistema — nunca en código ni en una hoja compartida.
• Sincroniza con updated_after + next_cursor en lugar de bajar todo cada vez.
• La columna Último uso te dice si una llave sigue viva; revoca las que ya no se usan.