NORTHLAV API v1

El dueño del negocio crea la clave en Ajustes → Northlav API y te la pasa. Tiene esta forma:

Authorization: Bearer nl_live_<key_id>_<secreto>

Va siempre en la cabecera Authorization. Nunca en la URL: las rutas acaban en los registros del proveedor, en el historial del navegador y en la cabecera Referer que se manda al siguiente sitio.

Base: https://cloud.northlavstudio.com/api/v1

Un envío, de principio a fin

Primero resuelves el contacto; la respuesta trae el conversation_id que usarás después.

curl -X POST https://cloud.northlavstudio.com/api/v1/contacts \
  -H "Authorization: Bearer $NORTHLAV_API_KEY" \
  -H "Idempotency-Key: alta-cliente-2026-09-19-0001" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+50662056819","name":"Ana Rodriguez"}'

# 201 Created
# {"contact":{"id":"…","phone":"50662056819","name":"Ana Rodriguez"},
#  "conversation_id":"…","created":true}

curl -X POST https://cloud.northlavstudio.com/api/v1/messages \
  -H "Authorization: Bearer $NORTHLAV_API_KEY" \
  -H "Idempotency-Key: aviso-pedido-8842" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"…","type":"text","text":"Su pedido esta listo."}'

# 201 Created
# {"message":{"id":"…","status":"sent"}}

Si vas a escribir por tu cuenta en una conversación, pausa antes al agente para que no conteste encima:

curl -X PATCH https://cloud.northlavstudio.com/api/v1/conversations/<id>/agent-state \
  -H "Authorization: Bearer $NORTHLAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"paused","pause_minutes":20,"expected_version":0}'

# 200 OK
# {"agent_state":{"requested":"paused","effective":"paused",
#                 "reason":"human_takeover","version":1}}

Tu sistema de inventario mantiene al día lo que Mortis ofrece: una venta en tu web resta una unidad, y Mortis deja de ofrecerla cuando se acaba.

curl -X POST https://cloud.northlavstudio.com/api/v1/products \
  -H "Authorization: Bearer $NORTHLAV_API_KEY" \
  -H "Idempotency-Key: producto-J01-2026-10-06" \
  -H "Content-Type: application/json" \
  -d '{"reference":"J01","name":"Jean Recto","price":119000,
       "variants":[{"size":"10","color":"Negro","sku":"J01-10-NE","stock":4}]}'

# 201 Created
# {"product":{"id":"…","name":"Jean Recto","variants":[{"sku":"J01-10-NE","stock":4,…}]},
#  "created":true}

curl -X POST https://cloud.northlavstudio.com/api/v1/stock \
  -H "Authorization: Bearer $NORTHLAV_API_KEY" \
  -H "Idempotency-Key: venta-web-55120" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"sku":"J01-10-NE","adjust":-1,"note":"pedido web 55120"}]}'

# 200 OK
# {"results":[{"sku":"J01-10-NE","status":"updated","stock":3}]}

Los dos POST exigen la cabecera Idempotency-Key: de 16 a 128 caracteres, letras, números, . _ ~ -. La generas tú, una por operación.

Sirve para el caso que más duele: la petición sale, se corta la conexión y no sabes si llegó. Reintenta con la misma clave y recibirás la respuesta original, sin que el cliente reciba el mensaje dos veces.

En Ajustes → Northlav API → Avisos a tu sistema registras una dirección https pública y eliges qué quieres recibir. Northlav te hace un POST con JSON: { event, created_at, data }.

GET /v1/messages/{id} devuelve dos campos, y hay que leerlos por separado.

sent significa que el proveedor lo aceptó, no que haya llegado al teléfono. Un fallo de entrega posterior convive perfectamente con una aceptación previa. Y delivery_uncertain quiere decir exactamente eso: salió y no tenemos confirmación. No lo trates como un fallo ni como un éxito — vuelve a consultar.

Todos los errores tienen la misma forma:

{"error":{"code":"resource_not_found",
          "message":"Recurso no encontrado.",
          "request_id":"7f3c…"}}

Guarda el request_id: es lo único que permite encontrar esa petición concreta si hay que mirarla. También viaja en la cabecera X-Request-Id de toda respuesta.

Mientras tanto, consulta. Para mensajes nuevos de un cliente, pide GET /v1/conversations/{id} con limit pequeño y quédate con el occurred_at del último que ya tenías. Para saber si algo tuyo llegó, GET /v1/messages/{id}.

Ajusta el ritmo al cupo de 60 peticiones por minuto: una consulta cada pocos segundos por conversación activa cabe de sobra, un bucle sin espera no.

Los webhooks firmados —con reintentos e identificador de evento para que puedas descartar duplicados— están en el diseño de la siguiente fase. Cuando existan se documentarán aquí, y no antes.

No son funciones pendientes: son límites a propósito.

De qué responde cada parte

Lo que la API envía sale del número de WhatsApp del negocio y, para quien lo recibe, lo escribió el negocio. El contenido, a quién se le manda y con qué frecuencia son responsabilidad de quien integra y del negocio que le dio la clave, no de Northlav.

Eso incluye respetar las reglas de Meta sobre mensajería, no escribirle a quien no lo ha pedido y no usar el canal para envíos masivos no solicitados. Un número que Meta bloquea por spam deja al negocio sin canal, y eso no lo arregla Northlav.

Northlav puede suspender una integración que incumpla estas reglas. Ver también Uso Aceptable y el Acuerdo de Tratamiento de Datos.

El dueño del negocio entra en Ajustes → Northlav API, da de alta la integración, elige qué ámbitos tendrá y genera la clave. Solo el administrador de la cuenta puede hacerlo.

Puede revocar una clave, que deja de funcionar en la siguiente petición, o apagar la integración entera, que corta todas sus claves de golpe. Las dos cosas son inmediatas y no requieren avisar a nadie.

Northlav Studio · Northlav API v1. Esta página describe el comportamiento del producto; no sustituye a los Términos y Condiciones. Última actualización: 19 de septiembre de 2026.