Integração API (webhook)

A integração API permite que o seu sistema (ou Zapier, Make, n8n etc.) envie eventos para a Emitfy e dispare a criação ou o cancelamento de notas fiscais, com as preferências configuradas na conexão (tipo de nota, emissão automática, e-mail ao cliente).

Em resumo: este guia descreve o webhook de recebimento por conexão. Ele não substitui a API REST documentada em docs.emitfy.com.

Como configurar

  1. No painel, abra Integrações → Nova integração → API.
  2. Defina o nome, o tipo de nota (NFS-e ou NF-e) e as preferências de emissão.
  3. Ao salvar, copie a URL do webhook e o token gerado pela Emitfy. O token é exibido uma única vez; se perder, gere um novo na aba Webhook.

URL

Texto
https://api.emitfy.com/v1/webhook/{integrationId}

O {integrationId} é o id da conexão criada. Use sempre https://api.emitfy.com em produção.

Autenticação

Toda conexão nova recebe um token gerado pela Emitfy. As requisições devem enviar esse token no header:

Shell
Authorization: Bearer seu-token-da-conexao

Requisições sem Authorization: Bearer válido recebem 401. Ao gerar um token novo, o anterior continua aceito por 24 horas para você atualizar o seu sistema. Conexões criadas antes desta mudança continuam como estavam até você gerar um token; depois de gerar, por 24 horas elas ainda aceitam as requisições como antes e, então, passam a exigir o token. Este token é da conexão — não confundir com X-Api-Key / X-Api-Secret da API REST da conta.

Produto e emissão automática

O payload do webhook é propositalmente simples (cliente + itens + valores). Cada item cria ou atualiza um produto/serviço no catálogo da Emitfy.

  • Primeira vez que um item chega pela integração: a nota fica pendente até você configurar o produto ou serviço no painel (dados fiscais necessários para emitir).
  • Depois de salvar a configuração do item: as notas que estavam aguardando são liberadas e as próximas vendas desse item seguem a preferência de emissão automática da conexão.

Emitir nota fiscal

POST com action: "emit". Valores de item em centavos. Use um externalId estável por pedido para idempotência.

JSON
{
  "action": "emit",
  "externalId": "pedido-123",
  "customer": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "[email protected]"
  },
  "items": [
    {
      "name": "Consultoria",
      "quantity": 1,
      "amount": 15000
    }
  ]
}
Shell
curl -X POST "https://api.emitfy.com/v1/webhook/SEU_INTEGRATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "action": "emit",
    "externalId": "pedido-123",
    "customer": {
      "name": "Maria Silva",
      "document": "12345678909",
      "email": "[email protected]"
    },
    "items": [
      { "name": "Consultoria", "quantity": 1, "amount": 15000 }
    ]
  }'

Campos

CampoObrigatórioDescrição
actionSimSempre emit
externalIdSimId do pedido/venda no seu sistema (único por empresa)
customer.nameSimNome do destinatário (mín. 3 caracteres)
customer.documentSimCPF ou CNPJ
customer.emailSimE-mail do destinatário
customer.phoneNãoTelefone
items[].nameSimDescrição do item
items[].amountSimValor unitário em centavos (ex.: R$ 150,00 → 15000)
items[].quantityNãoQuantidade (padrão 1)
items[].codeNãoId externo do produto no seu sistema (recomendado para reutilizar o mesmo item)

Cancelar nota fiscal

POST com action: "cancel" e o mesmo externalId da emissão. Respeita a preferência Cancelar nota após reembolso da conexão.

JSON
{
  "action": "cancel",
  "externalId": "pedido-123"
}
Shell
curl -X POST "https://api.emitfy.com/v1/webhook/SEU_INTEGRATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{
    "action": "cancel",
    "externalId": "pedido-123"
  }'

Idempotência

A deduplicação usa apenas action + externalId (ex.: emit + pedido-123 e cancel + pedido-123 são eventos distintos). Reenvios iguais retornam duplicated: true.

Respostas comuns

JSON
{
  "success": true,
  "data": {
    "received": true,
    "correlationId": "...",
    "invoiceIds": ["..."],
    "externalId": "pedido-123",
    "updated": false
  }
}
HTTPCódigoQuando
401WEBHOOK_UNAUTHORIZEDToken configurado na conexão, mas Bearer ausente ou inválido
400API_WEBHOOK_PAYLOAD_INVALIDJSON fora do contrato
404INTEGRATION_NOT_FOUNDConexão inexistente ou inativa

Diferença para a API REST

Se a sua integração precisa de mais controle, resiliência ou cobertura de endpoints, prefira a API REST — documentação completa.

Integração API (este guia)API REST da conta
Quando usarAtalho simples (Zapier, Make, n8n, scripts leves)Recomendado para integração robusta / produção
AuthAuthorization: Bearer com o token da conexãoX-Api-Key + X-Api-Secret da conta
UsoEventos push do seu sistema → EmitfyVocê chama endpoints de emissão, catálogo, consulta etc.
PreferênciasPor conexão (tipo, auto emissão…) + configuração do produto no painelPor request e campos do body
DocumentaçãoEsta páginadocs.emitfy.com