NF-e · TF Fiscal API

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
price_includes_ipi	boolean	Se os preços unitários já incluem IPI. Com true o IPI é calculado por dentro e o total da nota fica igual ao preço cotado; padrão false. Pode ser sobrescrito por produto
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 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
price_includes_ipi	boolean	Sobrescreve price_includes_ipi para este produto; omita para seguir a configuração da nota
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`)
impostos	object	Configuração inline de tributos (alternativa a `category_id`). Veja estrutura abaixo. O nome anterior `tax_info` continua aceito.
disable_difal	boolean	Desativa o cálculo de DIFAL para este item
desconta_icms_pis_cofins	boolean	Abate o ICMS antes de calcular PIS/COFINS — tributa (valor − ICMS), padrão atual no Brasil; default false (sem abatimento, imposto maior)
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`

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.tipo_pessoa	string	Tipo de pessoa (PF/PJ)
icms.codigo_beneficio_fiscal	string	cBenef (código de benefício fiscal)
icms.aliquota	string	Alíquota do ICMS próprio em % (CST 00, 10, 20, 51, 70, 90). Se vazio, o sistema deriva pela tabela interestadual/interna
icms.aliquota_reducao	string	Percentual de redução da base do ICMS próprio (CST 20, 51, 70, 90)
icms.aliquota_st	string	Alíquota do ICMS-ST do estado de destino em % (CST 10, 30, 70, 90)
icms.aliquota_reducao_st	string	Percentual de redução da base do ICMS-ST (CST 10, 30, 70, 90)
icms.aliquota_mva	string	MVA/IVA-ST em % (CST 10, 30, 70, 90)
icms.aliquota_fcp	string	Alíquota do FCP próprio em % — emite pFCP/vFCP no grupo ICMS (CST 00, 10, 20, 51, 70, 90)
icms.aliquota_fcp_st	string	Alíquota do FCP-ST em % (CST 10, 30, 70, 90)
icms.aliquota_fcp_uf_dest	string	Alíquota do FCP do estado de destino (pFCPUFDest). Se omitida, usa aliquota_fcp
icms.aliquota_uf_dest	string	Alíquota de ICMS do estado de destino. Normalmente não precisa informar — a plataforma mantém as alíquotas padrão por estado. Informe apenas quando o produto tiver alíquota diferenciada no destino (bebidas, fumo, energia). É a do destino, não a do remetente
icms.difal_desconta_icms_inter	boolean	Deduz da base do DIFAL o ICMS interestadual já recolhido — o "com exclusão" da legislação estadual. Veja "Interestadual: como informar a base do DIFAL" nesta página
icms.difal_base_por_dentro	boolean	Reconstitui a base do DIFAL porque o imposto integra o preço — a "base dupla" da legislação estadual. Veja "Interestadual: como informar a base do DIFAL" nesta página
icms.v_bc_uf_dest	string	Se você já calculou a base do DIFAL, informe o valor (R$) aqui. As duas opções acima deixam de valer
icms.aliquota_credito	string	Alíquota de crédito do Simples Nacional em % (CSOSN 101, 201, 900)
icms.aliquota_diferimento	string	Percentual de diferimento do ICMS (CST 51)
icms.motivo_desoneracao	string	Código do motivo de desoneração do ICMS (CST 20, 40, 41, 50, 90)
icms.ad_rem_icms	string	ICMS monofásico — alíquota ad rem em R$/unidade (CST 02, 15, 53)
icms.ad_rem_icms_ret	string	ICMS monofásico — ad rem retido em R$/unidade (CST 15, 61)
icms.p_dif_mono	string	ICMS monofásico — percentual de diferimento (CST 53)
icms.q_bc_mono	string	ICMS monofásico — quantidade tributada (litros/kg). Vazio usa a quantidade do item (CST 02, 15, 53)
icms.valor_desoneracao	string	Valor do ICMS desonerado em R$ — emite vICMSDeson (CST 40, 41, 50, 90)
icms.v_bc_st_ret	string	Base de cálculo do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
icms.p_st	string	Alíquota suportada pelo consumidor final em % (informado, não calculado — CST 60, CSOSN 500)
icms.v_icms_st_ret	string	Valor do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
icms.v_icms_substituto	string	Valor do ICMS próprio do substituto (informado, não calculado — CST 60, CSOSN 500)
icms.v_bc_fcp_st_ret	string	Base de cálculo do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
icms.p_fcp_st_ret	string	Alíquota do FCP retido por ST em % (informado, não calculado — CST 60, CSOSN 500)
icms.v_fcp_st_ret	string	Valor do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
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.valor_unidade	string	IPI por quantidade — valor em R$/unidade. Só usado quando não há alíquota percentual; havendo `aliquota`, o percentual prevalece (CST 00, 50, 49, 99)
ipi.tipo_pessoa	string	Tipo de pessoa
pis
pis.situacao_tributaria	string	CST PIS
pis.aliquota	string	Alíquota PIS
pis.valor_unidade	string	PIS por quantidade — valor em R$/unidade. vPIS = quantidade × valor (CST 03 e demais formas por quantidade)
pis.tipo_pessoa	string	Tipo de pessoa
cofins
cofins.situacao_tributaria	string	CST COFINS
cofins.aliquota	string	Alíquota COFINS
cofins.valor_unidade	string	COFINS por quantidade — valor em R$/unidade. vCOFINS = quantidade × valor (CST 03 e demais formas por quantidade)
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
ibs_cbs.p_ibs_uf	string	Alíquota do IBS UF em % (opcional; vazio usa o padrão da transição, 0,10 em 2026). Aceita ponto ou vírgula
ibs_cbs.p_ibs_mun	string	Alíquota do IBS Município em % (opcional; padrão 0 em 2026)
ibs_cbs.p_cbs	string	Alíquota da CBS em % (opcional; padrão 0,90 em 2026)
ibs_cbs.p_red_aliq	string	Percentual de redução de alíquota (CST 011, 200, 515)
ibs_cbs.p_dif	string	Percentual de diferimento (CST 510, 515)
ibs_cbs.p_red_bc	string	Percentual de redução da base de cálculo (CST 222)
ibs_cbs.proporcao	string	Proporção da operação em % (CST 221)
ibs_cbs.aliquota_cbs_mono	string	CBS monofásica — alíquota em % sobre a base; prevalece sobre `valor_unidade_cbs` (CST 620)
ibs_cbs.aliquota_ibs_mono	string	IBS monofásico — alíquota em % sobre a base; prevalece sobre `valor_unidade_ibs` (CST 620)
ibs_cbs.valor_unidade_cbs	string	CBS monofásica — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
ibs_cbs.valor_unidade_ibs	string	IBS monofásico — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
ibs_cbs.valor_deducao_legal	string	Valor da dedução legal da base em R$ (CST 830)
difal
difal.disable_difal	boolean	Desativa DIFAL para o item (alternativa ao `disable_difal` direto no produto)

