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.

list_alt

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.

sync_alt

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.

business

1. Criar Empresa

Criar informações fiscais da empresa local no Brasil

send

2. Push de Informações

Dados do pedido (usuário, endereço, impostos do produto)

receipt

3. Emitir Nota Fiscal

Processar e enviar para autorização SEFAZ

assignment_returned

4. Retornar Resultado

Status da emissão e dados da NF-e

description

5. Gerar Arquivos

XML e PDF da nota fiscal

published_with_changes

Verificação Fiscal

Validação com SEFAZ

check_circle

Sucesso

error

Falha

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.

flash_on

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
business 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
category 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
receipt 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
receipt 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
`/api/nfce/get_list`	GET	Listar NFC-e (paginado)
description 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
`/api/nfse/get_list`	GET	Listar NFS-e (paginado)
`/api/nfs/company/create`	POST	Cadastrar empresa para emissão de NFS-e
receipt_long NF-e — Eventos e Consultas
`/api/invoice/get_danfe`	POST	Obter DANFE (PDF) da NF-e
`/api/invoice/consultar_status`	POST	Consultar status da NF-e/NFC-e na SEFAZ
`/api/invoice/validar_cpf_cnpj`	POST	Validar CPF/CNPJ na base da Receita Federal
`/api/invoice/cce/send`	POST	Enviar Carta de Correção (CC-e)
`/api/invoice/cce/get_list`	POST	Listar CC-e de uma NF-e
`/api/invoice/cce/download_pdf`	POST	Baixar PDF da CC-e
`/api/invoice/cce/download_xml`	POST	Baixar XML da CC-e
mark_email_read NF-e — Manifestação e Notas Recebidas
`/api/invoice/manifest`	POST	Enviar evento de manifestação do destinatário
`/api/invoice/manifest/list`	POST	Listar manifestações enviadas
`/api/invoice/manifest/get_xml`	POST	Obter XML de uma manifestação
`/api/invoice/received/sync`	POST	Sincronizar NF-es/eventos recebidos (DistDFe)
`/api/invoice/received/list`	POST	Listar documentos recebidos
`/api/invoice/received/get_xml`	POST	Obter XML de documento recebido
`/api/invoice/received/get_sync_status`	POST	Consultar estado da sincronização DistDFe
category NFC-e — Categorias Fiscais
`/api/nfce/category/create`	POST	Criar categoria fiscal NFC-e
`/api/nfce/category/edit`	POST	Editar categoria fiscal NFC-e
`/api/nfce/category/delete`	POST	Excluir categoria fiscal NFC-e
`/api/nfce/category/get_detail`	GET	Obter detalhes da categoria NFC-e
`/api/nfce/category/get_list`	GET	Listar categorias fiscais NFC-e
local_shipping MDF-e (Manifesto Eletrônico de Documentos Fiscais)
`/api/mdfe/create`	POST	Emitir MDF-e
`/api/mdfe/consult`	POST	Consultar situação do MDF-e
`/api/mdfe/cancel`	POST	Cancelar MDF-e
`/api/mdfe/close`	POST	Encerrar MDF-e
`/api/mdfe/get_list`	GET	Listar MDF-e (paginado)
inventory_2 DC-e (Declaração de Conteúdo Eletrônica)
`/api/dce/create`	POST	Emitir DC-e
`/api/dce/consult`	POST	Consultar situação da DC-e
`/api/dce/cancel`	POST	Cancelar DC-e
`/api/dce/pdf`	POST	Obter DACE (PDF) da DC-e
`/api/dce/get_list`	GET	Listar DC-e (paginado)
local_shipping CT-e (Conhecimento de Transporte Eletrônico)
`/api/cte/create`	POST	Emitir CT-e
`/api/cte/cancel`	POST	Cancelar CT-e
`/api/cte/cce`	POST	Carta de Correção (CC-e)
`/api/cte/desacordo`	POST	Prestação em Desacordo
`/api/cte/consult`	POST	Consultar situação do CT-e
`/api/cte/inutilize`	POST	Inutilizar faixa de numeração
`/api/cte/get_list`	GET	Listar CT-e (paginado)
vpn_key SSO (Login Automático)
`/api/sso/create_ticket`	POST	Gerar link de login automático
`/api/sso/consume_ticket`	POST	Consumir ticket e receber o JWT de sessão
account_balance Contador
`/api/accountant/get_info`	POST	Obter informações do contador vinculado à empresa

📋 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, message e data

200

Sucesso

Requisição processada com sucesso

400

Erro do Cliente

Dados inválidos ou faltantes

500

Erro do Servidor

Erro interno no servidor

account_balance

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

sync_alt Fluxo do Sistema

input Dados de Entrada

Informações do Cliente
Dados dos Produtos
Informações Fiscais
Dados de Transporte

settings Processamento

Validação dos dados
Cálculo de impostos
Geração do XML
Autorização SEFAZ

download Saída

XML da nota fiscal
PDF da nota fiscal
DANFE (Documento Auxiliar)
Status de autorização

Endpoints Principais

POST /api/company/create

Cadastrar nova empresa emissora

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
email	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
Transporte (MDF-e / CT-e / DC-e)
serie_mdfe	int	Série do MDF-e
number_mdfe	int	Número inicial do MDF-e (onde a numeração começa)
serie_cte	int	Série do CT-e
number_cte	int	Número inicial do CT-e (onde a numeração começa)
serie_dce	int	Série da DC-e
number_dce	int	Número inicial da DC-e (onde a numeração começa)
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,
          "serie_mdfe": 2,
          "number_mdfe": 1,
          "serie_cte": 3,
          "number_cte": 1,
          "serie_dce": 4,
          "number_dce": 1
        }

Resposta

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

Cadastrar empresa com auto-preenchimento via certificado

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 /api/company/edit

Editar dados da empresa

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.

A empresa é criada com a configuração de NF-e (via /api/company/create). Para habilitar os demais documentos, complete o cadastro por aqui: este endpoint também aceita os campos de NFC-e, NFS-e, MDF-e, CT-e e DC-e (ver seções abaixo). Envie apenas os campos do(s) documento(s) que a empresa vai emitir.

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
email	string	E-mail
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 da NF-e
alias	string	Nome fantasia
telefone	string	Telefone
complemento	string	Complemento do endereço
NFC-e
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	Próximo número da NFC-e
NFS-e
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)
cnae_nfse	string	CNAE da atividade padrão
serie_nfse	int	Série da NFS-e
number_nfse	int	Próximo número da NFS-e
regime_especial_tributacao	int	Código do regime especial de tributação
optante_simples_nacional	bool	Optante pelo Simples Nacional
Transporte (MDF-e / CT-e / DC-e)
serie_mdfe	int	Série do MDF-e
number_mdfe	int	Número inicial do MDF-e (onde a numeração começa)
serie_cte	int	Série do CT-e
number_cte	int	Número inicial do CT-e (onde a numeração começa)
serie_dce	int	Série da DC-e
number_dce	int	Número inicial da DC-e (onde a numeração começa)

* Campo obrigatório. Enviar cnpj retorna erro. Todos os demais campos são opcionais — envie só os que quiser alterar.

Exemplo de payload

        {
          "company_id": "comp_789012",
          "name": "Nova Razão Social LTDA",
          "email": "novo@empresa.com",
          "cep": "01310100"
        }

Exemplo — habilitar NFC-e e CT-e na empresa

        {
          "company_id": "comp_789012",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "serie_cte": 1,
          "number_cte": 1
        }

Resposta

        {
          "success": true
        }

GET /api/company/get_list

Listar empresas do distribuidor

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 /api/company/get_detail

Detalhes da empresa autenticada

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 /api/company/get_cep_detail

Consultar endereço por CEP

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 /api/company/get_export_invoice_month_files

Listar arquivos de exportação mensal já gerados

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 /api/category/get_list

Listar categorias de produtos

Retorna todas as categorias disponíveis para classificação fiscal.

POST /api/invoice/create

Emitir nova nota fiscal

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
email	string	E-mail
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
email	string	E-mail

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 /api/invoice/get_list

Listar NF-e (com paginação)

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: `"Success"` (autorizada), `"Canceled"` (cancelada), `"Voided"` (inutilizada), `"Processing"` (em processamento), `"InvoicingFailed"` (falha na emissão), `"Failed"` (falhou), `"Contingencia"` (contingência offline), `"Unknown"` (desconhecida)

* Campo obrigatório.

Exemplo de chamada

GET /api/invoice/get_list?page=1&page_size=20&status=Success

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Success",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET /api/invoice/get_detail

Consultar detalhes da NF-e

