Referência da API · v1
Documentação EMITEX
API REST para emitir NF-e, NFC-e e NFS-e. Base URL: https://emitex.api.br
Para integrações e agentes de IA: openapi.yaml (contrato OpenAPI 3.1), llms.txt e llms-full.txt.
Visão geral
A API é REST com JSON. A emissão é assíncrona: o POST responde 202 com o id da nota, a transmissão ao autorizador roda em fila e o resultado pode ser acompanhado por consulta ou webhook configurado.
- Autenticação OAuth2 client_credentials (Bearer token).
- Multi-tenant: a credencial enxerga apenas as empresas da sua conta.
- Idempotência por
request_idna emissão. - Emissão: débito de 1 crédito no enfileiramento, com estorno em erro, rejeição ou denegação e novo débito no reenvio. Estorno inicial e saldo retornado na emissão inicial de NFC-e a confirmar. Header
x-quota-saldonas respostas de emissão inicial e movimentação de créditos.
Quick start
Acesso assistido. Antes deste exemplo resumido, configure uma empresa em homologação, o certificado A1 e o provedor NFS-e. O código de serviço e os dados fiscais dependem do provedor. Consulte o id retornado para acompanhar o resultado.
# 1. token
TOKEN=$(curl -s -X POST https://emitex.api.br/oauth/token \
-d grant_type=client_credentials \
-d client_id=$ID -d client_secret=$SECRET \
-d scope="empresas:gerenciar nfe:emitir nfe:consultar" \
| jq -r .access_token)
# 2. emitir
curl -X POST https://emitex.api.br/api/v1/empresas/1/nfse \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "descricao": "Servico", "valor": 100.0, "codigo_servico": "2919", "tomador": { "cnpj": "09272876000161" } }'
Autenticação
Troque suas credenciais por um token Bearer; observe expires_in na resposta. O ambiente fiscal é da empresa/documento, sem garantia de credencial exclusiva por ambiente. O scope sefaz:status permite consultar a disponibilidade da SEFAZ. Envie o token no header Authorization: Bearer <token> em todas as chamadas.
/oauth/token
grant_type=client_credentials
client_id=...&client_secret=...
scope=empresas:gerenciar nfe:emitir nfe:consultar nfe:cancelar
# 200
{ "access_token": "eyJ0eXAiOiJKV1Qi...", "token_type": "Bearer", "expires_in": 3600 }
Escopos
| empresas:gerenciar | Empresas, certificado, CSC, webhook, extrato de créditos |
| nfe:emitir | Emitir NF-e, NFC-e e NFS-e |
| nfe:consultar | Consultar status e baixar XML/PDF |
| nfe:cancelar | Cancelar notas autorizadas |
| distribuicao-nfe:consultar | Consultar DF-e recebidos e baixar XMLs |
| distribuicao-nfe:manifestar | Enviar manifestação do destinatário |
Empresas
A empresa é o emitente. Cadastre-a e depois anexe o certificado A1.
/api/v1/empresas
empresas:gerenciar
{
"razao_social": "EMPRESA LTDA",
"cnpj": "11222333000181",
"im": "02359227", // inscricao municipal (NFS-e)
"crt": 1, // 1=Simples, 2=Simples excesso, 3=Normal, 4=MEI
"logradouro": "RUA X", "numero": "100", "bairro": "CENTRO",
"cep": "01001000", "codigo_municipio": 3550308,
"municipio": "SAO PAULO", "uf": "SP",
"ambiente": "homologacao" // homologacao | producao
}
# 201 -> { "id": 1, "razao_social": "EMPRESA LTDA", ... }
Outras rotas: GET /api/v1/empresas (lista) e GET /api/v1/empresas/{empresa} (detalhe).
Certificado A1
Envie o .pfx e a senha. É cifrado em repouso e nunca retornado — a resposta traz só o CN e a validade.
/api/v1/empresas/{empresa}/certificado
empresas:gerenciar
# multipart/form-data: arquivo=@cert.pfx senha=123456
# ou JSON:
{ "certificado_base64": "MIICtTCC...", "senha": "123456" }
# 200 -> { "certificado_cn": "EMPRESA LTDA:112...", "certificado_validade": "2027-01-01T00:00:00Z" }
CSC (NFC-e)
Necessário para gerar o QR Code da NFC-e. Também cifrado em repouso.
/api/v1/empresas/{empresa}/csc
empresas:gerenciar
{ "csc": "CODIGO-CSC-DA-SEFAZ", "csc_id": "000001", "serie_nfce": 1 }
Emitir NF-e
/api/v1/empresas/{empresa}/nfe
nfe:emitir
{
"natureza_operacao": "VENDA",
"destinatario": { "cnpj": "99999999000191", "indicador_ie": 9 },
"itens": [
{ "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102",
"quantidade": 2, "valor_unitario": 10.50, "unidade": "UN" }
],
"pagamento": { "forma": "01", "valor": 21.00 },
"request_id": "pedido-123"
}
# 202 -> { "id": 10, "status": "pendente", "numero": 10, "serie": 1,
# "ambiente": "homologação", "consultar_em": ".../api/v1/nfe/10" }
Emitir NFC-e
Consumidor final. Destinatário é opcional; o pagamento aceita múltiplas formas e troco. Exige CSC configurado.
/api/v1/empresas/{empresa}/nfce
nfe:emitir
{
"destinatario": { "cpf": "12345678909" },
"itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102",
"quantidade": 1, "valor_unitario": 21.00, "unidade": "UN" } ],
"pagamento": { "formas": [ { "forma": "01", "valor": 21.00 } ], "troco": 0.00 }
}
Emitir NFS-e
Padrão Nacional (DPS/ADN) ou Prefeitura de São Paulo (RPS), conforme o cadastro da empresa (nfse_provedor). Em operação em produção: Padrão Nacional. O provedor São Paulo segue disponível na API; prefeituras no CNC migram para o padrão nacional.
/api/v1/empresas/{empresa}/nfse
nfe:emitir
{
"descricao": "DESENVOLVIMENTO DE SOFTWARE",
"valor": 1500.00,
"codigo_servico": "2919", // codigo do servico (municipal/nacional)
"aliquota": 2.00, // % ISS (use 0 para Simples Nacional)
"competencia": "2026-06-12",
"iss_retido": false, // true = retido pelo tomador
"tomador": { "cnpj": "99999999000191", "nome": "CLIENTE LTDA" },
"request_id": "fatura-456"
}
# 202 -> { "id": 29, "status": "pendente", "numero": 1, "serie": 1, ... }
Consulta & arquivos
Troque nfe por nfce ou nfse conforme o tipo. NF-e e NFC-e têm geração de PDF para notas autorizadas. NFS-e expõe XML quando disponível e serve PDF apenas para nota autorizada com pdf_path existente; não há geração de DANFSe.
/api/v1/empresas/{empresa}/nfelista paginada (também /nfce e /nfse)/api/v1/nfe/{nota}status + dados/api/v1/nfe/{nota}/xmlXML autorizado/api/v1/nfe/{nota}/pdfDANFE (NF-e/NFC-e)# GET /api/v1/nfe/10
{
"id": 10, "status": "autorizada", "numero": 10, "serie": 1,
"chave": "3526...", "protocolo": "135...",
"cStat": "100", "motivo": "Autorizado o uso da NF-e",
"autorizada_em": "2026-06-12T18:30:00-03:00",
"links": { "xml": ".../api/v1/nfe/10/xml", "pdf": ".../api/v1/nfe/10/pdf" }
}
Listagem: GET /api/v1/empresas/{empresa}/nfe, /nfce e /nfse (scope nfe:consultar), mais recentes primeiro, 20 por página (per_page de 1 a 100). Filtros opcionais: status, de, ate (Y-m-d, fuso de São Paulo, inclusivas), busca, numero, serie, chave, request_id, ambiente (homologacao ou producao). Filtro inválido retorna 422.
Status possíveis: pendente, processando, autorizada, rejeitada, denegada, cancelada, erro. Consulta NF-e/NFC-e usa cStat; webhook fiscal usa recurso.cstat e protocolo (NFC-e é identificada como nfe). Consulta NFS-e usa codigo/motivo; o webhook NFS-e inclui motivo, nfse_numero e codigo_verificacao, sem codigo. Downloads não implementam débito por repetição; condições comerciais sob consulta.
Cancelamento
/api/v1/{tipo}/{nota}/cancelar
nfe:cancelar
# NF-e / NFC-e
{ "justificativa": "texto entre 15 e 255 caracteres" }
# NFS-e Nacional
{ "motivo_codigo": 1, "motivo": "erro na emissao (15 a 255 chars)" }
# NFS-e Sao Paulo -> corpo vazio: {}
Distribuição de DF-e
Receba as NF-e emitidas contra o CNPJ da empresa (Ambiente Nacional / NFeDistribuicaoDFe). A sincronização roda periodicamente; você também pode forçá-la. Configure dist_ativa pela rota POST /api/v1/empresas/{empresa}/distribuicao ou pela interface de gestão. Consulta e download não implementam débito de crédito; condições comerciais sob consulta.
/api/v1/empresas/{empresa}/distribuicoeslista paginada/api/v1/empresas/{empresa}/distribuicoes/{id}detalhe/api/v1/empresas/{empresa}/distribuicoes/{id}/xmlXML do documento/api/v1/empresas/{empresa}/distribuicoes/sincronizarforçar syncEscopo distribuicao-nfe:consultar. Filtros: status, manifestacao_status, ambiente, chave.
# GET /api/v1/empresas/1/distribuicoes (item)
{
"nsu": 35, "chave": "3526...", "schema": "resNFe",
"emitente": { "cnpj": "99999999000191", "nome": "FORNECEDOR LTDA" },
"valor": "1250.00", "status": "recebida",
"manifestacao": { "tipo": null, "status": null },
"links": { "xml": ".../distribuicoes/12/xml" }
}
O autorizador pode fornecer resumo (resNFe) ou XML completo (procNFe) em NSUs distintos. Disponibilidade conforme documento e cenário; a manifestação não garante entrega imediata do XML.
Manifestação
Manifeste-se sobre um DF-e recebido. Cada manifestação registrada tenta debitar 1 crédito no código (135/136); rejeição não debita e falha no débito após registro é apenas logada; duplicidade reconhecida não gera novo débito. Condições comerciais sob consulta. A empresa pode dar ciência automática ao receber (dist_ciencia_automatica).
/api/v1/empresas/{empresa}/distribuicoes/{id}/manifestar
distribuicao-nfe:manifestar
{ "tipo": "ciencia", "justificativa": null }
# tipo: ciencia | confirmacao | desconhecimento | nao_realizada
# justificativa (15..255) obrigatoria apenas para nao_realizada
# 202 -> { "message": "Manifestacao enfileirada.", "tipo": "ciencia", "status": "pendente" }
Validador de XML
Validação offline de um XML fiscal: bem-formado, schema oficial (XSD) do tipo e assinatura digital. Não é por empresa e não implementa débito de crédito. Condições de uso sob consulta.
/api/v1/documentos/validar
nfe:consultar
{ "tipo": "nfe", "xml": "... " }
# tipo: nfe | nfce | nfeproc | dps | nfse | evento
# 200
{
"tipo": "nfe", "bem_formado": true,
"schema": { "valido": true, "erros": [] },
"assinatura": { "presente": true, "valida": true, "erro": null },
"valido": true
}
Documento sem assinatura (ex.: DPS) retorna assinatura.presente=false sem reprovar.
Automações
Automações por empresa, dependentes de configuração, filas, agendamento e serviço de e-mail:
- E-mail ao destinatário: ao autorizar, envia o XML (e o PDF, para NF-e/NFC-e) ao e-mail informado na nota.
- XML mensal ao contador: todo mês, compacta os XMLs do período e envia ao e-mail do contador.
Créditos
A emissão debita 1 crédito no enfileiramento; erro, rejeição ou denegação acionam estorno. O reenvio de nota rejeitada ou com erro debita novamente. Na emissão inicial de NFC-e, há divergência entre o tipo de recurso do débito e o do estorno; comportamento a confirmar. Sem saldo, a emissão retorna 402, separado de rejeição fiscal. O saldo é compartilhado pelas empresas vinculadas à conta; no cadastro legado fica na empresa. Preços, política comercial de estorno e condições sob consulta. Reenvio: POST /api/v1/nfe/{nota}/reenviar, /nfce/{nota}/reenviar ou /nfse/{nota}/reenviar, com o payload corrigido e scope nfe:emitir.
/api/v1/empresas/{empresa}/creditossaldo + extratoWebhooks
Configure uma URL para receber o status final da nota. O secret é exibido uma única vez; use-o para validar HMAC-SHA256 do corpo bruto. Confirme com HTTP 2xx. O job configura até cinco tentativas no total, incluindo a inicial, com backoff; isso não é SLA de entrega.
/api/v1/empresas/{empresa}/webhook
empresas:gerenciar
# config
{ "url": "https://seu-sistema/webhooks/emitex", "regenerar_secret": true }
# entrega (POST ao seu endpoint)
X-Emitex-Event: nfse.autorizada
X-Emitex-Signature: sha256=
{
"evento": "nfse.autorizada",
"ocorrido_em": "2026-06-13T18:35:00-03:00",
"recurso": { "tipo": "nfse", "id": 29, "status": "autorizada",
"numero": 1, "serie": 1, "chave": "...", "motivo": null }
}
# validacao: HMAC-SHA256(corpo_bruto, secret) == assinatura (sem "sha256=")
# responda 2xx para confirmar; senao, ate 5 tentativas no total com backoff
Auditoria: GET /api/v1/empresas/{empresa}/webhook/entregas.
Erros
| HTTP | Significado |
|---|---|
| 202 | Emissão enfileirada |
| 401 | Não autenticado (token ausente/inválido) |
| 402 | Crédito insuficiente para enfileirar; não é rejeição fiscal |
| 403 | Empresa não pertence à sua conta |
| 422 | Validação ou erro fiscal síncrono; quando presentes, cStat/motivo. Na emissão assíncrona, acompanhe status e campos fiscais na consulta |
| 429 | Limite de requisições; aguarde o intervalo de Retry-After antes de tentar novamente; agrupamento do limite por credencial/IP a confirmar |
| 502 | Falha de comunicação com a SEFAZ |
Limites de requisição
| Grupo | Limite |
|---|---|
| Gestão de empresas | 120 / min |
| Emissão | 60 / min |
| Consulta, listagem & arquivos | 240 / min |
| Cancelamento | 60 / min |
| Validador de XML | 120 / min |
| Distribuição (consulta) | 240 / min |
| Distribuição (sincronizar) | 12 / min |
| Manifestação | 60 / min |
Precisa de credenciais?
Em operação em produção (NF-e, NFC-e e NFS-e Nacional) · acesso assistido; solicitação pelo WhatsApp comercial. O portal do cliente fica em /portal, com permissões por conta e empresa. /admin é a administração interna. Eventos (cancelamento, carta de correção e inutilização) estão em implementação. Cobertura, produção, suporte, SLA e retenção sob consulta. CT-e, CT-e OS, MDF-e, NFCom, DC-e e consultas CEP/CNPJ são futuros.
Entrar no portal