DC-e 内容申报 · TF Fiscal API

说明

DC-e — 电子内容声明

DC-e API（型号 99，布局 1.00）支持开具、查询、取消电子内容声明并获取其 PDF（DACE）。DC-e 是在无须开具发票时为货物或商品运输提供凭证的税务文档——例如涉及 ICMS 非纳税人的发货。开具方始终为法人（CNPJ）；收件方可以是法人（CNPJ）或自然人（CPF）。业务数据放在 /create 的请求体中；访问密钥的技术字段（cDC、cDV、cUF、dhEmi、mod）由服务器自动计算。

端点	方法	说明
`/api/dce/create`	POST	开具 DC-e
`/api/dce/consult`	POST	查询 DC-e 状态
`/api/dce/cancel`	POST	取消已授权的 DC-e
`/api/dce/pdf`	POST	获取 DC-e 的 DACE（PDF）

DC-e 被路由到开具方所在 UF 的授权方。字段 ide.cUF 必须与 emit.enderEmit.UF 中填写的 UF 一致——两者不一致时税务局会以 cStat=220 拒绝；若省略，则从该 UF 推导出 cUF。

POST/api/dce/create

开具 DC-e

根据发送的请求体开具一张 DC-e。客户端只发送业务数据；访问密钥的技术识别字段由服务器计算（见 ide 表下方的说明）。仅在生产环境（tpAmb=1）且 DC-e 被授权时才扣除额度。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名：`MD5(token + path + body + timestamp)`
timestamp	string	Unix 时间戳（秒，5 分钟窗口）

Body — 根

字段	类型	说明
ide *	object	DC-e 的标识
emit *	object	开具方/发件方数据（CNPJ，或通过电商平台的 CPF——见下文）
dest *	object	收件方数据
det *	array	声明的项目/货物——至少 1 项
total *	object	声明的合计
transp	object	运输数据
marketplace	object	电商平台数据（仅当 `ide.tpEmit=1` 时）
fisco	object	税务机关数据（仅当 `ide.tpEmit=0` 时）
autXML	array	被授权访问 XML 的 CNPJ/CPF
infAdic	object	附加信息

请求中的必填字段： ide.tpAmb；emit.CNPJ（14 位）或 emit.CPF（11 位，通过电商平台的个人发件方——见 emit 中的注记）、emit.xNome 和 emit.enderEmit（xLgr、nro、xBairro、cMun、xMun、CEP 为 8 位、UF）；dest 含 CNPJ 或 CPF、dest.xNome 和 dest.enderDest（同样的地址字段）；det 中至少 1 项，含 xProd、NCM（2 或 8 位）、qCom > 0 和 vProd > 0；以及 total.vDC > 0。其余所有字段均为可选。

ide — 标识

字段	类型	说明
tpAmb *	int	环境：`1`=生产，`2`=测试。`ide` 中唯一真正必填的字段。
tpEmit	int	开具方类型：`0`=税务机关应用，`1`=电商平台，`2`=自主开具方。可选——默认：`2`
cUF	int	开具方 UF 的 IBGE 代码（2 位）。可选——省略时从 `emit.enderEmit.UF` 推导。如发送，必须与该 UF 一致（不一致时税务局会以 `cStat=220` 拒绝）
serie	int	税务文档系列号（访问密钥的 3 位）——标识 DC-e 的编号序列。可选——默认：公司中登记的 DC-e 系列
nDC	long	DC-e 的顺序号（构成访问密钥）。可选——省略或为 `0` 时由服务器自动递增
nSiteAutoriz	int	处理该 DC-e 的授权站点标识（访问密钥的 1 位）。通常为 `0`（主站点）。可选——默认：`0`
tpEmis	int	开具方式：`1`=正常，`9`=应急。可选——默认：`1`

由服务器自动填充——无须发送： mod（固定为 99）和 cDV（密钥校验位）始终由服务器设定；cDC（6 位数字代码）、dhEmi（开具日期时间）和 verProc（处理程序版本）在省略时生成。上表中的 serie、nDC 和 cUF 字段在省略时也会自动填充。

emit — 开具方 / 发件方

字段	类型	说明
CNPJ ⚠	string	开具方 CNPJ（14 位）。省略时填充为 token 对应公司的 CNPJ
CPF ⚠	string	个人发件方的 CPF（11 位）。仅允许通过电商平台开具——见下方注记
xNome *	string	开具方/发件方的姓名或公司名称
enderEmit *	object	开具方地址（见下方结构）

个人发件方（CPF）：根据税务局规则，CPF 不能作为自主开具方（tpEmit=2 要求 CNPJ）。如需以 CPF 作为发件方开具，只需发送 emit.CPF（不含 emit.CNPJ）：服务器会自动设置 tpEmit=1（电商平台），在访问密钥中使用贵公司的 CNPJ（token 对应公司）作为授权开具方，并以公司数据填充 marketplace 块。所填的 CPF 将在 emit 中显示为发件方。

dest — 收件方

字段	类型	说明
CNPJ ⚠	string	收件方 CNPJ（14 位）
CPF ⚠	string	收件方 CPF（11 位）
xNome *	string	收件方的姓名或公司名称
enderDest *	object	收件方地址（见下方结构）

