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

Visão geral

A API é REST com JSON. A emissão é assíncrona: o POST responde 202 imediatamente com o id da nota, a transmissão à SEFAZ roda em fila e o status final chega por webhook (ou consulta).

• • 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.
• • Cobrança por créditos: 1 crédito por documento processado. Header x-quota-saldo em cada resposta.

Quick start

Obtenha um token, cadastre a empresa com o certificado e emita.

# 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 (válido por 1h). Envie o token no header Authorization: Bearer <token> em todas as chamadas.

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

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

{
  "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": "producao"          // producao | homologacao
}

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

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

{ "csc": "CODIGO-CSC-DA-SEFAZ", "csc_id": "000001", "serie_nfce": 1 }

Emitir NF-e

{
  "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.

{
  "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).

{
  "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": 1,               // 1=nao retido, 2=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. O PDF existe para NF-e e NFC-e; a NFS-e expõe XML.

# 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" }
}

Status possíveis: pendente, processando, autorizada, rejeitada, denegada, cancelada, erro.

Cancelamento

# 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. Ative em dist_ativa no cadastro da empresa. Consulta e download não consomem crédito.

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 XML completo (procNFe) chega num NSU posterior após a manifestação de ciência/confirmação. Antes disso vem o resumo (resNFe).

Manifestação

Manifeste-se sobre um DF-e recebido. Cada manifestação registrada consome 1 crédito (rejeição não cobra). A empresa pode dar ciência automática ao receber (dist_ciencia_automatica).

{ "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 consome crédito.

{ "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

Configuradas por empresa (no console), sem chamada de API:

• • 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

Cada documento processado consome 1 crédito (mesmo se rejeitado pela SEFAZ). Sem saldo, a emissão retorna 402. O saldo é compartilhado entre as empresas da conta.

Webhooks

Configure uma URL para receber o status final da nota. O secret é exibido uma única vez; use-o para validar a assinatura HMAC.

# 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 retentativas com backoff

Auditoria: GET /api/v1/empresas/{empresa}/webhook/entregas.

Erros

Limites de requisição