NFC-e · TF Fiscal API

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_content *	string	Conteúdo do arquivo do certificado A1 (.pfx/.p12) em Base64
cert_file	string	Descontinuado — rejeitado a partir de 2026-09-01. URL HTTPS do certificado
cert_pwd *	string	Senha do certificado
csc_id *	string	ID do CSC (Código de Segurança do Contribuinte) no Fisco
csc *	string	Token CSC (segredo compartilhado com o Fisco)
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.

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

        {
          "cnpj": "12345678000199",
          "cert_content": "MIIOkAIBAzCC...(Base64)",
          "cert_pwd": "senha_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

        {
          "success": true,
          "message": "Empresa cadastrada para NFC-e",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST/api/nfce/company/update

Atualizar 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_content 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_content	string	Conteúdo do arquivo do certificado A1 (.pfx/.p12) em Base64
cert_file	string	Descontinuado — rejeitado a partir de 2026-09-01. URL HTTPS do certificado
cert_pwd	string	Senha do certificado

Pelo menos 1 campo no body é obrigatório. CNPJ é imutável.

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

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

        {
          "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_content": "MIIOkAIBAzCC...(Base64)",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

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

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
aliquota_reducao_st	decimal	Percentual de redução da base do ICMS-ST
aliquota_credito	decimal	Alíquota de crédito do Simples Nacional em % (CSOSN 101, 201, 900)
aliquota_diferimento	decimal	Percentual de diferimento do ICMS (CST 51)
motivo_desoneracao	string	Código do motivo de desoneração
ad_rem_icms	decimal	ICMS monofásico — alíquota ad rem em R$/unidade (CST 02, 15, 53)
ad_rem_icms_ret	decimal	ICMS monofásico — ad rem retido em R$/unidade (CST 15, 61)
p_dif_mono	decimal	ICMS monofásico — percentual de diferimento (CST 53)
q_bc_mono	decimal	ICMS monofásico — quantidade tributada (litros/kg); 0 usa a quantidade do item (CST 02, 15, 53)
valor_desoneracao	decimal	Valor do ICMS desonerado em R$ — emite vICMSDeson (CST 40, 41, 50, 90)
v_bc_st_ret	decimal	Base de cálculo do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
p_st	decimal	Alíquota suportada pelo consumidor final em % (informado, não calculado — CST 60, CSOSN 500)
v_icms_st_ret	decimal	Valor do ICMS-ST retido na operação anterior (informado, não calculado — CST 60, CSOSN 500)
v_icms_substituto	decimal	Valor do ICMS próprio do substituto (informado, não calculado — CST 60, CSOSN 500)
v_bc_fcp_st_ret	decimal	Base de cálculo do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
p_fcp_st_ret	decimal	Alíquota do FCP retido por ST em % (informado, não calculado — CST 60, CSOSN 500)
v_fcp_st_ret	decimal	Valor do FCP retido por ST (informado, não calculado — CST 60, CSOSN 500)
aliquota_icms	array	Alíquotas por estado: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_icms_st	array	Alíquota ICMS-ST por estado: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_mva	array	MVA/IVA-ST por estado: `[{ "estado": "SP", "aliquota": 40.00 }]`
aliquota_fcp	array	FCP por estado: `[{ "estado": "SP", "aliquota": 0.00 }]`
aliquota_fcp_st	array	FCP-ST 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")
valor_unidade	string	PIS/COFINS por quantidade — valor em R$/unidade; v = quantidade × valor (CST 03 e demais formas por quantidade)

ibs_cbs (opcional)

Campo	Tipo	Descrição
situacao_tributaria *	string	CST IBS/CBS
classificacao_tributaria *	string	Código de classificação tributária
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
p_ibs_mun	string	Alíquota do IBS Município em % (opcional; padrão 0 em 2026)
p_cbs	string	Alíquota da CBS em % (opcional; padrão 0,90 em 2026)
p_red_aliq	string	Percentual de redução de alíquota (CST 011, 200, 515)
p_dif	string	Percentual de diferimento (CST 510, 515)
p_red_bc	string	Percentual de redução da base de cálculo (CST 222)
proporcao	string	Proporção da operação em % (CST 221)
aliquota_cbs_mono	string	CBS monofásica — alíquota em % sobre a base; prevalece sobre `valor_unidade_cbs` (CST 620)
aliquota_ibs_mono	string	IBS monofásico — alíquota em % sobre a base; prevalece sobre `valor_unidade_ibs` (CST 620)
valor_unidade_cbs	string	CBS monofásica — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
valor_unidade_ibs	string	IBS monofásico — ad rem em R$/unidade; só usado quando não há alíquota percentual (CST 620)
valor_deducao_legal	string	Valor da dedução legal da base em R$ (CST 830)

* Campo 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/nfce/category/create" \
  -H "Content-Type: application/json" \
  -H "token: $TOKEN" \
  -H "timestamp: $TIMESTAMP" \
  -H "sign: $SIGN" \
  -d @body.json

        {
          "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",
            "p_ibs_uf": "0.1",
            "p_ibs_mun": "0",
            "p_cbs": "0.9"
          }
        }

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

GET/api/nfce/category/get_detail

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

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

GET /api/nfce/category/get_detail?category_id=TF00001

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "desconta_icms_pis_cofins": false,
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "aliquota_credito": 0,
              "aliquota_diferimento": 0,
              "motivo_desoneracao": "",
              "ad_rem_icms": 0,
              "ad_rem_icms_ret": 0,
              "p_dif_mono": 0,
              "q_bc_mono": 0,
              "valor_desoneracao": 0,
              "v_bc_st_ret": 0,
              "p_st": 0,
              "v_icms_st_ret": 0,
              "v_icms_substituto": 0,
              "v_bc_fcp_st_ret": 0,
              "p_fcp_st_ret": 0,
              "v_fcp_st_ret": 0,
              "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",
              "valor_unidade": ""
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00",
              "valor_unidade": ""
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001",
              "p_ibs_uf": "0.1",
              "p_ibs_mun": "0",
              "p_cbs": "0.9",
              "p_red_aliq": "",
              "p_dif": "",
              "p_red_bc": "",
              "proporcao": "",
              "aliquota_cbs_mono": "",
              "aliquota_ibs_mono": "",
              "valor_unidade_cbs": "",
              "valor_unidade_ibs": "",
              "valor_deducao_legal": ""
            }
          }
        }

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.

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

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

        {
          "success": true,
          "data": {
            "list": [
              {
                "category_id": "TF00001",
                "descricao": "Bebidas não alcoólicas",
                "ibs_cbs": [{
                  "situacao_tributaria": "000",
                  "classificacao_tributaria": "000001",
                  "p_ibs_uf": "0.1",
                  "p_ibs_mun": "0",
                  "p_cbs": "0.9",
                  "p_red_aliq": "",
                  "p_dif": "",
                  "p_red_bc": "",
                  "proporcao": "",
                  "aliquota_cbs_mono": "",
                  "aliquota_ibs_mono": "",
                  "valor_unidade_cbs": "",
                  "valor_unidade_ibs": "",
                  "valor_deducao_legal": ""
                }]
              },
              {
                "category_id": "TF00002",
                "descricao": "Alimentos industrializados",
                "ibs_cbs": []
              }
            ],
            "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.

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

        {
          "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",
            "p_ibs_uf": "0.1",
            "p_ibs_mun": "0",
            "p_cbs": "0.9"
          }
        }

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

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)
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 ou impostos, um deles é obrigatório.

