DC-e · TF Fiscal API

Nota

DC-e — Declaración de Contenido Electrónica

La API de DC-e (modelo 99, layout 1.00) permite emitir, consultar, cancelar y obtener el PDF (DACE) de declaraciones de contenido electrónicas. La DC-e es el documento fiscal que ampara el transporte de bienes o mercancías cuando no existe obligación de emisión de nota fiscal — por ejemplo, envíos que involucran no contribuyentes del ICMS. El emisor es siempre persona jurídica (CNPJ); el destinatario puede ser persona jurídica (CNPJ) o física (CPF). Los datos de negocio van en el cuerpo del /create; los campos técnicos de la clave de acceso (cDC, cDV, cUF, dhEmi, mod) son calculados automáticamente por el servidor.

Endpoint	Método	Descripción
`/api/dce/create`	POST	Emitir DC-e
`/api/dce/consult`	POST	Consultar situación de la DC-e
`/api/dce/cancel`	POST	Cancelar DC-e autorizada
`/api/dce/pdf`	POST	Obtener el DACE (PDF) de la DC-e

La DC-e se enruta al autorizador de la UF del emisor. El campo ide.cUF debe ser coherente con la UF informada en emit.enderEmit.UF — autoridad fiscal rechaza con cStat=220 cuando divergen; si se omite, el cUF se deriva de esa UF.

POST/api/dce/create

Emitir DC-e

Emite una DC-e a partir del cuerpo enviado. El cliente envía únicamente los datos de negocio; los campos de identificación técnica de la clave de acceso son calculados por el servidor (ver la nota debajo de la tabla ide). El débito de crédito ocurre solo en producción (tpAmb=1) y cuando la DC-e es autorizada.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5: `MD5(token + path + body + timestamp)`
timestamp	string	Unix timestamp en segundos (ventana de 5 minutos)

Body — raíz

Campo	Tipo	Descripción
ide *	object	Identificación de la DC-e
emit *	object	Datos del emisor/remitente (CNPJ; o CPF vía Marketplace — ver abajo)
dest *	object	Datos del destinatario
det *	array	Ítems/bienes declarados — mínimo 1
total *	object	Totalizador de la declaración
transp	object	Datos del transporte
marketplace	object	Datos del marketplace (solo cuando `ide.tpEmit=1`)
fisco	object	Datos del órgano del Fisco (solo cuando `ide.tpEmit=0`)
autXML	array	CNPJ/CPF autorizados a acceder al XML
infAdic	object	Información adicional

Campos obligatorios en la solicitud: ide.tpAmb; emit.CNPJ (14 dígitos) o emit.CPF (11 dígitos, remitente PF vía Marketplace — ver la nota en emit), emit.xNome y emit.enderEmit (xLgr, nro, xBairro, cMun, xMun, CEP con 8 dígitos, UF); dest con CNPJ o CPF, dest.xNome y dest.enderDest (los mismos campos de dirección); al menos 1 ítem en det con xProd, NCM (2 u 8 dígitos), qCom > 0 y vProd > 0; y total.vDC > 0. Todos los demás campos son opcionales.

ide — Identificación

Campo	Tipo	Descripción
tpAmb *	int	Ambiente: `1`=producción, `2`=homologación. Único campo de `ide` realmente obligatorio.
tpEmit	int	Tipo de emisor: `0`=Aplicación del Fisco, `1`=Marketplace, `2`=Emisor propio. Opcional — default: `2`
cUF	int	Código IBGE de la UF del emisor (2 dígitos). Opcional — derivado de `emit.enderEmit.UF` cuando se omite. Si se envía, debe ser coherente con esa UF (autoridad fiscal rechaza con `cStat=220` en caso de divergencia)
serie	int	Serie del documento fiscal (3 dígitos de la clave de acceso) — identifica el conjunto de numeración de la DC-e. Opcional — default: serie de DC-e registrada en la empresa
nDC	long	Número secuencial de la DC-e (compone la clave de acceso). Opcional — auto-incrementado por el servidor cuando se omite o es `0`
nSiteAutoriz	int	Identificación del sitio autorizador que procesó la DC-e (1 dígito de la clave de acceso). Normalmente `0` (sitio primario). Opcional — default: `0`
tpEmis	int	Forma de emisión: `1`=Normal, `9`=Contingencia. Opcional — default: `1`

Rellenados automáticamente por el servidor — no es necesario enviarlos: mod (fijo en 99) y cDV (dígito verificador de la clave) son siempre definidos por el servidor; cDC (código numérico de 6 dígitos), dhEmi (fecha/hora de emisión) y verProc (versión del proceso) se generan cuando se omiten. Los campos serie, nDC y cUF de la tabla anterior también se rellenan automáticamente cuando se omiten.

emit — Emisor / Remitente

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del emisor (14 dígitos). Rellenado con el CNPJ de la empresa del token cuando se omite
CPF ⚠	string	CPF del remitente persona física (11 dígitos). Solo permitido en la emisión vía Marketplace — ver nota abajo
xNome *	string	Nombre o razón social del emisor/remitente
enderEmit *	object	Dirección del emisor (ver estructura abajo)

Remitente persona física (CPF): por la regla de la autoridad fiscal, un CPF no puede ser emisor propio (tpEmit=2 exige CNPJ). Para emitir con un CPF como remitente, basta enviar emit.CPF (sin emit.CNPJ): el servidor define automáticamente tpEmit=1 (Marketplace), usa el CNPJ de su empresa (del token) como emisor autorizado en la clave de acceso y rellena el bloque marketplace con los datos de la empresa. El CPF informado aparece como remitente en emit.

dest — Destinatario

