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
- No painel, abra Integrações → Nova integração → API.
- Defina o nome, o tipo de nota (NFS-e ou NF-e) e as preferências de emissão.
- 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
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:
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.
{
"action": "emit",
"externalId": "pedido-123",
"customer": {
"name": "Maria Silva",
"document": "12345678909",
"email": "[email protected]"
},
"items": [
{
"name": "Consultoria",
"quantity": 1,
"amount": 15000
}
]
}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
| Campo | Obrigatório | Descrição |
|---|---|---|
action | Sim | Sempre emit |
externalId | Sim | Id do pedido/venda no seu sistema (único por empresa) |
customer.name | Sim | Nome do destinatário (mín. 3 caracteres) |
customer.document | Sim | CPF ou CNPJ |
customer.email | Sim | E-mail do destinatário |
customer.phone | Não | Telefone |
items[].name | Sim | Descrição do item |
items[].amount | Sim | Valor unitário em centavos (ex.: R$ 150,00 → 15000) |
items[].quantity | Não | Quantidade (padrão 1) |
items[].code | Não | Id 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.
{
"action": "cancel",
"externalId": "pedido-123"
}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
{
"success": true,
"data": {
"received": true,
"correlationId": "...",
"invoiceIds": ["..."],
"externalId": "pedido-123",
"updated": false
}
}| HTTP | Código | Quando |
|---|---|---|
401 | WEBHOOK_UNAUTHORIZED | Token configurado na conexão, mas Bearer ausente ou inválido |
400 | API_WEBHOOK_PAYLOAD_INVALID | JSON fora do contrato |
404 | INTEGRATION_NOT_FOUND | Conexã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 usar | Atalho simples (Zapier, Make, n8n, scripts leves) | Recomendado para integração robusta / produção |
| Auth | Authorization: Bearer com o token da conexão | X-Api-Key + X-Api-Secret da conta |
| Uso | Eventos push do seu sistema → Emitfy | Você chama endpoints de emissão, catálogo, consulta etc. |
| Preferências | Por conexão (tipo, auto emissão…) + configuração do produto no painel | Por request e campos do body |
| Documentação | Esta página | docs.emitfy.com |