Campos da resposta (`data`)

Campo	Tipo	Descrição
uuid	string	Identificador interno da NFC-e. Use nas consultas seguintes (`/api/nfce/get_detail`, `/api/nfce/get_danfe`)
status	string	Situação: `"Success"` (autorizada), `"Failed"` (rejeitada/falha), `"Contingencia"` (emitida em contingência offline, pendente de transmissão)
motivo	string	Mensagem oficial do Fisco conforme o `cStat` (formato bilíngue PT / 中文)
nfce	int	Número da NFC-e emitida (atenção: o campo chama-se `nfce`, não `nfe`)
serie	int	Série da NFC-e
chave	string	Chave de acesso de 44 dígitos (vazia quando a nota não é autorizada)
modelo	string	Modelo do documento: `"nfce"`
xml	string	URL do XML autorizado
danfe	string	URL do DANFE NFC-e — vem vazio na emissão; gere sob demanda com `/api/nfce/get_danfe`

Na contingência offline (issuance_type = "9" ou Fisco indisponível), a resposta vem com status: "Contingencia" e os campos extras contingencia: true e tpEmis: 9; a nota precisa ser transmitida ao Fisco depois.

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: 发件人所在州代码与授权州不一致",
            "nfce": 5,
            "serie": 1,
            "chave": "",
            "modelo": "nfce",
            "xml": "",
            "danfe": ""
          }
        }

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

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

        {
          "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": "matriz",
              "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": "matriz",
              "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",
                  "p_ibs_uf": "0.1",
                  "p_ibs_mun": "0",
                  "p_cbs": "0.9"
                }
              }
            }
          ],
          "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"
              }
            }
          ]
        }

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "status": "Success",
            "motivo": "Autorizado o uso da NF-e",
            "nfce": 5,
            "serie": 1,
            "chave": "35210112345678901234650010000000051234567890",
            "modelo": "nfce",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": ""
          }
        }

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 ao Fisco. A janela de cancelamento no Fisco é 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 Fisco)

