Ir para o conteúdo

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

Guia

API 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.

Rainer R. · FundadorAtualizado em 2 min de leitura

API ou integração de plataforma?

Se a venda nasce em Hotmart, Kiwify, Eduzz, Monetizze ou Asaas, a integração nativa emite sem uma linha de código. Se o checkout é seu (SaaS, app, ERP), a API de NFS-e é o caminho.

A emissão entra numa fila. Quando a prefeitura ou a Sefin Nacional falham, a fila tenta de novo com intervalos crescentes. Nota rejeitada pode ser corrigida e reenviada pelo endpoint de emissão da invoice.

O contrato detalhado está em docs.emitfy.com/reference/nfse.

Como emitir NFS-e pela API

  1. Autentique

    Envie X-Api-Key e X-Api-Secret em cada chamada. A empresa emissora vai no path: /v1/companies/{companyId}.

  2. Monte tomador e serviço

    Documento e dados do tomador, descrição do serviço, valor e os dados fiscais do serviço conforme o schema.

  3. Emita com Idempotency-Key

    POST /nfse com um identificador único da operação. Erro de validação volta como HTTP 422, code VALIDATION_ERROR, com os campos em error.details.fields.

  4. Guarde o retorno e acompanhe

    Salve o id da nota. Acompanhe por webhook (nfse.authorized, nfse.rejected) ou por GET /nfse/{id}; baixe XML e PDF em /nfse/{id}/xml e /pdf.

Casos de uso

SaaS com cobrança própria

Emite a NFS-e quando a fatura é paga no Stripe, num gateway ou no billing interno.

Vários CNPJs

Uma credencial da assinatura emite para todas as empresas cadastradas; o companyId no path escolhe o emissor.

Backoffice e ERP

O sistema interno dispara a emissão e consulta o status, sem ninguém no portal da prefeitura.

Perguntas frequentes

Funciona em todos os municípios?

Não. A Emitfy emite nos municípios listados em /cidades-atendidas, pelo padrão nacional ou pelo sistema da prefeitura. Confirme o seu antes de integrar.

Como cancelo uma NFS-e pela API?

POST /v1/companies/{companyId}/invoices/{id}/cancel. As regras e prazos de cancelamento são do município; a resposta informa se o cancelamento foi aceito.

O que fazer quando a nota é rejeitada?

Leia o motivo no retorno ou no webhook nfse.rejected, corrija os dados da nota (PATCH em /invoices/{id}) e reenvie com POST /invoices/{id}/emit.

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.