API y webhooks

A través de la API de allverto, las tiendas, los proveedores logísticos, los programas de contabilidad o tus propios programas intercambian datos con allverto: artículos, stock, clientes, pedidos, pagos, envíos, devoluciones, canales de venta, facturas y compras. Los webhooks comunican los cambios al instante a la dirección que elijas, por ejemplo «Pedido creado» o «Stock modificado».

Todo se configura en Configuración → API y webhooks. Allí también está la Documentación completa de todos los endpoints.

#Antes de empezar

• Las claves API y los webhooks los gestionan los roles con el permiso Gestionar claves API y webhooks, normalmente Propietario y Administración. Consulta Usuarios y roles.
• Una clave recibe como máximo los permisos que tienes tú. Si más adelante pierdes un permiso, la clave también lo pierde.
• Lo mismo se aplica a los webhooks: solo puedes suscribirte a eventos cuyos datos puedas leer tú mismo; «Cliente modificado», por ejemplo, solo con «Ver clientes», y «Factura creada» solo con «Ver documentos». allverto oculta los eventos sin el permiso correspondiente.

#Crear una clave API

1. Abre Configuración → API y webhooks, pestaña Claves API.
2. Haz clic en Crear clave.
3. Introduce un Nombre con el que reconozcas el sistema externo (p. ej., «Conexión Shopify»).
4. Elige los Permisos, p. ej., «Leer pedidos» e «Importar pedidos». Elige solo lo que el sistema externo necesite de verdad.
5. Opcional: limita la clave a una Empresa (entonces solo ve y escribe pedidos y documentos de esa empresa), establece una Fecha de caducidad y el Límite de solicitudes por minuto.
6. Haz clic en Crear clave. allverto muestra la clave (av_…) una sola vez: cópiala con Copiar y guárdala en el sistema externo.

En el menú de la fila puedes Copiar prefijo (así reconoces la clave en el sistema externo) y Revocar la clave en cualquier momento. A partir de entonces, la API la rechaza de inmediato. En la lista ves cuándo se usó una clave por última vez y desde qué dirección IP.

#Solicitudes a la API

Cada solicitud lleva la clave en la cabecera Authorization: Bearer av_…. Los endpoints están en /api/v1, por ejemplo:

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Las listas devuelven { data, page: { nextCursor, hasMore } }. La página siguiente la obtienes con cursor=<nextCursor>. Con updatedSince=2026-10-01T00:00:00Z solo llegan las entradas creadas o modificadas desde entonces: ideal para sincronizaciones periódicas.
• Los errores siempre tienen la forma { error, message, fields } con el estado HTTP correspondiente (400 entrada, 401 clave, 403 falta permiso, 404 no encontrado, 409 conflicto, 429 límite).
• Idempotencia: en las solicitudes POST, envía una cabecera Idempotency-Key única. Si repites la solicitud (p. ej., tras un error de red), allverto no registra nada por duplicado, sino que devuelve la misma respuesta durante 24 horas.
• Límite de solicitudes: por defecto son 120 solicitudes por minuto y clave. Si se supera, la API responde con 429 y Retry-After (segundos).
• Devoluciones y canales de venta: GET /api/v1/returns y /returns/{id} devuelven devoluciones con líneas, motivos y reembolso (permiso «Leer devoluciones»), y GET /api/v1/channels, los canales de venta: la contrapartida de channelId en pedidos y devoluciones.

Los cambios hechos a través de la API figuran en el Registro de cambios como «API: nombre de la clave».

#Configurar webhooks

1. Pestaña Webhooks, haz clic en Añadir webhook.
2. Introduce el nombre y la Dirección (https://…) del destinatario y elige los Eventos, p. ej., «Pedido creado», «Pago recibido», «Stock modificado». Con varias empresas puedes limitar el webhook a una empresa; así, los pedidos, documentos, devoluciones y pedidos de compra de otras empresas no se envían a esta dirección.
3. Haz clic en Guardar. allverto muestra el secret para comprobar la firma, también una sola vez.
4. Con Enviar prueba compruebas la conexión. El resultado aparece en el Registro de entregas.
5. Los webhooks nuevos están inactivos. Solo con Activar envía allverto eventos reales, como en todas las sincronizaciones.

Los eventos se generan en la misma transacción que el cambio: si se cancela una operación, tampoco sale ningún webhook. El contenido (data) tiene el mismo formato que la API (p. ej., GET /api/v1/orders/{id}; en devoluciones, GET /api/v1/returns/{id}).

En cada entrega, allverto comprueba los permisos actuales de la persona que creó o modificó por última vez el webhook. Si le falta el permiso de lectura de un evento o ya no tiene acceso activo, no se envía ningún contenido; el registro de entregas muestra la entrega como fallida con el motivo. Quien guarde el webhook después pasa a ser la persona responsable.

#Comprobar la firma

Cada llamada lleva la cabecera allverto-signature: t=<Unix-Zeit>,v1=<Signatur>. La firma es HMAC-SHA256 con el secret sobre t + "." + Body. Compruébala sobre el body sin modificar y descarta las llamadas cuya hora difiera más de 5 minutos.

#Entregas fallidas

Si el destinatario no responde con 2xx, allverto vuelve a intentarlo: tras 1 minuto, 5 minutos, 30 minutos, 2, 6, 12 y 24 horas. Tras 20 fallos seguidos, el webhook se desactiva automáticamente y recibes una notificación. En el Registro de entregas (periodo por defecto «Últimos 30 días») ves el estado, el código de respuesta y la duración de cada entrega, y puedes volver a enviarla con Reenviar.

Los webhooks solo pueden llamar a direcciones públicas: los destinos internos como localhost o las redes privadas están bloqueados.