* Campo obrigatório.

Campos da resposta (`data`)

Campo	Tipo	Descrição
motivo	string	Mensagem oficial do Fisco para o evento de cancelamento
status	string	Situação: `"Canceled"` (cancelada)
nfce	int	Número da NFC-e cancelada
serie	int	Série da NFC-e
chave	string	Chave de acesso de 44 dígitos
modelo	string	Modelo do documento: `"nfce"`
cStat	int	Código do evento no Fisco: `135` ou `155` = cancelamento homologado. Se a NFC-e já estava cancelada, a resposta de sucesso vem sem `cStat`

Resposta — erro

Quando o Fisco rejeita o evento (ex.: prazo de cancelamento excedido), success é false e data vem com status: "Failed" e o cStat da rejeição. Erros de validação (chave/motivo ausentes, motivo com menos de 15 caracteres, NFC-e não encontrada, contingência ainda não transmitida) retornam success: false com a mensagem em message, sem o objeto data.

        {
          "success": false,
          "data": {
            "motivo": "Rejeição: Pedido de Cancelamento intempestivo",
            "status": "Failed",
            "nfce": 5,
            "serie": 1,
            "chave": "35210112345678901234650010000000051234567890",
            "modelo": "nfce",
            "cStat": 501
          }
        }

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

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

        {
          "success": true,
          "data": {
            "motivo": "Evento registrado e vinculado a NF-e",
            "status": "Canceled",
            "nfce": 5,
            "serie": 1,
            "chave": "35210112345678901234650010000000051234567890",
            "modelo": "nfce",
            "cStat": 135
          }
        }

POST/api/nfce/return

Devolver NFC-e

Emite a devolução de uma NFC-e autorizada. A devolução é uma NF-e de entrada (modelo 55) que referencia a chave de acesso da NFC-e de origem no XML; a NFC-e não possui documento de devolução próprio. A nota de origem é localizada entre os registros de NFC-e por uuid ou chave, e itens e campos tributários são reaproveitados dela. /api/invoice/return procura a origem apenas entre as NF-e e responde "nota fiscal não existe" para qualquer NFC-e; utilize esta rota.

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	Obrigatório	Descrição
uuid	string	Não	uuid da NFC-e de origem. Informe este campo ou `chave`
chave	string	Não	Chave de acesso de 44 dígitos da NFC-e de origem. Informe este campo ou `uuid`
cfop	string	Sim	CFOP da devolução; em geral `1202` dentro do estado e `2202` entre estados
natureza_operacao	string	Não	Natureza da operação. Padrão `Devolução de Mercadoria`
cliente	object	Não	Destinatário, isto é, o comprador da nota de origem. Campos: `cpf`, `cnpj`, `name`, `endereco`, `numero`, `complemento`, `bairro`, `city`, `uf`, `cep`, `email`, `telefone`. Os campos enviados substituem os da origem; os omitidos são mantidos

A devolução é uma NF-e e o endereço do destinatário é obrigatório, enquanto a NFC-e normalmente não registra o endereço do comprador. Quando o XML de origem não traz endereço, cliente deve conter endereco, bairro, city, uf e cep; a rota informa quais faltam.

Somente NFC-e autorizada pode ser devolvida. O ambiente (produção ou homologação) segue o da nota de origem e não é informado como parâmetro.

Chamadas repetidas não emitem duas vezes: se já existe devolução para a mesma origem no mesmo ambiente, aquele documento é devolvido na resposta.

A devolução é integral. Itens, quantidades e campos tributários vêm da origem; os tributos são resolvidos primeiro pela categoria fiscal e, na falta dela, copiados da CST e das alíquotas do XML de origem.

Campos da resposta (`data`)

Campo	Tipo	Descrição
uuid	string	Identificador da nota de devolução
status	string	`Success` autorizada, `Failed` rejeitada
motivo	string	Mensagem retornada pelo Fisco
nfe	int	Número da nota de devolução
serie	int	Série da nota de devolução
chave	string	Chave de acesso de 44 dígitos da nota de devolução
modelo	string	Sempre `nfe`: a devolução é uma NF-e
epec	boolean	Se a emissão ocorreu em contingência
xml	string	URL do XML da nota de devolução

Resposta — erro