Campo	Tipo	Descripción
CNPJ ⚠	string	CNPJ del destinatario (14 dígitos)
CPF ⚠	string	CPF del destinatario (11 dígitos)
xNome *	string	Nombre o razón social del destinatario
enderDest *	object	Dirección del destinatario (ver estructura abajo)

enderEmit / enderDest — Dirección

Campo	Tipo	Descripción
xLgr *	string	Calle
nro *	string	Número
xCpl	string	Complemento
xBairro *	string	Barrio
cMun *	long	Código IBGE del municipio (7 dígitos)
xMun *	string	Nombre del municipio
CEP *	string	Código postal (8 dígitos)
UF *	string	Sigla de la UF (2 letras)
cPais	int	Código del país. Default: `1058` (Brasil)
xPais	string	Nombre del país. Default: `BRASIL`
fone	string	Teléfono
email	string	Correo electrónico

det[] — Ítems declarados

Campo	Tipo	Descripción
nItem	int	Número secuencial del ítem
xProd *	string	Descripción del bien/mercancía declarado
NCM *	string	Código NCM (2 u 8 dígitos)
qCom *	decimal	Cantidad (> 0)
vUnCom	decimal	Valor unitario
vProd *	decimal	Valor total del ítem (> 0)
infAdProd	string	Información adicional del ítem

total — Totalizador

Campo	Tipo	Descripción
vDC *	decimal	Valor total declarado (> 0)

transp — Transporte

Campo	Tipo	Descripción
modTrans	int	Modalidad del transporte: `0`=Correos, `1`=propia, `2`=transportista. Default: `2`
CNPJTransp	string	CNPJ del transportista

marketplace — Marketplace (solo `tpEmit=1`)

Campo	Tipo	Descripción
CNPJ	string	CNPJ del marketplace
xNome	string	Nombre del marketplace
Site	string	Sitio del marketplace

fisco — Órgano del Fisco (solo `tpEmit=0`)

Campo	Tipo	Descripción
CNPJ	string	CNPJ del órgano
xOrgao	string	Nombre del órgano
UF	string	UF del órgano

autXML[] — Autorizados al XML

Campo	Tipo	Descripción
CNPJ	string	CNPJ autorizado a consultar/descargar el XML
CPF	string	CPF autorizado a consultar/descargar el XML

infAdic — Información adicional

Campo	Tipo	Descripción
infAdFisco	string	Información de interés del Fisco
infCpl	string	Información complementaria de interés del contribuyente
infAdMarketPlace	string	Información adicional del marketplace

* Campo obligatorio. ⚠ En el emisor y en el destinatario, al menos uno de CNPJ o CPF es obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 situación de la DC-e

Consulta la situación actual de la DC-e en la autoridad fiscal a partir de la clave de acceso. Cuando la DC-e está cancelada, la respuesta refleja los datos de la cancelación (la base local es la fuente de la verdad sobre la cancelación).

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 una DC-e autorizada (evento 110111). Requiere que la DC-e haya sido autorizada (posea protocolo) y aún no esté cancelada. Cada DC-e admite una única cancelación.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)
xJust *	string	Justificación de la cancelación (mínimo 15 caracteres por exigencia de la autoridad fiscal)
nProt	string	Protocolo de autorización. Opcional: cuando se omite, usa el protocolo registrado en la emisión

* Campo obligatorio.

En caso de rechazo, la respuesta retorna success=false, el cStat/xMotivo de la negativa y un campo adicional xmlEnviadoDebug con el XML enviado, para diagnóstico.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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

Obtener PDF de la DC-e

Retorna la URL del DACE — la representación en PDF de la DC-e. Cuando el PDF aún no existe en el almacenamiento, se genera bajo demanda y se envía. En caso de que el almacenamiento esté indisponible, el PDF se retorna en base64 en el propio cuerpo de la respuesta.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5
timestamp	string	Unix timestamp en segundos

Body

Campo	Tipo	Descripción
chDCe *	string	Clave de acceso de la DC-e (44 dígitos)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 (paginado)

Lista las DC-e de la empresa con paginación. Los parámetros se pasan por query string (no en el body). El filtro de tiempo es opcional, pero si se envía requiere tanto start_create_time como end_create_time.

Headers obligatorios

Header	Tipo	Descripción
token	string	Token de la empresa emisora
sign	string	Firma MD5 (path incluye la query string)
timestamp	string	Unix timestamp en segundos

Query string

Parámetro	Tipo	Descripción
page *	int	Número de página (≥ 1)
page_size *	int	Tamaño de página (1–50)
start_create_time	long	Unix timestamp en milisegundos — inicio (requiere `end_create_time`)
end_create_time	long	Unix timestamp en milisegundos — fin
status	string	Filtrar por estado. Valores: `"Success"` (autorizado), `"Canceled"` (cancelado), `"Processing"` (en proceso), `"Failed"` (falló), `"Unknown"` (desconocido)

* Campo obligatorio.

# sign = md5(token + path + body + timestamp)
# Plantilla generada desde la ruta; reemplace los 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 — Declaración de Contenido Electrónica

Emitir DC-e

Headers obligatorios

Body — raíz

ide — Identificación

emit — Emisor / Remitente

dest — Destinatario

enderEmit / enderDest — Dirección

det[] — Ítems declarados

total — Totalizador

transp — Transporte

marketplace — Marketplace (solo tpEmit=1)

fisco — Órgano del Fisco (solo tpEmit=0)

autXML[] — Autorizados al XML

infAdic — Información adicional

Consultar situación de la DC-e

Headers obligatorios

Body

Cancelar DC-e

Headers obligatorios

Body

Obtener PDF de la DC-e

Headers obligatorios

Body

Listar DC-e (paginado)

Headers obligatorios

Query string

marketplace — Marketplace (solo `tpEmit=1`)

fisco — Órgano del Fisco (solo `tpEmit=0`)