Retorna os detalhes de uma NF-e específica pelo UUID ou pela chave de acesso. 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
chave	string	Chave de acesso da NF-e (44 dígitos)

Informe uuid ou chave (pelo menos um). Se ambos forem enviados, o uuid tem prioridade.

Exemplo de chamada

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9
GET /api/invoice/get_detail?chave=35210112345678901234567890123456789012345678

Resposta

        {
          "success": true,
          "data": {
            "id": "pedido-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Success",
            "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 /api/invoice/refresh

Atualizar status da nota fiscal

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 /api/invoice/cancel

Cancelar nota fiscal

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 /api/invoice/invalid

Inutilizar faixa de numeração

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 /api/invoice/get_danfe

Obter DANFE (PDF) da NF-e

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 /api/invoice/get_xml

Exportar XML/Excel em lote (assíncrono)

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 /api/invoice/consultar_status

Consultar status da NF-e/NFC-e na SEFAZ

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 /api/category/create

Criar categoria fiscal

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" }],
          "ibs_cbs":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "000", "classificacao_tributaria": "000001" }]
        }

Resposta

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

Detalhes da categoria fiscal

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 /api/category/get_list

Listar categorias fiscais

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 /api/category/edit

Editar categoria fiscal

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 /api/category/delete

Excluir categoria fiscal

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 /api/invoice/return

Emitir NF-e de devolução

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 — a devolução é um clone integral da nota) ou devolução parcial/customizada (envia chave + os campos completos da nota no próprio body, mesma estrutura do /api/invoice/create).

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 (devolução total; obrigatório se `chave` ausente). Se enviado, a devolução é sempre total — os campos da devolução parcial são ignorados
chave	string	Chave de 44 dígitos da NF-e original (obrigatória na devolução parcial; alternativa a `uuid` na devolução total)
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`
transaction_type	string	Tipo de operação: `"0"`=entrada, `"1"`=saída (obrigatório na devolução parcial). A devolução é sempre emitida como entrada (`tpNF=0`)
model	string	Modelo do documento: `"55"` (obrigatório na devolução parcial)
issuance_type	string	Tipo de emissão: `"1"`=normal (obrigatório na devolução parcial)
ambiente	string	Ambiente: `"1"`=produção, `"2"`=homologação (obrigatório na devolução parcial)
cliente	object	Dados do destinatário, mesma estrutura do `/api/invoice/create` (obrigatório na devolução parcial). Peculiaridade: o campo do número do endereço é `number` (em inglês), não `numero`. Sem `number`, o endereço sai com nro "S/N"; código IBGE, cidade e UF são resolvidos pelo `cep`
products	array	Itens devolvidos, mesma estrutura do `/api/invoice/create` (obrigatório na devolução parcial). `codigo` é opcional — sem ele, o cProd usa o `name`

* Campo obrigatório. uuid OU chave também é obrigatório (exatamente um).

Automático na devolução: o pagamento sai como 90 (Sem Pagamento) — pag_info é ignorado; natureza_operacao vazia usa "Devolução de Mercadoria"; a tributação dos itens (CST/CSOSN, PIS/COFINS, IPI, IBS/CBS) vem da categoria fiscal do category_id, conforme tipo de pessoa e cenário.

Exemplo — devolução total

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

Exemplo — devolução parcial (campos completos no body)

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "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
            }
          ]
        }

code Exemplos Completos de Emissão de NF-e

Exemplo Completo com Transporte

        {
          "nature_of_operation": "Venda de mercadoria",
          "transaction_type": "1",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "2",
          "ind_final": "0",
          "ind_pres": "1",
          "cliente": {
            "cnpj": "12345678000199",
            "ie": "123456789",
            "name": "Empresa Cliente Ltda",
            "endereco": "Rua Exemplo",
            "number": "123",
            "complemento": "Sala 45",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01234567",
            "telefone": "11999999999",
            "email": "contato@empresa.com"
          },
          "products": [
            {
              "codigo": "PROD001",
              "name": "Smartphone XYZ",
              "ncm": "85171210",
              "cest": "2804000",
              "count": 2,
              "unit": "UN",
              "unit_price": 1500.00,
              "total_price": 3000.00,
              "category_id": "YOUR_CATEGORY_ID",
              "origem": "0",
              "indicador_total": "1"
            }
          ],
          "transportation": {
            "transport_mode": "0",
            "freight_amount": 30.00,
            "carrier_info": {
              "cnpj": "12345678000188",
              "name": "Transportadora Expressa",
              "endereco": "Rua da Transportadora",
              "city": "São Paulo",
              "uf": "SP"
            },
            "vehicle_info": {
              "plate": "ABC1234",
              "uf": "SP",
              "rntc": "123456"
            },
            "packages": [
              {
                "qty": 1,
                "packaging_type": "CX",
                "gross_weight": 2.500,
                "net_weight": 2.000
              }
            ]
          },
          "shipping_address": {
            "cnpj": "12345678000199",
            "name": "Remetente Ltda",
            "endereco": "Rua do Remetente",
            "number": "100",
            "bairro": "Centro",
            "city": "São Paulo",
            "uf": "SP",
            "cep": "01001000"
          },
          "delivery_address": {
            "cnpj": "98765432000111",
            "name": "Destinatário Ltda",
            "endereco": "Rua do Destinatário",
            "number": "200",
            "bairro": "Centro",
            "city": "Rio de Janeiro",
            "uf": "RJ",
            "cep": "20040020"
          },
          "pag_info": [
            {
              "payment_method": "03",
              "payment_indicator": "0",
              "card_info": {
                "integration_type": "1",
                "brand_code": "01"
              }
            }
          ],
          "informacoes_complementares": "Sem informações adicionais",
          "informacoes_fisco": "ICMS recolhido conforme legislação"
        }

💡 INFORMAÇÃO: Este exemplo inclui todos os campos importantes, incluindo transporte, informações fiscais detalhadas e pagamento. Adapte os valores conforme suas necessidades específicas.

Exemplo Completo de Importação

        {
          "id": "PED-IMP-001",
          "nature_of_operation": "Importacao para revenda",
          "transaction_type": "2",
          "model": "55",
          "issuance_type": "1",
          "ambiente": "1",
          "finalidade": "1",
          "ind_final": "0",
          "ind_pres": "9",
          "cliente": {
            "name": "EXPORTADOR EXTERIOR CO LTD",
            "endereco": "Pudong District",
            "numero": "456",
            "city": "Shanghai",
            "id_estrangeiro": "CN-EXP-001",
            "c_pais": 1600,
            "x_pais": "CHINA"
          },
          "products": [
            {
              "name": "Fonte chaveada 12V 2A Quickfitting",
              "codigo": "123450000888",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 0.01,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 1,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            },
            {
              "name": "Quick fitting MA",
              "codigo": "123450000157",
              "ncm": "85044090",
              "count": 2,
              "unit": "PC",
              "unit_price": 0.25,
              "total_price": 0.50,
              "origem": 1,
              "indicador_total": "1",
              "category_id": "YOUR_CATEGORY_ID",
              "ii": {
                "vBC": 0.50,
                "vDespAdu": 0.00,
                "vII": 0.00,
                "vIOF": 0.00
              },
              "import_declarations": [
                {
                  "nDI": "2312345678",
                  "dDI": "2026-04-12",
                  "xLocDesemb": "PORTO DE SANTOS",
                  "UFDesemb": "SP",
                  "dDesemb": "2026-04-15",
                  "tpViaTransp": 1,
                  "vAFRMM": 1.00,
                  "tpIntermedio": 1,
                  "cExportador": "EXP-CN-001",
                  "additions": [
                    {
                      "nAdicao": 1,
                      "nSeqAdic": 2,
                      "cFabricante": "FAB-CN-001",
                      "vDescDI": 0,
                      "nDraw": ""
                    }
                  ]
                }
              ]
            }
          ],
          "pag_info": [
            {
              "payment_method": "90",
              "payment_indicator": "0"
            }
          ]
        }

💡 INFORMAÇÃO: Exemplo para NFe de Importação (CFOP 3.xxx). Diferenças em relação a uma NFe nacional:

transaction_type: "2" — operação de entrada (importação).
cliente sem cnpj/cpf/uf/cep; usa id_estrangeiro, c_pais (tabela BACEN — China = 1600) e x_pais.
category_id deve apontar para uma categoria fiscal com CFOP 3.xxx e CST/CSOSN compatíveis com importação.
origem do produto = 1 (estrangeira — importação direta) ou 2 (estrangeira — adquirida no mercado interno).
O bloco ii (Imposto de Importação) é obrigatório quando o CFOP é 3.xxx. Os valores vêm da DI emitida pelo despachante aduaneiro (vBC, vDespAdu, vII, vIOF). Podem ser zero para teste.
O bloco import_declarations (Declaração de Importação) contém os dados do desembaraço aduaneiro: nDI, dDI, local/UF/data do desembaraço, via de transporte, intermediação, exportador e adições.
vAFRMM é obrigatório quando tpViaTransp = 1 (Marítima).

percent Parâmetros Tributários Detalhados

scale_balance 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

51: Diferimento

60: ICMS cobrado anteriormente

70: Com redução e cobrança

90: Outras

pie_chart Parâmetros PIS/COFINS

Cenário de Tributação

padrao saida_fora_estado 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").

credit_card 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

bug_report Solução de Problemas com XML

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

Verificar se a NF-e foi autorizada (status "Autorizada")

Reemitir a NF-e se não foi autorizada

Inutilizar número se não foi utilizado

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

error 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 /api/nfce/company/create

Cadastrar empresa para NFC-e

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 /api/nfce/company/update

Atualizar dados da empresa NFC-e

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
email	string	E-mail
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 /api/nfce/company/get

Consultar empresa NFC-e

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 /api/nfce/category/create

Criar categoria fiscal NFC-e

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 /api/nfce/category/get_detail

Obter detalhes da categoria fiscal NFC-e

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 /api/nfce/category/get_list

Listar categorias fiscais NFC-e

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 /api/nfce/category/edit

Editar categoria fiscal NFC-e

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 /api/nfce/category/delete

Excluir categoria fiscal NFC-e

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 /api/nfce/create

Emitir NFC-e

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
email	string	E-mail

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 /api/nfce/cancel

Cancelar NFC-e

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 /api/nfce/get_detail

Consultar detalhes da NFC-e

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": "Success",
            "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 /api/nfce/get_danfe

Gerar/obter DANFE NFC-e (cupom térmico)

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

GET /api/nfce/get_list

Listar NFC-e (com paginação)

Lista as NFC-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: `"Success"` (autorizada), `"Canceled"` (cancelada), `"Processing"` (em processamento), `"Failed"` (falhou), `"Unknown"` (desconhecida)

* Campo obrigatório.

Exemplo de chamada

GET /api/nfce/get_list?page=1&page_size=20&status=Success

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35260112345678000190650010000000011000000017",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

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

tune 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)

description 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 /api/nfs/company/create

Cadastrar empresa para emissão de NFS-e

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
email	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 /api/nfse/create

Emitir NFS-e

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)
email	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 /api/nfse/cancel

Cancelar NFS-e

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 /api/nfse/get_danfse

Obter DANFSE (PDF)

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 /api/nfse/get_xml

Download XML da NFS-e

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": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_dps.xml",
            "nfseXml": "https://tffiscal-file.tffiscal.com/123/12345678000190/nfse/Z685RI9C_nfse.xml"
          }
        }

dpsXml: Link (URL no OSS) do XML enviado para a prefeitura/ADN. nfseXml: Link do XML de retorno com o resultado da emissao. Os XMLs sobem ao OSS na primeira consulta e a URL fica em cache.

POST /api/invoice/create

Emitir NFe Complementar (finalidade = 2)

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 /api/invoice/create

Emitir NFe de Ajuste (finalidade = 3)

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)

edit_note 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 /api/invoice/cce/send

Enviar Carta de Correção (CC-e)

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 /api/invoice/cce/get_list

Listar CC-e de uma NF-e

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 /api/invoice/cce/download_pdf

Baixar PDF da CC-e

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 /api/invoice/cce/download_xml

Baixar XML da CC-e

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

how_to_reg 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 /api/invoice/manifest

Enviar evento de manifestação do destinatário

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 /api/invoice/manifest/list

Listar manifestações enviadas (histórico)

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 /api/invoice/manifest/get_xml

Obter URL do XML de uma manifestação específica

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

cloud_download 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/list filtrando por doc_type: "resNFe" para ver notas sem Ciência
Para cada chave de interesse, chame /invoice/manifest com tipo_evento: 210210
Chame /received/sync novamente — agora o SEFAZ devolve os procNFe (XML completo) das chaves manifestadas
Use /received/get_xml para 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 /api/invoice/received/sync

Sincronizar — baixar NFes/eventos novos do SEFAZ via DistDFe

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 ultNSU persistido para esse (uid + cnpj)
Faz loop chamando o SEFAZ até cStat ≠ 138 ou atingir max_iterations
Descomprime os XMLs (gzip) retornados
Persiste cada documento em w_invoice_received com upload do XML no OSS
Atualiza ultNSU e maxNSU em w_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 /api/invoice/received/list

Listar documentos (NFes e eventos) capturados

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 /api/invoice/received/get_xml

Obter URL do XML de um documento recebido específico

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ência
procNFe — XML completo e assinado, equivalente ao gerado pela emissão. Pronto para importar no ERP do cliente
procEvento — 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 /api/invoice/received/get_sync_status

Consultar estado atual da sincronização DistDFe (sem chamar SEFAZ)

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.

GET /api/nfse/get_list

Listar NFS-e (com paginação)

Lista as NFS-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: `"autorizada"`, `"cancelada"`, `"pendente"`, `"rejeitada"`

* Campo obrigatório.

Exemplo de chamada

GET /api/nfse/get_list?page=1&page_size=20&status=autorizada

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "31250112345678000190000000000012345678901234",
                "codigo_verificacao": "ABCD-1234",
                "serie": 1,
                "number": 1,
                "status": "autorizada",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping 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 /api/mdfe/create

Emitir MDF-e

Emite um MDF-e a partir do corpo enviado. Os campos cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc são calculados automaticamente pelo servidor. O cliente envia apenas os campos de negócio. Os campos serie e nMDF são opcionais: quando omitidos (ou 0) o servidor aloca a numeração automaticamente; quando enviados no request, são respeitados (útil para pular a numeração, por exemplo após uma duplicidade na SEFAZ).

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
serie	int	Série do MDF-e (3 dígitos da chave de acesso). Opcional — auto-alocada (série de MDF-e da empresa) quando omitida ou `0`; respeitada quando enviada
nMDF	int	Número do MDF-e (compõe a chave de acesso). Opcional — auto-incrementado pelo servidor quando omitido ou `0`; respeitado quando enviado (útil para pular a numeração, ex.: após uma duplicidade)

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 /api/mdfe/consult

Consultar situação do MDF-e

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 /api/mdfe/cancel

Cancelar MDF-e

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 /api/mdfe/close

Encerrar MDF-e

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

GET /api/mdfe/get_list

Listar MDF-e (com paginação)

Lista os MDF-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Voided"` (encerrado), `"Processing"` (em processamento), `"Failed"` (falhou), `"Unknown"` (desconhecido)

