Ir para o conteúdo

OUT1515% off na primeira cobrança com o cupom OUT15.15% off na 1ª cobrançaVer planos

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.

Rainer R. · FundadorAtualizado em 3 min de leitura

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

Lista completa de códigos em docs.emitfy.com/errors.
HTTPQuando aconteceO que fazer
401Credenciais inválidasConfira X-Api-Key e X-Api-Secret
422Validação do corpo (code VALIDATION_ERROR)Mostre ao usuário os campos de error.details.fields
409Conflito, como versão desatualizada ao editar uma nota (INVOICE_VERSION_CONFLICT)Recarregue a nota e reenvie com a versão atual
429Limite de requisições do planoEspere o tempo do header Retry-After
5xxFalha temporáriaTente 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.