Claves API de socios: credenciales y callbacks

Crea credenciales en el panel, protege la API Key y el Webhook Secret, y configura callbacks opcionales con HTTPS y circuit breaker.

En esta guía vas a…

  1. Entender qué hace la integración de socios en N1
  2. Localizar la tarjeta Claves API de Socios en Configuración
  3. Crear y guardar con seguridad la API Key y el Webhook Secret
  4. Gestionar claves y callbacks opcionales

Qué hace esta integración

En términos sencillos: un socio (sistema externo) puede enviar pedidos a tu operación en N1 por API. Opcionalmente, N1 puede avisar al socio cuando cambie el estado del pedido (por ejemplo, enviado o entregado), si configuras un callback HTTPS.

Dónde encontrarla

  1. Abre el menú lateral y haz clic en Configuración
  2. Selecciona la pestaña Settings
  3. En el área de tarjetas de la página, localiza la tarjeta Claves API de Socios (hay un botón Crear junto al título)

El texto de apoyo de la tarjeta dice Envía tus pedidos por API.

Paso a paso — crear la clave

  1. Haz clic en Crear en la tarjeta Claves API de Socios
  2. Rellena Nombre de la Integración — nombre interno para identificarla (por ejemplo, el nombre de la plataforma)
  3. Rellena Identificador del Socio — debe ser único en la operación y pasa a formar parte del ID de los pedidos. Se permiten letras minúsculas, números, guion bajo (_) y guion (-); otros caracteres se ajustan automáticamente. Máximo 50 caracteres
  4. Haz clic en Crear API Key
  5. Se abre la ventana Credenciales de la API Key con la API Key y el Webhook Secret. Cópialos y guárdalos en un lugar seguro en ese momento: las credenciales completas solo se muestran una vez

Qué hacer con la API Key y el Webhook Secret

  • Guárdalos en un gestor de contraseñas o de secretos del equipo
  • Compártelos con el equipo técnico por un canal seguro
  • No los publiques en tickets abiertos, grupos ni repositorios

El Webhook Secret se usa en las firmas criptográficas de la integración (envío y recepción de webhooks). Quien implemente la API lo necesita para firmar y validar peticiones.

Gestión en la lista

Para cada clave verás el nombre, el identificador, el estado (Activa/Inactiva), el último uso y la información de callback cuando exista. Acciones principales:

  • Interruptor: activa o desactiva la clave sin eliminarla
  • Icono de webhook: abre Callback de Estado (URL HTTPS, activar, intentos, prueba)
  • Regenerar Secreto: genera un secreto nuevo — las integraciones que sigan usando el anterior dejan de autenticarse hasta que se actualicen
  • Eliminar: borra la clave de forma permanente

Callbacks (opcional)

Para que N1 notifique al sistema del socio cuando cambie el estado del pedido:

  1. La URL debe ser HTTPS (la interfaz exige una URL que empiece por https://)
  2. Haz clic en el icono de webhook en la fila de la clave para abrir Callback de Estado
  3. Indica la URL, marca si el callback está activo y ajusta los intentos en caso de fallo
  4. Usa Probar Callback para validar el endpoint antes de depender de él en producción
  5. Circuit breaker: si hay muchos fallos seguidos, el envío puede pausarse automáticamente. El panel muestra Circuit breaker activado y el botón Reactivar una vez corregido el endpoint

Siguiente paso

Guía técnica (endpoints, HMAC inbound/outbound, errores): API de socios — guía técnica.

La documentación JSON del formato de callbacks (outbound) está en: https://TU-DOMINIO-N1.com/api/webhooks/partner/docs — usa el mismo host de tu instancia N1 (donde accedes al panel).