* Campo obrigatório.

Exemplo de chamada

GET /api/mdfe/get_list?page=1&page_size=20&status=Success

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190580010000000011000000015",
                "serie": 1,
                "number": 1,
                "modal": "1",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

inventory_2 DC-e — Declaração de Conteúdo Eletrônica

A API de DC-e (modelo 99, leiaute 1.00) permite emitir, consultar, cancelar e obter o PDF (DACE) de declarações de conteúdo eletrônicas. A DC-e é o documento fiscal que ampara o transporte de bens ou mercadorias quando não há obrigatoriedade de emissão de nota fiscal — por exemplo, remessas envolvendo não contribuintes do ICMS. O emitente é sempre pessoa jurídica (CNPJ); o destinatário pode ser pessoa jurídica (CNPJ) ou física (CPF). Os dados de negócio vão no corpo do /create; os campos técnicos da chave de acesso (cDC, cDV, cUF, dhEmi, mod) são calculados automaticamente pelo servidor.

Endpoint	Método	Descrição
`/api/dce/create`	POST	Emitir DC-e
`/api/dce/consult`	POST	Consultar situação da DC-e
`/api/dce/cancel`	POST	Cancelar DC-e autorizada
`/api/dce/pdf`	POST	Obter o DACE (PDF) da DC-e

A DC-e é roteada para o autorizador da UF do emitente. O campo ide.cUF deve ser coerente com a UF informada em emit.enderEmit.UF — a SEFAZ rejeita com cStat=220 quando divergem; se omitido, o cUF é derivado dessa UF.

POST /api/dce/create

Emitir DC-e

