DC-e

查询 DC-e

返回状态、协议、XML / DACE 下载链接与发行入参回显。

GET/openapi/v2/empresas/{empresaId}/dc-e/{dceId}

需要 token、timestamp、sign 三个签名头，参见认证与签名。

按发行时传入的 id 查询单据。回显段（remetente … observacoesMarketplace）来自受理时规范化后的入参快照，任务终态后依旧可查。下载链接形如 {公网基址}/openapi/files/{kind}/{ref}?token=…（kind 为 xml 或 dace），令牌自带凭证、下载时不需要签名头，有效期取租户级设置（默认 7 天），每次查询重新签发。参见文件下载。

路径参数

`empresaId*`	string	发行主体标识
`dceId*`	string	单据标识

* 必填字段

200

单据存在。单据事实字段（numero、chaveAcesso、protocolo、链接）随状态推进逐步填充。

`id`	string	请求标识
`ambiente`	string	发行环境
`status`	string	单据状态
`motivoStatus`	string	状态原因
`dataCriacao`	string	受理时刻
`dataUltimaAlteracao`	string	最近变更时刻
`numero`	int	单据号
`serie`	string	系列号
`dataEmissao`	string	开具时刻
`chaveAcesso`	string	访问密钥
`dataAutorizacao`	string	授权时刻
`linkDace`	string	DACE 下载链接
`linkDownloadXml`	string	XML 下载链接
	object	授权协议
`emitidaEmContingencia`	bool	是否应急发行
`remetente`	object	发件方
`destinatario`	object	收件方
`itens`	array	申报物品
`transporte`	object	运输信息
`autorizacaoDownloadXml`	array	下载授权名单
`informacoesAdicionais`	string	平台备注
`informacoesAdicionaisFisco`	string	税务机关备注
`informacoesAdicionaisEmitente`	string	发行方备注
`observacoesMarketplace`	array	平台自定义项

`ambiente`发行环境

取值	含义
Homologacao	税务局测试环境，单据无法律效力
Producao	正式环境

`status`单据状态

Webhook 里另有 CancelamentoNegado：取消被 SEFAZ 拒绝，单据回到 Autorizada；查询按 Autorizada 返回并在 motivoStatus 带原因，可修正后再次发起取消。

取值	含义
Pendente	已受理，排队或发送中；取号后才有 `numero` 与 `chaveAcesso`
Autorizada	SEFAZ 已授权；`linkDownloadXml`、`linkDace`、`protocolo` 可用；若最近一次取消被拒，`motivoStatus` 带原因
Negada	SEFAZ 驳回；`motivoStatus` 为驳回代码与说明
CancelamentoPendente	取消已受理，等待 SEFAZ 结论
Cancelada	已取消；`linkDace` 指向带 `CANCELADA` 水印的版本
Falha	任务终态失败（参数无法解析、重试耗尽）；`motivoStatus` 给原因；同 `id` 可重新提交

错误码	HTTP
10019002	404	`dceId` 不存在或非本主体。核对 id 与 `empresaId`。
10019003	404	`dceId` 不存在或非本主体。核对 id 与 `empresaId`。
10003000	404	`empresaId` 不存在。

APP_SECRET='<APP_SECRET>'

API_PATH='/openapi/v2/empresas/{empresaId}/dc-e/{dceId}'

TIMESTAMP=$(date +%s)

SIGN=$(printf '%s%s%s' "$APP_SECRET" "$API_PATH" "$TIMESTAMP" | md5sum | cut -d' ' -f1)

curl -sS -X GET "https://api.v2.tffiscal.com${API_PATH}" \

-H "token: $APP_SECRET" -H "timestamp: $TIMESTAMP" -H "sign: $SIGN"

{

"id": "DCe-000012333",

"ambiente": "Homologacao",

"status": "Autorizada",

"motivoStatus": null,

"dataCriacao": "2026-09-06T12:00:00Z",

"dataUltimaAlteracao": "2026-09-06T12:00:03Z",

"numero": 1,

"serie": "1",

"dataEmissao": "2026-09-06T12:00:00Z",

"chaveAcesso": "41260940673061000134990010000000011101234565",

"dataAutorizacao": "2026-09-06T12:00:03Z",

"linkDace": "https://api.v2.tffiscal.com/openapi/files/dace/35260940673061000134990010000000011100000016?token=...",

"linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",

"protocolo": { "numero": "141260000000001", "digestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y=" },

"emitidaEmContingencia": false,

"remetente": {

"tipoPessoa": "F", "nome": "JOAO DA SILVA", "email": "joao@exemplo.com", "cpfCnpj": "12345678909", "telefone": "41999990000",

"endereco": { "uf": "PR", "cidade": "4106902", "logradouro": "RUA XV DE NOVEMBRO", "numero": "100", "complemento": null, "bairro": "CENTRO", "cep": "80020310" }

"destinatario": {

"tipoPessoa": "F", "nome": "MARIA OLIVEIRA", "email": null, "cpfCnpj": "11144477735", "telefone": null,

"endereco": { "uf": "SP", "cidade": "3550308", "logradouro": "AVENIDA PAULISTA", "numero": "1000", "complemento": "AP 12", "bairro": "BELA VISTA", "cep": "01310100" }

"itens": [

{ "descricao": "BOLSA DE COURO", "ncm": "42021220", "quantidade": 1, "valorUnitario": 80.00, "informacoesAdicionais": null },

{ "descricao": "CARTEIRA", "ncm": "42023100", "quantidade": 2, "valorUnitario": 40.00, "informacoesAdicionais": null }

"transporte": { "modalidade": "PelosCorreios", "cnpjTransportadora": null },

"autorizacaoDownloadXml": [ { "cpfCnpj": "14422279000106" } ],

"informacoesAdicionais": null,

"informacoesAdicionaisFisco": null,

"informacoesAdicionaisEmitente": null,

"observacoesMarketplace": [ { "nome": "PURCHASE_ID", "valor": "OC000332322SR-1" } ]

}

查询 DC-e

参数

路径参数

响应

枚举2 张表

ambiente发行环境

status单据状态

错误3 条

`ambiente`发行环境

`status`单据状态