enderEmit / enderDest — 地址

字段	类型	说明
xLgr *	string	街道
nro *	string	门牌号
xCpl	string	补充信息
xBairro *	string	街区
cMun *	long	自治市 IBGE 代码（7 位）
xMun *	string	自治市名称
CEP *	string	邮政编码（8 位）
UF *	string	UF 简称（2 个字母）
cPais	int	国家代码。默认：`1058`（巴西）
xPais	string	国家名称。默认：`BRASIL`
fone	string	电话
email	string	电子邮箱

det[] — 声明的项目

字段	类型	说明
nItem	int	项目顺序号
xProd *	string	声明的货物/商品描述
NCM *	string	NCM 代码（2 或 8 位）
qCom *	decimal	数量（> 0）
vUnCom	decimal	单价
vProd *	decimal	项目总金额（> 0）
infAdProd	string	项目附加信息

total — 合计

字段	类型	说明
vDC *	decimal	声明的总金额（> 0）

transp — 运输

字段	类型	说明
modTrans	int	运输方式：`0`=邮政，`1`=自有，`2`=承运商。默认：`2`
CNPJTransp	string	承运商 CNPJ

marketplace — 电商平台（仅 `tpEmit=1`）

字段	类型	说明
CNPJ	string	电商平台 CNPJ
xNome	string	电商平台名称
Site	string	电商平台网站

fisco — 税务机关（仅 `tpEmit=0`）

字段	类型	说明
CNPJ	string	机关 CNPJ
xOrgao	string	机关名称
UF	string	机关所在 UF

autXML[] — XML 授权对象

字段	类型	说明
CNPJ	string	被授权查询/下载 XML 的 CNPJ
CPF	string	被授权查询/下载 XML 的 CPF

infAdic — 附加信息

字段	类型	说明
infAdFisco	string	税务机关关注的信息
infCpl	string	纳税人关注的补充信息
infAdMarketPlace	string	电商平台附加信息

* 必填字段。⚠ 开具方和收件方中，CNPJ 或 CPF 至少须填一个。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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

查询 DC-e 状态

根据访问密钥查询 DC-e 在税务局上的当前状态。当 DC-e 已取消时，响应反映取消的数据（本地库是取消信息的事实来源）。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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

取消 DC-e

取消一张已授权的 DC-e（事件 110111）。要求 DC-e 已被授权（已有协议号）且尚未取消。每张 DC-e 只允许取消一次。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）
xJust *	string	取消理由（按税务局要求至少 15 个字符）
nProt	string	授权协议号。可选：省略时使用开具时登记的协议号

* 必填字段。

遇到拒绝时，响应返回 success=false、拒绝的 cStat/xMotivo 以及附加字段 xmlEnviadoDebug（含已发送的 XML），用于诊断。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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

获取 DC-e PDF

返回 DACE 的 URL——即 DC-e 的 PDF 表现形式。当 PDF 在存储中尚不存在时，会按需生成并发送。如存储不可用，则 PDF 以 base64 形式直接在响应体中返回。

必需请求头

请求头	类型	说明
token	string	开票公司的 Token
sign	string	MD5 签名
timestamp	string	Unix 时间戳（秒）

Body

字段	类型	说明
chDCe *	string	DC-e 访问密钥（44 位）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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

DC-e 列表（分页）

分页列出公司的 DC-e。参数通过 查询字符串（query string）传递（不在 body 中）。时间过滤可选，但若使用则需同时传入 start_create_time 和 end_create_time。

必需请求头

请求头	类型	说明
token	string	开票公司令牌
sign	string	MD5 签名（path 包含查询字符串）
timestamp	string	秒级 Unix 时间戳

查询字符串

参数	类型	说明
page *	int	页码（≥ 1）
page_size *	int	每页大小（1–50）
start_create_time	long	Unix 时间戳（毫秒） — 起始（需要 `end_create_time`）
end_create_time	long	Unix 时间戳（毫秒） — 结束
status	string	按状态过滤。值: `"Success"`（已授权）、`"Canceled"`（已取消）、`"Processing"`（处理中）、`"Failed"`（失败）、`"Unknown"`（未知）

* 必填字段。

# sign = md5(token + path + body + timestamp)
# 按接口路径生成的调用模板，占位符替换为实际值
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 — 电子内容声明

开具 DC-e

必需请求头

Body — 根

ide — 标识

emit — 开具方 / 发件方

dest — 收件方

enderEmit / enderDest — 地址

det[] — 声明的项目

total — 合计

transp — 运输

marketplace — 电商平台（仅 tpEmit=1）

fisco — 税务机关（仅 tpEmit=0）

autXML[] — XML 授权对象

infAdic — 附加信息

查询 DC-e 状态

必需请求头

Body

取消 DC-e

必需请求头

Body

获取 DC-e PDF

必需请求头

Body

DC-e 列表（分页）

必需请求头

查询字符串

marketplace — 电商平台（仅 `tpEmit=1`）

fisco — 税务机关（仅 `tpEmit=0`）