REST API v2.5
SYSTEM OPERATIONAL
Documentação NFE API
Bem-vindo à documentação da NFE API. API completa para emissão, consulta e cancelamento de Notas Fiscais Eletrônicas (NF-e) no Brasil. Suporta cálculo automático de impostos (ICMS, IPI, PIS/COFINS), geração de XML, autorização SEFAZ e integração com sistemas de gestão.
Campos Importantes da API
Interpretação de Campos Críticos
Esta seção explica os campos mais importantes da NFE API que são essenciais para o correto funcionamento da emissão de notas fiscais.
⚠️ ATENÇÃO: A configuração correta destes campos é
fundamental para a emissão válida de notas fiscais. Consulte sempre a
legislação tributária vigente.
| Campo | Descrição | Valores Possíveis | Importância |
|---|---|---|---|
invoice_type |
Tipo de empresa (pessoa jurídica/física) | juridica, fisica |
Alta - Define o regime tributário |
nature_of_operation |
Natureza da operação (venda, devolução, etc.) | Ex: VENDA, DEVOLUCAO |
Alta - Determina o CFOP |
transaction_type |
Tipo de transação (entrada/saída) | ENTRADA, SAIDA |
Alta - Direciona o fluxo fiscal |
model |
Modelo da nota fiscal | nfe, nfce |
Alta - Modelo do documento |
issuance_type |
Tipo de emissão (normal, contingência) | NORMAL, CONTINGENCIA |
Média - Modo de emissão |
ambiente |
Ambiente de processamento | PRODUCAO, HOMOLOGACAO |
Alta - Define SEFAZ destino |
cliente |
Tipo do cliente/comprador | CONSUMIDOR, CONTRIBUINTE |
Alta - Impacta nos impostos |
products.origem |
Origem do produto (nacional/importado) | 0 a 8 |
Alta - Determina tributação |
products.indicador_total |
Se o produto entra no total da NF | true, false |
Média - Para itens de amostra |
💡 DICA: Para produtos, o campo
origem é
crítico: 0-Nacional, 1-Estrangeira importação direta, 2-Estrangeira
adquirida no mercado interno, etc. Consulte a tabela completa de
origem de mercadorias.
Fluxo do Processo de Emissão
Diagrama completo da emissão de NF-e
O fluxo completo de emissão de nota fiscal eletrônica no Brasil, desde a criação da empresa até a geração dos arquivos finais.
Configuração Inicial
Processamento de Dados
Emissão Fiscal
Resultados Positivos
📊 Fluxo Detalhado: O processo segue uma sequência
lógica: (1) Configuração da empresa → (2) Recebimento dos dados do
pedido → (3) Processamento e emissão da NF-e → (4) Retorno do status →
(5) Geração dos arquivos. O ponto de decisão (Verificação Fiscal)
determina se a emissão foi autorizada pela SEFAZ.
Referência Rápida de Endpoints
Todos os endpoints da NFE API
Visão geral completa de todos os endpoints disponíveis na API. Use esta tabela como referência rápida para navegar na documentação.
URL Base
https://api.tffiscal.com
| Path | Método HTTP | Função |
|---|---|---|
| Gestão de Empresas | ||
/api/company/create
|
POST | Criar empresa |
/api/company/get_detail
|
GET | Consultar empresa |
/api/company/edit
|
POST | Modificar empresa |
/api/company/get_list
|
GET | Listar empresas |
/api/company/v2/create
|
POST | Criar empresa (simplificado) |
/api/company/get_cep_detail
|
GET | Consultar CEP |
/api/company/get_export_invoice_month_files
|
GET | Arquivos exportados mensais |
| Gestão de Categorias/Impostos | ||
/api/category/get_list
|
GET | Listar categorias de impostos |
/api/category/create
|
POST | Criar categoria de impostos |
/api/category/get_detail
|
GET | Consultar detalhes da categoria |
/api/category/edit
|
POST | Editar categoria de impostos |
/api/category/delete
|
POST | Excluir categoria de impostos |
| Gestão de Notas Fiscais | ||
/api/invoice/create
|
POST | Emitir nota fiscal |
/api/invoice/get_list
|
GET | Listar notas fiscais |
/api/invoice/get_detail
|
GET | Consultar detalhes da nota fiscal |
/api/invoice/refresh
|
POST | Atualizar status da nota fiscal |
/api/invoice/cancel
|
POST | Cancelar nota fiscal |
/api/invoice/invalid
|
POST | Invalidar número da nota fiscal |
/api/invoice/return
|
POST | Devolução de nota fiscal |
/api/invoice/get_xml
|
POST | Exportar XML da nota fiscal |
| NFC-e (Cupom Fiscal) | ||
/api/nfce/company/create |
POST | Cadastrar empresa NFC-e |
/api/nfce/company/update |
POST | Atualizar empresa NFC-e |
/api/nfce/company/get |
POST | Consultar empresa NFC-e |
/api/nfce/create |
POST | Emitir NFC-e |
/api/nfce/cancel |
POST | Cancelar NFC-e |
/api/nfce/get_detail |
POST | Consultar NFC-e |
/api/nfce/get_danfe |
POST | Obter DANFE NFC-e |
| NFS-e (Nota de Servico) | ||
/api/nfse/create |
POST | Emitir NFS-e |
/api/nfse/cancel |
POST | Cancelar NFS-e |
/api/nfse/get_danfse |
POST | Obter DANFSE (PDF) |
/api/nfse/get_xml |
POST | Download XML NFS-e |
📋 Notas Importantes:
-
Todos os endpoints requerem autenticação via headers:
sign,timestamp,token - Para criar empresa e listar empresas, use o token do distribuidor (b2b_token)
-
O Content-Type deve ser sempre
application/json;charset=utf-8 -
As respostas seguem o padrão JSON com campos
success,messageedata
200
Sucesso
Requisição processada com sucesso
400
Erro do Cliente
Dados inválidos ou faltantes
500
Erro do Servidor
Erro interno no servidor
NFE API
Nota Fiscal Eletrônica Brasileira (NF-e)
API completa para emissão, consulta e cancelamento de Notas Fiscais Eletrônicas (NF-e) no Brasil. Suporta cálculo automático de impostos (ICMS, IPI, PIS/COFINS), geração de XML, autorização SEFAZ e integração com sistemas de gestão. Atualmente suporta emissão de notas fiscais para produtos em todo território brasileiro.
Base URL (Produção)
https://api.tffiscal.com/v1
Autenticação
Headers: sign, timestamp, token
Requisitos
Certificado Digital A1 válido
Fluxo do Sistema
Dados de Entrada
- Informações do Cliente
- Dados dos Produtos
- Informações Fiscais
- Dados de Transporte
Processamento
- Validação dos dados
- Cálculo de impostos
- Geração do XML
- Autorização SEFAZ
Saída
- XML da nota fiscal
- PDF da nota fiscal
- DANFE (Documento Auxiliar)
- Status de autorização
Endpoints Principais
POST
Cadastrar nova empresa emissora
/api/company/create
Cadastra uma empresa emissora vinculada a uma conta de distribuidor (b2b). Use este endpoint quando os dados da empresa já estão disponíveis. Para extração automática a partir do certificado digital, use /api/company/v2/create.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token do distribuidor (b2b — a conta precisa ter isb2b=true) |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| Identificação | ||
| cnpj * | string | CNPJ da empresa emissora |
| name * | string | Razão social |
| ie * | string | Inscrição Estadual |
| invoice_type * | string | Regime tributário (ex.: "simples_nacional", "normal") |
| unit * | string | Tipo de unidade |
| string | E-mail da empresa | |
| Endereço | ||
| cep * | string | CEP |
| address * | string | Logradouro |
| house_number * | string | Número do endereço |
| town * | string | Bairro |
| city * | string | Município |
| state * | string | UF (sigla do estado) |
| Certificado digital | ||
| cert_file * | string | URL HTTPS do certificado digital A1 (.pfx ou .p12) |
| cert_pwd * | string | Senha do certificado |
| Numeração e configurações | ||
| serie * | int | Série da NF-e |
| number * | int | Número inicial da numeração |
| is_create_category_template | boolean | Cria categorias fiscais padrão automaticamente. Default: true |
* Campo obrigatório.
Exemplo de payload
{
"cnpj": "12345678000199",
"name": "Empresa Exemplo LTDA",
"ie": "123456789",
"invoice_type": "simples_nacional",
"unit": "UN",
"email": "contato@empresa.com",
"cep": "01001000",
"address": "Rua Exemplo",
"house_number": "100",
"town": "Centro",
"city": "São Paulo",
"state": "SP",
"cert_file": "https://exemplo.com/cert.pfx",
"cert_pwd": "senha_do_certificado",
"serie": 1,
"number": 1
}
Resposta
{
"success": true,
"data": {
"company_id": "comp_789012",
"token": "eyJhbGciOiJIUzI1NiIs..."
}
}
POST
Cadastrar empresa com auto-preenchimento via certificado
/api/company/v2/create
Versão simplificada de /api/company/create: a API valida o certificado digital e extrai automaticamente razão social, IE, endereço e demais dados via consulta interna. Apenas cnpj, cert_file e cert_pwd são obrigatórios.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token do distribuidor (b2b — a conta precisa ter isb2b=true) |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj * | string | CNPJ da empresa emissora |
| cert_file * | string | URL HTTPS do certificado digital A1 (.pfx ou .p12) |
| cert_pwd * | string | Senha do certificado |
| is_create_category_template | boolean | Cria categorias fiscais padrão automaticamente. Default: true |
* Campo obrigatório.
Exemplo de payload
{
"cnpj": "12345678000199",
"cert_file": "https://exemplo.com/cert.pfx",
"cert_pwd": "senha_do_certificado"
}
Resposta
{
"success": true,
"data": {
"company_id": "comp_789012",
"token": "eyJhbGciOiJIUzI1NiIs..."
}
}
POST
Editar dados da empresa
/api/company/edit
Atualiza dados da empresa emissora. Envie apenas os campos que deseja alterar — todos exceto company_id são opcionais. CNPJ é imutável: tentar enviá-lo retorna erro. Ao atualizar cep, o sistema resolve automaticamente stateCode e ibge. Quando cert_file e cert_pwd vêm juntos, o certificado é validado antes de salvar.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| company_id * | string | ID da empresa a editar |
| name | string | Razão social |
| invoice_type | string | Regime tributário |
| ie | string | Inscrição Estadual |
| unit | string | Tipo de unidade |
| string | ||
| cep | string | CEP (atualiza stateCode e ibge automaticamente) |
| address | string | Logradouro |
| house_number | string | Número |
| town | string | Bairro |
| city | string | Município |
| state | string | UF |
| cert_file | string | URL HTTPS do novo certificado (.pfx ou .p12). Se enviado junto com cert_pwd, é validado antes de salvar |
| cert_pwd | string | Nova senha do certificado |
| serie | int | Nova série da NF-e |
| number | int | Novo número inicial |
* Campo obrigatório. Enviar cnpj retorna erro.
Exemplo de payload
{
"company_id": "comp_789012",
"name": "Nova Razão Social LTDA",
"email": "novo@empresa.com",
"cep": "01310100"
}
Resposta
{
"success": true
}
GET
Listar empresas do distribuidor
/api/company/get_list
Lista, com paginação, as empresas emissoras vinculadas à conta de distribuidor (b2b). Parâmetros via query string.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token do distribuidor (b2b — a conta precisa ter isb2b=true) |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| page * | int | Número da página (≥ 1) |
| page_size * | int | Tamanho da página (1–20) |
* Campo obrigatório.
Exemplo de chamada
GET /api/company/get_list?page=1&page_size=10
Resposta
{
"success": true,
"data": {
"companys": [
{
"company_id": "comp_789012",
"invoice_type": "simples_nacional",
"token": "eyJhbGciOiJIUzI1NiIs...",
"cnpj": "12345678000199",
"name": "Empresa Exemplo LTDA",
"ie": "123456789",
"unit": "UN",
"email": "contato@empresa.com",
"cep": "01001000",
"address": "Rua Exemplo",
"house_number": "100",
"town": "Centro",
"city": "São Paulo",
"state": "SP",
"cert_file": "https://exemplo.com/cert.pfx",
"cert_pwd": "***",
"serie": 1,
"number": 142
}
],
"page": 1,
"total": 8,
"total_pages": 1
}
}
GET
Detalhes da empresa autenticada
/api/company/get_detail
Retorna os dados completos da empresa identificada pelo header token, incluindo a lista de categorias fiscais cadastradas. Não aceita body nem query string.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Exemplo de chamada
GET /api/company/get_detail
Resposta
{
"success": true,
"data": {
"company_id": "comp_789012",
"name": "Empresa Exemplo LTDA",
"token": "eyJhbGciOiJIUzI1NiIs...",
"invoice_type": "simples_nacional",
"cnpj": "12345678000199",
"ie": "123456789",
"unit": "UN",
"email": "contato@empresa.com",
"cep": "01001000",
"address": "Rua Exemplo",
"house_number": "100",
"town": "Centro",
"city": "São Paulo",
"state": "SP",
"cert_file": "https://exemplo.com/cert.pfx",
"cert_pwd": "***",
"serie": 1,
"number": 142,
"categorys": [
{
"category_id": "cat_001",
"descricao": "Venda de mercadoria",
"disable_difal": false,
"desconta_icms_pis_cofins": false
}
]
}
}
GET
Consultar endereço por CEP
/api/company/get_cep_detail
Resolve um CEP brasileiro retornando UF, código IBGE do município e dados do endereço. Útil para preencher endereços de empresas e clientes. Requer conta de distribuidor (b2b).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token do distribuidor (b2b — a conta precisa ter isb2b=true) |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| cep * | string | CEP brasileiro (8 dígitos, com ou sem traço) |
* Campo obrigatório.
Exemplo de chamada
GET /api/company/get_cep_detail?cep=01001000
Resposta
{
"success": true,
"data": {
"cep": "01001-000",
"uf": "SP",
"ibge": 3550308,
"logradouro": "Praça da Sé",
"bairro": "Sé",
"localidade": "São Paulo",
"ddd": "11"
}
}
GET
Listar arquivos de exportação mensal já gerados
/api/company/get_export_invoice_month_files
Retorna a lista de arquivos de exportação mensal que já foram gerados para a empresa no ano corrente (timezone America/Sao_Paulo). Cada mês pode ter até 4 arquivos: 1 planilha Excel (apenas status Success) + 3 XMLs (por status Success, Canceled e Voided). Apenas arquivos efetivamente exportados aparecem no retorno — use /api/invoice/get_xml para gerar novos.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Exemplo de chamada
GET /api/company/get_export_invoice_month_files
Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| files[] | array | Lista de arquivos disponíveis |
| files[].url | string | URL do arquivo no OSS |
| files[].year | int | Ano do período |
| files[].month | string | Mês (1–12) |
| files[].type | string | Tipo do arquivo: "xlsx" ou "xml" |
| files[].status | string | Status das notas no arquivo: "Success", "Canceled" ou "Voided" |
| files[].create | datetime | Quando o arquivo foi gerado |
Exemplo de resposta
{
"success": true,
"data": {
"files": [
{
"url": "https://oss.example.com/.../2024_01_success.xlsx",
"year": 2024,
"month": "1",
"type": "xlsx",
"status": "Success",
"create": "2024-02-01T03:15:00Z"
},
{
"url": "https://oss.example.com/.../2024_01_success.zip",
"year": 2024,
"month": "1",
"type": "xml",
"status": "Success",
"create": "2024-02-01T03:15:30Z"
}
]
}
}
GET
Listar categorias de produtos
/api/category/get_list
Retorna todas as categorias disponíveis para classificação fiscal.
POST
Emitir nova nota fiscal
/api/invoice/create
Emite uma NF-e (modelo 55). A empresa emissora é identificada pelo header token; não envie company_id no body.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body — campos top-level
| Campo | Tipo | Descrição |
|---|---|---|
| Identificação e operação | ||
| id | string | ID único do cliente para idempotência (compõe a chave de deduplicação) |
| nature_of_operation * | string | Natureza da operação (ex: "Venda de mercadoria") |
| transaction_type * | string | Tipo: "0"=entrada, "1"=saída, "2"=importação, "3"=exportação |
| model * | string | Modelo do documento: "55"=NF-e |
| issuance_type * | string | Tipo de emissão ("1"=normal, "9"=contingência, etc.) |
| ambiente * | string | "1"=produção, "2"=homologação |
| finalidade | string | Finalidade: "1"=normal, "2"=complementar, "3"=ajuste, "4"=devolução |
| ref_nfe_chave | string | Chave de 44 dígitos da NF-e referenciada (complementar/ajuste/devolução) |
| is_reopen | boolean | Reabrir/sobrescrever uma NF-e já emitida anteriormente |
| dh_sai_ent | string | Data/hora de saída ou entrada (ISO 8601). Default: timestamp atual |
| Valores e descontos | ||
| total_discount_amount | decimal | Desconto total da nota |
| troco | decimal | Troco (uso típico em NFC-e) |
| seguro | decimal | Valor de seguro (rateado entre os produtos no XML vSeg) |
| outras_despesas | decimal | Outras despesas (rateadas entre os produtos no XML vOutro) |
| Indicadores e informações adicionais | ||
| ind_final | string | Consumidor final: "0"=B2B, "1"=B2C |
| ind_pres | string | Indicador de presença: "1"=presencial, "2"=internet, "3"=teleatendimento, etc. |
| informacoes_complementares | string | Informações complementares (escrito em infAdic.infCpl) |
| informacoes_fisco | string | Informações para o fisco (escrito em infAdic.infAdFisco) |
Body — cliente (objeto, obrigatório)
Para operações nacionais (
transaction_type 0 ou 1): cpf ou cnpj, name, endereco, bairro (mín. 2 caracteres), city, uf e cep são obrigatórios. Para importação/exportação (transaction_type 2 ou 3): apenas name é obrigatório.
| Campo | Tipo | Descrição |
|---|---|---|
| cpf | string | CPF do cliente (alternativa a cnpj) |
| cnpj | string | CNPJ do cliente (alternativa a cpf) |
| ie | string | Inscrição Estadual |
| name * | string | Razão social / nome do cliente |
| endereco | string | Logradouro |
| complemento | string | Complemento |
| numero | string | Número do endereço |
| bairro | string | Bairro (mínimo 2 caracteres em operações nacionais) |
| city | string | Município |
| uf | string | UF (é substituída pelo UF resolvido a partir do CEP) |
| cep | string | CEP (valida o UF e o município) |
| telefone | string | Telefone |
| string | ||
| id_estrangeiro | string | Identificação estrangeira (uso em importação/exportação) |
| c_pais | int | Código BACEN do país. Default: 1058 (Brasil) |
| x_pais | string | Nome do país. Default: "BRASIL" |
Body — products[] (array, mínimo 1 item)
Cada produto exige tributação: ou
category_id (referência a uma categoria fiscal pré-cadastrada), ou o objeto impostos/tax_info com a configuração inline.
| Campo | Tipo | Descrição |
|---|---|---|
| codigo | string | Código interno do produto |
| name * | string | Descrição do produto (caracteres CJK são removidos) |
| ncm * | string | NCM com 8 dígitos |
| cest | string | Código CEST (obrigatório quando há ICMS-ST) |
| gtin | string | GTIN / código de barras |
| gtin_tributavel | string | GTIN da unidade tributável |
| count * | decimal | Quantidade |
| unit * | string | Unidade comercial (ex: "UN", "KG", "MT") |
| unit_price * | decimal | Valor unitário |
| total_price * | decimal | Valor total do item |
| discount_price | decimal | Desconto aplicado ao item |
| origem * | int | Origem da mercadoria (0=Nacional, 1=Estrangeira—Importação direta, etc.) |
| indicador_total * | int | Compõe o total da NF-e: 0=não, 1=sim |
| category_id | string | ID da categoria fiscal pré-cadastrada (obrigatório se não enviar impostos/tax_info) |
| impostos | object | Configuração inline de tributos (alternativa a category_id). Veja estrutura abaixo |
| tax_info | object | Alias de impostos (mesma estrutura) |
| disable_difal | boolean | Desativa o cálculo de DIFAL para este item |
| desconta_icms_pis_cofins | boolean | Desconta o ICMS da base de PIS/COFINS apenas para este item (sobrepõe a categoria) |
| ii | object | Imposto de Importação — obrigatório para CFOP 3.xxx. Veja estrutura abaixo |
| import_declarations | array | Declarações de Importação (DI) — obrigatório quando transaction_type="2". Veja estrutura abaixo |
| nItemPed | int | Item do Pedido de Compra (I61). Número sequencial do item dentro do pedido referenciado em xPed (vem do id da raiz). Valores válidos: 1–999999. Default: omitido. |
Body — products[].impostos / products[].tax_info
| Campo | Tipo | Descrição |
|---|---|---|
| industria | string | Indústria/alíquota base (alias: aliquota) |
| icms | ||
| icms.codigo_cfop | string | CFOP |
| icms.situacao_tributaria | string | CST/CSOSN do ICMS |
| icms.industria | string | Indústria ICMS |
| icms.tipo_pessoa | string | Tipo de pessoa (PF/PJ) |
| icms.codigo_beneficio_fiscal | string | cBenef (código de benefício fiscal) |
| ipi | ||
| ipi.codigo_enquadramento | string | Código de enquadramento legal do IPI |
| ipi.situacao_tributaria | string | CST IPI |
| ipi.aliquota | string | Alíquota IPI |
| ipi.tipo_pessoa | string | Tipo de pessoa |
| pis | ||
| pis.situacao_tributaria | string | CST PIS |
| pis.aliquota | string | Alíquota PIS |
| pis.tipo_pessoa | string | Tipo de pessoa |
| cofins | ||
| cofins.situacao_tributaria | string | CST COFINS |
| cofins.aliquota | string | Alíquota COFINS |
| cofins.tipo_pessoa | string | Tipo de pessoa |
| is (Imposto Seletivo) | ||
| is.cenario | string | Cenário IS |
| is.situacao_tributaria | string | CST IS |
| is.aliquota | string | Alíquota IS |
| is.tipo_pessoa | string | Tipo de pessoa |
| ibs_cbs (Reforma Tributária) | ||
| ibs_cbs.situacao_tributaria | string | CST IBS/CBS |
| ibs_cbs.tipo_pessoa | string | Tipo de pessoa |
| ibs_cbs.classificacao_tributaria | string | Classificação tributária IBS/CBS |
| difal | ||
| difal.disable_difal | boolean | Desativa DIFAL para o item (alternativa ao disable_difal direto no produto) |
Body — products[].ii (Imposto de Importação)
| Campo | Tipo | Descrição |
|---|---|---|
| vBC | decimal | Base de cálculo do II |
| vDespAdu | decimal | Despesas aduaneiras |
| vII | decimal | Valor do II |
| vIOF | decimal | Valor do IOF |
Body — products[].import_declarations[]
| Campo | Tipo | Descrição |
|---|---|---|
| nDI | string | Número da DI |
| dDI | string (date) | Data da DI |
| xLocDesemb | string | Local do desembaraço |
| UFDesemb | string | UF do desembaraço |
| dDesemb | string (date) | Data do desembaraço |
| cExportador | string | Código do exportador |
| tpViaTransp | int | Via de transporte internacional |
| tpIntermedio | int | Tipo de intermediação |
| vAFRMM | decimal | Valor do AFRMM |
| additions | array | Adições da DI (campos: nAdicao, nSeqAdic, cFabricante, vDescDI, nDraw) |
Body — shipping_address / delivery_address (objetos, opcionais)
shipping_address é o local de retirada (origem física da mercadoria, se diferente do emitente). delivery_address é o local de entrega (destino físico, se diferente do cliente). Quando presentes, exigem: cpf ou cnpj, name, endereco, bairro (mín. 2 caracteres), city, uf e cep. Ambos objetos têm a mesma estrutura.
| Campo | Tipo | Descrição |
|---|---|---|
| cpf | string | CPF (alternativa a cnpj) |
| cnpj | string | CNPJ (alternativa a cpf) |
| ie | string | Inscrição Estadual |
| name * | string | Razão social / nome |
| endereco * | string | Logradouro |
| complemento | string | Complemento |
| number | string | Número (atenção: o campo é number, não numero) |
| bairro * | string | Bairro |
| city * | string | Município |
| uf * | string | UF |
| cep * | string | CEP |
| telefone | string | Telefone |
| string |
Body — transportation (objeto, opcional)
Se
transportation for omitido, o sistema assume transport_mode="9" (sem frete).
| Campo | Tipo | Descrição |
|---|---|---|
| transport_mode | string | Modalidade do frete: "0"=por conta do emitente, "1"=por conta do destinatário, "2"=por conta de terceiros, "3"=transporte próprio do remetente, "4"=transporte próprio do destinatário, "9"=sem frete |
| freight_amount | decimal | Valor total do frete |
| carrier_info — transportador | ||
| carrier_info.cpf | string | CPF do transportador (alternativa a cnpj) |
| carrier_info.cnpj | string | CNPJ do transportador (alternativa a cpf) |
| carrier_info.ie | string | Inscrição Estadual |
| carrier_info.name | string | Razão social |
| carrier_info.endereco | string | Logradouro |
| carrier_info.city | string | Município |
| carrier_info.uf | string | UF |
| carrier_info.cep | string | CEP |
| vehicle_info — veículo | ||
| vehicle_info.plate | string | Placa |
| vehicle_info.uf | string | UF da placa |
| vehicle_info.rntc | string | RNTC (Registro Nacional de Transportadores de Carga) |
| trailer_info — reboque (mesma estrutura de vehicle_info) | ||
| trailer_info.plate | string | Placa do reboque |
| trailer_info.uf | string | UF |
| trailer_info.rntc | string | RNTC |
| packages[] — volumes | ||
| packages[].qty | int | Quantidade |
| packages[].gross_weight | decimal | Peso bruto |
| packages[].net_weight | decimal | Peso líquido |
| packages[].packaging_type | string | Espécie |
| packages[].number | string | Numeração |
| packages[].mark | string | Marca |
| packages[].seals | array<string> | Lacres |
| transport_tax_retention_info — retenção de ICMS sobre frete | ||
| transport_tax_retention_info.freight_service_amount | decimal | Valor do serviço de transporte |
| transport_tax_retention_info.tax_base | decimal | Base de cálculo da retenção |
| transport_tax_retention_info.tax_rate | decimal | Alíquota da retenção |
| transport_tax_retention_info.cfop | string | CFOP |
| transport_tax_retention_info.cep | string | CEP |
Body — pag_info[] (array, opcional)
Se omitido, o sistema assume
[{ "payment_method": "01", "payment_indicator": "0" }] (dinheiro, à vista).
| Campo | Tipo | Descrição |
|---|---|---|
| payment_method * | string | Forma de pagamento: "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, "17"=PIX, "90"=sem pagamento, "99"=outros |
| payment_indicator * | string | Indicador: "0"=à vista, "1"=a prazo |
| payment_value | decimal | Valor pago |
| card_info — dados do cartão (para payment_method 03/04) | ||
| card_info.integration_type * | string | Tipo de integração da maquininha (obrigatório se card_info presente) |
| card_info.brand_code * | string | Bandeira do cartão (obrigatório se card_info presente) |
| card_info.acquirer_cnpj | string | CNPJ da adquirente |
| card_info.authorization_code | string | Código de autorização |
* Campo obrigatório.
Exemplo simplificado
{
"nature_of_operation": "Venda de mercadoria",
"transaction_type": "1",
"model": "55",
"issuance_type": "1",
"ambiente": "2",
"cliente": {
"cpf": "12345678909",
"name": "Cliente Exemplo",
"endereco": "Rua Exemplo",
"numero": "100",
"bairro": "Centro",
"city": "São Paulo",
"uf": "SP",
"cep": "01001000",
"email": "cliente@exemplo.com"
},
"products": [
{
"codigo": "PROD001",
"name": "Produto Exemplo",
"ncm": "85176277",
"count": 2,
"unit": "UN",
"unit_price": 150.00,
"total_price": 300.00,
"category_id": "SEU_CATEGORY_ID",
"origem": 0,
"indicador_total": 1
}
],
"pag_info": [
{ "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
]
}
Exemplo completo (todos os campos)
{
"id": "PEDIDO-2026-0001",
"nature_of_operation": "Venda de mercadoria",
"transaction_type": "1",
"model": "55",
"issuance_type": "1",
"ambiente": "2",
"finalidade": "1",
"ref_nfe_chave": "",
"is_reopen": false,
"dh_sai_ent": "",
"total_discount_amount": 0.00,
"troco": 0.00,
"seguro": 0.00,
"outras_despesas": 0.00,
"ind_final": "1",
"ind_pres": "9",
"informacoes_complementares": "Entrega via transportadora",
"informacoes_fisco": "ICMS recolhido conforme legislação",
"cliente": {
"cpf": "",
"cnpj": "12345678000199",
"ie": "123456789",
"name": "Cliente Exemplo LTDA",
"endereco": "Av. Paulista",
"numero": "1000",
"complemento": "Sala 200",
"bairro": "Bela Vista",
"city": "São Paulo",
"uf": "SP",
"cep": "01310100",
"telefone": "11999998888",
"email": "cliente@exemplo.com",
"id_estrangeiro": "",
"c_pais": 1058,
"x_pais": "BRASIL"
},
"shipping_address": {
"cnpj": "98765432000111",
"name": "Depósito Origem LTDA",
"ie": "987654321",
"endereco": "Rua do Depósito",
"number": "50",
"complemento": "Galpão 3",
"bairro": "Industrial",
"city": "Guarulhos",
"uf": "SP",
"cep": "07000000",
"telefone": "11988887777",
"email": "deposito@exemplo.com"
},
"delivery_address": {
"cnpj": "12345678000199",
"name": "Cliente Exemplo LTDA",
"ie": "123456789",
"endereco": "Rua de Entrega",
"number": "25",
"complemento": "Loja 2",
"bairro": "Centro",
"city": "Campinas",
"uf": "SP",
"cep": "13010000",
"telefone": "11977776666",
"email": "entrega@exemplo.com"
},
"products": [
{
"codigo": "PROD001",
"name": "Notebook Dell",
"ncm": "84713012",
"cest": "",
"gtin": "7891234567890",
"gtin_tributavel": "7891234567890",
"count": 2,
"unit": "UN",
"unit_price": 3500.00,
"total_price": 7000.00,
"discount_price": 0.00,
"origem": 0,
"indicador_total": 1,
"category_id": "TF00001",
"nItemPed": 1
},
{
"codigo": "PROD002",
"name": "Mouse sem fio",
"ncm": "84716053",
"count": 5,
"unit": "UN",
"unit_price": 80.00,
"total_price": 400.00,
"origem": 0,
"indicador_total": 1,
"nItemPed": 2,
"impostos": {
"icms": {
"codigo_cfop": "5102",
"situacao_tributaria": "00",
"industria": "",
"tipo_pessoa": "juridica",
"codigo_beneficio_fiscal": ""
},
"ipi": {
"codigo_enquadramento": "999",
"situacao_tributaria": "99",
"aliquota": "0.00",
"tipo_pessoa": "juridica"
},
"pis": {
"situacao_tributaria": "01",
"aliquota": "0.65",
"tipo_pessoa": "juridica"
},
"cofins": {
"situacao_tributaria": "01",
"aliquota": "3.00",
"tipo_pessoa": "juridica"
},
"ibs_cbs": {
"situacao_tributaria": "000",
"tipo_pessoa": "juridica",
"classificacao_tributaria": "000001"
}
}
}
],
"transportation": {
"transport_mode": "1",
"freight_amount": 150.00,
"carrier_info": {
"cnpj": "11222333000144",
"ie": "112223334",
"name": "Transportadora Exemplo LTDA",
"endereco": "Rod. BR-101, km 50",
"city": "Santos",
"uf": "SP",
"cep": "11000000"
},
"vehicle_info": {
"plate": "ABC1D23",
"uf": "SP",
"rntc": "12345"
},
"trailer_info": {
"plate": "DEF4G56",
"uf": "SP",
"rntc": "67890"
},
"packages": [
{
"qty": 3,
"gross_weight": 12.500,
"net_weight": 11.000,
"packaging_type": "CAIXA",
"number": "001-003",
"mark": "FRAGIL",
"seals": ["LACRE001", "LACRE002"]
}
],
"transport_tax_retention_info": {
"freight_service_amount": 150.00,
"tax_base": 150.00,
"tax_rate": 12.00,
"cfop": "5932",
"cep": "11000000"
}
},
"pag_info": [
{
"payment_indicator": "1",
"payment_method": "03",
"payment_value": 7400.00,
"card_info": {
"integration_type": "1",
"brand_code": "01",
"acquirer_cnpj": "01234567000189",
"authorization_code": "AUTH987654"
}
}
]
}
GET
Listar NF-e (com paginação)
/api/invoice/get_list
Lista as NF-e da empresa com paginação. Parâmetros passados via query string (não no body). O filtro de tempo é opcional, mas se enviado exige ambos start_create_time e end_create_time.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| page * | int | Número da página (≥ 1) |
| page_size * | int | Tamanho da página (1–50) |
| start_create_time | long | Unix timestamp em milissegundos — início (exige end_create_time) |
| end_create_time | long | Unix timestamp em milissegundos — fim |
| status | string | Filtrar por status (valores: "Authorized", "Canceled", "Processing", "Rejected", etc.) |
* Campo obrigatório.
Exemplo de chamada
GET /api/invoice/get_list?page=1&page_size=20&status=Authorized
Resposta
{
"success": true,
"data": {
"list": [
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
"chave": "35210112345678901234567890123456789012345678",
"status": "Authorized",
"create": "2024-01-10T10:30:00Z",
"issue_time": "2024-01-10T10:31:00Z"
}
],
"page": 1,
"total": 142,
"total_pages": 8
}
}
GET
Consultar detalhes da NF-e
/api/invoice/get_detail
Retorna os detalhes de uma NF-e específica pelo UUID. Inclui URLs do XML, do DANFE (completo, simplificado e de etiqueta) e metadados.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| uuid * | string | UUID da NF-e |
* Campo obrigatório.
Exemplo de chamada
GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
Resposta
{
"success": true,
"data": {
"id": "pedido-2024-0001",
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
"chave": "35210112345678901234567890123456789012345678",
"serie": 1,
"number": 100,
"status": "Authorized",
"total_price": 300.00,
"xml": "https://oss.example.com/.../chave.xml",
"danfe": "https://oss.example.com/.../chave.pdf",
"danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
"danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
"create": "2024-01-10T10:30:00Z",
"issue_time": "2024-01-10T10:31:00Z"
}
}
POST
Atualizar status da nota fiscal
/api/invoice/refresh
Consulta o status atual da NF-e na SEFAZ e atualiza o registro local. Útil quando a emissão ficou em processamento ou contingência.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid * | string | UUID da NF-e a consultar |
* Campo obrigatório.
Exemplo de payload
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
}
POST
Cancelar nota fiscal
/api/invoice/cancel
Cancela uma NF-e já autorizada. A justificativa enviada à SEFAZ é fixa: "Erro no preenchimento da nota fiscal." — não é configurável pelo payload.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid * | string | UUID da NF-e a cancelar (identificador interno retornado por /api/invoice/create) |
* Campo obrigatório.
Exemplo de payload
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
}
POST
Inutilizar faixa de numeração
/api/invoice/invalid
Inutiliza uma faixa contínua de numeração que não chegou a ser emitida (não confundir com cancelamento — cancelamento é para nota já autorizada). Operação registrada na SEFAZ e irreversível.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| modelo * | string | Modelo do documento: "55"=NF-e, "65"=NFC-e. (Atenção: o campo aqui é modelo, não model) |
| ambiente * | string | "1"=produção, "2"=homologação |
| serie * | int | Série da numeração a inutilizar |
| start_number * | int | Número inicial da faixa |
| end_number * | int | Número final da faixa |
| motivo * | string | Justificativa da inutilização (mín. 15 caracteres por exigência SEFAZ) |
* Campo obrigatório.
Exemplo de payload
{
"modelo": "55",
"ambiente": "2",
"serie": 1,
"start_number": 100,
"end_number": 105,
"motivo": "Falha no sistema durante a emissao do lote"
}
POST
Obter DANFE (PDF) da NF-e
/api/invoice/get_danfe
Retorna três URLs da DANFE de uma NF-e: a DANFE completa (PDF), a DANFE simplificada em PDF (formato cupom) e a DANFE simplificada em PNG (etiqueta/imagem). Os PDFs são gerados sob demanda a partir do XML autorizado e cacheados no OSS. Em chamadas subsequentes, se o status da nota não mudou, retorna o cache existente; se o status mudou (ex.: nota foi cancelada), os PDFs são regerados.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid ⚠ | string | UUID interno da NF-e (retornado por /api/invoice/create) |
| chave ⚠ | string | Chave de acesso da NF-e (44 dígitos) |
⚠ uuid ou chave, um dos dois é obrigatório.
Exemplo de payload
{
"uuid": "abc123-def456-..."
}
Resposta
{
"success": true,
"data": {
"danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
"danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
"danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| danfe | string | URL do PDF da DANFE completa (formato A4) |
| danfe_simples | string | URL do PDF da DANFE simplificada (formato cupom) |
| danfe_simples_png | string | URL do PNG da DANFE simplificada (etiqueta/imagem) |
Respostas de erro
| Mensagem | Causa |
|---|---|
| uuid/chave不能为空 | Nem uuid nem chave foram enviados |
| 发票不存在 | Nota não encontrada para o usuário do token, ou XML autorizado ausente |
| 发票详情不存在 | Detalhe da nota (com protocolo) não encontrado |
| 获取PDF失败:<motivo> | Falha ao gerar o PDF a partir do XML |
POST
Exportar XML/Excel em lote (assíncrono)
/api/invoice/get_xml
Inicia uma tarefa assíncrona de exportação em lote de notas fiscais do usuário, filtrando por período e status. Pode gerar uma planilha Excel (somente metadados) ou um pacote ZIP com os XMLs. A primeira chamada cria a tarefa e retorna status: "Processing"; chamadas seguintes com os mesmos parâmetros retornam o progresso até status: "Success", quando o campo url contém o link de download.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| type * | string | Formato de saída: "excel" (planilha de metadados) ou qualquer outro valor (ex.: "xml") para ZIP com XMLs |
| status | string | Filtra por status da nota (ex.: "Success", "Canceled", "Voided"). Para type=excel, é tratado em minúsculas |
| month | int | Mês (1–12). Se informado, sobrepõe start_create_time/end_create_time; usa fuso America/Sao_Paulo e ano corrente (ou anterior se o mês for futuro) |
| start_create_time | long | Início do período (Unix timestamp em milissegundos) |
| end_create_time | long | Fim do período (Unix timestamp em milissegundos) |
* Campo obrigatório.
Exemplo de payload
{
"type": "xml",
"status": "Success",
"month": 5
}
Resposta — processando
{
"success": true,
"data": {
"status": "Processing",
"progress_count": 120,
"total_count": 543,
"url": ""
}
}
Resposta — concluído
{
"success": true,
"data": {
"status": "Success",
"progress_count": 543,
"total_count": 543,
"url": "https://storage.../exports/uid/.zip"
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| status | string | "Processing" enquanto a tarefa roda, "Success" quando o arquivo está pronto |
| progress_count | int | Quantidade de notas já processadas |
| total_count | int | Total de notas a processar |
| url | string | URL de download do arquivo final (vazio enquanto status = Processing) |
Idempotência: a tarefa é deduplicada por hash dos parâmetros (
uid + token + período + status + type). Chamadas repetidas com os mesmos parâmetros retornam o progresso da mesma tarefa, sem disparar novas execuções.
Respostas de erro
| Mensagem | Causa |
|---|---|
| 发票类型字段不能为空 | type ausente |
POST
Consultar status da NF-e/NFC-e na SEFAZ
/api/invoice/consultar_status
Consulta o status atual de uma NF-e ou NFC-e diretamente na SEFAZ pela chave de acesso (44 dígitos), via serviço NfeConsultaProtocolo4. Funciona tanto para notas próprias (emitidas pela empresa do token) quanto para notas de terceiros (ex.: capturadas via DistDFe). O modelo (NF-e/NFC-e) é detectado automaticamente pelas posições 20-21 da chave.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa (cujo certificado será usado na consulta) |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| chave * | string | Chave de acesso (44 dígitos numéricos). UF do emitente é extraída das posições 0-1; modelo das posições 20-21 (55=NF-e, 65=NFC-e). |
* Campo obrigatório.
Exemplo de payload
{
"chave": "35260512345678000199550010000000011000000018"
}
Resposta
{
"success": true,
"message": "Sucesso",
"data": {
"chave": "35260512345678000199550010000000011000000018",
"status": "autorizada",
"cstat": 100,
"motivo": "Autorizado o uso da NF-e"
}
}
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| chave | string | Chave de acesso consultada |
| status | string | Status normalizado (ver tabela abaixo) |
| cstat | int | Código cStat bruto da SEFAZ |
| motivo | string | Mensagem xMotivo bruta da SEFAZ |
Mapeamento de status
status | cStat da SEFAZ | Significado |
|---|---|---|
| autorizada | 100, 150 | NF-e autorizada para uso |
| cancelada | 101, 151 | Cancelada (também retornado se houver evento de cancelamento vinculado, mesmo com cStat=100) |
| denegada | 110, 301, 302 | Uso denegado pela SEFAZ |
| inutilizada | 102 | Número inutilizado (faixa de numeração) |
| nao_encontrada | 217 | NF-e não consta na base da SEFAZ |
| desconhecido | outros | cStat não mapeado — consulte cstat e motivo brutos |
Respostas de erro
| Mensagem | Causa |
|---|---|
| chave inválida: deve ter 44 dígitos | Chave ausente, com tamanho diferente de 44 ou contendo caracteres não numéricos |
| empresa não possui certificado configurado | A empresa do token não tem cert_file cadastrado |
| SEFAZ retornou resposta vazia | A SEFAZ não devolveu retorno (timeout, fora do ar) |
| erro ao consultar SEFAZ: <detalhe> | Exceção ao chamar o serviço (XML inválido, timeout, certificado expirado, etc.) |
POST
Criar categoria fiscal
/api/category/create
Cria uma nova categoria fiscal (template de impostos) vinculada à empresa autenticada. Cada categoria agrega cenários de ICMS, IPI, PIS, COFINS, e opcionalmente IBS/CBS e IS. Para editar uma existente, use /api/category/edit.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body — top-level
| Campo | Tipo | Descrição |
|---|---|---|
| descricao * | string | Descrição da categoria fiscal |
| category_id | string | ID customizado. Quando omitido, é auto-gerado no formato "TF" + número incremental |
| disable_difal | boolean | Desabilita o cálculo de DIFAL para esta categoria. Default: false |
| desconta_icms_pis_cofins | boolean | Desconta o ICMS da base de cálculo de PIS/COFINS (base = vProd − vICMS). Default: false |
| icms[] * | array | Cenários de ICMS (estrutura abaixo) |
| ipi[] * | array | Cenários de IPI (estrutura abaixo) |
| pis[] * | array | Cenários de PIS (estrutura abaixo) |
| cofins[] * | array | Cenários de COFINS (estrutura abaixo) |
| ibs_cbs[] | array | Cenários de IBS/CBS — reforma tributária (estrutura abaixo) |
| is[] | array | Cenários de IS — Imposto Seletivo (estrutura abaixo) |
Body — icms[]
| Campo | Tipo | Descrição |
|---|---|---|
| tipo_tributacao * | string | Tipo de tributação ICMS |
| cenario * | string | Cenário (ex.: "saida_dentro_estado", "saida_fora_estado", "padrao") |
| tipo_pessoa * | string | "fisica" ou "juridica" |
| codigo_cfop * | string | CFOP |
| situacao_tributaria * | string | CST/CSOSN do ICMS |
| nao_contribuinte | boolean | Cliente não-contribuinte |
| aliquota_importacao | string | Alíquota de importação |
| aliquota_credito | decimal | Alíquota de crédito (% para Simples Nacional) |
| aliquota_diferimento | decimal | Percentual de diferimento |
| aliquota_diferimentoFcp | string | Diferimento do FCP (atenção: campo usa camelCase diferimentoFcp) |
| aliquota_reducao | decimal | Percentual de redução de base ICMS |
| aliquota_reducaoSt | decimal | Percentual de redução de base ICMS-ST (atenção: reducaoSt camelCase) |
| motivo_desoneracao | string | Código do motivo da desoneração ICMS |
| motivo_desoneracaoSt | string | Código do motivo da desoneração ICMS-ST (atenção: camelCase) |
| Alíquotas por estado — opcional | ||
| aliquota_mva[] | array | MVA por UF — itens: { estado, aliquota } |
| aliquota_icms[] | array | Alíquota ICMS por UF — itens: { estado, aliquota } |
| aliquota_icms_st[] | array | Alíquota ICMS-ST por UF — itens: { estado, aliquota } |
| aliquota_fcp[] | array | Alíquota FCP por UF — itens: { estado, aliquota } |
| aliquota_fcp_st[] | array | Alíquota FCP-ST por UF — itens: { estado, aliquota } |
| beneficio_fiscal[] | array | Código de benefício fiscal por UF — itens: { estado, codigo } |
Body — ipi[]
| Campo | Tipo | Descrição |
|---|---|---|
| cenario * | string | Cenário |
| tipo_pessoa * | string | "fisica" ou "juridica" |
| situacao_tributaria * | string | CST IPI |
| codigo_enquadramento * | string | Código de enquadramento legal |
| aliquota * | string | Alíquota IPI |
Body — pis[] e cofins[] (mesma estrutura)
| Campo | Tipo | Descrição |
|---|---|---|
| cenario * | string | Cenário |
| tipo_pessoa * | string | "fisica" ou "juridica" |
| situacao_tributaria * | string | CST PIS/COFINS |
| aliquota * | string | Alíquota |
Body — ibs_cbs[] (Reforma Tributária)
| Campo | Tipo | Descrição |
|---|---|---|
| cenario * | string | Cenário |
| tipo_pessoa * | string | "fisica" ou "juridica" |
| situacao_tributaria * | string | CST IBS/CBS |
| classificacao_tributaria * | string | Classificação tributária |
Body — is[] (Imposto Seletivo)
| Campo | Tipo | Descrição |
|---|---|---|
| cenario * | string | Cenário |
| tipo_pessoa * | string | "fisica" ou "juridica" |
| situacao_tributaria * | string | CST IS |
| aliquota * | string | Alíquota IS |
* Campo obrigatório.
Exemplo mínimo
{
"descricao": "Venda de mercadoria padrão",
"icms": [{
"tipo_tributacao": "normal",
"cenario": "padrao",
"tipo_pessoa": "juridica",
"codigo_cfop": "5102",
"situacao_tributaria": "00"
}],
"ipi": [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
"pis": [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
"cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }]
}
Resposta
{
"success": true,
"data": {
"category_id": "TF123"
}
}
GET
Detalhes da categoria fiscal
/api/category/get_detail
Retorna a configuração completa de uma categoria fiscal: todos os cenários de ICMS, IPI, PIS, COFINS, IBS/CBS, incluindo arrays por UF (MVA, alíquotas, benefícios fiscais).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria fiscal |
* Campo obrigatório.
Exemplo de chamada
GET /api/category/get_detail?category_id=TF123
Resposta
{
"success": true,
"data": {
"category_id": "TF123",
"descricao": "Venda de mercadoria padrão",
"disable_difal": false,
"desconta_icms_pis_cofins": false,
"icms": [{
"tipo_tributacao": "normal",
"cenario": "padrao",
"tipo_pessoa": "juridica",
"nao_contribuinte": false,
"codigo_cfop": "5102",
"situacao_tributaria": "00",
"aliquota_importacao": "",
"aliquota_credito": 0,
"aliquota_reducao": 0,
"aliquota_reducao_st": 0,
"motivo_desoneracao": "",
"motivo_desoneracao_st": "",
"aliquota_icms": [{"estado":"SP","aliquota":18}]
}],
"ipi": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
"pis": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
"cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
"ibs_cbs":[]
}
}
GET
Listar categorias fiscais
/api/category/get_list
Lista as categorias fiscais da empresa autenticada com paginação. Retorna apenas category_id e descricao de cada categoria — use /api/category/get_detail para detalhes completos.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| page * | int | Número da página (≥ 1) |
| page_size * | int | Tamanho da página (1–50) |
* Campo obrigatório.
Exemplo de chamada
GET /api/category/get_list?page=1&page_size=20
Resposta
{
"success": true,
"data": {
"list": [
{ "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
{ "category_id": "TF124", "descricao": "Devolução de venda" }
],
"page": 1,
"total": 2,
"total_pages": 1
}
}
POST
Editar categoria fiscal
/api/category/edit
Edita uma categoria fiscal existente. O corpo é idêntico ao de /api/category/create, com a única diferença de que category_id é obrigatório e deve corresponder a uma categoria existente. O upsert substitui completamente os arrays icms, ipi, pis, cofins, ibs_cbs, is — envie todos os cenários atualizados (não há merge por cenário).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
A estrutura completa do body está documentada em /api/category/create. Aqui só o category_id tem tratamento diferente:
| Campo | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria a editar (deve existir; caso contrário retorna erro) |
| descricao * | string | Descrição |
| icms[] * | array | Cenários ICMS (substitui completamente) |
| ipi[] * | array | Cenários IPI |
| pis[] * | array | Cenários PIS |
| cofins[] * | array | Cenários COFINS |
| ibs_cbs[] | array | Cenários IBS/CBS (opcional) |
| is[] | array | Cenários IS (opcional) |
| disable_difal | boolean | Default: false |
| desconta_icms_pis_cofins | boolean | Default: false |
* Campo obrigatório. Para os campos internos de cada array (icms[].codigo_cfop etc.), veja /api/category/create.
Resposta
{
"success": true,
"data": {
"category_id": "TF123"
}
}
POST
Excluir categoria fiscal
/api/category/delete
Remove uma categoria fiscal da empresa. Operação irreversível. Produtos que estavam vinculados a esta categoria continuarão referenciando o category_id removido, então a emissão de NFe vai falhar — atualize os produtos antes de excluir.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria a excluir |
* Campo obrigatório.
Exemplo de payload
{
"category_id": "TF123"
}
Resposta
{
"success": true
}
POST
Emitir NF-e de devolução
/api/invoice/return
Emite uma NF-e de devolução (modelo 55, finalidade 4) a partir de uma NF-e original. Suporta dois modos: devolução total (referencia a nota original via uuid ou chave) ou devolução parcial/customizada (envia o body completo via return_detail).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body — campos de raiz
| Campo | Tipo | Descrição |
|---|---|---|
| uuid | string | UUID da NF-e original (obrigatório se chave ausente; não usado no modo return_detail) |
| chave | string | Chave de 44 dígitos da NF-e original (obrigatória no modo return_detail; alternativa a uuid no modo simples) |
| cfop * | string | CFOP de devolução (ex.: "1202", "1411", "2202", "5202", "5411", "6202") |
| natureza_operacao | string | Natureza da operação (ex.: "Devolução de venda"). Alias aceito: nature_of_operation |
| return_detail | object | Body completo da NF-e de devolução. Mesma estrutura de /api/invoice/create, com uma peculiaridade: dentro de return_detail.cliente o campo do número do endereço é number (em inglês), não numero. Quando ausente, a devolução é um clone integral da NF-e original. |
* Campo obrigatório. uuid OU chave também é obrigatório (exatamente um).
Exemplo — devolução total
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
"cfop": "5202",
"natureza_operacao": "Devolução de venda"
}
Exemplo — devolução parcial via return_detail
{
"chave": "35210112345678901234567890123456789012345678",
"cfop": "5202",
"natureza_operacao": "Devolução parcial",
"return_detail": {
"nature_of_operation": "Devolução parcial",
"transaction_type": "1",
"model": "55",
"issuance_type": "1",
"ambiente": "2",
"cliente": { "cnpj": "12345678000199", "name": "Fornecedor", "endereco": "...", "bairro": "...", "city": "...", "uf": "SP", "cep": "01001000" },
"products": [ { "name": "...", "ncm": "...", "count": 1, "unit": "UN", "unit_price": 100, "total_price": 100, "category_id": "...", "origem": 0, "indicador_total": 1 } ]
}
}
Parâmetros Tributários Detalhados
Parâmetros ICMS
Cenário de Tributação
padrao
saida_fora_estado
saida_dentro_estado
entrada_fora_estado
entrada_dentro_estado
Situação Tributária (CST)
00: Tributada integralmente
02: Tributada isenta
10: Tributada com cobrança do ICMS
20: Com redução de base de cálculo
30: Isenta ou não tributada
40: Isenta
41: Não tributada
50: Suspensão
">saida_dentro_estado
entrada_fora_estado
entrada_dentro_estado
Situação Tributária (CST)
01: Operação Tributável (alíquota normal)
02: Operação Tributável (alíquota
diferenciada)
03: Operação Tributável (isenta)
04: Operação Tributável (suspensão)
05: Operação Tributável (ST)
06: Operação Tributável (alíquota zero)
07: Operação Isenta da Contribuição
08: Operação sem Incidência da Contribuição
09: Operação com Suspensão da Contribuição
49: Outras Operações de Saída
50: Direito a crédito (operações próprias)
51: Direito a crédito (aquisições)
52: Lançamento a crédito
53: Lançamento a débito
54: Lançamento a crédito (extemporâneo)
55: Lançamento a débito (extemporâneo)
56: Crédito Presumido
60: Crédito Presumido (aquisições)
61: Crédito Presumido (importação)
62: Crédito Presumido (atividade rural)
63: Crédito Presumido (outras)
64: Crédito Presumido (não gerador)
65: Crédito Presumido (substituição)
66: Crédito Presumido (substituição)
67: Crédito Presumido (exportação)
70: Operação de Aquisição sem Direito a
Crédito
71: Operação de Aquisição com Isenção
72: Operação de Aquisição com Suspensão
73: Operação de Aquisição a Alíquota Zero
74: Operação de Aquisição sem Incidência
75: Operação de Aquisição por Substituição
98: Outras Operações de Entrada
99: Outras Operações
💡 INFORMAÇÃO: Os campos
tipo_pessoa aceitam valores
fisica (pessoa física) ou
juridica (pessoa jurídica). Para PIS/COFINS, o campo
aliquota deve ser formatado como string com duas
casas decimais (ex: "1.65").
Parâmetros de Pagamento
Indicador de Pagamento
0
|
À vista |
1
|
À prazo |
Métodos de Pagamento
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 |
12
|
Vale Presente |
13
|
Vale Combustível |
15
|
Boleto Bancário |
90
|
Sem Pagamento |
99
|
Outros |
Bandeiras de Cartão
01
|
Visa |
02
|
Mastercard |
03
|
American Express |
04
|
Sorocred |
05
|
Diners Club |
06
|
Elo |
07
|
Hipercard |
08
|
Aura |
09
|
Cabal |
99
|
Outros |
Solução de Problemas com XML
Rejeição 225 - Falha no Schema XML
Ocorre quando tenta cancelar, baixar XML, inutilizar número ou fazer manifestação de uma NF-e que não foi registrada com sucesso na base de dados da SEFAZ.
1
Verificar se a NF-e foi autorizada (status "Autorizada")
2
Reemitir a NF-e se não foi autorizada
3
Inutilizar número se não foi utilizado
Validação Online da SEFAZ
Use o validador oficial para identificar problemas no XML:
https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx
Problemas comuns: Endereço incompleto, NCM inválido, formatação de valores incorreta, campos obrigatórios ausentes.
Códigos de Erro da SEFAZ
| Código | Descrição | Solução |
|---|---|---|
217 |
Data de emissão muito atrasada | Emitir em contingência ou regularizar |
404 |
CNPJ/CPF do destinatário inválido | Verificar documento do cliente |
563 |
CFOP não permitido para operação | Revisar CFOP da operação |
POST
Cadastrar empresa para NFC-e
/api/nfce/company/create
Cadastra (ou atualiza) uma empresa para emissão de NFC-e. Razão social, IE, endereço e demais dados são extraídos automaticamente via SintegraWS a partir do CNPJ. Se o CNPJ já existir para o usuário, atualiza os campos NFC-e e retorna a empresa existente.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token do distribuidor (b2b) |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj * | string | CNPJ da empresa emissora |
| cert_file * | string | URL HTTPS do certificado digital A1 (.pfx ou .p12) |
| cert_pwd * | string | Senha do certificado |
| csc_id * | string | ID do CSC (Código de Segurança do Contribuinte) na SEFAZ |
| csc * | string | Token CSC (segredo compartilhado com a SEFAZ) |
| serie_nfce | int | Série da NFC-e |
| number_nfce | int | Número inicial da numeração de NFC-e |
| telefone | string | Telefone da empresa |
* Campo obrigatório. Demais dados (nome, IE, endereço, etc.) são extraídos automaticamente via SintegraWS pelo CNPJ.
Exemplo de payload
{
"cnpj": "12345678000199",
"cert_file": "https://exemplo.com/cert.pfx",
"cert_pwd": "senha_certificado",
"csc_id": "000001",
"csc": "ABCDEF0123456789",
"serie_nfce": 1,
"number_nfce": 1,
"telefone": "11999999999"
}
Resposta
{
"success": true,
"message": "Empresa cadastrada para NFC-e",
"data": {
"company_id": "comp_789012",
"token": "eyJhbGciOiJIUzI1NiIs..."
}
}
POST
Atualizar dados da empresa NFC-e
/api/nfce/company/update
Atualiza dados da empresa NFC-e identificada pelo header token. Todos os campos do body são opcionais — envie apenas os que deseja modificar. Ao atualizar cep, o sistema resolve automaticamente stateCode e ibge. Quando cert_file e cert_pwd vêm juntos, o certificado é validado antes de salvar.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body (todos os campos opcionais — envie ≥ 1)
| Campo | Tipo | Descrição |
|---|---|---|
| Identificação | ||
| name | string | Razão social |
| alias | string | Nome fantasia |
| ie | string | Inscrição Estadual |
| invoice_type | string | Regime tributário |
| string | ||
| telefone | string | Telefone |
| Endereço | ||
| cep | string | CEP (atualiza automaticamente stateCode e ibge) |
| address | string | Logradouro |
| house_number | string | Número |
| complemento | string | Complemento |
| town | string | Bairro |
| city | string | Município |
| state | string | UF |
| NFC-e | ||
| csc_id | string | ID do CSC |
| csc | string | Token CSC |
| serie_nfce | int | Série |
| number_nfce | int | Próximo número |
| cert_file | string | URL HTTPS do novo certificado A1 (.pfx ou .p12) |
| cert_pwd | string | Senha do certificado |
Pelo menos 1 campo no body é obrigatório. CNPJ é imutável.
Exemplo de payload
{
"alias": "Loja Centro - Filial 02",
"telefone": "11988888888",
"serie_nfce": 2,
"number_nfce": 1
}
Resposta
{
"success": true,
"message": "Empresa NFC-e atualizada com sucesso"
}
POST
Consultar empresa NFC-e
/api/nfce/company/get
Retorna os dados da empresa NFC-e identificada pelo header token. Atenção: método é POST mas não há campos no body — a empresa é resolvida apenas pelo token.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
Vazio. Pode ser enviado {}.
Resposta
{
"success": true,
"data": {
"company_id": "comp_789012",
"cnpj": "12345678000199",
"name": "Empresa Exemplo LTDA",
"alias": "Loja Centro",
"ie": "123456789",
"invoice_type": "simples_nacional",
"email": "contato@empresa.com",
"telefone": "11999999999",
"cep": "01001000",
"address": "Rua Exemplo",
"house_number": "100",
"complemento": "Sala 5",
"town": "Centro",
"city": "São Paulo",
"state": "SP",
"state_code": "SP",
"cert_file": "https://exemplo.com/cert.pfx",
"csc_id": "000001",
"csc": "ABCDEF0123456789",
"serie_nfce": 1,
"number_nfce": 42
}
}
Gerenciamento de Categorias Fiscais NFC-e
Categorias fiscais definem as regras tributárias aplicadas aos produtos na emissão de NFC-e. Diferente da NFe, a NFC-e opera apenas com vendas internas (dentro do estado), portanto a estrutura é simplificada: um único objeto por imposto, sem necessidade de múltiplos cenários.
Nota: As categorias NFC-e são armazenadas separadamente das categorias NFe. Cada categoria possui configurações de ICMS, PIS, COFINS e IBS/CBS. Todos os endpoints desta seção exigem os headers
token, sign e timestamp.
POST
Criar categoria fiscal NFC-e
/api/nfce/category/create
Cria uma categoria fiscal NFC-e. Cada categoria tem um único cenário (saída interna) e usa objetos planos para ICMS, PIS, COFINS e IBS/CBS (sem array, pois NFC-e não permite múltiplos cenários por categoria). Não possui IPI.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body (raiz)
| Campo | Tipo | Descrição |
|---|---|---|
| descricao * | string | Descrição da categoria |
| codigo_cfop * | string | Código CFOP (ex.: 5102, 5405) |
| icms * | object | Configuração de ICMS (objeto plano) |
| pis * | object | Configuração de PIS (objeto plano) |
| cofins * | object | Configuração de COFINS (objeto plano) |
| ibs_cbs | object | Configuração de IBS/CBS (Reforma Tributária, opcional) |
icms
| Campo | Tipo | Descrição |
|---|---|---|
| situacao_tributaria * | string | CST/CSOSN (ex.: 102, 500) |
| aliquota_reducao | decimal | Percentual de redução da base de cálculo |
| motivo_desoneracao | string | Código do motivo de desoneração |
| aliquota_icms | array | Alíquotas por estado: [{ "estado": "SP", "aliquota": 18.00 }] |
| aliquota_fcp | array | FCP por estado: [{ "estado": "SP", "aliquota": 0.00 }] |
| beneficio_fiscal | array | Benefício fiscal por estado: [{ "estado": "SP", "codigo": "SP800001" }] |
pis / cofins
| Campo | Tipo | Descrição |
|---|---|---|
| situacao_tributaria * | string | CST PIS/COFINS |
| aliquota * | string | Alíquota percentual (ex.: "0.00", "1.65", "7.60") |
ibs_cbs (opcional)
| Campo | Tipo | Descrição |
|---|---|---|
| situacao_tributaria * | string | CST IBS/CBS |
| classificacao_tributaria * | string | Código de classificação tributária |
* Campo obrigatório.
Exemplo de payload
{
"descricao": "Bebidas não alcoólicas",
"codigo_cfop": "5102",
"icms": {
"situacao_tributaria": "102",
"aliquota_icms": [
{ "estado": "SP", "aliquota": 18.00 }
]
},
"pis": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"cofins": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"ibs_cbs": {
"situacao_tributaria": "000",
"classificacao_tributaria": "000001"
}
}
Resposta
{
"success": true,
"data": {
"category_id": "TF00001"
}
}
GET
Obter detalhes da categoria fiscal NFC-e
/api/nfce/category/get_detail
Retorna os dados completos de uma categoria fiscal NFC-e (descrição, CFOP, ICMS, PIS, COFINS e IBS/CBS).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Query string
| Campo | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria NFC-e |
* Campo obrigatório.
Exemplo de requisição
GET /api/nfce/category/get_detail?category_id=TF00001
Resposta
{
"success": true,
"data": {
"category_id": "TF00001",
"descricao": "Bebidas não alcoólicas",
"codigo_cfop": "5102",
"icms": {
"situacao_tributaria": "102",
"aliquota_icms": [
{ "estado": "SP", "aliquota": 18.00 }
],
"aliquota_fcp": [
{ "estado": "SP", "aliquota": 0.00 }
],
"beneficio_fiscal": [
{ "estado": "SP", "codigo": "SP800001" }
]
},
"pis": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"cofins": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"ibs_cbs": {
"situacao_tributaria": "000",
"classificacao_tributaria": "000001"
}
}
}
GET
Listar categorias fiscais NFC-e
/api/nfce/category/get_list
Retorna lista paginada de categorias fiscais NFC-e cadastradas para a empresa autenticada.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Query string
| Campo | Tipo | Descrição |
|---|---|---|
| page * | int | Número da página (mínimo 1) |
| page_size * | int | Itens por página (1 a 50) |
* Campo obrigatório.
Exemplo de requisição
GET /api/nfce/category/get_list?page=1&page_size=20
Resposta
{
"success": true,
"data": {
"list": [
{ "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
{ "category_id": "TF00002", "descricao": "Alimentos industrializados" }
],
"page": 1,
"total": 2,
"total_pages": 1
}
}
POST
Editar categoria fiscal NFC-e
/api/nfce/category/edit
Nota: Mesma estrutura do endpoint
/api/nfce/category/create, com o campo adicional category_id obrigatório. Os campos icms, pis, cofins e ibs_cbs são substituídos integralmente (não fazem merge).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Campo adicional
| Campo | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria a editar |
* Campo obrigatório.
Exemplo de payload
{
"category_id": "TF00001",
"descricao": "Bebidas não alcoólicas — atualizado",
"codigo_cfop": "5102",
"icms": {
"situacao_tributaria": "102",
"aliquota_icms": [
{ "estado": "SP", "aliquota": 18.00 }
]
},
"pis": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"cofins": {
"situacao_tributaria": "99",
"aliquota": "0.00"
},
"ibs_cbs": {
"situacao_tributaria": "000",
"classificacao_tributaria": "000001"
}
}
Resposta
{
"success": true,
"data": {
"category_id": "TF00001"
}
}
POST
Excluir categoria fiscal NFC-e
/api/nfce/category/delete
Remove uma categoria fiscal NFC-e. Operação irreversível. Produtos vinculados a esta categoria continuarão referenciando o category_id removido — atualize-os antes.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| category_id * | string | ID da categoria NFC-e a excluir |
* Campo obrigatório.
Exemplo de payload
{
"category_id": "TF123"
}
Resposta
{
"success": true
}
POST
Emitir NFC-e
/api/nfce/create
Emite uma NFC-e (modelo 65, sempre saída interna ao estado, sem frete). Diferenças importantes em relação ao endpoint de NFe: o objeto do consumidor chama-se client (não cliente); o número do endereço é client.number; o consumidor é opcional; não existem impostos.ipi, shipping_address, delivery_address, nem transportation. O campo de valor em pag_info chama-se amount.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa NFC-e |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body (raiz)
| Campo | Tipo | Descrição |
|---|---|---|
| nature_of_operation * | string | Natureza da operação (ex.: "Venda de mercadoria") |
| issuance_type * | string | Tipo de emissão: "1" (normal), "9" (contingência off-line NFC-e) |
| ambiente * | string | "1" produção, "2" homologação |
| products * | array | Lista de produtos (ver detalhes abaixo) |
| id | string | Identificador externo |
| ind_pres | string | Presença do comprador: "1" presencial (default), "4" entrega em domicílio, "5" presencial fora do estabelecimento, "9" não se aplica |
| ind_intermed | string | "0" sem intermediador, "1" marketplace. Obrigatório quando ind_pres = 2, 3 ou 4 |
| total_discount_amount | decimal | Desconto total da nota |
| troco | decimal | Valor do troco |
| seguro | decimal | Valor de seguro |
| outras_despesas | decimal | Outras despesas acessórias |
| informacoes_complementares | string | Informações complementares ao consumidor |
| informacoes_fisco | string | Informações de interesse do fisco |
| client | object | Dados do consumidor (opcional — ver tabela) |
| pag_info | array | Pagamentos (default: dinheiro à vista — ver tabela) |
client (opcional)
Preencha apenas se o consumidor for identificado. CPF ou CNPJ devem ser informados como apenas dígitos.
| Campo | Tipo | Descrição |
|---|---|---|
| cpf | string | CPF (define pessoa física) |
| cnpj | string | CNPJ (pessoa jurídica) |
| ie | string | Inscrição estadual |
| name | string | Nome / razão social |
| endereco | string | Logradouro |
| number | string | Número do endereço (atenção: nome diferente da NFe, que usa numero) |
| complemento | string | Complemento |
| bairro | string | Bairro |
| city | string | Cidade |
| uf | string | UF (validada com base no CEP, se informado) |
| cep | string | CEP (apenas dígitos) |
| telefone | string | Telefone |
| string |
products[] (cada item)
| Campo | Tipo | Descrição |
|---|---|---|
| name * | string | Nome do produto (caracteres CJK são removidos) |
| ncm * | string | NCM (8 dígitos) |
| count * | decimal | Quantidade |
| unit * | string | Unidade comercial (ex.: "UN", "KG") |
| unit_price * | decimal | Preço unitário |
| total_price * | decimal | Valor total do item |
| origem * | int | Origem da mercadoria (0..8) |
| indicador_total * | int | 1 = compõe o total da nota; 0 = não compõe |
| category_id ⚠ | string | ID da categoria fiscal NFC-e (obrigatório se não enviar impostos) |
| impostos ⚠ | object | Impostos manuais (alternativa a category_id; sem IPI) |
| tax_info ⚠ | object | Alias de impostos (mesma estrutura). Usado apenas se impostos estiver ausente |
| codigo | string | Código interno do produto |
| cest | string | CEST |
| gtin | string | GTIN/EAN comercial |
| gtin_tributavel | string | GTIN tributável |
| discount_price | decimal | Desconto do item |
| nItemPed | int | Item do Pedido de Compra (I61). Número sequencial do item dentro do pedido referenciado em xPed (vem do id da raiz). Valores válidos: 1–999999. Default: omitido. |
pag_info[] (cada item)
| Campo | Tipo | Descrição |
|---|---|---|
| payment_indicator * | string | "0" à vista, "1" a prazo |
| payment_method * | string | Forma de pagamento (01=dinheiro, 03=cartão crédito, 04=cartão débito, 17=PIX, 99=outros, etc.) |
| amount | decimal | Valor pago nesta forma |
| card_info.integration_type | string | "1" integrado, "2" não integrado (obrigatório para cartão 03/04) |
| card_info.brand_code | string | Bandeira do cartão (obrigatório para cartão 03/04) |
| card_info.acquirer_cnpj | string | CNPJ da credenciadora |
| card_info.authorization_code | string | Código de autorização |
* Campo obrigatório. ⚠ category_id, impostos ou tax_info, um deles é obrigatório.
Exemplo simplificado
{
"nature_of_operation": "Venda de mercadoria",
"issuance_type": "1",
"ambiente": "2",
"ind_pres": "1",
"client": {
"cpf": "12345678909",
"name": "Consumidor Final"
},
"products": [
{
"name": "Refrigerante 2L",
"ncm": "22021000",
"count": 2,
"unit": "UN",
"unit_price": 10.50,
"total_price": 21.00,
"origem": 0,
"indicador_total": 1,
"category_id": "TF00001"
}
],
"pag_info": [
{
"payment_indicator": "0",
"payment_method": "17",
"amount": 21.00
}
]
}
Exemplo completo (todos os campos)
{
"id": "PEDIDO-2026-0001",
"nature_of_operation": "Venda de mercadoria",
"issuance_type": "1",
"ambiente": "2",
"ind_pres": "1",
"ind_intermed": "0",
"total_discount_amount": 0.00,
"troco": 0.00,
"seguro": 0.00,
"outras_despesas": 0.00,
"informacoes_complementares": "Pedido entregue na loja",
"informacoes_fisco": "ICMS recolhido conforme legislação",
"client": {
"cpf": "12345678909",
"cnpj": "",
"ie": "",
"name": "Consumidor Final",
"endereco": "Rua das Flores",
"number": "100",
"complemento": "Sala 5",
"bairro": "Centro",
"city": "São Paulo",
"uf": "SP",
"cep": "01001000",
"telefone": "11999998888",
"email": "cliente@exemplo.com"
},
"products": [
{
"codigo": "PROD001",
"name": "Refrigerante 2L",
"ncm": "22021000",
"cest": "0300100",
"gtin": "7891234567890",
"gtin_tributavel": "7891234567890",
"count": 2,
"unit": "UN",
"unit_price": 10.50,
"total_price": 21.00,
"discount_price": 0.00,
"origem": 0,
"indicador_total": 1,
"category_id": "TF00001",
"nItemPed": 1
},
{
"codigo": "PROD002",
"name": "Salgadinho 100g",
"ncm": "19053100",
"count": 1,
"unit": "UN",
"unit_price": 8.00,
"total_price": 8.00,
"origem": 0,
"indicador_total": 1,
"impostos": {
"icms": {
"codigo_cfop": "5102",
"situacao_tributaria": "102",
"industria": "",
"tipo_pessoa": "juridica"
},
"pis": {
"situacao_tributaria": "99",
"aliquota": "0.00",
"tipo_pessoa": "juridica"
},
"cofins": {
"situacao_tributaria": "99",
"aliquota": "0.00",
"tipo_pessoa": "juridica"
},
"ibs_cbs": {
"situacao_tributaria": "000",
"tipo_pessoa": "juridica",
"classificacao_tributaria": "000001"
}
}
}
],
"pag_info": [
{
"payment_indicator": "0",
"payment_method": "03",
"amount": 24.00,
"card_info": {
"integration_type": "1",
"brand_code": "01",
"acquirer_cnpj": "01234567000189",
"authorization_code": "AUTH123456"
}
}
]
}
Resposta
{
"success": true,
"data": {
"uuid": "abc123...",
"chave": "35..."
}
}
POST
Cancelar NFC-e
/api/nfce/cancel
Cancela uma NFC-e já autorizada. Diferente da NFe, aqui o motivo do cancelamento é enviado pelo cliente e repassado à SEFAZ. A janela de cancelamento na SEFAZ é curta (geralmente 15-30 minutos após a autorização).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| chave * | string | Chave de 44 dígitos da NFC-e (atenção: aqui é chave, não uuid como em outros endpoints) |
| motivo * | string | Justificativa do cancelamento (mín. 15 caracteres por exigência SEFAZ) |
* Campo obrigatório.
Exemplo de payload
{
"chave": "35210112345678901234650010000000051234567890",
"motivo": "Cancelamento por erro de operacao do caixa"
}
GET
Consultar detalhes da NFC-e
/api/nfce/get_detail
Retorna os detalhes de uma NFC-e específica pelo UUID. Inclui URLs do XML e do DANFE (cupom térmico), além de dados do cliente quando informado.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 (path inclui a query string) |
| timestamp | string | Unix timestamp em segundos |
Query string
| Parâmetro | Tipo | Descrição |
|---|---|---|
| uuid * | string | UUID da NFC-e |
* Campo obrigatório.
Exemplo de chamada
GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
Resposta
{
"success": true,
"data": {
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
"chave": "35210112345678901234650010000000051234567890",
"serie": 1,
"number": 5,
"status": "Authorized",
"modelo": "nfce",
"total_price": 145.90,
"nprot": "135210000123456",
"motivo": "",
"xml": "https://oss.example.com/.../chave.xml",
"danfe": "https://oss.example.com/.../chave_nfce.pdf",
"client_cpf": "12345678909",
"client_cnpj": "",
"client_name": "Cliente",
"create": "2024-01-10T10:30:00Z",
"issue_time": "2024-01-10T10:31:00Z"
}
}
POST
Gerar/obter DANFE NFC-e (cupom térmico)
/api/nfce/get_danfe
Retorna a URL do DANFE NFC-e (cupom fiscal eletrônico) em PDF, com QR Code para consulta na SEFAZ. Geração sob demanda com cache por hash (chave + status); chamadas repetidas retornam a URL existente.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid * | string | UUID da NFC-e (atenção: aqui é uuid, diferente do cancel que usa chave) |
* Campo obrigatório.
Exemplo de payload
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
}
Resposta
{
"success": true,
"data": {
"danfe": "https://oss.example.com/.../chave_nfce.pdf"
}
}
Exemplos Completos NFC-e
Exemplo 1 — Venda Presencial (sem destinatário)
{
"nature_of_operation": "Venda de mercadoria",
"ambiente": "2",
"ind_pres": "1",
"products": [
{
"codigo": "001",
"name": "Refrigerante 350ml",
"ncm": "22021000",
"count": 3,
"unit": "UN",
"unit_price": 5.50,
"total_price": 16.50,
"category_id": "BEBIDAS_PADRAO",
"origem": "0",
"indicador_total": "1",
"cfop": "5102"
}
],
"pag_info": [
{ "payment_indicator": "0", "payment_method": "17" }
]
}
Exemplo 2 — Entrega a Domicílio (com destinatário)
{
"nature_of_operation": "Venda de mercadoria",
"ambiente": "2",
"ind_pres": "4",
"client": {
"cpf": "12345678900",
"name": "Maria Silva",
"endereco": "Rua das Flores",
"number": "456",
"bairro": "Jardim Primavera",
"city": "São Paulo",
"uf": "SP",
"cep": "04567000"
},
"products": [
{
"codigo": "PIZZA01",
"name": "Pizza Grande Marguerita",
"ncm": "19059090",
"count": 1,
"unit": "UN",
"unit_price": 45.90,
"total_price": 45.90,
"category_id": "ALIMENTOS",
"origem": "0",
"indicador_total": "1",
"cfop": "5102"
}
],
"pag_info": [
{ "payment_indicator": "0", "payment_method": "03" }
],
"frete": 8.00,
"informacoes_complementares": "Entrega em até 40 minutos"
}
NFe Ajuste / Complementar
A NFe Complementar e a NFe de Ajuste são notas fiscais emitidas para corrigir valores fiscais de uma nota já autorizada. Diferente da CC-e, que corrige apenas dados cadastrais, essas notas permitem alterar valores de impostos, quantidades e preços.
NFe Complementar (finalidade = 2):
- Usada para acrescentar valores que foram informados a menor na nota original
- Complemento de preço, quantidade ou valor do imposto
- Exemplo: emitiu nota com ICMS de 12% mas o correto era 18% — emite complementar com a diferença
NFe de Ajuste (finalidade = 3):
- Usada para ajustes fiscais diversos previstos na legislação
- Ajuste de estoque, transferência de crédito, regularização fiscal
- Exemplo: ajuste de ICMS por apuração, transferência de crédito entre filiais
Importante:
- Ambas são notas fiscais novas — geram nova chave de acesso e novo número
- Devem referenciar a nota original pelo campo
ref_nfe_chave(chave de 44 dígitos) - A nota original precisa estar autorizada
- Consomem 1 crédito cada (como uma emissão normal)
Autenticação
Utiliza o mesmo endpoint e autenticação da emissão de NFe:
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa (obtido no cadastro) |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
NFS-e - Nota Fiscal de Servicos Eletronica
A API de NFS-e permite emitir, cancelar e consultar Notas Fiscais de Servico Eletronicas. O sistema detecta automaticamente o municipio da empresa e roteia para a API correta:
- Sao Paulo (SP) - Emissao via Nota Fiscal Paulistana (SOAP)
- Demais municipios - Emissao via API Nacional (ADN/SEFIN)
O integrador nao precisa se preocupar com qual API usar - basta enviar os dados e o sistema faz o roteamento automaticamente pelo codigo IBGE do municipio cadastrado na empresa.
| Endpoint | Metodo | Descricao |
|---|---|---|
/api/nfse/create | POST | Emitir NFS-e |
/api/nfse/cancel | POST | Cancelar NFS-e |
/api/nfse/get_danfse | POST | Obter DANFSE (PDF) |
/api/nfse/get_xml | POST | Download do XML |
POST
Cadastrar empresa para emissão de NFS-e
/api/nfs/company/create
Cadastra (ou atualiza) uma empresa para emissão de NFS-e. Se o CNPJ já existir para o usuário, apenas os campos NFS-e e o certificado são atualizados; caso contrário, uma nova empresa é criada e um token dedicado é retornado. Atenção ao path: /api/nfs/... (sem o "e"), diferente dos demais endpoints NFS-e.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token B2B do integrador |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj * | string | CNPJ da empresa (apenas dígitos) |
| name * | string | Razão social |
| cep * | string | CEP (apenas dígitos) |
| address * | string | Logradouro |
| house_number * | string | Número do endereço |
| town * | string | Bairro |
| city * | string | Cidade |
| state * | string | UF (2 dígitos, ex.: "SP") |
| cert_file * | string | URL do certificado digital A1 (.pfx) |
| cert_pwd * | string | Senha do certificado digital |
| im * | string | Inscrição Municipal |
| codigo_municipio_nfse * | string | Código IBGE do município emissor |
| codigo_servico_nfse * | string | Código do serviço padrão (LC 116) |
| alias | string | Nome fantasia |
| ie | string | Inscrição estadual |
| invoice_type | string | Regime tributário |
| unit | string | Unidade / filial |
| string | E-mail de contato | |
| telefone | string | Telefone |
| complemento | string | Complemento do endereço |
| cnae_nfse | string | CNAE da atividade padrão |
| serie_nfse | int | Série inicial da NFS-e |
| number_nfse | int | Número inicial da NFS-e |
| regime_especial_tributacao | int | Código do regime especial de tributação |
| optante_simples_nacional | bool | Optante pelo Simples Nacional |
* Campo obrigatório.
Exemplo de payload
{
"cnpj": "43649380000100",
"name": "EMPRESA EXEMPLO LTDA",
"alias": "Exemplo",
"ie": "ISENTO",
"invoice_type": "simples_nacional",
"email": "contato@empresa.com",
"telefone": "11999999999",
"cep": "03027020",
"address": "Rua Exemplo",
"house_number": "86",
"complemento": "Andar 2",
"town": "Centro",
"city": "São Paulo",
"state": "SP",
"cert_file": "https://storage.exemplo.com/cert.pfx",
"cert_pwd": "senha-do-certificado",
"im": "12345678",
"codigo_municipio_nfse": "3550308",
"codigo_servico_nfse": "07498",
"cnae_nfse": "6201501",
"serie_nfse": 1,
"number_nfse": 1,
"regime_especial_tributacao": 0,
"optante_simples_nacional": true
}
Resposta
{
"success": true,
"message": "Empresa cadastrada para NFS-e",
"data": {
"company_id": 12345,
"token": "token-dedicado-da-empresa"
}
}
Nota: O token retornado deve ser usado nas demais chamadas NFS-e (/api/nfse/create, /cancel, /get_danfse, /get_xml). Se a empresa já existir, a mensagem será "Empresa atualizada para NFS-e" e o token retornado é o token existente.
POST
Emitir NFS-e
/api/nfse/create
Headers obrigatorios
| Header | Tipo | Descricao |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"ambiente": "1",
"id": "REF-001",
"descricao_servico": "Desenvolvimento de sistemas",
"valor_servico": 10000.00,
"aliquota_iss": 2.90,
"iss_retido": false,
"codigo_servico": "",
"cnae": "",
"valor_deducoes": 0,
"desconto_incondicionado": 0,
"desconto_condicionado": 0,
"valor_iss": 0,
"valor_pis": 0,
"valor_cofins": 0,
"valor_inss": 0,
"valor_ir": 0,
"valor_csll": 0,
"tomador": {
"cnpj": "43649380000100",
"cpf": "",
"name": "EMPRESA TOMADORA LTDA",
"email": "contato@empresa.com",
"telefone": "11999999999",
"inscricao_municipal": "",
"cep": "03027020",
"endereco": "Rua Exemplo",
"numero": "86",
"complemento": "Andar 2",
"bairro": "Centro",
"city": "Sao Paulo",
"uf": "SP",
"codigo_municipio": "3550308"
}
}
Campos Principais
| Campo | Tipo | Descricao |
|---|---|---|
| ambiente | string | "1" = Producao, "2" = Homologacao |
| id | string | ID de referencia externa (opcional) |
| descricao_servico | string | Descricao do servico prestado (obrigatorio) |
| valor_servico | decimal | Valor total do servico em R$ (obrigatorio) |
| aliquota_iss | decimal | Aliquota ISS em % (ex: 2.90) |
| iss_retido | boolean | false = Nao retido, true = Retido pelo tomador |
| valor_iss | decimal | Override do valor do ISS. Se maior que 0, sobrepoe o calculo automatico (base_calculo x aliquota_iss div 100). Default: calculado automaticamente |
| codigo_servico | string | Codigo do servico. Se vazio, usa o padrao da empresa |
| cnae | string | CNAE. Se vazio, usa o padrao da empresa |
| tomador | object | Dados do tomador do servico (obrigatorio) |
Tomador - Campos
| Campo | Tipo | Descricao |
|---|---|---|
| cnpj | string | CNPJ do tomador (somente numeros) |
| cpf | string | CPF do tomador (usar cnpj OU cpf) |
| name | string | Nome/Razao Social (obrigatorio) |
| string | Email do tomador | |
| telefone | string | Telefone |
| cep | string | CEP (obrigatorio) |
| endereco | string | Logradouro (obrigatorio) |
| numero | string | Numero (obrigatorio) |
| complemento | string | Complemento |
| bairro | string | Bairro (obrigatorio) |
| city | string | Cidade |
| uf | string | UF (2 digitos) |
| codigo_municipio | string | Codigo IBGE do municipio |
Resposta de Sucesso
{
"success": true,
"data": {
"_id": "661234abcdef...",
"uuid": "guid-unico",
"status": "autorizada",
"nfse": "48",
"serie": 1,
"chave": "Z685RI9C",
"codigoVerificacao": "Z685RI9C",
"modelo": "nfse",
"tipoEmissao": "paulistana",
"danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
}
}
POST
Cancelar NFS-e
/api/nfse/cancel
Headers obrigatorios
| Header | Tipo | Descricao |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Payload
{
"chave": "Z685RI9C",
"motivo": "Cancelamento da NFS-e por erro na emissao"
}
Campos
| Campo | Tipo | Descricao |
|---|---|---|
| chave | string | Codigo de verificacao da NFS-e (obrigatorio) |
| motivo | string | Motivo do cancelamento (obrigatório) |
Resposta de Sucesso
{
"success": true,
"message": "Nota de servico cancelada com sucesso"
}
POST
Obter DANFSE (PDF)
/api/nfse/get_danfse
Headers obrigatorios
| Header | Tipo | Descricao |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Payload
{
"chave": "Z685RI9C"
}
Campos
| Campo | Tipo | Descricao |
|---|---|---|
| chave | string | Codigo de verificacao da NFS-e (obrigatorio) |
Resposta
{
"success": true,
"data": {
"danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
}
}
Nota: Para Paulistana (SP), retorna a URL direta do PDF da prefeitura. Para API Nacional, retorna o PDF em base64.
POST
Download XML da NFS-e
/api/nfse/get_xml
Headers obrigatorios
| Header | Tipo | Descricao |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Payload
{
"chave": "Z685RI9C"
}
Campos
| Campo | Tipo | Descricao |
|---|---|---|
| chave | string | Codigo de verificacao da NFS-e (obrigatorio) |
Resposta
{
"success": true,
"data": {
"dpsXml": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
"nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
}
}
dpsXml: XML enviado para a prefeitura/ADN. nfseXml: XML de retorno com o resultado da emissao.
POST
Emitir NFe Complementar (finalidade = 2)
/api/invoice/create
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"finalidade": "2",
"ref_nfe_chave": "CHAVE_NFE_AQUI",
"nature_of_operation": "Complemento de preço",
"transaction_type": "1",
"model": "55",
"issuance_type": "1",
"ambiente": "1",
"ind_final": "1",
"ind_pres": "2",
"cliente": {
"cpf": "264.438.800-72",
"name": "Nome do Destinatário",
"endereco": "Rua Example",
"number": "100",
"bairro": "Centro",
"city": "São Paulo",
"uf": "SP",
"cep": "01310100",
"indIEDest": "9"
},
"products": [
{
"codigo": "001",
"name": "Complemento de valor - Produto X",
"ncm": "82100090",
"count": 1,
"unit": "UN",
"unit_price": 5.00,
"total_price": 5.00,
"category_id": "SEU_CATEGORY_ID",
"origem": "0",
"indicador_total": "1",
"cfop": "5102"
}
],
"pag_info": [
{
"payment_method": "90",
"payment_indicator": "0"
}
]
}
Campos específicos
| Campo | Tipo | Descrição |
|---|---|---|
| finalidade | string | "2" para Complementar (obrigatório) |
| ref_nfe_chave | string | Chave de acesso da nota original — 44 dígitos (obrigatório) |
Nota: Os demais campos seguem o mesmo padrão do endpoint
/api/invoice/create para emissão normal. Consulte a documentação de emissão de NFe para detalhes de todos os campos.
Pagamento: Em notas complementares, o pagamento geralmente é
"90" (Sem Pagamento) pois trata-se apenas de complemento de valores fiscais.
Resposta de Sucesso
{
"success": true,
"data": {
"uuid": "a1b2c3d4-e5f6-...",
"chave": "35260312345678000195550010000004051234567890",
"status": "Success",
"motivo": "Autorizado o uso da NF-e",
"nfe": 405,
"serie": 1,
"danfe": "https://storage.../danfe.pdf",
"xml": "https://storage.../xml.xml"
}
}
POST
Emitir NFe de Ajuste (finalidade = 3)
/api/invoice/create
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"finalidade": "3",
"ref_nfe_chave": "CHAVE_NFE_AQUI",
"nature_of_operation": "Ajuste fiscal",
"transaction_type": "1",
"model": "55",
"issuance_type": "1",
"ambiente": "1",
"ind_final": "1",
"ind_pres": "2",
"cliente": {
"cpf": "264.438.800-72",
"name": "Nome do Destinatário",
"endereco": "Rua Example",
"number": "100",
"bairro": "Centro",
"city": "São Paulo",
"uf": "SP",
"cep": "01310100",
"indIEDest": "9"
},
"products": [
{
"codigo": "001",
"name": "Ajuste fiscal - Regularização",
"ncm": "82100090",
"count": 1,
"unit": "UN",
"unit_price": 0.01,
"total_price": 0.01,
"category_id": "SEU_CATEGORY_ID",
"origem": "0",
"indicador_total": "1",
"cfop": "5949"
}
],
"pag_info": [
{
"payment_method": "90",
"payment_indicator": "0"
}
]
}
Campos específicos
| Campo | Tipo | Descrição |
|---|---|---|
| finalidade | string | "3" para Ajuste (obrigatório) |
| ref_nfe_chave | string | Chave de acesso da nota original — 44 dígitos (obrigatório) |
Valores de finalidade disponíveis:
| Valor | Descrição |
|---|---|
| 1 | Normal (padrão) |
| 2 | Complementar |
| 3 | Ajuste |
| 4 | Devolução |
Diferença entre Complementar e Ajuste:
- Complementar (2): Complementa valores da nota original (preço, imposto, quantidade informados a menor)
- Ajuste (3): Ajustes fiscais previstos na legislação (regularização, transferência de crédito, ajuste de estoque)
CC-e — Carta de Correção Eletrônica
A CC-e (Carta de Correção Eletrônica) é um evento vinculado à NF-e que permite corrigir informações da nota fiscal já autorizada, sem alterar valores fiscais. Regulamentada pelo Ajuste SINIEF 01/07.
O que pode ser corrigido via CC-e:
- Endereço do destinatário ou do emitente
- Razão social do destinatário (sem alterar CNPJ/CPF)
- Código fiscal de operação (CFOP), desde que não mude a natureza dos impostos
- Descrição da mercadoria
- Dados adicionais e informações complementares
O que NÃO pode ser corrigido via CC-e:
- Valores fiscais (base de cálculo, alíquota, valor do imposto)
- Quantidade e valor da mercadoria
- CNPJ/CPF do emitente ou destinatário
- Dados que alterem o cálculo dos impostos
Regras:
- Somente notas com status autorizada (Success) podem receber CC-e
- Texto da correção deve ter entre 15 e 1000 caracteres
- É possível emitir até 20 CC-e para a mesma nota fiscal
- Cada CC-e consome 1 crédito
Autenticação
Todos os endpoints CC-e utilizam a mesma autenticação da API principal:
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa (obtido no cadastro) |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
POST
Enviar Carta de Correção (CC-e)
/api/invoice/cce/send
Envia uma CC-e (evento 110110) à SEFAZ para corrigir dados de uma NF-e já autorizada. A sequência (nSeqEvento) é calculada automaticamente — não envie. Apenas dados não-fiscais podem ser corrigidos (não corrige valores, CNPJ, IE, etc.).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid | string | UUID da NF-e (obrigatório se chave ausente) |
| chave | string | Chave de 44 dígitos da NF-e (obrigatório se uuid ausente) |
| correcao * | string | Texto da correção (limite SEFAZ: 15–1000 caracteres) |
* Campo obrigatório. Pelo menos um entre uuid e chave também é obrigatório.
Exemplo de payload
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
"correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
}
Resposta
{
"success": true,
"data": {
"nProt": "135210000123456",
"nSeqEvento": 1,
"xml": "https://oss.example.com/.../cce.xml"
}
}
POST
Listar CC-e de uma NF-e
/api/invoice/cce/get_list
Retorna todas as CC-e (Cartas de Correção) emitidas para uma NF-e específica, ordenadas da mais recente para a mais antiga.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| uuid | string | UUID da NF-e (obrigatório se chave ausente) |
| chave | string | Chave de 44 dígitos da NF-e (obrigatório se uuid ausente) |
Pelo menos um entre uuid e chave é obrigatório.
Exemplo de payload
{
"uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
}
Resposta
{
"success": true,
"data": {
"items": [
{
"id": "65fa1b2c3d4e5f6a7b8c9d0e",
"detail": "Corrigir nome do destinatario para Empresa XYZ LTDA",
"nProt": "135210000123456",
"nSeqEvento": 1,
"date": "15/01/2024 14:30:00",
"pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
"xmlUrl": "https://oss.example.com/.../cce.xml"
}
],
"total": 1
}
}
POST
Baixar PDF da CC-e
/api/invoice/cce/download_pdf
Retorna a URL do PDF da CC-e. O PDF é gerado sob demanda na primeira chamada (renderizando a partir do XML da nota + XML da CC-e) e armazenado no OSS; chamadas subsequentes retornam a URL existente.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| cce_id * | string | ID da CC-e (ObjectId) retornado por /api/invoice/cce/get_list no campo id |
* Campo obrigatório.
Exemplo de payload
{
"cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
}
Resposta
{
"success": true,
"data": {
"url": "https://oss.example.com/.../cce_seq1.pdf"
}
}
POST
Baixar XML da CC-e
/api/invoice/cce/download_xml
Retorna a URL do XML assinado da CC-e (já armazenado no OSS após o envio à SEFAZ).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| cce_id * | string | ID da CC-e (ObjectId) retornado por /api/invoice/cce/get_list no campo id |
* Campo obrigatório.
Exemplo de payload
{
"cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
}
Resposta
{
"success": true,
"data": {
"url": "https://oss.example.com/.../cce.xml"
}
}
Manifestação do Destinatário
A Manifestação do Destinatário permite que o destinatário de uma NF-e se posicione formalmente sobre uma nota fiscal emitida contra seu CNPJ. São 4 tipos de eventos previstos pela SEFAZ, todos com base legal definida.
Tipos de Evento
| Código | Nome | Significado | Justificativa |
|---|---|---|---|
| 210210 | Ciência da Operação | O destinatário tomou conhecimento da NF-e, mas ainda não confirmou nem rejeitou. Geralmente o primeiro evento dado, requisito para baixar o XML completo via DistDFe. | Não obrigatória |
| 210200 | Confirmação da Operação | O destinatário confirma que a operação aconteceu e a mercadoria/serviço foi recebida. Evento final, comprova recebimento. | Não obrigatória |
| 210220 | Desconhecimento da Operação | O destinatário declara que NÃO reconhece a operação (suspeita de fraude, uso indevido do CNPJ, etc). | Obrigatória (15-255 chars) |
| 210240 | Operação Não Realizada | O destinatário reconhece a operação mas declara que ela NÃO se concretizou (devolução, recusa de recebimento, etc). | Obrigatória (15-255 chars) |
Regra de sequência: Após dar Ciência (210210), pode-se enviar Confirmação (210200) OU Desconhecimento (210220) OU Não Realizada (210240). Confirmação/Desconhecimento/Não Realizada são estados finais — não podem ser sobrepostos.
Atenção: O CNPJ enviado no campo
cnpj deve ser o do destinatário da NF-e (quem está manifestando) e deve estar cadastrado no sistema vinculado ao token usado. Caso contrário a SEFAZ retorna a rejeição "O autor do evento diverge do destinatário da NF-e".
Códigos cStat de Retorno
| cStat | Significado |
|---|---|
| 135 | ✅ Evento registrado com sucesso |
| 573 | ✅ Duplicidade de evento — já registrado anteriormente (tratado como sucesso) |
| 236 | ❌ Chave de acesso inválida |
| 491 | ❌ Manifestação já registrada — não pode sobrescrever estado final |
| 596 | ❌ CNPJ destinatário diverge do informado |
| 656 | ❌ Consumo indevido (rate limit) |
POST
Enviar evento de manifestação do destinatário
/api/invoice/manifest
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"chave": "35260514200166000187550010000000011000000018",
"cnpj": "14200166000187",
"tipo_evento": 210210,
"justificativa": "Operação reconhecida pelo destinatário"
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| chave | string | Sim | Chave de acesso da NF-e — 44 dígitos |
| cnpj | string | Sim | CNPJ do destinatário (quem manifesta) — 14 dígitos, sem formatação. Deve estar cadastrado no sistema |
| tipo_evento | int | Sim | Código do evento: 210200, 210210, 210220 ou 210240 |
| justificativa | string | Condicional | Obrigatória para 210220 e 210240. Deve ter entre 15 e 255 caracteres. Ignorada para 210200 e 210210 |
Sequência (nSeqEvento): calculada automaticamente. Para a mesma combinação (cnpj + chave + tipo_evento) é incrementada a cada chamada — assim duplicatas retornam
cStat: 573 e são gravadas sem erro.
Resposta de Sucesso
{
"success": true,
"message": "data",
"data": {
"id": "67341a8f5d4e1f2a3b4c5d6e",
"chave": "35260514200166000187550010000000011000000018",
"cnpj": "14200166000187",
"tipo_evento": 210210,
"desc_evento": "Ciencia da Operacao",
"nProt": "135260000123456",
"cStat": 135,
"xMotivo": "Evento registrado e vinculado a NF-e",
"nSeqEvento": 1,
"xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ObjectId interno do registro da manifestação (usado em /get_xml) |
| chave | string | Chave de acesso da NF-e manifestada |
| cnpj | string | CNPJ do destinatário que manifestou |
| tipo_evento | int | Código do evento enviado (210200/210210/210220/210240) |
| desc_evento | string | Descrição textual do evento |
| nProt | string | Número do protocolo SEFAZ — comprovante do evento |
| cStat | int | Código de status SEFAZ. 135 = registrado, 573 = duplicidade (também aceito) |
| xMotivo | string | Mensagem descritiva do retorno SEFAZ |
| nSeqEvento | int | Sequência do evento atribuída automaticamente |
| xml_url | string | URL pública do XML do procEvento (assinado e protocolado) armazenado no OSS |
Exemplo — Desconhecimento (210220) com justificativa
{
"chave": "35260514200166000187550010000000011000000018",
"cnpj": "14200166000187",
"tipo_evento": 210220,
"justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
}
POST
Listar manifestações enviadas (histórico)
/api/invoice/manifest/list
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"cnpj": "14200166000187",
"chave": "",
"start_create_time": "01/05/2026",
"end_create_time": "31/05/2026",
"page": 1,
"page_size": 20
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cnpj | string | Não | Filtra por CNPJ do destinatário. Se omitido, lista de todos os CNPJs do usuário |
| chave | string | Não | Filtra por chave NF-e específica (44 dígitos) |
| start_create_time | string/long | Não | Data inicial da criação. Aceita formatos: "dd/MM/yyyy", "yyyy-MM-dd", "dd/MM/yyyy HH:mm:ss" ou Unix timestamp em segundos. Considera 00:00:00 UTC se só data |
| end_create_time | string/long | Não | Data final da criação. Mesmo formato. Se só data, considera 23:59:59.999 UTC |
| page | int | Não | Número da página (default 1) |
| page_size | int | Não | Itens por página (default 20, máximo 100) |
Resposta de Sucesso
{
"success": true,
"message": "成功",
"data": {
"total": 2,
"page": 1,
"page_size": 20,
"list": [
{
"id": "67341a8f5d4e1f2a3b4c5d6e",
"chave": "35260514200166000187550010000000011000000018",
"cnpj": "14200166000187",
"tipo_evento": 210210,
"desc_evento": "Ciencia da Operacao",
"justificativa": "Operação reconhecida pelo destinatário",
"nProt": "135260000123456",
"nSeqEvento": 1,
"cStat": 135,
"xMotivo": "Evento registrado e vinculado a NF-e",
"xml_url": "https://storage.../...210210_1.xml",
"create": "2026-05-13 14:25:33"
}
]
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| total | int | Total de registros que atendem aos filtros (independente de paginação) |
| page | int | Página atual retornada |
| page_size | int | Tamanho da página retornada |
| list[].id | string | ObjectId interno do registro |
| list[].chave | string | Chave de acesso da NF-e manifestada |
| list[].cnpj | string | CNPJ destinatário que manifestou |
| list[].tipo_evento | int | Código do evento (210200/210210/210220/210240) |
| list[].desc_evento | string | Descrição textual do evento |
| list[].justificativa | string | Justificativa enviada (preenchido apenas para 210220/210240) |
| list[].nProt | string | Protocolo SEFAZ do evento |
| list[].nSeqEvento | int | Sequência do evento |
| list[].cStat | int | Código de status SEFAZ |
| list[].xMotivo | string | Mensagem descritiva do retorno SEFAZ |
| list[].xml_url | string | URL pública do XML do procEvento no OSS |
| list[].create | string | Data/hora UTC do registro (formato yyyy-MM-dd HH:mm:ss) |
Ordenação: registros são retornados do mais recente para o mais antigo (por
create decrescente).
POST
Obter URL do XML de uma manifestação específica
/api/invoice/manifest/get_xml
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"id": "67341a8f5d4e1f2a3b4c5d6e"
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ObjectId da manifestação — retornado em /manifest ou /manifest/list |
Resposta de Sucesso
{
"success": true,
"message": "data",
"data": {
"id": "67341a8f5d4e1f2a3b4c5d6e",
"chave": "35260514200166000187550010000000011000000018",
"tipo_evento": 210210,
"xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
}
}
Erros Comuns
| Mensagem | Causa |
|---|---|
| id inválido | Valor não é um ObjectId válido |
| manifestação não encontrada | ObjectId existe mas não pertence ao usuário do token, ou foi excluído |
Captura DistDFe — NFes Recebidas
Permite consultar e baixar NFes e eventos destinados ao seu CNPJ via o serviço NFeDistribuicaoDFe da SEFAZ (Ambiente Nacional). A captura é incremental por NSU (Número Sequencial Único) — cada chamada baixa apenas o que ainda não foi capturado anteriormente.
Tipos de Documento Retornados
| doc_type | O que é | Conteúdo |
|---|---|---|
| resNFe | Resumo de NFe | Metadados básicos (chave, valor, emitente, situação). Vem ANTES da Ciência ser dada — não contém produtos/impostos |
| procNFe | NFe completa autorizada | XML completo da NFe (com produtos, impostos, transporte, etc). Só vem APÓS o destinatário dar Ciência (210210) na chave |
| resEvento | Resumo de evento | Metadados de evento (chave, tipo, sequência, motivo) |
| procEvento | Evento completo | XML completo do evento (CCe, cancelamento, manifestações de outros destinatários sobre suas notas) |
Fluxo recomendado:
- Chame
/received/sync— baixa todos os documentos novos - Liste com
/received/listfiltrando pordoc_type: "resNFe"para ver notas sem Ciência - Para cada chave de interesse, chame
/invoice/manifestcomtipo_evento: 210210 - Chame
/received/syncnovamente — agora o SEFAZ devolve osprocNFe(XML completo) das chaves manifestadas - Use
/received/get_xmlpara obter a URL do XML e baixar/processar
Rate limit do SEFAZ: a SEFAZ permite no máximo 1 chamada DistDFe por hora por CNPJ. Se exceder, retorna
cStat: 656 (Consumo Indevido). Em ambiente de homologação a regra é mais permissiva.
Códigos cStat de Retorno do DistDFe
| cStat | Significado |
|---|---|
| 137 | ✅ Nenhum documento localizado (fim normal do loop) |
| 138 | ✅ Documentos localizados — loop continua |
| 656 | ❌ Consumo indevido — aguardar 1h e tentar novamente |
| 252 | ❌ Ambiente diferente do informado (produção vs homologação) |
| 280 | ❌ Certificado expirado ou inválido |
POST
Sincronizar — baixar NFes/eventos novos do SEFAZ via DistDFe
/api/invoice/received/sync
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"cnpj": "26638419000167",
"max_iterations": 50
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cnpj | string | Sim | CNPJ da empresa destinatária — 14 dígitos, sem formatação. Deve estar cadastrado no sistema vinculado ao token |
| max_iterations | int | Não | Número máximo de chamadas SEFAZ por execução. Cada chamada baixa até 50 documentos. Default 50 (≈2500 docs), máximo 200 |
Como funciona:
- Lê o último
ultNSUpersistido para esse (uid + cnpj) - Faz loop chamando o SEFAZ até
cStat ≠ 138ou atingirmax_iterations - Descomprime os XMLs (gzip) retornados
- Persiste cada documento em
w_invoice_receivedcom upload do XML no OSS - Atualiza
ultNSUemaxNSUemw_invoice_received_sync - Deduplica por
(uid + cnpj + nsu)— chamadas repetidas não duplicam
Resposta de Sucesso
{
"success": true,
"message": "data",
"data": {
"cnpj": "26638419000167",
"uf": "SP",
"initial_nsu": 0,
"ult_nsu": 2323,
"max_nsu": 2323,
"pending": 0,
"iterations": 8,
"last_cstat": 137,
"last_motivo": "Nenhum documento localizado",
"stats": {
"resNFe": 3,
"procNFe": 4,
"resEvento": 336,
"procEvento": 5,
"skipped": 0
}
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj | string | CNPJ destinatário consultado |
| uf | string | UF do destinatário usada na consulta |
| initial_nsu | long | NSU de partida — o último processado antes dessa execução |
| ult_nsu | long | Novo último NSU após a sincronização |
| max_nsu | long | Maior NSU disponível no SEFAZ AN no momento da consulta |
| pending | long | Documentos ainda pendentes (max_nsu - ult_nsu). Se > 0, chame /sync novamente para baixar o restante |
| iterations | int | Quantas chamadas SEFAZ foram feitas nessa execução |
| last_cstat | int | Último cStat retornado pelo SEFAZ. 137 é fim normal, 656 é rate limit |
| last_motivo | string | Mensagem descritiva do último retorno SEFAZ |
| stats.resNFe | int | Quantidade de resumos de NFe baixados nessa execução |
| stats.procNFe | int | Quantidade de NFes completas baixadas |
| stats.resEvento | int | Quantidade de resumos de evento baixados |
| stats.procEvento | int | Quantidade de eventos completos baixados |
| stats.skipped | int | Documentos ignorados (duplicados ou erro de parsing isolado) |
Volume inicial: empresas que nunca sincronizaram podem ter centenas a milhares de documentos históricos. A primeira execução pode demorar mais e ser interrompida pelo
max_iterations. Verifique pending na resposta — se > 0, chame de novo (respeitando o rate limit).
POST
Listar documentos (NFes e eventos) capturados
/api/invoice/received/list
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"cnpj": "26638419000167",
"doc_type": "resNFe",
"chave": "",
"emitente_cnpj": "",
"start_create_time": "01/05/2026",
"end_create_time": "31/05/2026",
"page": 1,
"page_size": 20
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cnpj | string | Não | Filtra por CNPJ destinatário (o seu CNPJ). Se omitido, lista de todos do usuário |
| doc_type | string | Não | Filtra por tipo de documento: resNFe, procNFe, resEvento ou procEvento |
| chave | string | Não | Filtra por chave de acesso (44 dígitos) |
| emitente_cnpj | string | Não | Filtra por CNPJ do emitente da NFe (fornecedor) |
| start_create_time | string/long | Não | Data inicial. Aceita "dd/MM/yyyy", ISO ou Unix timestamp |
| end_create_time | string/long | Não | Data final. Mesmo formato |
| page | int | Não | Número da página (default 1) |
| page_size | int | Não | Itens por página (default 20, máximo 100) |
Resposta de Sucesso
{
"success": true,
"message": "成功",
"data": {
"total": 3,
"page": 1,
"page_size": 20,
"list": [
{
"id": "6a04a70d3201b5a62f3ac2f8",
"nsu": 2318,
"doc_type": "resNFe",
"schema": "resNFe_v1.01.xsd",
"chave": "35260563845920000120550020000085471156822656",
"cnpj_destinatario": "26638419000167",
"emitente_cnpj": "63845920000120",
"emitente_nome": "MEGA ONLINE LTDA",
"valor": 1.00,
"dh_emi": "2026-05-13 14:05:35",
"serie": 0,
"number": 0,
"tp_nf": 1,
"c_sit_nfe": 3,
"tp_evento": 0,
"desc_evento": "",
"n_seq_evento": 0,
"dh_evento": null,
"xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
"create": "2026-05-13 16:30:05"
}
]
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| total | int | Total de registros que atendem aos filtros |
| page | int | Página atual |
| page_size | int | Tamanho da página |
| list[].id | string | ObjectId interno (use em /received/get_xml) |
| list[].nsu | long | NSU atribuído pela SEFAZ a este documento |
| list[].doc_type | string | Tipo do documento: resNFe, procNFe, resEvento, procEvento |
| list[].schema | string | Schema do documento (ex: resNFe_v1.01.xsd) |
| list[].chave | string | Chave de acesso da NF-e (44 dígitos) |
| list[].cnpj_destinatario | string | CNPJ destinatário (o seu CNPJ) |
| list[].emitente_cnpj | string | CNPJ do emitente da NFe (fornecedor) |
| list[].emitente_nome | string | Razão social do emitente |
| list[].valor | decimal | Valor total da NFe (vNF) |
| list[].dh_emi | string | Data/hora de emissão da NFe |
| list[].serie | int | Série da NFe (preenchido apenas em procNFe) |
| list[].number | long | Número da NFe (preenchido apenas em procNFe) |
| list[].tp_nf | int | Tipo da operação: 0=Entrada, 1=Saída (na ótica do emitente) |
| list[].c_sit_nfe | int | Situação da NFe (preenchido em resNFe): 1=Autorizada, 2=Denegada, 3=Cancelada |
| list[].tp_evento | int | Código do evento (preenchido em resEvento/procEvento). Ex: 110110=CCe, 110111=Cancelamento, 210210=Ciência |
| list[].desc_evento | string | Descrição textual do evento |
| list[].n_seq_evento | int | Sequência do evento |
| list[].dh_evento | string | Data/hora do evento (eventos) |
| list[].xml_url | string | URL pública do XML do documento no OSS |
| list[].create | string | Data/hora UTC da captura |
Ordenação: registros são retornados por NSU decrescente (mais recente primeiro).
POST
Obter URL do XML de um documento recebido específico
/api/invoice/received/get_xml
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"id": "6a04a70d3201b5a62f3ac2f8"
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ObjectId do documento — retornado em /received/list |
Resposta de Sucesso
{
"success": true,
"message": "data",
"data": {
"id": "6a04a70d3201b5a62f3ac2f8",
"nsu": 2318,
"doc_type": "resNFe",
"chave": "35260563845920000120550020000085471156822656",
"xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
}
}
Sobre o XML retornado:
resNFe— XML é apenas o resumo, NÃO contém produtos/impostos. Use para auditoria/triagem antes de manifestar CiênciaprocNFe— XML completo e assinado, equivalente ao gerado pela emissão. Pronto para importar no ERP do clienteprocEvento— XML do evento completo com assinatura e protocolo
Erros Comuns
| Mensagem | Causa |
|---|---|
| id inválido | Valor não é um ObjectId válido |
| documento recebido não encontrado | ObjectId existe mas não pertence ao usuário do token |
POST
Consultar estado atual da sincronização DistDFe (sem chamar SEFAZ)
/api/invoice/received/get_sync_status
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"cnpj": "26638419000167"
}
Campos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| cnpj | string | Sim | CNPJ da empresa destinatária — 14 dígitos, sem formatação |
Resposta — Empresa já sincronizada
{
"success": true,
"message": "成功",
"data": {
"cnpj": "26638419000167",
"uf": "SP",
"ult_nsu": 2323,
"max_nsu": 2323,
"pending": 0,
"last_sync": "2026-05-13 16:30:05"
}
}
Resposta — Empresa nunca sincronizou
{
"success": true,
"message": "成功",
"data": {
"cnpj": "26638419000167",
"ult_nsu": 0,
"max_nsu": 0,
"pending": 0,
"last_sync": null
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj | string | CNPJ consultado |
| uf | string | UF do destinatário usada na última sincronização (ausente se nunca sincronizou) |
| ult_nsu | long | Último NSU processado. 0 = nunca sincronizou |
| max_nsu | long | Maior NSU disponível no SEFAZ na última sincronização |
| pending | long | Documentos pendentes (max_nsu - ult_nsu). Se > 0, há novos documentos no SEFAZ |
| last_sync | string | Data/hora UTC da última sincronização bem-sucedida. null se nunca sincronizou |
Uso típico: chame esse endpoint antes de
/received/sync para decidir se precisa chamar o SEFAZ. Esse endpoint não consome o rate limit do SEFAZ — só lê o estado local do MongoDB.
MDF-e — Manifesto Eletrônico de Documentos Fiscais
A API de MDF-e (modelo 58, layout PL-MDFe 3.00) permite emitir, consultar, cancelar e encerrar manifestos de transporte. O MDF-e agrega NF-es e/ou CT-es vinculados a uma operação de transporte, suportando 4 modais: rodoviário, aéreo, aquaviário e ferroviário. Toda informação operacional (condutor, veículo, contratante, CIOT, vale-pedágio, pagamento) vai no corpo do /create — não há eventos de inclusão/alteração após a emissão.
| Endpoint | Método | Descrição |
|---|---|---|
/api/mdfe/create | POST | Emitir MDF-e |
/api/mdfe/consult | POST | Consultar situação do MDF-e |
/api/mdfe/cancel | POST | Cancelar MDF-e (até 24h após autorização) |
/api/mdfe/close | POST | Encerrar MDF-e (após finalizar viagem) |
POST
Emitir MDF-e
/api/mdfe/create
Emite um MDF-e a partir do corpo enviado. Os campos serie, nMDF, cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc são calculados automaticamente pelo servidor. O cliente envia apenas os campos de negócio.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body — raiz
| Campo | Tipo | Descrição |
|---|---|---|
| ide * | object | Identificação do MDF-e |
| emit * | object | Dados do emitente |
| infModal * | object | Informações do modal (apenas UM dos quatro: rodo, aereo, aquav, ferrov) |
| infDoc * | object | Documentos fiscais vinculados |
| tot * | object | Totalizadores da carga |
| prodPred | object | Produto predominante da carga |
| seg | array | Informações de seguro |
| lacres | array | Lacres do MDF-e |
| autXML | array | CNPJs/CPFs autorizados a acessar o XML |
| infAdic | object | Informações adicionais (fisco e contribuinte) |
| infRespTec | object | Responsável técnico (CNPJ, contato, email, etc.) |
ide — Identificação
| Campo | Tipo | Descrição |
|---|---|---|
| tpAmb * | int | Ambiente: 1=produção, 2=homologação |
| tpEmit * | int | Tipo do emitente: 1=transportador, 2=carga própria, 3=prestador de serviço de transporte |
| modal * | string | Modal: "1"=rodoviário, "2"=aéreo, "3"=aquaviário, "4"=ferroviário |
| UFIni * | string | UF de início da viagem (2 letras) |
| UFFim * | string | UF de fim da viagem |
| infMunCarrega[] * | array | Municípios de carregamento: [{ cMunCarrega, xMunCarrega }] |
| infPercurso[] | array | UFs do percurso: [{ UFPer }] |
| tpTransp | string | Tipo de transportador (rodoviário) |
| dhIniViagem | string | Data/hora de início da viagem (ISO 8601) |
| indCanalVerde | string | Indicador de canal verde |
| indCarregaPosterior | string | Indicador de carregamento posterior |
emit — Emitente
| Campo | Tipo | Descrição |
|---|---|---|
| CNPJ ⚠ | string | CNPJ do emitente (14 dígitos) |
| CPF ⚠ | string | CPF do emitente (11 dígitos) |
| IE | string | Inscrição Estadual |
| xNome * | string | Razão social |
| xFant | string | Nome fantasia |
| enderEmit | object | Endereço: { xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email } |
infModal — Modal Rodoviário (modal="1")
| Campo | Tipo | Descrição |
|---|---|---|
| rodo.veicTracao * | object | Veículo de tração: { placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop } |
| rodo.veicTracao.condutor[] * | array | Condutores: [{ xNome, CPF }] — mínimo 1 |
| rodo.veicReboque[] | array | Veículos de reboque (mesma estrutura de veicTracao sem condutor) |
| rodo.infANTT | object | Informações da ANTT: { RNTRC, infCIOT[], valePed, infContratante[], infPag[] } |
| rodo.codAgPorto | string | Código de agendamento no porto |
| rodo.lacRodo[] | array | Lacres do modal: [{ nLacre }] |
infModal — Modal Aéreo (modal="2")
| Campo | Tipo | Descrição |
|---|---|---|
| aereo.nac * | string | Marca de nacionalidade da aeronave |
| aereo.matr * | string | Matrícula da aeronave |
| aereo.nVoo * | string | Número do voo |
| aereo.cAerEmb * | string | Código IATA do aeroporto de embarque |
| aereo.cAerDes * | string | Código IATA do aeroporto de destino |
| aereo.dVoo * | string | Data do voo (AAAA-MM-DD) |
infModal — Modal Aquaviário (modal="3")
| Campo | Tipo | Descrição |
|---|---|---|
| aquav.irin * | string | IRIN da embarcação |
| aquav.tpEmb * | string | Tipo de embarcação (2 dígitos). Use valores ≥ 10 para evitar truncamento do byte interno do Zeus (ex.: "10", "11") |
| aquav.cEmbar * | string | Código da embarcação |
| aquav.xEmbar * | string | Nome da embarcação |
| aquav.nViag * | string | Número da viagem. Não pode começar com zero (validação do schema) — use "1", "100", etc. |
| aquav.cPrtEmb * | string | Código do porto de embarque |
| aquav.cPrtDest * | string | Código do porto de destino |
| aquav.prtTrans | string | Porto de transbordo |
| aquav.tpNav | string | Tipo de navegação |
| aquav.infTermCarreg[] | array | Terminais de carregamento: [{ cTermCarreg, xTermCarreg }] |
| aquav.infTermDescarreg[] | array | Terminais de descarregamento |
| aquav.infEmbComb[] | array | Embarcações de comboio: [{ cEmbComb, xBalsa }] |
| aquav.infUnidCargaVazia[] | array | Unidades de carga vazias |
| aquav.infUnidTranspVazia[] | array | Unidades de transporte vazias |
infModal — Modal Ferroviário (modal="4")
| Campo | Tipo | Descrição |
|---|---|---|
| ferrov.trem * | object | Dados do trem: { xPref, dhTrem, xOri, xDest, qVag } |
| ferrov.vag[] * | array | Vagões: [{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }] — mínimo 1. Restrições do Zeus/SEFAZ: serie deve ter exatamente 3 dígitos (use 100+, ex.: "100"); nVag só aceita dígitos (long internamente, ex.: "100001"); nSeq opcional 1-3 dígitos. |
infDoc — Documentos vinculados
| Campo | Tipo | Descrição |
|---|---|---|
| infMunDescarga[] * | array | Municípios de descarga — mínimo 1 |
| infMunDescarga[].cMunDescarga * | string | Código IBGE do município |
| infMunDescarga[].xMunDescarga * | string | Nome do município |
| infMunDescarga[].infNFe[] | array | NF-es vinculadas: [{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }] |
| infMunDescarga[].infCTe[] | array | CT-es vinculados |
| infMunDescarga[].infMDFeTransp[] | array | MDF-es de transporte (subcontratação) |
prodPred — Produto predominante
| Campo | Tipo | Descrição |
|---|---|---|
| tpCarga * | string | Tipo de carga: "01"=granel sólido, "02"=granel líquido, "03"=frigorificada, "04"=conteinerizada, "05"=carga geral, "06"=neogranel, "07"=perigosa, "08"=granel pressurizado |
| xProd * | string | Descrição do produto predominante |
| cEAN | string | GTIN/EAN |
| NCM | string | NCM |
| infLotacao | object | Lotação: { infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} } |
tot — Totalizadores
| Campo | Tipo | Descrição |
|---|---|---|
| vCarga * | decimal | Valor total da carga (> 0) |
| cUnid * | string | Código da unidade: "01"=KG, "02"=TON |
| qCarga * | decimal | Quantidade total da carga (> 0) |
| qCTe | int | Quantidade de CT-es vinculados |
| qNFe | int | Quantidade de NF-es vinculadas |
| qMDFe | int | Quantidade de MDF-es vinculados |
* Campo obrigatório. ⚠ Pelo menos um de CNPJ ou CPF é obrigatório.
Exemplo simplificado — Modal Rodoviário
{
"ide": {
"tpAmb": 2,
"tpEmit": 2,
"modal": "1",
"UFIni": "SP",
"UFFim": "ES",
"infMunCarrega": [
{ "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
],
"infPercurso": [
{ "UFPer": "MG" }
]
},
"emit": {
"CNPJ": "12345678000199",
"IE": "123456789012",
"xNome": "TRANSPORTADORA EXEMPLO LTDA",
"enderEmit": {
"xLgr": "RUA EXEMPLO",
"nro": "100",
"xBairro": "CENTRO",
"cMun": "3550308",
"xMun": "SAO PAULO",
"UF": "SP"
}
},
"infModal": {
"versaoModal": "3.00",
"rodo": {
"veicTracao": {
"placa": "ABC1D23",
"tara": 8000,
"condutor": [
{ "xNome": "João da Silva", "CPF": "12345678909" }
],
"tpRod": "01",
"tpCar": "01"
}
}
},
"infDoc": {
"infMunDescarga": [
{
"cMunDescarga": "3205200",
"xMunDescarga": "Vila Velha",
"infNFe": [
{ "chNFe": "35260512345678000199550010000000011000000018" }
]
}
]
},
"prodPred": {
"tpCarga": "05",
"xProd": "CARGA GERAL"
},
"tot": {
"vCarga": 50000.00,
"cUnid": "01",
"qCarga": 1500.00
}
}
Exemplo simplificado — Modal Aéreo
{
"ide": {
"tpAmb": 2,
"tpEmit": 2,
"modal": "2",
"UFIni": "SP",
"UFFim": "RJ",
"infMunCarrega": [
{ "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
]
},
"emit": {
"CNPJ": "12345678000199",
"IE": "123456789012",
"xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
"enderEmit": {
"xLgr": "AV AEROPORTO",
"nro": "5000",
"xBairro": "CUMBICA",
"cMun": "3550308",
"xMun": "SAO PAULO",
"UF": "SP"
}
},
"infModal": {
"versaoModal": "3.00",
"aereo": {
"nac": "PT",
"matr": "ABC1234",
"nVoo": "AB1234",
"cAerEmb": "GRU",
"cAerDes": "GIG",
"dVoo": "2026-05-21"
}
},
"infDoc": {
"infMunDescarga": [
{
"cMunDescarga": "3304557",
"xMunDescarga": "Rio de Janeiro",
"infNFe": [
{ "chNFe": "35260512345678000199550010000000011000000018" }
]
}
]
},
"prodPred": {
"tpCarga": "05",
"xProd": "CARGA GERAL"
},
"tot": {
"vCarga": 25000.00,
"cUnid": "01",
"qCarga": 500.00
}
}
Exemplo simplificado — Modal Aquaviário
{
"ide": {
"tpAmb": 2,
"tpEmit": 2,
"modal": "3",
"UFIni": "SP",
"UFFim": "PA",
"infMunCarrega": [
{ "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
]
},
"emit": {
"CNPJ": "12345678000199",
"IE": "123456789012",
"xNome": "NAVEGACAO EXEMPLO LTDA",
"enderEmit": {
"xLgr": "AV PORTUARIA",
"nro": "200",
"xBairro": "PORTO",
"cMun": "3548500",
"xMun": "SANTOS",
"UF": "SP"
}
},
"infModal": {
"versaoModal": "3.00",
"aquav": {
"irin": "1234567",
"tpEmb": "10",
"cEmbar": "1234",
"xEmbar": "EMBARCACAO EXEMPLO",
"nViag": "1",
"cPrtEmb": "BRSSZ",
"cPrtDest": "BRBEL"
}
},
"infDoc": {
"infMunDescarga": [
{
"cMunDescarga": "1501402",
"xMunDescarga": "Belém",
"infNFe": [
{ "chNFe": "35260512345678000199550010000000011000000018" }
]
}
]
},
"prodPred": {
"tpCarga": "01",
"xProd": "GRAOS DE SOJA"
},
"tot": {
"vCarga": 500000.00,
"cUnid": "02",
"qCarga": 50.00
}
}
Exemplo simplificado — Modal Ferroviário
{
"ide": {
"tpAmb": 2,
"tpEmit": 2,
"modal": "4",
"UFIni": "MG",
"UFFim": "SP",
"infMunCarrega": [
{ "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
]
},
"emit": {
"CNPJ": "12345678000199",
"IE": "123456789012",
"xNome": "FERROVIA EXEMPLO LTDA",
"enderEmit": {
"xLgr": "AV FERROVIARIA",
"nro": "300",
"xBairro": "INDUSTRIAL",
"cMun": "3106200",
"xMun": "BELO HORIZONTE",
"UF": "MG"
}
},
"infModal": {
"versaoModal": "3.00",
"ferrov": {
"trem": {
"xPref": "F123",
"dhTrem": "2026-05-21T08:00:00-03:00",
"xOri": "BELO HORIZONTE",
"xDest": "SANTOS",
"qVag": 2
},
"vag": [
{
"pesoBC": 30.000,
"pesoR": 30.000,
"tpVag": "Gôndola",
"serie": "100",
"nVag": "100001",
"nSeq": "1",
"TU": 28.000
},
{
"pesoBC": 30.000,
"pesoR": 30.000,
"tpVag": "Gôndola",
"serie": "101",
"nVag": "100002",
"nSeq": "2",
"TU": 28.000
}
]
}
},
"infDoc": {
"infMunDescarga": [
{
"cMunDescarga": "3548500",
"xMunDescarga": "Santos",
"infNFe": [
{ "chNFe": "35260512345678000199550010000000011000000018" }
]
}
]
},
"prodPred": {
"tpCarga": "01",
"xProd": "MINERIO DE FERRO"
},
"tot": {
"vCarga": 800000.00,
"cUnid": "02",
"qCarga": 56.00
}
}
Exemplo completo (todos os campos) — Modal Rodoviário
{
"ide": {
"tpAmb": 2,
"tpEmit": 2,
"tpTransp": "1",
"modal": "1",
"UFIni": "SP",
"UFFim": "ES",
"infMunCarrega": [
{ "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
],
"infPercurso": [
{ "UFPer": "MG" }
],
"dhIniViagem": "2026-05-21T08:00:00-03:00",
"indCanalVerde": "1",
"indCarregaPosterior": "0"
},
"emit": {
"CNPJ": "12345678000199",
"IE": "123456789012",
"xNome": "TRANSPORTADORA EXEMPLO LTDA",
"xFant": "Exemplo Transportes",
"enderEmit": {
"xLgr": "RUA EXEMPLO",
"nro": "100",
"xCpl": "GALPAO A",
"xBairro": "CENTRO",
"cMun": "3550308",
"xMun": "SAO PAULO",
"CEP": "01001000",
"UF": "SP",
"fone": "1133334444",
"email": "contato@exemplo.com"
}
},
"infModal": {
"versaoModal": "3.00",
"rodo": {
"infANTT": {
"RNTRC": "12345678",
"infCIOT": [
{ "CIOT": "1234567890", "CNPJ": "12345678000199" }
],
"valePed": {
"categCombVeic": "01",
"disp": [
{
"CNPJForn": "98765432000111",
"CNPJPg": "12345678000199",
"nCompra": "VP001",
"vValePed": 250.00,
"tpValePed": "01"
}
]
},
"infContratante": [
{
"xNome": "EMPRESA CONTRATANTE LTDA",
"CNPJ": "11222333000144"
}
],
"infPag": [
{
"xNome": "João da Silva",
"CPF": "12345678909",
"Comp": [
{ "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
],
"vContrato": 5000.00,
"indAltoDesemp": "1",
"indPag": "0",
"infBanc": {
"codBanco": "001",
"codAgencia": "1234",
"PIX": "12345678909"
}
}
]
},
"veicTracao": {
"cInt": "VT001",
"placa": "ABC1D23",
"RENAVAM": "12345678901",
"tara": 8000,
"capKG": 25000,
"capM3": 80,
"prop": {
"CNPJ": "12345678000199",
"RNTRC": "12345678",
"xNome": "TRANSPORTADORA EXEMPLO LTDA",
"IE": "123456789012",
"UF": "SP",
"tpProp": "0"
},
"condutor": [
{ "xNome": "João da Silva", "CPF": "12345678909" },
{ "xNome": "Maria Souza", "CPF": "98765432100" }
],
"tpRod": "01",
"tpCar": "01",
"UF": "SP"
},
"veicReboque": [
{
"cInt": "VR001",
"placa": "DEF4G56",
"RENAVAM": "98765432109",
"tara": 3500,
"capKG": 30000,
"capM3": 90,
"tpCar": "02",
"UF": "SP"
}
],
"lacRodo": [
{ "nLacre": "LACRE001" },
{ "nLacre": "LACRE002" }
]
}
},
"infDoc": {
"infMunDescarga": [
{
"cMunDescarga": "3205200",
"xMunDescarga": "Vila Velha",
"infNFe": [
{
"chNFe": "35260512345678000199550010000000011000000018",
"SegCodBarras": "",
"indReentrega": "0",
"infUnidTransp": [
{
"tpUnidTransp": "1",
"idUnidTransp": "UT001",
"qtdRat": 100.000,
"lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
"infUnidCarga": [
{
"tpUnidCarga": "1",
"idUnidCarga": "UC001",
"qtdRat": 100.000,
"lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
}
]
}
],
"peri": []
}
]
}
]
},
"seg": [
{
"infResp": {
"respSeg": "1",
"CNPJ": "12345678000199"
},
"infSeg": {
"xSeg": "SEGURADORA EXEMPLO SA",
"CNPJ": "55666777000188"
},
"nApol": "APOL-2026-001",
"nAver": ["AV001", "AV002"]
}
],
"prodPred": {
"tpCarga": "05",
"xProd": "CARGA GERAL",
"cEAN": "7891234567890",
"NCM": "84713012",
"infLotacao": {
"infLocalCarrega": {
"CEP": "01001000",
"latitude": "-23.5505",
"longitude": "-46.6333"
},
"infLocalDescarrega": {
"CEP": "29100000",
"latitude": "-20.3297",
"longitude": "-40.2925"
}
}
},
"tot": {
"qCTe": 0,
"qNFe": 1,
"qMDFe": 0,
"vCarga": 50000.00,
"cUnid": "01",
"qCarga": 1500.00
},
"lacres": [
{ "nLacre": "LACRE-GERAL-001" }
],
"autXML": [
{ "CNPJ": "11222333000144" }
],
"infAdic": {
"infAdFisco": "Documento emitido em conformidade com a legislação vigente",
"infCpl": "Transporte com escolta armada"
},
"infRespTec": {
"CNPJ": "12345678000199",
"xContato": "Suporte Técnico",
"email": "suporte@exemplo.com",
"fone": "1133334444"
}
}
Resposta de sucesso
{
"success": true,
"data": {
"chMDFe": "35260512345678000199580010000000011000000018",
"nMDF": 1,
"serie": 1,
"protocolo": "135260000123456",
"xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
}
}
POST
Consultar situação do MDF-e
/api/mdfe/consult
Consulta a situação do MDF-e diretamente na SEFAZ a partir da chave de acesso.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| chMDFe * | string | Chave de acesso do MDF-e (44 dígitos) |
* Campo obrigatório.
Exemplo de payload
{
"chMDFe": "35260512345678000199580010000000011000000018"
}
Resposta
{
"success": true,
"data": {
"chMDFe": "35260512345678000199580010000000011000000018",
"cStat": 100,
"xMotivo": "Autorizado o uso do MDF-e",
"protocolo": "135260000123456",
"dhRecbto": "2026-05-21T10:30:00-03:00",
"encerrado": false,
"cancelado": false
}
}
POST
Cancelar MDF-e
/api/mdfe/cancel
Cancela um MDF-e autorizado. Janela: até 24 horas após a autorização. Não permitido se o MDF-e já tiver sido encerrado.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| chMDFe * | string | Chave de acesso do MDF-e (44 dígitos) |
| xJust * | string | Justificativa do cancelamento (mínimo 15 caracteres por exigência SEFAZ) |
* Campo obrigatório.
Exemplo de payload
{
"chMDFe": "35260512345678000199580010000000011000000018",
"xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
}
Resposta
{
"success": true,
"data": {
"chMDFe": "35260512345678000199580010000000011000000018",
"cStat": 135,
"xMotivo": "Evento registrado e vinculado a MDF-e",
"nProt": "135260000123457",
"dhRegEvento": "2026-05-21T11:00:00-03:00"
}
}
POST
Encerrar MDF-e
/api/mdfe/close
Encerra um MDF-e ao final da viagem. Após o encerramento, não é mais possível cancelar. Os campos dtEnc, cUF e cMun são opcionais — quando omitidos, o sistema infere a partir do MDF-e original (data atual, UF e município do emitente).
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa emissora |
| sign | string | Assinatura MD5 |
| timestamp | string | Unix timestamp em segundos |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| chMDFe * | string | Chave de acesso do MDF-e (44 dígitos) |
| dtEnc | string | Data do encerramento (AAAA-MM-DD). Default: data atual |
| cUF | int | Código IBGE da UF onde ocorreu o encerramento. Default: UF do emitente |
| cMun | string | Código IBGE do município onde ocorreu o encerramento. Default: município do emitente |
* Campo obrigatório.
Exemplo de payload
{
"chMDFe": "35260512345678000199580010000000011000000018",
"dtEnc": "2026-05-22",
"cUF": 32,
"cMun": "3205200"
}
Resposta
{
"success": true,
"data": {
"chMDFe": "35260512345678000199580010000000011000000018",
"cStat": 135,
"xMotivo": "Evento registrado e vinculado a MDF-e",
"nProt": "135260000123458",
"dhRegEvento": "2026-05-22T18:00:00-03:00"
}
}
SSO — Login Automático via Token
Base URL (Produção)
https://api.tffiscal.com
Autenticação
Headers: sign, timestamp, token
Validade do Ticket
60 segundos — uso único
O SSO (Single Sign-On) permite que seu ERP gere um link de acesso direto ao TFiscal para o usuário, já autenticado na empresa correspondente e no idioma desejado — sem que ele precise digitar credenciais.
Como funciona:
- O ERP chama
POST /api/sso/create_ticketenviando o token da empresa. - A TFiscal devolve um
redirectUrlcontendo um ticket opaco de uso único. - O ERP redireciona o navegador do usuário para essa URL.
- A página consome o ticket e o usuário entra logado no painel da empresa.
⚠️ Segurança: o token real da empresa nunca aparece na URL. Apenas o ticket efêmero (válido por 60 segundos e de uso único) transita pelo navegador.
POST
Gerar link de login automático
/api/sso/create_ticket
Gera um ticket de uso único que pode ser usado em até 60 segundos para logar automaticamente o usuário no painel da empresa correspondente ao token.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa (o mesmo usado para emitir NF-e) |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Payload
{
"token": "TOKEN_DA_EMPRESA",
"language": "br",
"page": "emitir_nfe"
}
Campos
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| token | Sim | string | Token da empresa (w_company.token) — o mesmo usado em /api/invoice/create |
| language | Não | string | Idioma da interface: br, en, zh, es, ja, ko. Default: br |
| page | Não | string | Página de destino após o login. Valores aceitos: emitir_nfe. Vazio ou ausente abre o painel padrão (/company/kanban). |
Resposta de sucesso
{
"success": true,
"message": "ticket",
"ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
"redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
"expiresInSeconds": 60,
"expiresAt": "2026-04-24T18:34:56.0000000Z"
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| success | boolean | true quando o ticket foi gerado com sucesso |
| ticket | string | Ticket opaco (aleatório, 32 bytes base64url) |
| redirectUrl | string | URL completa para onde o ERP deve redirecionar o navegador do usuário |
| expiresInSeconds | number | Tempo de validade em segundos (sempre 60) |
| expiresAt | string | Data/hora UTC de expiração (ISO 8601) |
Respostas de erro
| Mensagem | Causa |
|---|---|
Token é obrigatório |
Campo token não foi enviado no body |
Token inválido |
Token não corresponde a nenhuma empresa cadastrada |
Este token está vinculado a múltiplas empresas. Envie o token da empresa que deseja acessar. |
Token de integrador com mais de uma empresa — envie o token específico da empresa desejada |
Rate limit exceeded |
Mais de 30 chamadas por minuto para o mesmo token |
POST
Consumir ticket e receber o JWT de sessão
/api/sso/consume_ticket
Troca o ticket gerado por /api/sso/create_ticket pelo JWT de sessão da TFiscal. Endpoint chamado pelo frontend (rota /sso) e não requer headers sign/timestamp — o próprio ticket opaco é a credencial. Cada ticket pode ser consumido apenas uma vez e expira em 60 segundos.
Body
| Campo | Tipo | Descrição |
|---|---|---|
| ticket * | string | Ticket retornado por create_ticket |
* Campo obrigatório.
Exemplo de payload
{
"ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
}
Resposta de sucesso
{
"success": true,
"message": "Login succeeded",
"access_token": "eyJhbGciOi...",
"type": "user",
"uid": 1234,
"company_id": 5678,
"language": "br",
"page": "emitir_nfe"
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| access_token | string | JWT de sessão (validade de 365 dias). Use no header Authorization das chamadas TFiscal |
| type | string | Tipo do usuário (user, admin, etc.) |
| uid | int | ID interno do usuário |
| company_id | int | ID da empresa selecionada no create_ticket |
| language | string | Idioma escolhido no create_ticket (sempre normalizado) |
| page | string | Página de destino (ou string vazia se não definida) |
Respostas de erro
| Mensagem | Causa |
|---|---|
Ticket inválido | Body sem campo ticket |
Ticket inválido ou expirado | Ticket não existe, já foi consumido ou passou dos 60 segundos |
Rate limit exceeded | Mais de 60 consumos por minuto a partir do mesmo IP |
Sessão inválida | Usuário vinculado ao ticket não existe mais |
Restrições e Segurança
Características do ticket
| Característica | Valor |
|---|---|
| Validade | 60 segundos após geração |
| Uso | Único — após consumido, não pode ser reutilizado |
| Rate limit | 30 tickets/minuto por token · 60 consumos/minuto por IP |
| Armazenamento | MongoDB com TTL automático — tickets expirados são removidos |
Restrições de navegação
Usuários autenticados via SSO têm acesso apenas às telas da empresa correspondente
(/invoice/company/*). Tentativas de acessar outras áreas (painéis de revendedor,
relatórios gerais, administração) são redirecionadas automaticamente para o painel da empresa.
Sessão após o login
Após a troca do ticket por JWT, o usuário possui uma sessão normal na TFiscal (JWT com validade de 365 dias, igual ao login tradicional). Os 60 segundos são apenas a janela entre gerar o ticket e abrir o link — depois disso o usuário fica logado normalmente até sair.
⚠️ Importante: o
create_ticket deve ser chamado exclusivamente
server-side pelo ERP. Nunca chame esse endpoint diretamente do navegador —
isso exporia o token da empresa no front-end.
Contador (Accountant)
API para consulta dos dados de cadastro de contadores vinculados a uma empresa. Útil para sistemas contábeis externos que precisam buscar dados completos do contador responsável por uma determinada empresa.
POST
Obter informações do contador vinculado à empresa
/api/accountant/get_info
Retorna os dados completos de cadastro do contador vinculado à empresa informada. O contador precisa estar previamente vinculado à empresa (mesmo CNPJ) e o e-mail informado deve coincidir com o cadastro.
Headers obrigatórios
| Header | Tipo | Descrição |
|---|---|---|
| token | string | Token da empresa ou token B2B do integrador |
| sign | string | Assinatura MD5: MD5(token + path + body + timestamp) |
| timestamp | string | Unix timestamp em segundos (janela de 5 minutos) |
Body
| Campo | Tipo | Descrição |
|---|---|---|
| companyId * | int | ID da empresa vinculada ao token |
| accountantId * | string | ObjectId do contador (24 hex) |
| email * | string | E-mail do contador (deve coincidir com o cadastro) |
* Campo obrigatório.
Exemplo de payload
{
"companyId": 12345,
"accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
"email": "contador@escritorio.com"
}
Resposta de sucesso
{
"success": true,
"data": {
"email": "contador@escritorio.com",
"officeDocumentType": "CNPJ",
"officeDocument": "12345678000199",
"officeName": "Escritório Contábil LTDA",
"responsibleName": "João da Silva",
"crc": "SP123456/O-7",
"accountantCpf": "12345678909",
"workAddress": "Rua Exemplo, 100 - Centro - São Paulo/SP",
"site": "https://escritorio.com",
"landline": "1133334444",
"mobile": "11999998888",
"assistantName": "Maria Souza",
"assistantEmail": "maria@escritorio.com",
"assistantPhone": "11988887777",
"observations": "Atendimento de segunda a sexta, 9h às 18h"
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
| string | E-mail principal do contador | |
| officeDocumentType | string | Tipo do documento do escritório: "CNPJ" ou "CPF" |
| officeDocument | string | Documento do escritório (apenas dígitos) |
| officeName | string | Razão social / nome do escritório |
| responsibleName | string | Nome do contador responsável |
| crc | string | Número do CRC (Conselho Regional de Contabilidade) |
| accountantCpf | string | CPF do contador (apenas dígitos) |
| workAddress | string | Endereço comercial |
| site | string | Site do escritório |
| landline | string | Telefone fixo |
| mobile | string | Celular |
| assistantName | string | Nome do assistente |
| assistantEmail | string | E-mail do assistente |
| assistantPhone | string | Telefone do assistente |
| observations | string | Observações livres do cadastro |
Respostas de erro
| Mensagem | Causa |
|---|---|
| 会计师ID参数异常或不存在 | accountantId ausente ou não é um ObjectId válido |
| 该会计师邮箱异常或不存在 | email inválido ou não cadastrado |
| 发票账号{companyId}异常或不存在 | companyId não pertence ao usuário do token |
| 该会计师未绑定该发票账号 | O contador não está vinculado à empresa informada |