Conectar otros sistemas con la API y los webhooks

Con la API otro sistema lee y registra información en Nori: clientes, artículos, documentos, cobros, inventario o el CRM. Con los webhooks es al revés: Nori le avisa a ese sistema cuando algo pasa, por ejemplo cuando se contabiliza una factura o llega un cobro.

Todo se configura en Administración › Integraciones › API y webhooks. Necesitas el permiso API: tokens de integración para otros sistemas para los tokens y API: webhooks salientes para los webhooks.

Tokens de integración

Un token de integración es la llave con la que un sistema entra a la API. Cada token es de un solo sistema y tiene su propio usuario técnico:

• No ocupa licencia.
• No puede entrar a Nori: ni a la web ni a la app; solo sirve para llamar a la API.
• Hace lo que su rol permite, y solo en sus alcances. Si el rol no tiene un permiso, el token tampoco, aunque el alcance lo incluya.

Crear un token

1. En Tokens de integración pulsa Nuevo token.
2. Ponle un nombre que diga qué sistema lo usa, por ejemplo «Tienda en línea».
3. Elige el rol. Si quieres que haga poco, crea antes un rol con solo esos permisos.
4. Marca los alcances: solo lo que el otro sistema necesita. Por ejemplo, una tienda en línea suele necesitar Leer artículos, precios y existencias y Crear y cambiar documentos de venta.
5. Si el otro sistema sale siempre de las mismas IP, escríbelas en IP permitidas (una por renglón; también redes como 201.150.10.0/24).
6. Si es temporal, pon una fecha en Vence el.
7. Pulsa Crear token y cópialo en ese momento: solo se muestra una vez.

El otro sistema lo manda en cada llamada en el encabezado Authorization: Bearer <token>. La documentación técnica de la API está en el botón Documentación de la API.

Cambiar o revocar un token

En la lista ves cuándo y desde qué IP se usó por última vez. Con Cambiar o revocar cambias sus alcances, IP o vencimiento, o lo revocas. Un token revocado deja de servir en ese momento.

Si el otro sistema recibe «Este token no tiene el alcance para esta operación», el mensaje dice qué alcance le falta: agrégalo si está bien que lo haga.

Webhooks

Un webhook es una dirección del otro sistema a la que Nori manda un aviso cuando pasa algo. Puedes elegir entre estos eventos:

• Documentos: creado, contabilizado y cancelado.
• Cobros: recibido y cancelado.
• Facturación electrónica: CFDI timbrado y cancelado.
• Envíos a domicilio: cuando cambia su estado, fecha o paquetería.
• Clientes: alta y cambios.
• Inventario: cambios de un artículo y cambios de existencia (se agrupan por minuto para no mandar un aviso por cada movimiento).

Crear un webhook

1. En Webhooks pulsa Nuevo webhook.
2. Escribe la URL del otro sistema. Debe empezar con https:// y ser una dirección pública.
3. Marca los eventos que le interesan.
4. Pulsa Crear webhook y copia el secreto: solo se muestra una vez. El otro sistema lo usa para comprobar que el aviso viene de Nori (encabezado Nori-Signature).
5. Pulsa Enviar prueba para confirmar que el otro sistema responde.

Entregas y reintentos

En el detalle de cada webhook ves sus Entregas: fecha, evento, estado, respuesta e intentos. Con Ver revisas lo que se mandó y lo que contestó el otro sistema; con Reenviar lo mandas otra vez.

Si el otro sistema no responde bien, Nori reintenta durante casi un día (8 intentos, cada vez más espaciados). Si falla muchas veces seguidas, el webhook se apaga solo y los administradores reciben un aviso. Revisa el otro sistema, envía una prueba y vuelve a activarlo.

Cambiar el secreto

Con Cambiar secreto se genera uno nuevo y se muestra una vez. Durante 24 horas Nori firma con los dos, para que tengas tiempo de cambiarlo en el otro sistema sin perder avisos.

Webhooks de las automatizaciones del CRM

La acción Avisar a otro sistema de las automatizaciones del CRM también firma lo que manda y lo reintenta si falla. Usa su propio secreto, que generas en la sección Webhooks de las automatizaciones del CRM de esta misma pantalla.

Si no ves…

• La opción API y webhooks en el menú: tu rol necesita alguno de los dos permisos de API. Pídelo a un administrador (roles y permisos).
• El token después de crearlo: no se puede volver a ver. Revócalo y crea otro.
• Que llegue un aviso: revisa en Entregas si falló y qué respondió el otro sistema, y que el webhook esté Activo.
• Que te deje guardar la URL: debe ser https://, sin usuario ni contraseña, y no puede apuntar a una red interna.