Interestadual: como informar a base do DIFAL

Esta seção vale apenas para vendas interestaduais a pessoa física (não contribuinte). Não se aplica a operações internas nem B2B.

Passo 1 — consulte a UF do destinatário

UF do destinatário	Informar além de aliquota, aliquota_fcp
PE, RJ	nada além disso
SE	apenas `difal_base_por_dentro: true`
as outras 24 UFs AC AL AM AP BA CE DF ES GO MA MG MS MT PA PB PI PR RN RO RR RS SC SP TO	`difal_desconta_icms_inter: true` `difal_base_por_dentro: true`

Atenção: a metodologia da base do DIFAL determina diretamente o imposto devido; a escolha incorreta resulta em recolhimento a menor (com exposição a autuação e multa) ou a maior. A tabela acima reflete a prática predominante por UF e serve apenas como referência — a legislação estadual muda e mercadorias específicas podem seguir regras diferenciadas. Confirme a metodologia aplicável à UF de destino com sua contabilidade ou assessoria tributária antes de entrar em produção. Na dúvida, não informe difal_desconta_icms_inter nem difal_base_por_dentro: a base será o valor da nota, tratamento mais conservador.

Passo 2 — exemplos de requisição por cenário

Venda para RJ — difal_desconta_icms_inter e difal_base_por_dentro não são necessários (FECP 2%)

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "2" }
}

Venda para AL — difal_desconta_icms_inter e difal_base_por_dentro ambos true (FECP 1%)

{
  "icms": { "codigo_cfop": "6102", "situacao_tributaria": "00",
            "aliquota": "4", "aliquota_fcp": "1",
            "difal_desconta_icms_inter": true,
            "difal_base_por_dentro": true }
}

Se o seu sistema já calcula a base do DIFAL, informe v_bc_uf_dest; difal_desconta_icms_inter e difal_base_por_dentro deixam de valer

{
  "icms": { "aliquota": "4", "aliquota_fcp": "1", "v_bc_uf_dest": "122.29" }
}

O que cada opção produz

Como enviar	Base do DIFAL	DIFAL devido
sem difal_desconta_icms_inter nem difal_base_por_dentro	100,00	16,50
ambos true	122,29	21,07
v_bc_uf_dest=150	150,00	26,75

Nota de 100,00, ICMS interestadual de 4,00, alíquota de destino 20,5%, FECP 1%.

Por que as UFs diferem (contexto, pode pular)

