Saltar al contenido principal
La integración Webhooks está pensada para desarrolladores. Envía un evento JSON a una dirección HTTPS que tú eliges cada vez que ocurre algo en Foliant, para que tu propio sistema pueda reaccionar, por ejemplo, archivando el PDF de cada factura o recogiendo una exportación terminada. Webhooks está en beta. Si no la ves en Configuración › Integraciones, todavía no está disponible para tu tienda. Contacta con soporte para pedir acceso.

Eventos

Conecta los webhooks

  1. En Foliant, ve a Configuración › Integraciones.
  2. En Webhooks, haz clic en Conectar.
  3. Completa la configuración:
  4. Haz clic en Conectar.
Puedes cambiar la URL, el secreto y los eventos más adelante en Configuración, en la página de la integración.

Qué contiene cada solicitud

Foliant envía una solicitud POST con un cuerpo JSON:

Datos de document.generated

  • template: el uuid y el name de la plantilla.
  • document_type: invoice, credit_note, quote, o vacío para otros documentos.
  • order: su id, name y type (pedidos o borradores de pedidos).
  • refund_id y fulfillment_id, cuando el documento corresponde a un reembolso o a un envío.
  • document_number y issued_at, para documentos numerados.
  • source: cómo se generó, como download, admin_download, export o email.
  • export: el ID de la exportación, cuando forma parte de una exportación.
  • generated_at.

Datos de export.completed

  • export: su uuid, order_type, template_uuids, el número de orders, orders_skipped (eliminados después de seleccionarlos) y documents, requested_by (merchant o customer) y completed_at.
  • download_url: un enlace para descargar la exportación, y download_url_expires_at, cuándo deja de funcionar ese enlace.
  • download_expires_at: cuándo caduca la propia exportación.
Los eventos contienen IDs y recuentos, no direcciones de correo electrónico de clientes.

Encabezados

Comprueba la firma

La firma es un HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto y el cuerpo sin procesar de la solicitud (<timestamp>.<body>), usando tu secreto de firma como clave. Calcúlala por tu parte y compárala con el valor que sigue a sha256= en X-Foliant-Signature. Usa el cuerpo sin procesar exactamente como lo recibes.

Respuestas y reintentos

  • Cualquier respuesta 2xx cuenta como entregada.
  • Si tu endpoint devuelve un error 5xx, 408 o 429, o no responde en 10 segundos, Foliant vuelve a intentarlo más tarde, esperando más cada vez, hasta 5 intentos.
  • Las demás respuestas 4xx son definitivas: Foliant no las reintenta.
  • Cada evento se entrega una vez por documento o exportación. Los reintentos nunca lo envían dos veces después de una entrega correcta.
Cada entrega aparece en Actividad, en la página de la integración, donde puedes usar Reintentar en una que haya fallado. Consulta Actividad de la integración.

Artículos relacionados