Emite uma DC-e a partir do corpo enviado. O cliente envia apenas os dados de negócio; os campos de identificação técnica da chave de acesso são calculados pelo servidor (ver a nota abaixo da tabela ide). O débito de crédito ocorre somente em produção (tpAmb=1) e quando a DC-e é autorizada.

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 da DC-e
emit *	object	Dados do emitente/remetente (CNPJ; ou CPF via Marketplace — ver abaixo)
dest *	object	Dados do destinatário
det *	array	Itens/bens declarados — mínimo 1
total *	object	Totalizador da declaração
transp	object	Dados do transporte
marketplace	object	Dados do marketplace (apenas quando `ide.tpEmit=1`)
fisco	object	Dados do órgão do Fisco (apenas quando `ide.tpEmit=0`)
autXML	array	CNPJs/CPFs autorizados a acessar o XML
infAdic	object	Informações adicionais

Campos obrigatórios na requisição: ide.tpAmb; emit.CNPJ (14 dígitos) ou emit.CPF (11 dígitos, remetente PF via Marketplace — ver nota em emit), emit.xNome e emit.enderEmit (xLgr, nro, xBairro, cMun, xMun, CEP com 8 dígitos, UF); dest com CNPJ ou CPF, dest.xNome e dest.enderDest (mesmos campos de endereço); pelo menos 1 item em det com xProd, NCM (2 ou 8 dígitos), qCom > 0 e vProd > 0; e total.vDC > 0. Todos os demais campos são opcionais.

ide — Identificação

Campo	Tipo	Descrição
tpAmb *	int	Ambiente: `1`=produção, `2`=homologação. Único campo de `ide` realmente obrigatório.
tpEmit	int	Tipo de emitente: `0`=Aplicativo do Fisco, `1`=Marketplace, `2`=Emissor próprio. Opcional — default: `2`
cUF	int	Código IBGE da UF do emitente (2 dígitos). Opcional — derivado de `emit.enderEmit.UF` quando omitido. Se enviado, deve ser coerente com essa UF (a SEFAZ rejeita com `cStat=220` em caso de divergência)
serie	int	Série do documento fiscal (3 dígitos da chave de acesso) — identifica o conjunto de numeração da DC-e. Opcional — default: série de DC-e cadastrada na empresa
nDC	long	Número sequencial da DC-e (compõe a chave de acesso). Opcional — auto-incrementado pelo servidor quando omitido ou `0`
nSiteAutoriz	int	Identificação do site autorizador que processou a DC-e (1 dígito da chave de acesso). Normalmente `0` (site primário). Opcional — default: `0`
tpEmis	int	Forma de emissão: `1`=Normal, `9`=Contingência. Opcional — default: `1`

Preenchidos automaticamente pelo servidor — não é necessário enviá-los: mod (fixo em 99) e cDV (dígito verificador da chave) são sempre definidos pelo servidor; cDC (código numérico de 6 dígitos), dhEmi (data/hora de emissão) e verProc (versão do processo) são gerados quando omitidos. Os campos serie, nDC e cUF da tabela acima também são preenchidos automaticamente quando omitidos.

emit — Emitente / Remetente

Campo	Tipo	Descrição
CNPJ ⚠	string	CNPJ do emitente (14 dígitos). Preenchido com o CNPJ da empresa do token quando omitido
CPF ⚠	string	CPF do remetente pessoa física (11 dígitos). Só permitido na emissão via Marketplace — ver nota abaixo
xNome *	string	Nome ou razão social do emitente/remetente
enderEmit *	object	Endereço do emitente (ver estrutura abaixo)

Remetente pessoa física (CPF): pela regra da SEFAZ, um CPF não pode ser emissor próprio (tpEmit=2 exige CNPJ). Para emitir com um CPF como remetente, basta enviar emit.CPF (sem emit.CNPJ): o servidor define automaticamente tpEmit=1 (Marketplace), usa o CNPJ da sua empresa (do token) como emissor autorizado na chave de acesso e preenche o bloco marketplace com os dados da empresa. O CPF informado aparece como remetente no emit.

dest — Destinatário

Campo	Tipo	Descrição
CNPJ ⚠	string	CNPJ do destinatário (14 dígitos)
CPF ⚠	string	CPF do destinatário (11 dígitos)
xNome *	string	Nome ou razão social do destinatário
enderDest *	object	Endereço do destinatário (ver estrutura abaixo)

enderEmit / enderDest — Endereço

Campo	Tipo	Descrição
xLgr *	string	Logradouro
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Bairro
cMun *	long	Código IBGE do município (7 dígitos)
xMun *	string	Nome do município
CEP *	string	CEP (8 dígitos)
UF *	string	Sigla da UF (2 letras)
cPais	int	Código do país. Default: `1058` (Brasil)
xPais	string	Nome do país. Default: `BRASIL`
fone	string	Telefone
email	string	E-mail

det[] — Itens declarados

Campo	Tipo	Descrição
nItem	int	Número sequencial do item
xProd *	string	Descrição do bem/mercadoria declarado
NCM *	string	Código NCM (2 ou 8 dígitos)
qCom *	decimal	Quantidade (> 0)
vUnCom	decimal	Valor unitário
vProd *	decimal	Valor total do item (> 0)
infAdProd	string	Informações adicionais do item

total — Totalizador

Campo	Tipo	Descrição
vDC *	decimal	Valor total declarado (> 0)

transp — Transporte

Campo	Tipo	Descrição
modTrans	int	Modalidade do transporte: `0`=Correios, `1`=própria, `2`=transportadora. Default: `2`
CNPJTransp	string	CNPJ da transportadora

marketplace — Marketplace (somente `tpEmit=1`)

Campo	Tipo	Descrição
CNPJ	string	CNPJ do marketplace
xNome	string	Nome do marketplace
Site	string	Site do marketplace

fisco — Órgão do Fisco (somente `tpEmit=0`)

Campo	Tipo	Descrição
CNPJ	string	CNPJ do órgão
xOrgao	string	Nome do órgão
UF	string	UF do órgão

autXML[] — Autorizados ao XML

Campo	Tipo	Descrição
CNPJ	string	CNPJ autorizado a consultar/baixar o XML
CPF	string	CPF autorizado a consultar/baixar o XML

infAdic — Informações adicionais

Campo	Tipo	Descrição
infAdFisco	string	Informações de interesse do Fisco
infCpl	string	Informações complementares de interesse do contribuinte
infAdMarketPlace	string	Informações adicionais do marketplace

* Campo obrigatório. ⚠ No emitente e no destinatário, pelo menos um de CNPJ ou CPF é obrigatório.

Exemplo simplificado (campos mínimos)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR"
            }
          },
          "dest": {
            "CPF": "12345678909",
            "xNome": "JOAO DA SILVA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR"
            }
          },
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00
            }
          ],
          "total": {
            "vDC": 150.00
          }
        }

Exemplo completo (todos os campos)

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "cUF": 41,
            "serie": 1,
            "nSiteAutoriz": 0
          },
          "emit": {
            "CNPJ": "12345678000199",
            "xNome": "EMPRESA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "SALA 2",
              "xBairro": "CENTRO",
              "cMun": 4106902,
              "xMun": "CURITIBA",
              "CEP": "80010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4133334444",
              "email": "contato@exemplo.com"
            }
          },
          "dest": {
            "CNPJ": "98765432000188",
            "xNome": "DESTINATARIO EXEMPLO LTDA",
            "enderDest": {
              "xLgr": "AVENIDA DESTINO",
              "nro": "500",
              "xCpl": "GALPAO 3",
              "xBairro": "JARDIM",
              "cMun": 4113700,
              "xMun": "LONDRINA",
              "CEP": "86010000",
              "UF": "PR",
              "cPais": 1058,
              "xPais": "BRASIL",
              "fone": "4333335555",
              "email": "destino@exemplo.com"
            }
          },
          "autXML": [
            { "CNPJ": "11222333000144" },
            { "CPF": "98765432100" }
          ],
          "det": [
            {
              "nItem": 1,
              "xProd": "LIVROS DIVERSOS",
              "NCM": "49019900",
              "qCom": 3,
              "vUnCom": 50.00,
              "vProd": 150.00,
              "infAdProd": "Caixa 1 de 2"
            },
            {
              "nItem": 2,
              "xProd": "MATERIAL DE ESCRITORIO",
              "NCM": "48201000",
              "qCom": 10,
              "vUnCom": 8.00,
              "vProd": 80.00,
              "infAdProd": "Caixa 2 de 2"
            }
          ],
          "total": {
            "vDC": 230.00
          },
          "transp": {
            "modTrans": 2,
            "CNPJTransp": "55666777000188"
          },
          "infAdic": {
            "infAdFisco": "Operacao nao sujeita a emissao de nota fiscal",
            "infCpl": "Remessa de bens entre filiais"
          }
        }