O ICMS é imposto por dentro. Parte das UFs exige que o próprio DIFAL seja reconstituído na base (base dupla), deduzindo antes o ICMS interestadual já recolhido (com exclusão); outras usam direto o valor da operação (base única). difal_desconta_icms_inter e difal_base_por_dentro correspondem a essas duas etapas. A alíquota do destino é mantida pela plataforma.

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.

Campos da resposta (`data`)

Campo	Tipo	Descrição
uuid	string	Identificador interno da NF-e. Use nas consultas seguintes (`/api/invoice/get_detail`, `/refresh`, `/cancel`)
status	string	Situação: `"Success"` (autorizada), `"Failed"` (rejeitada/falha), `"Processing"` (em processamento), `"Canceled"` (cancelada)
motivo	string	Mensagem oficial do Fisco conforme o `cStat` (formato bilíngue PT / 中文)
nfe	int	Número da NF-e emitida
serie	int	Série da NF-e
chave	string	Chave de acesso de 44 dígitos (vazia quando a nota não é autorizada)
modelo	string	Modelo do documento: `"nfe"`
epec	boolean	Emissão em contingência EPEC
xml	string	URL do XML autorizado. O DANFE (PDF) e demais formatos são obtidos em `/api/invoice/get_detail`

Resposta — rejeição / erro

Quando o Fisco rejeita a nota, success é false e data.motivo traz o motivo; a chave vem vazia. Erros de validação de campos (antes de chegar ao Fisco) retornam success: false com a mensagem em message, sem o objeto data.

        {
          "success": false,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Failed",
            "motivo": "Rejeição 226: Código da UF do Emitente diverge da UF autorizadora / 拒绝 226: 发件人所在州代码与授权州不一致",
            "nfe": 100,
            "serie": 1,
            "chave": "",
            "modelo": "nfe",
            "epec": false,
            "xml": ""
          }
        }

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "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": "matriz",
              "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 }
          ]
        }

        {
          "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.0,
          "troco": 0.0,
          "seguro": 0.0,
          "outras_despesas": 0.0,
          "price_includes_ipi": false,
          "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": "matriz",
              "unit_price": 3500.0,
              "total_price": 7000.0,
              "discount_price": 0.0,
              "origem": 0,
              "indicador_total": 1,
              "category_id": "TF00001",
              "nItemPed": 1,
              "price_includes_ipi": false,
              "desconta_icms_pis_cofins": false,
              "disable_difal": false
            },
            {
              "codigo": "PROD002",
              "name": "Mouse sem fio",
              "ncm": "84716053",
              "count": 5,
              "unit": "matriz",
              "unit_price": 80.0,
              "total_price": 400.0,
              "origem": 0,
              "indicador_total": 1,
              "nItemPed": 2,
              "impostos": {
                "icms": {
                  "codigo_cfop": "5102",
                  "situacao_tributaria": "00",
                  "industria": "",
                  "tipo_pessoa": "juridica",
                  "codigo_beneficio_fiscal": "",
                  "aliquota": "18",
                  "aliquota_fcp": "0",
                  "aliquota_reducao": "0",
                  "aliquota_st": "0",
                  "aliquota_reducao_st": "0",
                  "aliquota_mva": "0",
                  "aliquota_fcp_st": "0",
                  "aliquota_credito": "0",
                  "motivo_desoneracao": "",
                  "valor_desoneracao": "0",
                  "aliquota_uf_dest": "20.5",
                  "difal_desconta_icms_inter": true,
                  "difal_base_por_dentro": true,
                  "v_bc_uf_dest": ""
                },
                "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",
                  "p_ibs_uf": "0.1",
                  "p_ibs_mun": "0",
                  "p_cbs": "0.9"
                },
                "is": {},
                "difal": {
                  "disable_difal": false
                }
              },
              "discount_price": 0.0,
              "price_includes_ipi": false,
              "desconta_icms_pis_cofins": true
            }
          ],
          "transportation": {
            "transport_mode": "1",
            "freight_amount": 150.0,
            "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.5,
                "net_weight": 11.0,
                "packaging_type": "CAIXA",
                "number": "001-003",
                "mark": "FRAGIL",
                "seals": [
                  "LACRE001",
                  "LACRE002"
                ]
              }
            ],
            "transport_tax_retention_info": {
              "freight_service_amount": 150.0,
              "tax_base": 150.0,
              "tax_rate": 12.0,
              "cfop": "5932",
              "cep": "11000000"
            }
          },
          "pag_info": [
            {
              "payment_indicator": "1",
              "payment_method": "03",
              "payment_value": 7400.0,
              "card_info": {
                "integration_type": "1",
                "brand_code": "01",
                "acquirer_cnpj": "01234567000189",
                "authorization_code": "AUTH987654"
              }
            }
          ]
        }

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfe": 100,
            "serie": 1,
            "chave": "35260112345678000199550010000001001000000017",
            "modelo": "nfe",
            "epec": false,
            "xml": "https://oss.example.com/.../chave.xml"
          }
        }

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.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X GET "https://api.tffiscal.com/api/invoice/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

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

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

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X GET "https://api.tffiscal.com/api/invoice/get_detail" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN"

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

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