Em problemas de parâmetro ou da nota de origem, success é false, o motivo vem em message e não há data. Quando o Fisco rejeita o documento, success também é false, porém data está presente com status igual a Failed e o motivo em motivo.

        {
          "success": false,
          "message": "A devolução é uma NF-e e exige o endereço do comprador; a NFC-e original não o traz. Informe em cliente: endereco, bairro, city, uf, cep / 退货票是 NF-e，必须有买方地址，原 NFC-e 没有。请在 cliente 里传：endereco、bairro、city、uf、cep"
        }

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

        {
          "chave": "35210112345678901234650010000000051234567890",
          "cfop": "1202",
          "natureza_operacao": "Devolucao de venda",
          "cliente": {
            "cpf": "12345678909",
            "name": "Cliente Exemplo",
            "endereco": "Av. Paulista",
            "numero": "1000",
            "bairro": "Bela Vista",
            "city": "Sao Paulo",
            "uf": "SP",
            "cep": "01311000"
          }
        }

        {
          "success": true,
          "message": "成功",
          "data": {
            "uuid": "8f2d6c1e-4b3a-4c9d-9e7f-1a2b3c4d5e6f",
            "status": "Success",
            "motivo": "Rejeição 100: Autorizado o uso da NF-e",
            "nfe": 31,
            "serie": 1,
            "chave": "35210112345678901234550010000000311234567891",
            "modelo": "nfe",
            "epec": false,
            "xml": "https://tffiscal-file.tffiscal.com/xml/.../35210112345678901234550010000000311234567891.xml"
          }
        }

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.

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

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

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

Obter DANFE da NFC-e

Retorna a URL do DANFE NFC-e (cupom fiscal eletrônico) em PDF, com QR Code para consulta no Fisco. 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.

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.

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

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

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

POST/api/nfce/export

Exportar NFC-e em lote

Exporta em lote as NFC-e de produção da empresa por período (notas de homologação não entram). A geração é assíncrona: a primeira chamada dispara a exportação e responde "status": "Processing"; repita a mesma chamada (mesmo body) até receber "status": "Success" com a url de download. XML e PDF saem em .zip (um arquivo por nota); planilha sai em .xlsx ou .csv. O resultado vale por 10 dias: nesse prazo, os mesmos parâmetros devolvem o mesmo arquivo (notas emitidas depois da geração não entram — use outro período para gerar um arquivo novo).

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	`"xml"` (ZIP de XMLs), `"pdf"` (ZIP de DANFEs) ou `"sheet"` (planilha)
start_create_time	string	Data inicial `dd/MM/yyyy`, hora de Brasília — o período começa às 00:00:00 desse dia
end_create_time	string	Data final `dd/MM/yyyy` — o dia final entra inteiro (até 23:59:59)
month	int	Alternativa ao período: mês completo (1–12, hora de Brasília); mês maior que o atual = ano passado
status	string	`"all"` (padrão), `"emitida"`, `"cancelada"` ou `"contingencia"`
pattern	string	Para sheet: `"xlsx"` (padrão) ou `"csv"`. Para pdf: largura do cupom em mm — `"80"` (padrão), `"72"` ou `"50"`

* Campo obrigatório. Informe o período com start_create_time + end_create_time ou com month.

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

        {
          "type": "sheet",
          "start_create_time": "01/08/2026",
          "end_create_time": "31/08/2026",
          "status": "all"
        }

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

        {
          "success": true,
          "data": {
            "status": "Success",
            "progress_count": 450,
            "total_count": 450,
            "url": "https://.../nfce-export/12345678000190_NFCe_planilha_01-08-2026_a_31-08-2026_todas_20260824153000.xlsx"
          }
        }

Nota

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

Headers obrigatórios

Body

Headers obrigatórios

Body (todos os campos opcionais — envie ≥ 1)

Headers obrigatórios

Body

Gerenciamento de Categorias Fiscais NFC-e

Headers obrigatórios

Body (raiz)

icms

pis / cofins

ibs_cbs (opcional)

Headers obrigatórios

Query string

Headers obrigatórios

Query string

Headers obrigatórios

Campo adicional

Headers obrigatórios

Body

Headers obrigatórios

Body (raiz)

client (opcional)

products[] (cada item)

pag_info[] (cada item)

Campos da resposta (data)

Resposta — rejeição / erro

Headers obrigatórios

Body

Campos da resposta (data)

Resposta — erro

Headers obrigatórios

Body

Campos da resposta (data)

Resposta — erro

Headers obrigatórios

Query string

Headers obrigatórios

Body

Headers obrigatórios

Query string

Headers obrigatórios

Body

Exemplo 1 — Venda Presencial (sem destinatário)

Exemplo 2 — Entrega a Domicílio (com destinatário)

Campos da resposta (`data`)

Campos da resposta (`data`)

Campos da resposta (`data`)