Resposta de sucesso

        {
          "success": true,
          "message": "DC-e autorizada",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Resposta de rejeição

        {
          "success": false,
          "message": "DC-e rejeitada: Rejeicao: ...",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "serie": 1,
            "number": 1,
            "cStat": "225",
            "xMotivo": "Rejeicao: Falha no Schema XML",
            "nProt": "",
            "xml": "",
            "dace": ""
          }
        }

POST /api/dce/consult

Consultar situação da DC-e

Consulta a situação atual da DC-e na SEFAZ a partir da chave de acesso. Quando a DC-e está cancelada, a resposta reflete os dados do cancelamento (a base local é a fonte da verdade sobre cancelamento).

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
chDCe *	string	Chave de acesso da DC-e (44 dígitos)

* Campo obrigatório.

Exemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Resposta — DC-e ativa

        {
          "success": true,
          "message": "Autorizado o uso do DC-e",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Success",
            "cStat": "100",
            "xMotivo": "Autorizado o uso do DC-e",
            "nProt": "141250000123456",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Resposta — DC-e cancelada

        {
          "success": true,
          "message": "DC-e Cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "status": "Canceled",
            "cStat": "101",
            "xMotivo": "Cancelamento de DCe homologado",
            "nProt": "141250000123457",
            "xml": "https://storage.../dce/41250612345678000199990010000000011201234564.xml",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml",
            "dhEventoCancel": "2026-06-11T11:00:00-03:00"
          }
        }

POST /api/dce/cancel

Cancelar DC-e

Cancela uma DC-e autorizada (evento 110111). Requer que a DC-e tenha sido autorizada (possua protocolo) e ainda não esteja cancelada. Cada DC-e admite um único cancelamento.

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
chDCe *	string	Chave de acesso da DC-e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência SEFAZ)
nProt	string	Protocolo de autorização. Opcional: quando omitido, usa o protocolo registrado na emissão

* Campo obrigatório.

Exemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564",
          "xJust": "Cancelamento por erro no preenchimento dos dados da declaracao"
        }

Resposta de sucesso

        {
          "success": true,
          "message": "DC-e cancelada",
          "data": {
            "chDCe": "41250612345678000199990010000000011201234564",
            "cStat": "135",
            "xMotivo": "Evento registrado e vinculado a DC-e",
            "nProtCancel": "141250000123457",
            "xmlCancel": "https://storage.../dce/41250612345678000199990010000000011201234564-110111-01.xml"
          }
        }

Em caso de rejeição, a resposta retorna success=false, o cStat/xMotivo da recusa e um campo adicional xmlEnviadoDebug com o XML enviado, para diagnóstico.

POST /api/dce/pdf

Obter DACE (PDF) da DC-e

Retorna a URL do DACE — a representação em PDF da DC-e. Quando o PDF ainda não existe no armazenamento, é gerado sob demanda e enviado. Caso o armazenamento esteja indisponível, o PDF é retornado em base64 no próprio corpo da resposta.

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
chDCe *	string	Chave de acesso da DC-e (44 dígitos)

* Campo obrigatório.

Exemplo de payload

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

Resposta — URL do PDF

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "dace": "https://storage.../dce/41250612345678000199990010000000011201234564.pdf"
          }
        }

Resposta — fallback base64 (armazenamento indisponível)

        {
          "success": true,
          "message": "DACE disponível",
          "data": {
            "chave": "41250612345678000199990010000000011201234564",
            "pdfBase64": "JVBERi0xLjcKJ...",
            "pdfSize": 84213
          }
        }

GET /api/dce/get_list

Listar DC-e (com paginação)

Lista as DC-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (em processamento), `"Failed"` (falhou), `"Unknown"` (desconhecido)

* Campo obrigatório.

Exemplo de chamada

GET /api/dce/get_list?page=1&page_size=20&status=Success

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190990010000000011000000013",
                "serie": 1,
                "number": 1,
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

local_shipping CT-e — Conhecimento de Transporte Eletrônico

A API de CT-e (modelo 57, leiaute 4.00 + NT2025/001) permite emitir, cancelar, corrigir (CC-e), registrar prestação em desacordo, consultar e inutilizar numeração de Conhecimentos de Transporte Eletrônicos. O CT-e documenta a prestação de serviço de transporte de cargas. Suporta 6 modais (rodoviário, aéreo, aquaviário, ferroviário, dutoviário, multimodal) e 4 tipos de CT-e (Normal, Complemento, Anulação, Substituto). Os dados de negócio vão no corpo do /create; os campos técnicos da chave de acesso (cCT, cDV, cUF, dhEmi, mod) são calculados automaticamente pelo servidor. Os campos serie e nCT são opcionais: quando omitidos (ou 0) o servidor aloca a numeração automaticamente; quando enviados no request, são respeitados (útil para pular a numeração, por exemplo após uma duplicidade na SEFAZ).

Endpoint	Método	Descrição
`/api/cte/create`	POST	Emitir CT-e
`/api/cte/cancel`	POST	Cancelar CT-e (evento 110111)
`/api/cte/cce`	POST	Carta de Correção — CC-e (evento 110110)
`/api/cte/desacordo`	POST	Prestação em Desacordo (evento 610110, registrado pelo tomador)
`/api/cte/consult`	POST	Consultar situação do CT-e
`/api/cte/inutilize`	POST	Inutilizar faixa de numeração

O tomador do serviço (quem paga o frete) é definido em ide.toma: 0=Remetente, 1=Expedidor, 2=Recebedor, 3=Destinatário, 4=Outros (neste caso preencha ide.toma4).

POST /api/cte/create

Emitir CT-e

Emite um CT-e a partir do corpo enviado. O cliente envia apenas os dados de negócio; os campos de identificação técnica da chave de acesso são calculados pelo servidor (ver a nota abaixo da tabela ide). O débito de crédito ocorre somente em produção (tpAmb=1) e quando o CT-e é autorizado. Os exemplos abaixo cobrem o caso mais comum: modal rodoviário (modal=01) e CT-e Normal (tpCTe=0).

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)

Campos obrigatórios na requisição: ide (tpAmb, CFOP, natOp, modal, tpCTe, toma, cMunIni, UFIni, cMunFim, UFFim); emit com CNPJ ou CPF e xNome; rem com CNPJ ou CPF; dest com CNPJ ou CPF; vPrest.vTPrest > 0; imp (com uma variante de ICMS). Para tpCTe=0 (Normal): infCTeNorm com infCarga (proPred + ao menos 1 infQ) e infModal (o modal correspondente a ide.modal; para modal=01, rodo.RNTRC é obrigatório). Demais campos opcionais.

Body — raiz

Campo	Tipo	Descrição
ide *	object	Identificação do CT-e
emit *	object	Dados do emitente (transportador)
rem *	object	Remetente da carga
dest *	object	Destinatário da carga
vPrest *	object	Valores da prestação do serviço
imp *	object	Impostos (ICMS + tributos)
infCTeNorm *	object	Corpo do CT-e Normal — obrigatório quando `tpCTe=0` (Normal) ou `3` (Substituto)
exped	object	Expedidor (opcional)
receb	object	Recebedor (opcional)
compl	object	Dados complementares (observações, fluxo, entrega)
infCteComp	object	Chave do CT-e complementado — obrigatório quando `tpCTe=1` (Complemento): `{ chCTe }`
infCteAnu	object	Chave do CT-e anulado — obrigatório quando `tpCTe=2` (Anulação): `{ chCte, dEmi }`
autXML	array	CNPJs/CPFs autorizados a acessar o XML: `[{ CNPJ } \| { CPF }]`
infRespTec	object	Responsável técnico — preenchido automaticamente pelo servidor por UF

ide — Identificação