POST/api/invoice/cancel

Cancelar nota fiscal

Cancela uma NF-e já autorizada. A justificativa enviada ao Fisco é 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.

Campos da resposta (`data`)

Campo	Tipo	Descrição
motivo	string	Mensagem oficial do Fisco confirmando o cancelamento
status	string	Situação: `"Canceled"` (cancelada)
nfe	int	Número da NF-e cancelada
serie	int	Série da NF-e
chave	string	Chave de acesso de 44 dígitos
modelo	string	Modelo do documento: `"nfe"`
epec	boolean	Emissão em contingência EPEC
xml	string	URL do XML do evento de cancelamento

Resposta — erro

Falhas retornam success: false com a mensagem do Fisco em message, sem o objeto data. Ocorre quando o uuid está ausente, o certificado é inválido, ou o Fisco rejeita o cancelamento (ex.: prazo excedido, nota já cancelada).

        {
          "success": false,
          "message": "Rejeição: NF-e já está cancelada na base de dados do Fisco"
        }

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/cancel" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

        {
          "success": true,
          "data": {
            "motivo": "Cancelamento de NF-e homologado",
            "status": "Canceled",
            "nfe": 100,
            "serie": 1,
            "chave": "35260112345678000199550010000001001000000017",
            "modelo": "nfe",
            "epec": false,
            "xml": "https://oss.example.com/.../chave-cancelamento.xml"
          }
        }

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 no Fisco 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 Fisco)

* Campo obrigatório.

Campos da resposta (`data`)

Campo	Tipo	Descrição
uuid	string	Identificador interno do registro de inutilização
xml	string	URL do XML de inutilização autorizado pelo Fisco

Resposta — erro

Falhas retornam success: false com a mensagem do Fisco em message, sem o objeto data. Ocorre quando falta um campo obrigatório, o certificado é inválido, ou o Fisco rejeita a inutilização (ex.: faixa já inutilizada).

        {
          "success": false,
          "message": "Rejeição: Faixa de numeração já inutilizada"
        }

POST/api/invoice/get_danfe

Obter DANFE 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.

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 NF-e em lote

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, inclusivo (Unix timestamp em milissegundos). O dia e a hora UTC do valor são lidos como hora de Brasília: envie a meia-noite UTC do dia, ex.: `Date.UTC(2026, 7, 1)` = `1785542400000` vale como 01/08/2026 00:00 em Brasília
end_create_time	long	Fim do período, exclusivo (mesma regra). Envie a meia-noite UTC do dia seguinte ao último dia desejado: para agosto de 2026 inteiro, `Date.UTC(2026, 8, 1)` = `1788220800000`

* Campo obrigatório.

Período: start_create_time/end_create_time são lidos pelo seu dia e hora em UTC e interpretados como hora de Brasília (UTC−3, sem horário de verão). Mande a meia-noite UTC dos dias-calendário: início inclusivo, fim exclusivo. Exemplo, 29/08 a 01/09 de 2026 inteiros: start_create_time = 1787961600000 (2026-08-29T00:00Z) e end_create_time = 1788307200000 (2026-09-02T00:00Z). Não some 3 horas ao valor.

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

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/get_xml" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "type": "xml",
          "status": "Success",
          "start_create_time": 1787961600000,
          "end_create_time": 1788307200000
        }

        {
          "success": true,
          "data": {
            "status": "Processing",
            "progress_count": 120,
            "total_count": 543,
            "url": ""
          }
        }

        {
          "success": true,
          "data": {
            "status": "Success",
            "progress_count": 543,
            "total_count": 543,
            "url": "https://storage.../exports/uid/<sn>.zip"
          }
        }

POST/api/invoice/consultar_status

Consultar situação da NF-e

Consulta o status atual de uma NF-e ou NFC-e diretamente no Fisco 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).
ambiente	string	Qual ambiente consultar: `1`=produção, `2`=homologação (também aceita `producao`/`homologacao`). Se omitido, usa o ambiente em que a nota foi emitida; produção quando a nota não é encontrada localmente. São bases independentes — consultar produção por uma nota emitida em homologação sempre retorna 217.

* Campo obrigatório.

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 do Fisco
motivo	string	Mensagem `xMotivo` bruta do Fisco

