Pular para o conteúdo

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_id na 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-saldo nas 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.

POST /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:gerenciarEmpresas, certificado, CSC, webhook, extrato de créditos
nfe:emitirEmitir NF-e, NFC-e e NFS-e
nfe:consultarConsultar status e baixar XML/PDF
nfe:cancelarCancelar notas autorizadas
distribuicao-nfe:consultarConsultar DF-e recebidos e baixar XMLs
distribuicao-nfe:manifestarEnviar manifestação do destinatário

Empresas

A empresa é o emitente. Cadastre-a e depois anexe o certificado A1.

POST /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.

POST /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.

POST /api/v1/empresas/{empresa}/csc empresas:gerenciar
{ "csc": "CODIGO-CSC-DA-SEFAZ", "csc_id": "000001", "serie_nfce": 1 }

Emitir NF-e

POST /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.

POST /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.

POST /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.

GET/api/v1/empresas/{empresa}/nfelista paginada (também /nfce e /nfse)
GET/api/v1/nfe/{nota}status + dados
GET/api/v1/nfe/{nota}/xmlXML autorizado
GET/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

POST /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.

GET/api/v1/empresas/{empresa}/distribuicoeslista paginada
GET/api/v1/empresas/{empresa}/distribuicoes/{id}detalhe
GET/api/v1/empresas/{empresa}/distribuicoes/{id}/xmlXML do documento
POST/api/v1/empresas/{empresa}/distribuicoes/sincronizarforçar sync

Escopo 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).

POST /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.

POST /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.

GET/api/v1/empresas/{empresa}/creditossaldo + extrato

Webhooks

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.

POST /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

HTTPSignificado
202Emissão enfileirada
401Não autenticado (token ausente/inválido)
402Crédito insuficiente para enfileirar; não é rejeição fiscal
403Empresa não pertence à sua conta
422Validação ou erro fiscal síncrono; quando presentes, cStat/motivo. Na emissão assíncrona, acompanhe status e campos fiscais na consulta
429Limite de requisições; aguarde o intervalo de Retry-After antes de tentar novamente; agrupamento do limite por credencial/IP a confirmar
502Falha de comunicação com a SEFAZ

Limites de requisição

GrupoLimite
Gestão de empresas120 / min
Emissão60 / min
Consulta, listagem & arquivos240 / min
Cancelamento60 / min
Validador de XML120 / min
Distribuição (consulta)240 / min
Distribuição (sincronizar)12 / min
Manifestação60 / 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