Campo	Tipo	Descrição
tpAmb *	int	Ambiente: `1`=produção, `2`=homologação
CFOP *	int	Código fiscal da operação (ex.: `5353` dentro do estado, `6353` interestadual)
natOp *	string	Natureza da operação (ex.: `"PRESTACAO DE SERVICO DE TRANSPORTE"`)
modal *	string	Modal: `"01"`=rodoviário, `"02"`=aéreo, `"03"`=aquaviário, `"04"`=ferroviário, `"05"`=dutoviário, `"06"`=multimodal
tpCTe *	int	Tipo do CT-e: `0`=Normal, `1`=Complemento, `2`=Anulação, `3`=Substituto
tpServ *	int	Tipo de serviço: `0`=Normal, `1`=Subcontratação, `2`=Redespacho, `3`=Redespacho Intermediário, `4`=Serviço Vinculado a Multimodal
toma *	int	Tomador do serviço: `0`=Remetente, `1`=Expedidor, `2`=Recebedor, `3`=Destinatário, `4`=Outros
toma4	object	Dados do tomador — obrigatório quando `toma=4` (ver tabela abaixo)
indIEToma	int	Indicador de IE do tomador: `1`=Contribuinte ICMS, `2`=Isento, `9`=Não Contribuinte (quando `9`, a IE do tomador é omitida automaticamente)
cMunIni *	long	Código IBGE do município de início da prestação (7 dígitos)
xMunIni	string	Nome do município de início
UFIni *	string	UF de início (2 letras)
cMunFim *	long	Código IBGE do município de fim da prestação (7 dígitos)
xMunFim	string	Nome do município de fim
UFFim *	string	UF de fim (2 letras)
cMunEnv	long	Código IBGE do município de emissão
xMunEnv	string	Nome do município de emissão
UFEnv	string	UF de emissão
retira	int	Retira na origem: `0`=Sim, `1`=Não. Default: `1`
xDetRetira	string	Detalhes da retirada
tpImp	int	Formato do DACTE: `1`=Retrato, `2`=Paisagem. Default: `1`
infPercurso	array	UFs do percurso: `[{ UFPer }]`
dhCont	string	Data/hora de entrada em contingência (ISO 8601)
xJust	string	Justificativa da contingência
serie	int	Série do CT-e (3 dígitos da chave de acesso). Opcional — auto-alocada (série de CT-e da empresa) quando omitida ou `0`; respeitada quando enviada
nCT	long	Número do CT-e (compõe a chave de acesso). Opcional — auto-incrementado pelo servidor quando omitido ou `0`; respeitado quando enviado (útil para pular a numeração, ex.: após uma duplicidade)

Preenchidos automaticamente pelo servidor — não é necessário enviá-los: mod (fixo 57), cCT (código numérico de 8 dígitos), cDV (dígito verificador), cUF (derivado da UF do emitente), dhEmi (data/hora atual), tpEmis (default 1=Normal), procEmi e verProc.

toma4 — Tomador "Outros" (quando `ide.toma=4`)

Campo	Tipo	Descrição
CNPJ ⚠ / CPF ⚠	string	Documento do tomador (um dos dois)
IE	string	Inscrição Estadual
xNome	string	Razão social/nome
xFant, fone, email	string	Nome fantasia, telefone, e-mail
enderToma	object	Endereço: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, cPais, xPais }`

emit — Emitente (transportador)

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
IEST	string	Inscrição Estadual do substituto tributário
xNome *	string	Razão social
xFant	string	Nome fantasia
CRT	int	Código de Regime Tributário: `1`=Simples Nacional, `2`=SN excesso de sublimite, `3`=Regime Normal, `4`=MEI. Default: `3`
enderEmit	object	Endereço: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone }`

rem — Remetente

Campo	Tipo	Descrição
CNPJ ⚠ / CPF ⚠	string	Documento do remetente (um dos dois)
IE	string	Inscrição Estadual (ou `"ISENTO"`)
xNome	string	Razão social/nome
xFant, fone, email	string	Nome fantasia, telefone, e-mail
enderReme	object	Endereço do remetente (estrutura abaixo)
locColeta	array	Locais de coleta (opcional): `[{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }]`

dest — Destinatário

Campo	Tipo	Descrição
CNPJ ⚠ / CPF ⚠	string	Documento do destinatário (um dos dois)
IE	string	Inscrição Estadual (ou `"ISENTO"`)
xNome	string	Razão social/nome
fone, email, ISUF	string	Telefone, e-mail, Inscrição na SUFRAMA
enderDest	object	Endereço do destinatário (estrutura abaixo)
locEnt	object	Local de entrega (opcional): `{ CNPJ\|CPF, xNome, xLgr, nro, xBairro, cMun, xMun, UF }`

exped / receb — Expedidor / Recebedor (opcionais)

Campo	Tipo	Descrição
CNPJ / CPF	string	Documento (um dos dois)
IE, xNome, fone, email	string	Inscrição Estadual, nome, telefone, e-mail
enderExped / enderReceb	object	Endereço (mesma estrutura genérica abaixo)

Endereço (enderEmit / enderReme / enderExped / enderReceb / enderDest)

Campo	Tipo	Descrição
xLgr	string	Logradouro
nro	string	Número
xCpl	string	Complemento
xBairro	string	Bairro
cMun	string	Código IBGE do município (7 dígitos)
xMun	string	Nome do município
CEP	string	CEP (8 dígitos) — não usado em `enderEmit`
UF	string	Sigla da UF (2 letras)
cPais	string	Código do país (opcional, default 1058 Brasil)
xPais	string	Nome do país (opcional)
fone	string	Telefone (somente em `enderEmit`)

vPrest — Valores da Prestação

Campo	Tipo	Descrição
vTPrest *	decimal	Valor total da prestação do serviço (> 0)
vRec	decimal	Valor a receber
Comp	array	Componentes do valor: `[{ xNome, vComp }]` — ex.: `"FRETE PESO"`, `"PEDÁGIO"`, `"GRIS"`

imp — Impostos

Campo	Tipo	Descrição
ICMS *	object	Tributação do ICMS — preencher apenas uma das variantes (ver abaixo)
vTotTrib	decimal	Valor aproximado total de tributos
infAdFisco	string	Informações adicionais de interesse do Fisco
ICMSUFFim	object	DIFAL (partilha interestadual, opcional): `{ vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni }`
infTribFed	object	Tributos federais (opcional): `{ vPIS, vCOFINS, vIR, vINSS, vCSLL }`

ICMS — variantes (preencher só uma)

Variante	Quando usar	Campos
ICMS00	Tributação normal	`{ vBC, pICMS, vICMS }` (CST 00)
ICMS20	Com redução de base de cálculo	`{ pRedBC, vBC, pICMS, vICMS }` (CST 20)
ICMS45	Isenta / não tributada / diferida	`{ CST }` — `"40"`=Isenta, `"41"`=Não tributada, `"51"`=Diferido
ICMS60	ICMS cobrado por substituição tributária	`{ vBCSTRet, vICMSSTRet, pICMSSTRet, vCred }` (CST 60)
ICMS90	Outros (regime especial)	`{ pRedBC, vBC, pICMS, vICMS, vCred }` (CST 90)
ICMSOutraUF	ICMS devido a outra UF	`{ pRedBCOutraUF, vBCOutraUF, pICMSOutraUF, vICMSOutraUF }`
ICMSSN	Emitente do Simples Nacional	`{ CST: "90", indSN: 1 }`

infCTeNorm — CT-e Normal (obrigatório para `tpCTe=0`/`3`)

Campo	Tipo	Descrição
infCarga *	object	Informações da carga (tabela abaixo)
infDoc	object	Documentos transportados (tabela abaixo)
infModal *	object	Informações do modal (tabela abaixo)
docAnt	object	Documentos anteriores (subcontratação/redespacho): `{ emiDocAnt[]{ CNPJ\|CPF, IE, UF, xNome, idDocAnt[] } }`
seg	array	Seguro da carga: `[{ respSeg, xSeg, CNPJ, nApol, nAver, vCarga }]` — `respSeg`: 1=Remetente…6=Tomador
cobr	object	Cobrança/faturas: `{ fat{ nFat, vOrig, vDesc, vLiq }, dup[]{ nDup, dVenc, vDup } }`
veicNovos	array	Veículos novos transportados: `[{ chassi, cCor, xCor, cMod, vUnit, vFrete }]`
infCteSub	object	Substituição — obrigatório quando `tpCTe=3`: `{ chCte, indAltToma, refNF, tomaICMS, tomaNaoICMS }`

infCTeNorm.infCarga — Carga

Campo	Tipo	Descrição
proPred *	string	Produto predominante
vCarga	decimal	Valor total da carga
xOutCat	string	Outras características da carga (ex.: FRIA, GRANEL, REFRIGERADA)
vCargaAverb	decimal	Valor da carga para efeito de averbação
infQ[] *	array	Quantidades — mínimo 1: `[{ cUnid, tpMed, qCarga }]`
infQ[].cUnid	string	Unidade: `"00"`=M³, `"01"`=KG, `"02"`=TON, `"03"`=UNIDADE, `"04"`=LITROS, `"05"`=MMBTU
infQ[].tpMed	string	Tipo de medida (ex.: `"PESO BRUTO"`, `"PESO DECLARADO"`)
infQ[].qCarga	decimal	Quantidade

infCTeNorm.infDoc — Documentos transportados