Mapeamento de status

`status`	cStat do Fisco	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 pelo Fisco
inutilizada	`102`	Número inutilizado (faixa de numeração)
nao_encontrada	`217`	NF-e não consta na base do Fisco
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
Fisco retornou resposta vazia	O Fisco não devolveu retorno (timeout, fora do ar)
erro ao consultar Fisco: <detalhe>	Exceção ao chamar o serviço (XML inválido, timeout, certificado expirado, etc.)

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 sempre lidos da raiz

Campo	Tipo	Descrição
uuid	string	UUID da NF-e original (devolução total; envie este ou `chave`). É um GUID de 36 caracteres com hífens, não o `_id` de 24 caracteres. Com uuid e sem `return_detail` a nota é clonada por inteiro; se `return_detail` também for enviado, a devolução é parcial
chave	string	Chave de 44 dígitos da NF-e original (obrigatória na devolução parcial; alternativa a `uuid` na devolução total)
return_detail	object	Objeto de detalhe da devolução parcial. Todos os campos da devolução parcial devem ficar dentro deste objeto (cliente, products, transaction_type, model, issuance_type, ambiente, id); deixá-los na raiz retorna erro. `chave`, `cfop` e `natureza_operacao` são sempre lidos da raiz, e o `natureza_operacao` da raiz sobrescreve o de dentro do objeto
cfop *	string	CFOP de devolução. A nota de devolução é de entrada (`tpNF=0`) e exige CFOP de entrada: `"1202"`, `"1411"` dentro do estado; `"2202"`, `"2411"` interestadual. Se omitido, usa `"1202"`/`"2202"` automaticamente. Enviar CFOP de saída (`"5202"`, `"6202"`, ...) conflita com o tpNF e é rejeitado pelo Fisco
natureza_operacao	string	Natureza da operação (ex.: "Devolução de venda"). Alias aceito: `nature_of_operation`

Body — campos dentro de `return_detail`

Todos os campos abaixo vão dentro do objeto return_detail. Colocá-los na raiz da requisição não funciona — o endpoint retorna erro em vez de cair silenciosamente na devolução total.

