Esta API REST permite que sistemas externos (parceiros) emitam NFC-e (Nota Fiscal de Consumidor Eletrônica, modelo 65) ou NF-e (Nota Fiscal Eletrônica, modelo 55) em nome de um estabelecimento cadastrado no EmiteFácil, sem que o operador precise acessar o sistema manualmente. Ela também disponibiliza endpoints de consulta para sincronizar produtos, clientes e formas de pagamento já cadastrados.
Casos de uso típicos: um PDV próprio ou um sistema de controle de restaurante que precisa emitir a NFC-e automaticamente ao fechar um pedido de balcão; ou um ERP externo que precisa emitir NF-e para vendas de revenda/entre empresas.
O EmiteFácil resolve automaticamente todos os parâmetros fiscais (CFOP, CST/CSOSN, ICMS, PIS, COFINS) — o parceiro só precisa informar produto, quantidade, valor e forma de pagamento (e, para NF-e, os dados do destinatário).
Qual modelo emitir? Por padrão a API emite NFC-e (modelo 65) — ideal para venda de balcão a consumidor final, sem necessidade de identificar o cliente. Para emitir NF-e (modelo 55) — venda para revenda/empresa, ou qualquer operação que exija destinatário identificado com endereço — envie
"modelo": 55no payload de emissão. Veja a seção "Emissão de NF-e (modelo 55)" mais abaixo para os campos adicionais exigidos.
Sobre cadastro de produtos: esta API não cadastra nem altera produtos. O cadastro de itens continua sendo feito pela tela Cadastros → Produtos e Serviços do EmiteFácil (ou pela importação por planilha, disponível na mesma tela). A API oferece apenas a consulta
GET /items, usada para obter o código (produto_cod) de um produto já cadastrado e referenciá-lo na emissão da NFC-e.
Todos os endpoints exigem uma API key enviada no header X-API-Key. Requisições sem a chave, ou com chave inválida/inativa, recebem HTTP 401.
X-API-Key: sua_chave_aqui
Caminho: Parâmetros Gerais → aba "Integração via API"
Atenção: desativar uma API key interrompe imediatamente a integração de quem a utiliza. Use essa opção se a chave for exposta ou comprometida.
https://api.emitenfe.com.br/nfe/
Todos os exemplos desta página usam esse prefixo.
POST /emitCria a venda e emite o documento fiscal (NFC-e ou NF-e, conforme modelo) para a SEFAZ em uma única chamada.
Atenção: se a venda for gravada mas a SEFAZ rejeitar a nota, a resposta traz o código da venda (
venda.codigo) e uma URL de reemissão (retry_url). Use o endpoint de reemissão para reenviar sem duplicar a venda.
Headers
| Header | Valor |
|---|---|
X-API-Key |
Sua API key |
Content-Type |
application/json |
Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
modelo |
integer | não | 55 (NF-e) ou 65 (NFC-e). Padrão: 65. Para 55, ver campos adicionais na seção "Emissão de NF-e (modelo 55)" logo abaixo |
consumidor_final |
boolean | sim | true para venda a consumidor final, false para revenda |
cliente.cpf_cnpj |
string | não* | CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números. *Obrigatório em NF-e (modelo 55) quando não usar cod_terceiro |
cliente.nome |
string | não* | Nome do cliente. Se o CPF/CNPJ não estiver cadastrado, é criado automaticamente. *Obrigatório em NF-e (modelo 55) quando não usar cod_terceiro |
cliente.inscricao_estadual |
string | não | Inscrição Estadual do cliente, ou "ISENTO". Usado apenas ao criar um cliente novo (só relevante para NF-e) |
cliente.endereco.* |
objeto | não* | Endereço do cliente (ver tabela na seção de NF-e). *Obrigatório em NF-e (modelo 55) quando não usar cod_terceiro |
cod_terceiro |
integer | não | Código interno do cliente, alternativa aos campos cliente.*. Obtido via GET /customers |
itens |
array | sim | Lista de itens da venda (mínimo 1) |
itens[].produto_cod |
integer | sim | Código do produto, obtido via GET /items |
itens[].quantidade |
number | sim | Quantidade (mínimo 0,001) |
itens[].valor_unitario |
number | sim | Valor unitário (mínimo 0,01) |
itens[].desconto |
number | não | Desconto em reais (padrão 0) |
forma_pagamento.codigo |
integer | sim | Código da forma de pagamento, obtido via GET /payment-methods |
forma_pagamento.valor |
number | sim | Valor total do pagamento (deve cobrir o total dos itens) |
informacoes_complementares |
string | não | Texto livre para o campo de informações complementares da nota |
Exemplo de requisição (NFC-e, modelo padrão)
curl -X POST https://api.emitenfe.com.br/nfe/emit \
-H "X-API-Key: sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{
"consumidor_final": true,
"cliente": {
"cpf_cnpj": "12345678901",
"nome": "João da Silva"
},
"itens": [
{
"produto_cod": 1,
"quantidade": 2,
"valor_unitario": 29.90,
"desconto": 0
}
],
"forma_pagamento": {
"codigo": 1,
"valor": 59.80
},
"informacoes_complementares": "Pedido #1234 - Mesa 5"
}'
Resposta — sucesso (HTTP 200)
{
"sucesso": true,
"msg": "NF-e emitida com sucesso",
"venda": { "codigo": 789, "valor_total": 59.80 },
"nfe": {
"serie": 1,
"numero": 1234,
"chave_acesso": "43260312345678901234550650000012341234567890",
"protocolo": "143260000123456",
"status": "AU"
},
"url_danfe": "https://api.emitenfe.com.br/nfe/sale/789/danfe"
}
Resposta — venda criada mas rejeitada pela SEFAZ (HTTP 422)
{
"sucesso": false,
"msg": "Descrição do erro da SEFAZ",
"venda": { "codigo": 789 },
"retry_url": "https://api.emitenfe.com.br/nfe/sale/789/emit"
}
NFC-e sem identificação de cliente: para emitir sem informar dados do cliente (consumidor não identificado), basta omitir os campos cliente e cod_terceiro.
Envie "modelo": 55 em POST /emit para emitir NF-e em vez de NFC-e. Diferente da NFC-e, a NF-e exige destinatário identificado com endereço completo — a SEFAZ rejeita NF-e sem essas informações.
Pré-requisito: o estabelecimento precisa ter uma série de NF-e configurada (Parâmetros Fiscais → Séries de Documentos Fiscais), além da série de NFC-e já usada pela emissão padrão. Sem isso, a emissão falha com "Série da NF-e não definida" — a venda já fica gravada e pode ser reenviada via
retry_urldepois de configurar a série.
Use uma das duas opções:
cod_terceiro de um cliente já cadastrado no EmiteFácil com endereço completo. Se o cadastro existente não tiver endereço válido, a emissão falha (venda gravada, com retry_url) — corrija o cadastro do cliente e reenvie.cliente.cpf_cnpj, cliente.nome e o endereço completo em cliente.endereco. O EmiteFácil cria automaticamente um cadastro mínimo do cliente.Diferente da NFC-e, em NF-e não é possível omitir os dados do cliente — a API rejeita a requisição (HTTP 422) se modelo: 55 for enviado sem cod_terceiro nem um cliente completo.
Campos de cliente.endereco (obrigatórios em NF-e sem cod_terceiro)
| Campo | Tipo | Descrição |
|---|---|---|
cliente.endereco.logradouro |
string | Rua/avenida do cliente |
cliente.endereco.numero |
string | Número do endereço |
cliente.endereco.bairro |
string | Bairro |
cliente.endereco.cep |
string | CEP (apenas números) |
cliente.endereco.cidade |
integer | Código IBGE do município (7 dígitos) — ex.: 4106902 para Curitiba/PR. É um dado público, disponível na tabela de municípios do IBGE |
Exemplo de requisição (NF-e, cliente novo)
curl -X POST https://api.emitenfe.com.br/nfe/emit \
-H "X-API-Key: sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{
"modelo": 55,
"consumidor_final": false,
"cliente": {
"cpf_cnpj": "12345678000190",
"nome": "Empresa Compradora LTDA",
"inscricao_estadual": "1234567890",
"endereco": {
"logradouro": "Rua das Indústrias",
"numero": "500",
"bairro": "Distrito Industrial",
"cep": "80000000",
"cidade": 4106902
}
},
"itens": [
{
"produto_cod": 1,
"quantidade": 10,
"valor_unitario": 29.90,
"desconto": 0
}
],
"forma_pagamento": {
"codigo": 1,
"valor": 299.00
}
}'
Resposta — sucesso (HTTP 200): mesmo formato da NFC-e.
Resposta — endereço incompleto ao criar cliente novo (HTTP 422)
{
"message": "Para emissão de NF-e (modelo 55), é necessário informar o endereço completo do cliente em \"cliente.endereco\" (campo \"cep\" ausente).",
"errors": {
"cliente.endereco.cep": ["Para NF-e (modelo 55), informe o CEP do cliente."]
}
}
Diferenças em relação à NFC-e:
idDest (operação interna/interestadual) é calculado automaticamente pela UF do cliente — na NFC-e é sempre internacliente.inscricao_estadual)POST /sale/{codLancamento}/emitReenvia para a SEFAZ o documento fiscal (NFC-e ou NF-e, conforme o modelo da venda) de uma venda já existente. Use quando a emissão inicial falhou e a resposta trouxe um retry_url. Opcionalmente permite corrigir a forma de pagamento antes de reenviar.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
forma_pagamento.codigo |
integer | não | Novo código da forma de pagamento (correção) |
forma_pagamento.valor |
number | não | Novo valor do pagamento (correção) |
curl -X POST https://api.emitenfe.com.br/nfe/sale/789/emit \
-H "X-API-Key: sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{"forma_pagamento": {"codigo": 1, "valor": 59.80}}'
A resposta de sucesso segue o mesmo formato de POST /emit.
POST /sale/{codLancamento}/cancelCancela uma nota (NFC-e ou NF-e) já autorizada. O cancelamento reverte automaticamente o estoque dos produtos. Só é possível cancelar notas com status AU (Autorizada).
Prazo legal: a legislação permite cancelar a NFC-e em até 30 minutos após a autorização e a NF-e em até 24 horas — em ambos os casos o prazo pode variar conforme o estado do estabelecimento. Depois do prazo, a SEFAZ pode rejeitar o cancelamento.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
motivo |
string | sim | Justificativa do cancelamento — mínimo 15, máximo 255 caracteres |
curl -X POST https://api.emitenfe.com.br/nfe/sale/789/cancel \
-H "X-API-Key: sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{"motivo": "Cancelamento solicitado pelo cliente"}'
{
"sucesso": true,
"msg": "NFC-e cancelada com sucesso.",
"venda": { "codigo": 789 },
"nfe": {
"chave_acesso": "43260312345678901234550650000012341234567890",
"status": "CA",
"cstat": 135,
"protocolo": "143260000654321"
}
}
A mensagem
msgdiz "NF-e cancelada com sucesso." quando a nota é modelo 55, e "NFC-e cancelada com sucesso." quando é modelo 65 — o restante da resposta é idêntico.
GET /sale/{codLancamento}Retorna o status e os dados fiscais (NFC-e ou NF-e) de uma venda.
curl -H "X-API-Key: sua_chave_aqui" \
https://api.emitenfe.com.br/nfe/sale/789
{
"sucesso": true,
"venda": { "codigo": 789, "valor_total": 59.80 },
"nfe": {
"serie": 1,
"numero": 1234,
"chave_acesso": "43260312345678901234550650000012341234567890",
"protocolo": "143260000123456",
"status": "AU",
"cstat": 100,
"motivo": "Autorizado o uso da NF-e"
}
}
Valores do campo status
| Valor | Significado |
|---|---|
NE |
Não emitida (aguardando envio) |
AU |
Autorizada pela SEFAZ |
CA |
Cancelada |
RE |
Rejeitada pela SEFAZ |
GET /sale/{codLancamento}/danfeRetorna o PDF do documento auxiliar — DANFCe para NFC-e (modelo 65) ou DANFE para NF-e (modelo 55). A nota precisa estar com status AU para o PDF ser gerado. A mesma URL também é retornada no campo url_danfe da resposta de emissão.
curl -H "X-API-Key: sua_chave_aqui" \
https://api.emitenfe.com.br/nfe/sale/789/danfe \
--output danfce.pdf
Resposta: conteúdo binário do PDF, com Content-Type: application/pdf.
Use estes endpoints para sincronizar, no sistema parceiro, os códigos necessários para montar a chamada de POST /emit.
GET /items?search=termo&page=1Lista os produtos cadastrados no estabelecimento, paginados (máximo 30 por página). Somente leitura — não cria nem altera produtos.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
page |
não | Número da página (padrão 1) |
search |
não | Filtro por nome do produto ou referência |
{
"sucesso": true,
"pagina": 1,
"itens_por_pagina": 30,
"ultima_pagina": false,
"itens": [
{ "codigo": 1, "nome": "Coca-Cola 350ml", "unidade": "UN", "valor_venda": 5.50, "ncm": "22021000" },
{ "codigo": 2, "nome": "Frango Frito", "unidade": "UN", "valor_venda": 29.90, "ncm": "02071400" }
]
}
Loop de sincronização (página a página):
PAGE=1
while true; do
RESPONSE=$(curl -s -H "X-API-Key: sua_chave_aqui" \
"https://api.emitenfe.com.br/nfe/items?page=$PAGE")
echo "$RESPONSE" | jq '.itens'
ULTIMA=$(echo "$RESPONSE" | jq '.ultima_pagina')
if [ "$ULTIMA" = "true" ]; then break; fi
PAGE=$((PAGE + 1))
done
Um produto que ainda não existe precisa ser criado antes pela tela Cadastros → Produtos e Serviços. Depois de cadastrado, ele aparece nesta listagem e pode ser referenciado por
codigono campoitens[].produto_codda emissão.
GET /customers?search=termoLista até 50 clientes cadastrados, filtrando por razão social, nome fantasia ou CPF/CNPJ.
{
"sucesso": true,
"clientes": [
{ "codigo": 42, "cnpj_cpf": "12345678901", "tipo_pessoa": "F", "razaosocial": "João da Silva", "nomefantasia": null }
]
}
O campo codigo pode ser usado como cod_terceiro na emissão da nota (NFC-e ou NF-e).
GET /payment-methodsLista as formas de pagamento cadastradas e ativas no estabelecimento.
{
"sucesso": true,
"formas_pagamento": [
{ "codigo": 1, "descricao": "DINHEIRO", "t_pag": "01" },
{ "codigo": 2, "descricao": "PIX", "t_pag": "17" },
{ "codigo": 3, "descricao": "CRÉDITO", "t_pag": "03" },
{ "codigo": 4, "descricao": "DÉBITO", "t_pag": "04" }
]
}
Use o campo codigo (não t_pag) em forma_pagamento.codigo ao emitir a nota. t_pag é o código de referência da SEFAZ:
| Código | Descrição |
|---|---|
01 |
Dinheiro |
02 |
Cheque |
03 |
Cartão de Crédito |
04 |
Cartão de Débito |
05 |
Crédito Loja |
10 |
Vale Alimentação |
11 |
Vale Refeição |
15 |
Boleto Bancário |
17 |
PIX |
90 |
Sem pagamento |
99 |
Outros |
Todas as respostas de erro seguem o formato:
{ "sucesso": false, "msg": "Descrição do problema" }
| HTTP | Situação |
|---|---|
| 401 | API key ausente, inválida ou inativa |
| 400 | Payload inválido (campo obrigatório ausente ou com valor incorreto) |
| 404 | Venda ou produto não encontrado |
| 422 | Nota rejeitada pela SEFAZ (msg traz o motivo) ou validação de negócio falhou (ex.: motivo de cancelamento muito curto, endereço incompleto em NF-e) |
| 500 | Erro interno inesperado no servidor |
1. Sincronização inicial (uma vez, e periodicamente):
GET /items — paginar até ultima_pagina = true e guardar os códigos dos produtosGET /payment-methods — guardar os códigos das formas de pagamento2. Ao fechar um pedido:
POST /emit
sucesso: true → salvar venda.codigo e chave_acesso, imprimir o DANFCe/DANFE (url_danfe)sucesso: false com retry_url → a venda foi criada mas a SEFAZ rejeitou; chame POST {retry_url} para tentar novamente (corrigindo a forma de pagamento se for o caso)3. Cancelamento:
POST /sale/{cod}/cancel — em caso de sucesso, o estoque é revertido e cstat = 135 confirma o cancelamento na SEFAZPara NFC-e (modelo 65, padrão):
cliente nem cod_terceirocliente: { cpf_cnpj, nome }; o sistema busca automaticamente e, se não encontrar, cadastra um registro mínimoGET /customers, guarde o codigo e envie como cod_terceiroPara NF-e (modelo 55), a identificação não é opcional — use cod_terceiro de um cliente já cadastrado com endereço completo, ou envie cliente com CPF/CNPJ, nome e endereço completo. Ver seção "Emissão de NF-e (modelo 55)".
A API cadastra produtos novos?
Não. A API só consulta produtos já cadastrados (GET /items). O cadastro é feito pela tela Cadastros → Produtos e Serviços ou pela importação por planilha da mesma tela.
Preciso informar CFOP, CST, ICMS ou outros dados fiscais na requisição?
Não. O EmiteFácil resolve automaticamente todos os parâmetros fiscais a partir da configuração do produto e do estabelecimento. Basta informar produto, quantidade, valor e forma de pagamento.
O que fazer quando POST /emit retorna sucesso: false com retry_url?
A venda já foi gravada no sistema — não chame POST /emit novamente, pois isso criaria uma venda duplicada. Em vez disso, chame o endpoint indicado em retry_url (equivalente a POST /sale/{codigo}/emit).
É possível emitir NF-e modelo 55 (não NFC-e) por essa API?
Sim. Envie "modelo": 55 no payload de POST /emit. Diferente da NFC-e, a NF-e exige destinatário identificado com endereço completo — veja a seção "Emissão de NF-e (modelo 55)". Sem o campo modelo, a API continua emitindo NFC-e (comportamento padrão).
Qual o prazo para cancelar uma NFC-e?
Em geral até 30 minutos após a autorização, podendo variar conforme a legislação do estado do estabelecimento. Depois desse prazo a SEFAZ pode rejeitar o cancelamento.
Um cliente informado por CPF/CNPJ que ainda não existe é cadastrado automaticamente?
Sim. Se o CPF/CNPJ informado em cliente.cpf_cnpj não existir na base, o EmiteFácil cria um cadastro mínimo (nome, documento, tipo de pessoa e município padrão do estabelecimento) automaticamente durante a emissão. Em NF-e (modelo 55), o endereço completo é obrigatório nesse cadastro mínimo — não há preenchimento automático.
Por que minha NF-e foi rejeitada mesmo informando o endereço?
Confira se o código enviado em cliente.endereco.cidade é o código IBGE do município (7 dígitos, ex.: 4106902) e não o nome da cidade. Confirme também que o estabelecimento tem série de NF-e configurada em Parâmetros Fiscais.