Campo	Tipo	Descrição
infNFe	array	NF-es por chave de acesso: `[{ chave, PIN, dPrev, infUnidCarga[], infUnidTransp[] }]` — `chave` com 44 dígitos
infNF	array	Notas em papel (legado): `[{ mod, serie, nDoc, dEmi, vBC, vICMS, vProd, vNF, nCFOP, nPeso, … }]`
infOutros	array	Outros documentos: `[{ tpDoc, descOutros, nDoc, dEmi, vDocFisc }]` — `tpDoc`: `"00"`=Declaração, `"10"`=Dutoviário, `"99"`=Outros

infCTeNorm.infModal — Modais (preencher só o correspondente a `ide.modal`)

Modal	Objeto	Campos
01 Rodoviário	rodo	`{ RNTRC* }` — RNTRC com 8 dígitos ou `"ISENTO"`. Opcional: `occ[]` (ordens de coleta)
02 Aéreo	aereo	`{ nMinu, nOCA, dPrevAereo, natCarga{ xDime, cInfManu[] }, tarifa{ CL, cTar, vTar }, peri[] }` — `dPrevAereo` AAAA-MM-DD
03 Aquaviário	aquav	`{ vPrest, vAFRMM, xNavio, nViag, direc, irin, tpNav, balsa[], detCont[] }` — `direc`: N/L/S/O; `tpNav`: 0=Interior, 1=Cabotagem
04 Ferroviário	ferrov	`{ tpTraf, respFat, ferrEmi, vFrete, chCTeFerroOrigem, ferroEnv[] }` — `tpTraf`: 0=Próprio, 1=Mútuo, 2=Rodoferroviário, 3=Rodoviário
05 Dutoviário	duto	`{ vTar, dIni, dFim }` — datas AAAA-MM-DD
06 Multimodal	multimodal	`{ COTM, indNegociavel, seg[] }` — `indNegociavel`: 0=Não, 1=Sim

Todo o bloco infModal aceita versaoModal (default "4.00").

compl — Dados complementares (opcional)

Campo	Tipo	Descrição
xCaracAd, xCaracSer, xEmi	string	Característica adicional do transporte / do serviço / nome do emissor
origCalc, destCalc	string	Município de origem / destino para cálculo do frete
xObs	string	Observações gerais
ObsCont / ObsFisco	array	Observações livres do contribuinte / fisco: `[{ xCampo, xTexto }]`
fluxo, Entrega	object	Fluxo de carga (origem/passagem/destino/rota) e previsão de entrega

* Campo obrigatório. ⚠ Pelo menos um de CNPJ ou CPF é obrigatório no grupo.

Exemplo simplificado — Modal Rodoviário, Simples Nacional

        {
          "ide": {
            "CFOP": 5353,
            "natOp": "PRESTACAO DE SERVICO DE TRANSPORTE",
            "tpAmb": 2,
            "tpCTe": 0,
            "modal": "01",
            "tpServ": 0,
            "cMunEnv": 3550308,
            "xMunEnv": "SAO PAULO",
            "UFEnv": "SP",
            "cMunIni": 3550308,
            "xMunIni": "SAO PAULO",
            "UFIni": "SP",
            "cMunFim": 3304557,
            "xMunFim": "RIO DE JANEIRO",
            "UFFim": "RJ",
            "retira": 1,
            "indIEToma": 9,
            "toma": 0
          },
          "emit": {
            "CNPJ": "26638419000167",
            "IE": "141507411110",
            "CRT": 1,
            "xNome": "TF COMERCIO DE PRESENTES LTDA",
            "enderEmit": {
              "xLgr": "RUA QUINTANA",
              "nro": "34",
              "xBairro": "CIDADE MONCOES",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "04571010",
              "UF": "SP",
              "fone": "1133334444"
            }
          },
          "rem": {
            "CNPJ": "11111111000111",
            "IE": "ISENTO",
            "xNome": "EMPRESA REMETENTE LTDA",
            "fone": "1122223333",
            "enderReme": {
              "xLgr": "AV PAULISTA",
              "nro": "1500",
              "xBairro": "BELA VISTA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01310200",
              "UF": "SP"
            }
          },
          "dest": {
            "CNPJ": "22222222000122",
            "IE": "ISENTO",
            "xNome": "EMPRESA DESTINATARIA LTDA",
            "fone": "2133334444",
            "enderDest": {
              "xLgr": "AV RIO BRANCO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3304557",
              "xMun": "RIO DE JANEIRO",
              "CEP": "20040002",
              "UF": "RJ"
            }
          },
          "vPrest": {
            "vTPrest": 1500.00,
            "vRec": 1500.00,
            "Comp": [
              { "xNome": "FRETE PESO", "vComp": 1500.00 }
            ]
          },
          "imp": {
            "ICMS": {
              "ICMSSN": { "CST": "90", "indSN": 1 }
            },
            "vTotTrib": 0
          },
          "infCTeNorm": {
            "infCarga": {
              "vCarga": 10000.00,
              "proPred": "PRODUTOS DIVERSOS",
              "infQ": [
                { "cUnid": "01", "tpMed": "PESO BRUTO", "qCarga": 1000.0000 }
              ]
            },
            "infDoc": {
              "infNFe": [
                { "chave": "35260526638419000167550030000006561341688760" }
              ]
            },
            "infModal": {
              "versaoModal": "4.00",
              "rodo": {
                "RNTRC": "12345678"
              }
            }
          }
        }

Resposta de sucesso

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

Resposta de rejeição

        {
          "success": false,
          "message": "Rejeicao: ...",
          "data": {
            "cStat": "539",
            "chCTe": "",
            "nProt": "",
            "xml": ""
          }
        }

POST /api/cte/cancel

Cancelar CT-e

Cancela um CT-e autorizado (evento 110111). Requer que o CT-e tenha sido autorizado (possua protocolo) e ainda não esteja cancelado.

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
chCTe *	string	Chave de acesso do CT-e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência SEFAZ)
nProt	string	Protocolo de autorização. Opcional: quando omitido, usa o protocolo registrado na emissão

* Campo obrigatório.

Exemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xJust": "Cancelamento por erro no preenchimento dos dados da prestacao"
        }

Resposta de sucesso

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123457",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/cce

Carta de Correção (CC-e)

Registra uma Carta de Correção Eletrônica (evento 110110) sobre um CT-e autorizado. A CC-e não pode corrigir valores que impactem o imposto, dados cadastrais que mudem emitente/tomador/remetente/destinatário, ou a data de emissão. Cada correção indica o grupo, campo e novo valor.

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
chCTe *	string	Chave de acesso do CT-e (44 dígitos)
infCorrecao[] *	array	Correções (mínimo 1, até 20)
infCorrecao[].grupoAlterado *	string	Grupo alterado (ex.: `"ide"`, `"rem"`, `"dest"`)
infCorrecao[].campoAlterado *	string	Campo alterado (ex.: `"xNome"`)
infCorrecao[].valorAlterado *	string	Novo valor
infCorrecao[].nroItemAlterado	int	Número do item alterado (quando o grupo for uma lista)

* Campo obrigatório. A condição de uso (xCondUso) é preenchida automaticamente pelo servidor.

Exemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "infCorrecao": [
            {
              "grupoAlterado": "compl",
              "campoAlterado": "xObs",
              "valorAlterado": "OBSERVACAO CORRIGIDA"
            }
          ]
        }

Resposta de sucesso

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123458",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml"
          }
        }

POST /api/cte/desacordo

Prestação em Desacordo

Registra a Prestação de Serviço em Desacordo (evento 610110) — utilizada pelo tomador do serviço para manifestar que a prestação descrita no CT-e está em desacordo com o contratado. O CNPJ que registra o evento (o tomador) é o da empresa do token; não é necessário ser o emissor do CT-e.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa (tomador)
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
chCTe *	string	Chave de acesso do CT-e (44 dígitos)
xObs *	string	Descrição do desacordo (mínimo 15 caracteres)

* Campo obrigatório. O indicador de operação em desacordo é sempre 1 (PL-CTe v4.00).

Exemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780",
          "xObs": "Valor do frete cobrado diverge do contratado entre as partes"
        }

Resposta de sucesso

        {
          "success": true,
          "message": "Evento registrado e vinculado a CT-e",
          "data": {
            "cStat": "135",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123459"
          }
        }

POST /api/cte/consult

Consultar situação do CT-e

Consulta a situação do CT-e na SEFAZ a partir da chave de acesso. Quando o CT-e está cancelado (registro local), a resposta reflete o cancelamento.

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
chCTe *	string	Chave de acesso do CT-e (44 dígitos)

* Campo obrigatório.

Exemplo de payload

        {
          "chCTe": "35260626638419000167570010000000011123456780"
        }

