DC-e · TF Fiscal API

Nota

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

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

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

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

POST/api/dce/create

Emitir DC-e

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

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp em segundos (janela de 5 minutos)

Body — raiz

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

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

ide — Identificação

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

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

emit — Emitente / Remetente

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

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

dest — Destinatário

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

enderEmit / enderDest — Endereço

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

det[] — Itens declarados

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

total — Totalizador

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

transp — Transporte

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

marketplace — Marketplace (somente `tpEmit=1`)

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

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

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

autXML[] — Autorizados ao XML

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

infAdic — Informações adicionais

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

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

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

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

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

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

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

POST/api/dce/consult

Consultar situação da DC-e

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

Headers obrigatórios

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

Body

Campo	Tipo	Descrição
chDCe *	string	Chave de acesso da DC-e (44 dígitos)

* Campo obrigatório.

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

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

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

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

POST/api/dce/cancel

Cancelar DC-e

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

Headers obrigatórios

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

Body

Campo	Tipo	Descrição
chDCe *	string	Chave de acesso da DC-e (44 dígitos)
xJust *	string	Justificativa do cancelamento (mínimo 15 caracteres por exigência Fisco)
nProt	string	Protocolo de autorização. Opcional: quando omitido, usa o protocolo registrado na emissão

* Campo obrigatório.

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

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

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

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

POST/api/dce/pdf

Obter PDF da DC-e

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

Headers obrigatórios

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

Body

Campo	Tipo	Descrição
chDCe *	string	Chave de acesso da DC-e (44 dígitos)

* Campo obrigatório.

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

        {
          "chDCe": "41250612345678000199990010000000011201234564"
        }

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

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

GET/api/dce/get_list

Listar DC-e (com paginação)

Lista as DC-e da empresa com paginação. Parâmetros passados via query string (não no body). O filtro de tempo é opcional, mas se enviado exige ambos start_create_time e end_create_time.

Headers obrigatórios

Header	Tipo	Descrição
token	string	Token da empresa emissora
sign	string	Assinatura MD5 (path inclui a query string)
timestamp	string	Unix timestamp em segundos

Query string

Parâmetro	Tipo	Descrição
page *	int	Número da página (≥ 1)
page_size *	int	Tamanho da página (1–50)
start_create_time	long	Unix timestamp em milissegundos — início (exige `end_create_time`)
end_create_time	long	Unix timestamp em milissegundos — fim
status	string	Filtrar por status. Valores: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (em processamento), `"Failed"` (falhou), `"Unknown"` (desconhecido)

* Campo obrigatório.

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

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

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

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

Emitir DC-e

Headers obrigatórios

Body — raiz

ide — Identificação

emit — Emitente / Remetente

dest — Destinatário

enderEmit / enderDest — Endereço

det[] — Itens declarados

total — Totalizador

transp — Transporte

marketplace — Marketplace (somente tpEmit=1)

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

autXML[] — Autorizados ao XML

infAdic — Informações adicionais

Consultar situação da DC-e

Headers obrigatórios

Body

Cancelar DC-e

Headers obrigatórios

Body

Obter PDF da DC-e

Headers obrigatórios

Body

Listar DC-e (com paginação)

Headers obrigatórios

Query string

marketplace — Marketplace (somente `tpEmit=1`)

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