Campo	Tipo	Descrição
transaction_type	string	Tipo de operação. Obrigatório, mas o valor não tem efeito: o endpoint sobrescreve incondicionalmente para entrada (`tpNF=0`), então `"0"` e `"1"` se comportam igual — é apenas um placeholder
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)
id	string	Número do pedido (chave de deduplicação da devolução). A devolução não usa o mecanismo de reserva de pedido, então a proteção contra duplicidade depende inteiramente deste campo: havendo devolução já emitida para o mesmo `id`, ela é devolvida em vez de emitir outra. Sem ele não há nenhuma proteção e a mesma devolução pode ser emitida repetidamente — altamente recomendado
total_discount_amount	number	Valor de desconto total da nota. Padrão 0
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` Dados tributários via `category_id` ou `impostos` — um ou outro; use o segundo quando a nota de origem foi emitida por outro provedor.
products[].n_item	int	Número do item na nota de origem (1..990). Somente homologação: ali a devolução referencia a origem por item, e a devolução parcial não tem como deduzir esse número (a nota de origem pode não estar nesta plataforma). Sem ele o grupo de referência é omitido e o Fisco devolve `Rejeição 321`. Em produção a referência é no cabeçalho e o campo não é necessário

* 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, ou é enviada direto no item via impostos — um ou outro.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/return" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "4663a257-adf1-4561-971f-6aaffbd30ca8",
          "cfop": "1202",
          "natureza_operacao": "Devolução de venda"
        }

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "1202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "id": "PED-2026-0001",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "total_discount_amount": 0,
            "cliente": {
              "cnpj": "12345678000199",
              "cpf": "",
              "ie": "111222333444",
              "name": "Fornecedor",
              "endereco": "Rua das Flores",
              "number": "1000",
              "complemento": "Sala 2",
              "bairro": "Centro",
              "city": "Sao Paulo",
              "uf": "SP",
              "cep": "01001000",
              "telefone": "1132294790",
              "email": "fornecedor@exemplo.com.br"
            },
            "products": [
              {
                "name": "Produto A",
                "codigo": "SKU-001",
                "ncm": "39269090",
                "cest": "",
                "gtin": "SEM GTIN",
                "gtin_tributavel": "SEM GTIN",
                "count": 1,
                "unit": "UN",
                "unit_price": 100,
                "total_price": 100,
                "discount_price": 0,
                "category_id": "68b1f0c2a1d4e5f6a7b8c9d0",
                "origem": 0,
                "indicador_total": 1,
                "price_includes_ipi": false,
                "n_item_ped": 1,
                "n_item": 1
              }
            ]
          }
        }

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "1202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "id": "PED-2026-0002",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "cliente": {
              "cnpj": "12345678000199",
              "name": "Fornecedor",
              "endereco": "Rua das Flores",
              "number": "1000",
              "bairro": "Centro",
              "city": "Sao Paulo",
              "uf": "SP",
              "cep": "01001000"
            },
            "products": [
              {
                "name": "Produto A",
                "ncm": "39269090",
                "count": 1,
                "unit": "UN",
                "unit_price": 100,
                "total_price": 100,
                "origem": 0,
                "indicador_total": 1,
                "n_item": 1,
                "impostos": {
                  "icms": {
                    "codigo_cfop": "1202",
                    "situacao_tributaria": "102",
                    "tipo_pessoa": "juridica",
                    "aliquota": "18"
                  },
                  "ipi": {
                    "codigo_enquadramento": "999",
                    "situacao_tributaria": "99",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  },
                  "pis": {
                    "situacao_tributaria": "07",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  },
                  "cofins": {
                    "situacao_tributaria": "07",
                    "aliquota": "0.00",
                    "tipo_pessoa": "juridica"
                  }
                }
              }
            ]
          }
        }

Nota

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": "matriz",
              "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).

Nota

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)

POST/api/invoice/create

Emitir NF-e complementar

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)

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.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "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": "matriz",
              "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"
            }
          ]
        }

        {
          "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 NF-e de ajuste

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)

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)

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "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": "matriz",
              "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"
            }
          ]
        }

POST/api/invoice/v2/create

Emitir NF-e (assíncrono)

O corpo da requisição e a validação são idênticos a /api/invoice/create. A diferença é que não espera o Fisco: após a validação a requisição entra na fila e o número de recebimento task_id é devolvido imediatamente; a emissão conclui em segundo plano. Obtenha o resultado consultando /api/invoice/v2/task/get ou receba-o no endereço de webhook configurado no portal (veja “Webhook” abaixo).

Cabeçalhos obrigatórios

Campo	Tipo	Descrição
token	string	Token da empresa emitente
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Os campos são idênticos a /api/invoice/create (cliente, products[], pag_info…) e não se repetem aqui. Um callback_url na requisição é ignorado: o endereço de retorno vem só da configuração do portal.

Campo	Tipo	Descrição
is_reopen	boolean	Reabrir / sobrescrever uma NF-e já emitida, mesmo significado da v1

Regras de processamento

Regra	Descrição
Idempotência	Quando o `id` do pedido é enviado, requisições idênticas do mesmo CNPJ em 5 minutos reutilizam a mesma tarefa e devolvem o mesmo `task_id` sem reenfileirar; sem `id` não há deduplicação.
Limite	No máximo 100 tarefas pendentes ou em processamento por CNPJ por minuto; acima disso a resposta é `Rate limit exceeded for this CNPJ`.
Status	`pending` ao aceitar, `processing` durante a execução, final `success` / `failed`.

Campos da resposta

Campo	Tipo	Descrição
task_id	string	Número da tarefa, usado na consulta e na deduplicação do callback
id	string	Id do pedido enviado (vazio se não informado)
status	string	Status da tarefa, sempre `pending` na aceitação

Resposta — recusada

{ "success": false, "message": "Rate limit exceeded for this CNPJ, please slow down" }

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/v2/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

{
  "id": "PED-1001",
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "cliente": { "cpf": "26443880072", "name": "Nome do Destinatário", "endereco": "Rua Example",
               "number": "100", "bairro": "Centro", "city": "São Paulo", "uf": "SP", "cep": "01310100" },
  "products": [ { "codigo": "P1", "name": "Produto", "ncm": "10063021", "count": 1, "unit": "UN",
                  "unit_price": 100, "total_price": 100, "origem": 0, "indicador_total": 1,
                  "category_id": "CATEGORY_ID" } ],
  "pag_info": [ { "payment_method": "01", "payment_indicator": "0", "payment_value": 100 } ]
}

{
  "success": true,
  "message": "Recebido. Consulte o resultado via /api/invoice/v2/task/get (task_id) ou aguarde o callback. Não reenvie.",
  "task_id": "66d0a1b2c3d4e5f6a7b8c9d0",
  "id": "PED-1001",
  "status": "pending"
}

POST/api/invoice/v2/task/get

Consultar resultado da emissão assíncrona

Consulta status e resultado pela task_id. O caminho oficial é /api/invoice/v2/task/get; o caminho antigo /api/invoice/task/get continua disponível com comportamento e cobrança idênticos. Só tarefas da própria conta podem ser consultadas; caso contrário Task not found. Consulte a cada 1–2 segundos; as tarefas costumam concluir em segundos.

Cabeçalhos obrigatórios

Campo	Tipo	Descrição
token	string	Token da empresa emitente
sign	string	Assinatura MD5
timestamp	string	Unix timestamp em segundos

Body

Campo	Tipo	Descrição
task_id *	string	Número devolvido por `/api/invoice/v2/create`

status

Status	Significado
pending	Aceita, aguardando processamento
processing	Em envio ao Fisco
success	Emitida; a resposta traz o mesmo `data` de `/api/invoice/create`
failed	Emissão falhou; `message` traz o motivo (rejeição do Fisco quando houver)

O status de primeiro nível é o status da tarefa (minúsculo); no sucesso, data.status é o status do resultado da emissão (ex.: Success), idêntico a /api/invoice/create.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/v2/task/get" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

{ "task_id": "66d0a1b2c3d4e5f6a7b8c9d0" }

{ "success": true, "message": "Em processamento, consulte novamente.", "status": "processing" }

{
  "success": true,
  "message": "成功",
  "status": "success",
  "data": {
    "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
    "status": "Success",
    "motivo": "Autorizado o uso da NF-e",
    "nfe": 100,
    "serie": 1,
    "chave": "35260112345678000199550010000001001000000017",
    "modelo": "nfe",
    "epec": false,
    "xml": "https://oss.example.com/.../chave.xml"
  }
}

{ "success": false, "message": "Rejeição 539: Duplicidade de NF-e, com diferença na Chave de Acesso", "status": "failed" }

Nota

Webhook (notificação do resultado da emissão)

Quando a tarefa assíncrona chega ao estado final, a plataforma envia uma notificação ao endereço configurado pelo integrador. Webhook e consulta podem ser combinados: use o callback como principal e a consulta como reserva.

Configuração e requisitos do endereço

Endereço da conta: portal do integrador, “Conta → URL de Webhook”.
Endereço da aplicação: configurado na aplicação (chave de API) que gerencia a empresa, com assinatura opcional por endpoint; tem prioridade sobre o endereço da conta.
callback_url na requisição não é suportado e é ignorado.
O endereço deve ser http(s) público, nunca rede interna ou loopback; redirecionamentos não são seguidos (3xx conta como falha); timeout de 10 s; qualquer 2xx conta como entregue.

Momento da entrega e reenvios

Entregue uma vez imediatamente após a tarefa chegar a success / failed.
Em falha, reenviado em +1 min, +10 min, +60 min, +4 h e +12 h, 6 tentativas no total (cerca de 17 horas); depois a entrega para e /api/invoice/v2/task/get segue disponível como reserva.
Entrega ao menos uma vez; deduplique pela task_id.

Mensagem (descriptografada)

Campo	Tipo	Descrição
task_id	string	Número da tarefa, chave de deduplicação
id	string	Id do pedido enviado
company_id	int	ID da empresa emitente
cnpj	string	CNPJ da empresa emitente
status	string	`success` / `failed`
result	object	No sucesso, o mesmo objeto de resposta de `/api/invoice/create` mais `data.danfe` (URL do DANFE em PDF); `null` na falha
error	string	Motivo da falha, rejeição do Fisco quando houver; string vazia no sucesso
test	boolean	Presente e `true` só nas mensagens do botão “Testar envio” do portal; devem ser ignoradas

{
  "task_id": "66d0a1b2c3d4e5f6a7b8c9d0",
  "id": "PED-1001",
  "company_id": 1263,
  "cnpj": "12345678000199",
  "status": "success",
  "result": {
    "success": true,
    "message": "成功",
    "data": {
      "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
      "status": "Success",
      "motivo": "Autorizado o uso da NF-e",
      "nfe": 100, "serie": 1,
      "chave": "35260112345678000199550010000001001000000017",
      "modelo": "nfe", "epec": false,
      "xml": "https://oss.example.com/.../chave.xml",
      "danfe": "https://oss.example.com/.../chave.pdf"
    }
  },
  "error": ""
}

Envelope criptografado

As mensagens são entregues criptografadas com AES-256-GCM. A chave deriva da chave de API do integrador, sem troca de segredo adicional: key = SHA-256(UTF-8(token)), sendo token a chave da aplicação que gerencia a empresa. O GCM garante integridade: alterar qualquer campo (inclusive ts) faz a descriptografia falhar, por isso não há cabeçalho de assinatura separado.

Cabeçalhos: X-Webhook-Timestamp (Unix em segundos, igual ao ts do envelope) e X-Webhook-Encryption: A256GCM. Se nenhuma chave puder ser resolvida a mensagem vai em texto claro, sem o cabeçalho X-Webhook-Encryption; trate os dois casos por esse cabeçalho.

Descriptografia: nonce, payload e tag em Base64; os dados adicionais autenticados (AAD) são a string decimal de ts (UTF-8).

POST {webhook_url}
Content-Type: application/json
X-Webhook-Timestamp: 1786990396
X-Webhook-Encryption: A256GCM

{
  "enc": "A256GCM",
  "kid": "token",
  "ts": 1786990396,
  "nonce": "<base64, 12 bytes>",
  "payload": "<base64 ciphertext>",
  "tag": "<base64, 16 bytes>"
}

Exemplo em Python (cryptography)

import base64, hashlib, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def decrypt(token, body):
    env = json.loads(body)
    key = hashlib.sha256(token.encode("utf-8")).digest()
    aad = str(env["ts"]).encode("utf-8")
    data = base64.b64decode(env["payload"]) + base64.b64decode(env["tag"])
    plain = AESGCM(key).decrypt(base64.b64decode(env["nonce"]), data, aad)
    return json.loads(plain)

Exemplo em Node.js

const crypto = require("crypto");

function decrypt(token, body) {
  const env = JSON.parse(body);
  const key = crypto.createHash("sha256").update(token, "utf8").digest();
  const d = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(env.nonce, "base64"));
  d.setAAD(Buffer.from(String(env.ts), "utf8"));
  d.setAuthTag(Buffer.from(env.tag, "base64"));
  const plain = Buffer.concat([d.update(Buffer.from(env.payload, "base64")), d.final()]);
  return JSON.parse(plain.toString("utf8"));
}

Homologação

O botão “Testar envio” ao lado da URL de Webhook no portal envia uma mensagem de teste criptografada (test: true) para validar conectividade e descriptografia.
A caixa de entrada de teste do sistema (/webhook/inbox/{slot}, slot um identificador à sua escolha) também pode ser configurada como URL de Webhook; as mensagens descriptografadas ficam visíveis no portal.

Nota

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) ao Fisco 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 Fisco: 15–1000 caracteres)
n_seq_evento	int	Número sequencial do evento. Por padrão é calculado a partir das cartas de correção já registradas nesta plataforma. Informe um valor maior quando a nota já tiver recebido cartas de correção em outro provedor

* Campo obrigatório. Pelo menos um entre uuid e chave também é obrigatório.

Notas emitidas em outro provedor também aceitam carta de correção: a carta é um evento independente da nota original e basta que o CNPJ do emitente contido na chave de acesso pertença a uma empresa deste token. Para essas notas a plataforma não possui o registro original, portanto o número sequencial não pode ser calculado e assume 1. Caso o Fisco informe que já existe evento com esse número, reenvie com n_seq_evento maior. Para essas notas o PDF da carta de correção não fica disponível, apenas o XML do evento.

POST/api/invoice/cce/get_list

Listar CC-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.

# sign = md5(token + path + body + timestamp)
# Modelo gerado a partir do caminho; substitua os placeholders
curl -X POST "https://api.tffiscal.com/api/invoice/cce/get_list" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

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

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 ao Fisco).

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.

Headers obrigatórios

Body — campos top-level

Body — cliente (objeto, obrigatório)

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

Body — products[].impostos

Interestadual: como informar a base do DIFAL

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)

Campos da resposta (data)

Resposta — rejeição / erro

Headers obrigatórios

Query string

Headers obrigatórios

Query string

Headers obrigatórios

Body

Headers obrigatórios

Body

Campos da resposta (data)

Resposta — erro

Headers obrigatórios

Body

Campos da resposta (data)

Resposta — erro

Headers obrigatórios

Body

Campos da Resposta

Respostas de erro

Headers obrigatórios

Body

Campos da Resposta

Respostas de erro

Headers obrigatórios

Body

Campos da resposta

Mapeamento de status

Respostas de erro

Headers obrigatórios

Body — campos sempre lidos da raiz

Body — campos dentro de return_detail

Exemplo Completo com Transporte

Exemplo Completo de Importação

Autenticação

Headers obrigatórios

Campos específicos

Headers obrigatórios

Campos específicos

Cabeçalhos obrigatórios

Body

Regras de processamento

Campos da resposta

Resposta — recusada

Cabeçalhos obrigatórios

Body

status

Configuração e requisitos do endereço

Momento da entrega e reenvios

Mensagem (descriptografada)

Envelope criptografado

Homologação

Autenticação

Headers obrigatórios

Body

Headers obrigatórios

Body

Headers obrigatórios

Body

Headers obrigatórios

Body

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

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

Body — `products[].impostos`

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)

Campos da resposta (`data`)

Campos da resposta (`data`)

Campos da resposta (`data`)

Body — campos dentro de `return_detail`