Resposta

        {
          "success": true,
          "message": "Autorizado o uso do CT-e",
          "data": {
            "cStat": "100",
            "chCTe": "35260626638419000167570010000000011123456780",
            "nProt": "135260000123456",
            "xml": "https://storage.../cte/35260626638419000167570010000000011123456780.xml",
            "dacte": "https://storage.../cte/35260626638419000167570010000000011123456780.pdf"
          }
        }

POST /api/cte/inutilize

Inutilizar faixa de numeração

Inutiliza uma faixa de numeração de CT-e que não será utilizada (por exemplo, após uma quebra de sequência). A inutilização é definitiva.

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
tpAmb *	int	Ambiente: `1`=produção, `2`=homologação
CNPJ *	string	CNPJ do emitente (14 dígitos)
ano *	int	Ano da numeração (2 dígitos, ex.: `26` para 2026)
serie *	int	Série da numeração
nCTIni *	long	Número inicial da faixa
nCTFin *	long	Número final da faixa (≥ `nCTIni`)
xJust *	string	Justificativa (mínimo 15 caracteres)
mod	int	Modelo. Default: `57`

* Campo obrigatório.

Exemplo de payload

        {
          "tpAmb": 2,
          "CNPJ": "26638419000167",
          "ano": 26,
          "serie": 1,
          "nCTIni": 51,
          "nCTFin": 55,
          "xJust": "Quebra de sequencia na numeracao por falha no sistema emissor"
        }

Resposta de sucesso

        {
          "success": true,
          "message": "Inutilizacao de numero homologado",
          "data": {
            "cStat": "102",
            "chCTe": "",
            "nProt": "135260000123460"
          }
        }

GET /api/cte/get_list

Listar CT-e (com paginação)

Lista os CT-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: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (em processamento), `"Failed"` (falhou), `"Unknown"` (desconhecido)

* Campo obrigatório.

Exemplo de chamada

GET /api/cte/get_list?page=1&page_size=20&status=Success

Resposta

        {
          "success": true,
          "data": {
            "list": [
              {
                "chave": "35260112345678000190570010000000011000000019",
                "serie": 1,
                "number": 1,
                "modal": "01",
                "status": "Success",
                "create": "2026-01-10T10:30:00Z",
                "issue_time": "2026-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

vpn_key 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_ticket enviando o token da empresa.
A TFiscal devolve um redirectUrl contendo 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 /api/sso/create_ticket

Gerar link de login automático

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 /api/sso/consume_ticket

Consumir ticket e receber o JWT de sessão

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

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

badge 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 /api/accountant/get_info

Obter informações do contador vinculado à empresa

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

verified_user Validação de CPF e CNPJ

API para validar CPF e CNPJ contra a base oficial da Receita Federal. Para CPF, retorna nome, situação cadastral, idade e bloqueio automático de menores de idade (conforme LGPD). Para CNPJ, retorna razão social, nome fantasia, endereço, quadro societário e situação cadastral completa. Indicado para validar cadastros antes de emitir documentos fiscais e identificar contribuintes com situação irregular (suspensa, cancelada, baixada).

POST /api/invoice/validar_cpf_cnpj

Valida CPF (com data de nascimento) ou CNPJ contra a base oficial da Receita Federal

Aceita CPF ou CNPJ, com ou sem formatação. O tipo é detectado automaticamente. Para CPF, a dataNascimento é obrigatória.

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
cpfCnpj *	string	CPF (11 dígitos) ou CNPJ (14 caracteres). Aceita formatação.
dataNascimento	string	Data de nascimento — obrigatória apenas para CPF. Formatos aceitos: `dd/MM/yyyy`, `dd-MM-yyyy` ou `ddMMyyyy`.

* Campo obrigatório.

Exemplo de payload — CPF

        {
          "cpfCnpj": "407.105.368-28",
          "dataNascimento": "09/01/1997"
        }

Exemplo de payload — CNPJ

        {
          "cpfCnpj": "03.354.151/0001-36"
        }

Resposta — CPF encontrado, situação regular

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "nome": "FULANO DE TAL",
            "situacao_codigo": "0",
            "situação_descricao": "REGULAR",
            "menor_de_idade_lgpd": false,
            "idade": 29,
            "data_nascimento": "1997-01-09"
          }
        }

Resposta — CPF de menor de idade (LGPD)

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "situação_descricao": "Menor de idade",
            "menor_de_idade_lgpd": true
          }
        }

Resposta — CPF não encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "12345678901",
            "Situação": "CPF não encontrado"
          }
        }

Resposta — Data de nascimento não confere com CPF

        {
          "success": true,
          "data": {
            "tipo_doc": "CPF",
            "documento": "40710536828",
            "Situação": "Data de nascimento não confere com o CPF"
          }
        }

Resposta — CNPJ encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "03354151000136",
            "nome": "EMPRESA EXEMPLO LTDA",
            "situacao_codigo": "2",
            "situação_descricao": "Ativo",
            "nome_empresarial": "EMPRESA EXEMPLO LTDA",
            "nome_fantasia": "EXEMPLO",
            "data_situacao": "20180515",
            "motivo_situacao": ""
          }
        }

Resposta — CNPJ não encontrado

        {
          "success": true,
          "data": {
            "tipo_doc": "CNPJ",
            "documento": "12345678000199",
            "Situação": "Não encontrado"
          }
        }

Códigos de Situação CPF

Código	Descrição
0	REGULAR
2	SUSPENSA
3	TITULAR FALECIDO
4	PENDENTE DE REGULARIZACAO
5	CANCELADA POR MULTIPLICIDADE
8	NULA
9	CANCELADA DE OFICIO

Códigos de Situação CNPJ

Código	Descrição
1	Nulo
2	Ativo
3	Suspenso
4	Inapto
8	Baixado

Respostas de erro

Mensagem	Causa
cpfCnpj é obrigatório	Campo `cpfCnpj` ausente ou vazio
CPF inválido, verifique a quantidade de dígitos	O CPF informado não tem 11 dígitos
CPF inválido	O CPF informado tem dígitos verificadores inválidos ou contém letras
CNPJ inválido, verifique a quantidade de dígitos	O CNPJ informado não tem 14 caracteres
CNPJ inválido	O CNPJ informado tem dígitos verificadores inválidos
é necessário informar a data de nascimento	CPF foi enviado sem `dataNascimento`
dataNascimento inválida (use dd/MM/yyyy)	Formato da data não bate com nenhum dos aceitos

Documentação NFE API

Campos Importantes da API

Fluxo do Processo de Emissão

1. Criar Empresa

2. Push de Informações

3. Emitir Nota Fiscal

4. Retornar Resultado

5. Gerar Arquivos

Verificação Fiscal

Sucesso

Falha

Referência Rápida de Endpoints

Sucesso

Erro do Cliente

Erro do Servidor

NFE API

sync_alt Fluxo do Sistema

input Dados de Entrada

settings Processamento

download Saída

Endpoints Principais

Headers obrigatórios

Body

Exemplo de payload

Resposta

Headers obrigatórios

Body

Exemplo de payload

Resposta

Headers obrigatórios

Body

Exemplo de payload

Exemplo — habilitar NFC-e e CT-e na empresa

Resposta

Headers obrigatórios

Query string

Exemplo de chamada

Resposta

Headers obrigatórios

Exemplo de chamada

Resposta

Headers obrigatórios

Query string

Exemplo de chamada

Resposta

Headers obrigatórios

Exemplo de chamada

Resposta

Exemplo de resposta

Headers obrigatórios

Body — campos top-level

Body — cliente (objeto, obrigatório)

Body — products[] (array, mínimo 1 item)

Body — products[].impostos / products[].tax_info

Body — products[].ii (Imposto de Importação)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (objetos, opcionais)

Body — transportation (objeto, opcional)

Body — pag_info[] (array, opcional)

Exemplo simplificado

Exemplo completo (todos os campos)

Headers obrigatórios

Query string

Exemplo de chamada

Resposta

Headers obrigatórios

Query string

Exemplo de chamada

Resposta

Headers obrigatórios

Body

Exemplo de payload

Headers obrigatórios

Body

Exemplo de payload

Headers obrigatórios

Body

Exemplo de payload

Headers obrigatórios

Body

Body — `cliente` (objeto, obrigatório)

Body — `products[]` (array, mínimo 1 item)

Body — `products[].impostos` / `products[].tax_info`

Body — `products[].ii` (Imposto de Importação)

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address` (objetos, opcionais)

Body — `transportation` (objeto, opcional)

Body — `pag_info[]` (array, opcional)

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` e `cofins[]` (mesma estrutura)

Body — `ibs_cbs[]` (Reforma Tributária)

Body — `is[]` (Imposto Seletivo)