Saltar para o conteúdo principal
A integração Webhooks destina-se a programadores. Envia um evento JSON para um endereço HTTPS à sua escolha sempre que algo acontece no Foliant, para que o seu próprio sistema possa reagir, por exemplo, arquivando o PDF de cada fatura ou recolhendo uma exportação concluída. A integração Webhooks está em beta. Se não a vir em Definições › Integrações, ainda não está disponível para a sua loja. Contacte o suporte para pedir acesso.

Eventos

Ligar os webhooks

  1. No Foliant, aceda a Definições › Integrações.
  2. Em Webhooks, clique em Ligar.
  3. Preencha as definições:
  4. Clique em Ligar.
Pode alterar o URL, o segredo e os eventos mais tarde em Definições, na página da integração.

O que cada pedido contém

O Foliant envia um pedido POST com um corpo JSON:

Dados de document.generated

  • template: o uuid e o name do modelo.
  • document_type: invoice, credit_note, quote, ou vazio para outros documentos.
  • order: o respetivo id, name e type (encomendas ou encomendas de rascunho).
  • refund_id e fulfillment_id, quando o documento se refere a um reembolso ou a um envio.
  • document_number e issued_at, para documentos numerados.
  • source: como foi criado, como download, admin_download, export ou email.
  • export: o ID da exportação, quando faz parte de uma exportação.
  • generated_at.

Dados de export.completed

  • export: o respetivo uuid, order_type, template_uuids, número de orders, orders_skipped (eliminadas depois de terem sido escolhidas) e documents, requested_by (merchant ou customer) e completed_at.
  • download_url: uma ligação para transferir a exportação, e download_url_expires_at, quando essa ligação deixa de funcionar.
  • download_expires_at: quando a própria exportação expira.
Os eventos contêm IDs e contagens, não endereços de email de clientes.

Cabeçalhos

Verificar a assinatura

A assinatura é um HMAC-SHA256 em hexadecimal do timestamp, um ponto final e o corpo bruto do pedido (<timestamp>.<body>), usando o seu segredo de assinatura como chave. Calcule-a do seu lado e compare-a com o valor a seguir a sha256= em X-Foliant-Signature. Use o corpo bruto exatamente como foi recebido.

Respostas e novas tentativas

  • Qualquer resposta 2xx conta como entregue.
  • Se o seu endpoint devolver um erro 5xx, 408 ou 429, ou não responder em 10 segundos, o Foliant tenta novamente mais tarde, esperando mais tempo de cada vez, até 5 tentativas.
  • As outras respostas 4xx são definitivas: o Foliant não volta a tentar.
  • Cada evento é entregue uma vez por documento ou exportação. As novas tentativas nunca o enviam duas vezes depois de um sucesso.
Cada entrega aparece em Atividade, na página da integração, onde pode clicar em Tentar novamente numa entrega falhada. Consulte Atividade da integração.

Artigos relacionados