Guia
Exemplos de API Emitfy
Exemplos de chamadas à API Emitfy: autenticação, emissão de NFS-e, NF-e e CT-e, idempotência, erros e NF-e recebidas. Contrato completo no OpenAPI.
Autenticação
Toda chamada autenticada envia X-Api-Key e X-Api-Secret, gerados no painel em API & Webhooks. A empresa emissora vai no path, em /v1/companies/{companyId}. Webhooks e rotação de credenciais não usam companyId.
Headers de uma emissão: X-Api-Key: <sua key> X-Api-Secret: <seu secret> Idempotency-Key: pedido-42 Content-Type: application/json
Emissão de NFS-e
POST https://api.emitfy.com/v1/companies/{companyId}/nfse
O corpo leva tomador, descrição do serviço, valor e dados fiscais conforme o schema. Repetir a chamada com a mesma Idempotency-Key devolve a nota já criada, com a mesma resposta, em vez de emitir outra.
O JSON canônico e os campos avançados estão em docs.emitfy.com/reference/nfse. Esta página não copia o contrato para não ficar desatualizada.
Emissão de NF-e
POST https://api.emitfy.com/v1/companies/{companyId}/nfe
Inclua itens com NCM e CFOP e o destinatário. Para NFC-e, o endpoint é /nfce. Payload atual na referência de NF-e.
Emissão de CT-e
POST https://api.emitfy.com/v1/companies/{companyId}/cte (e /cte-os para outros serviços de transporte)
Para transportadoras que querem CT-e na mesma API da NF-e e da NFS-e, conforme habilitação da conta. Payload na referência de CT-e.
NF-e recebidas
Além de emitir, a API lista as NF-e emitidas contra o seu CNPJ: GET /companies/{companyId}/received-nfes, sincronização com a SEFAZ em /received-nfes/sync, XML em /received-nfes/{id}/xml e manifestação do destinatário em /received-nfes/{id}/manifest.
Erros que você vai tratar
| HTTP | Quando acontece | O que fazer |
|---|---|---|
| 401 | Credenciais inválidas | Confira X-Api-Key e X-Api-Secret |
| 422 | Validação do corpo (code VALIDATION_ERROR) | Mostre ao usuário os campos de error.details.fields |
| 409 | Conflito, como versão desatualizada ao editar uma nota (INVOICE_VERSION_CONFLICT) | Recarregue a nota e reenvie com a versão atual |
| 429 | Limite de requisições do plano | Espere o tempo do header Retry-After |
| 5xx | Falha temporária | Tente de novo com a mesma Idempotency-Key |
Perguntas frequentes
Onde acho exemplos oficiais?
Na documentação em docs.emitfy.com, que tem versão em Markdown de cada página, no OpenAPI em api.emitfy.com/openapi.yaml e no arquivo api.emitfy.com/llms-full.txt, pensado para agentes de IA.
Posso usar no ChatGPT, Claude ou Cursor?
Sim. Para operar notas com um agente, use o servidor MCP remoto (docs.emitfy.com/mcp). Para gerar código de integração, aponte o assistente para o llms-full.txt e para os SDKs.
A Idempotency-Key é obrigatória?
Não, mas é recomendada em toda emissão. Como alternativa, envie externalId no corpo; o header tem prioridade. A chave é única por empresa.
Próximo passo
Automatize a emissão fiscal com a Emitfy
Conecte sua plataforma ou use a API REST. 10 notas grátis para testar, sem cartão.
Continue lendo
Leitura relacionada
SDKs da API Emitfy
Os SDKs oficiais da Emitfy para Node.js, PHP, Python, .NET e Java: como instalar, o que cobrem e quando vale chamar a API REST direto pelo OpenAPI.
2 min · 23/10/2026Ler o guia GuiaAPIAPI de NF-e da Emitfy
Como emitir NF-e pela API da Emitfy: credenciais, companyId no path, Idempotency-Key, XML/PDF, carta de correção e recebimento de NF-e de fornecedores.
3 min · 23/10/2026Ler o guia GuiaAPIAPI de NFS-e da Emitfy
Como emitir NFS-e pela API da Emitfy quando o checkout é seu: credenciais, endpoint, erros de validação, retentativa e quando preferir a integração nativa.
2 min · 23/10/2026Ler o guia