DC-e

Visión general y flujo de onboarding

El DC-e (modelo 99, Declaração de Conteúdo Eletrônica, Ajuste SINIEF 05/2021) es la declaración electrónica de contenido que acompaña los envíos de mercancías remitidas por no contribuyentes, emitida en su nombre por un marketplace, o por una empresa para sí misma. El registro de empresa, la vinculación de certificado y el registro de webhook se comparten con la NF-e; el segmento de recurso mantiene el dc-e original del documento y toda operación a nivel de documento vive bajo /dc-e/{dceId}.

La autenticación es idéntica a la NF-e: cabeceras token / timestamp / sign, con sign = MD5(token + path + body + timestamp) en hexadecimal minúsculo; path incluye el prefijo /openapi y las variables de ruta y excluye la query string; GET / DELETE sin cuerpo usan la cadena vacía; un DELETE con cuerpo (cancelación con motivo) firma el JSON bruto con CR/LF eliminados. Vea Autenticación.

Requisitos previos

• La empresa debe estar aprobada con certificado utilizable (de lo contrario DCe00008). El autorizador del DC-e es la SEFAZ-PR (el único autorizador listado en el portal nacional del DC-e); las empresas de todos los estados se enrutan hacia él.
• La empresa debe tener configurados sus parámetros de emisión de DC-e: emissaoDCe.tipoEmitente y una serie del modelo 99 (sequencialDCe / serieDCe); la falta de cualquiera devuelve DCe00004.
• La fase uno admite dos tipos de emisor: Marketplace (una plataforma que emite en nombre de vendedores no contribuyentes / personas físicas) y OwnIssuer (una empresa que emite para sí misma). Carrier puede registrarse, pero la emisión se rechaza (10019013) hasta que SVRS publique el nuevo paquete de schema.
• ambiente en la solicitud debe coincidir con el entorno actual de la empresa, de lo contrario DCe00004 (texto del documento: "not configured for the informed environment"). Tras el registro la empresa está en el entorno de certificación (Homologacao); el cambio a producción es una acción de operaciones sin API, y enviar ambiente=Producao antes del cambio devuelve DCe00004.
• La fase uno admite solo emisión normal (tpEmis=1); la contingencia offline llega en la fase dos.

Registro de empresa: la sección emissaoDCe

Registrar empresa acepta una sección opcional emissaoDCe (todos los demás campos sin cambios):

"emissaoDCe": {
  "ambienteProducao": {
    "tipoEmitente": "Marketplace",
    "sequencialDCe": 1,
    "serieDCe": "1",
    "siteMarketplace": "https://loja.exemplo.com.br"
  }
}

• Una empresa registrada sin emissaoDCe no queda habilitada para DC-e: el registro se acepta, pero la respuesta trae dceHabilitado=false y la emisión devuelve DCe00004. Verifique ese campo justo después de registrar.
• Para habilitar DC-e después, elevar el número inicial o corregir datos de contacto, reenvíe el payload de registro con id. La serie del modelo 99 solo avanza; las reglas completas de actualización están en la página Registrar empresa.

Endpoints

Carga del webhook

El registro de webhook y las cabeceras de firma se comparten con la NF-e; registre la URL de callback en Registrar webhook. Cabeceras de la entrega: además de las cinco cabeceras de firma de la plataforma (X-Tffiscal-Event / X-Tffiscal-Event-Id / X-Tffiscal-Delivery-Id / X-Tffiscal-Timestamp / X-Tffiscal-Signature), toda entrega lleva token y x-token con el mismo valor (el token registrado en el webhook, devuelto sin cambios); el receptor puede verificar cualquiera de los dos.

Códigos de evento y carga de compatibilidad (tipo="DC-e", 14 campos en orden fijo):

Campos de la carga

dce.authorized

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Autorizada", "dceMotivoStatus": null,
  "dceLinkDace": "https://api.v2.tffiscal.com/openapi/files/dace/35260940673061000134990010000000011100000012?token=...", "dceLinkXml": "https://api.v2.tffiscal.com/openapi/files/xml/7?token=...",
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "41260940673061000134990010000000011101234567",
  "dceDataEmissao": "2026-09-06T12:00:00Z", "dceDataAutorizacao": "2026-09-06T12:00:03Z",
  "dceNumeroProtocolo": "141260000000001", "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y=" }

dce.rejected

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Negada",
  "dceMotivoStatus": "225 - Rejeicao: Falha no schema XML", "dceLinkDace": null, "dceLinkXml": null,
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null, "dceNumeroProtocolo": null, "dceDigestValue": null }

Fallo antes de la numeración (empresa no configurada para DC-e / serie ausente / fallo en el mapeo del mensaje y otros fallos terminales en los que el documento nunca fue numerado y no tiene chave): dce.rejected se entrega igualmente, los campos de hecho del documento son null, dceMotivoStatus lleva el motivo del fallo y dceDataEmissao el momento de la aceptación. Correlacione por dceId y nunca asuma que dceChaveAcesso está presente:

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Negada",
  "dceMotivoStatus": "Empresa não configurada para emissão de DC-e", "dceLinkDace": null, "dceLinkXml": null,
  "dceNumero": null, "dceSerie": null, "dceChaveAcesso": null, "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": null, "dceNumeroProtocolo": null, "dceDigestValue": null }

dce.canceled

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "Cancelada", "dceMotivoStatus": null,
  "dceLinkDace": "https://.../openapi/files/dace/35260940673061000134990010000000011100000012?token=...", "dceLinkXml": "https://.../openapi/files/xml/7?token=...",
  "dceNumero": "1", "dceSerie": "1", "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z",
  "dceDataAutorizacao": "2026-09-06T15:00:00Z", "dceNumeroProtocolo": "141260000000099", "dceDigestValue": null }

dce.cancel_rejected

{ "tipo": "DC-e", "empresaId": "1934811222334455", "dceId": "DCe-000012333", "dceStatus": "CancelamentoNegado",
  "dceMotivoStatus": "594 - Rejeicao: O numero de sequencia do evento informado e maior que o permitido",
  "dceLinkDace": null, "dceLinkXml": "https://.../openapi/files/xml/7?token=...", "dceNumero": "1", "dceSerie": "1",
  "dceChaveAcesso": "4126...", "dceDataEmissao": "2026-09-06T12:00:00Z", "dceDataAutorizacao": null,
  "dceNumeroProtocolo": "141260000000001", "dceDigestValue": "tasG40Ic6Zh7PIBiLEEH7Hb940Y=" }

En los callbacks de autorización / cancelación, dceLinkDace es el enlace del DACE renderizado bajo demanda por la chave (nada se renderiza en el momento de la entrega; la primera descarga lo renderiza y archiva); ambos enlaces tienen el mismo formato que la API de consulta (/openapi/files/{kind}/{ref}?token=…) y su validez proviene de la configuración del inquilino (por defecto 7 días). Vea Descarga de archivos.

Modelo de errores

Mismos formatos que la NF-e: los errores de negocio son [{ "codigo", "mensagem" }] (HTTP 400; un documento / tarea inexistente es HTTP 404 con codigo DCe0001); los errores de la capa de autenticación usan el sobre de la plataforma (401 / 403 / 429, vea Autenticación). Los casos con código de ejemplo documentado reutilizan el código del documento; todo otro codigo es el código de error numérico de la plataforma, y mensagem se localiza según el idioma de la solicitud (el portugués usa el texto del documento).

Las listas de códigos por endpoint están en Emitir DC-e, Consultar DC-e y Cancelar DC-e. Los rechazos de la SEFAZ durante la emisión no son errores HTTP: aparecen como estado Negada en la consulta y en el webhook dce.rejected; los rechazos de la SEFAZ a la cancelación aparecen como dce.cancel_rejected.

Máquina de estados

Aceptado (POST 200) ─→ Pendente ─numera + envía a SEFAZ─┬─ cStat 100 ─→ Autorizada ─DELETE 200─→ CancelamentoPendente ─┬─ 135/136/155 ─→ Cancelada
                                                        │                                                              └─ rechazo SEFAZ ─→ Autorizada (webhook CancelamentoNegado)
                                                        ├─ otro cStat terminal ─→ Negada
                                                        └─ parámetros no interpretables / reintentos agotados ─→ Falha (el mismo id puede reenviarse)

• Mientras está Pendente, las caídas de la SEFAZ (108 / 109) se reintentan con back-off por la plataforma; no hay redireccionamiento de contingencia en la fase uno. La emisión duplicada (451 / 452 / 539) se reconcilia consultando primero a la SEFAZ.
• Tras Negada / Falha el mismo id puede reenviarse (reabierto con el nuevo mensaje); tras Autorizada un reenvío con el mismo id solo activa la idempotencia.

Observaciones

• El CNPJ de la clave es la empresa de la plataforma: las posiciones 7-20 siempre llevan al emisor autorizado (la empresa Marketplace o la empresa que emite para sí); un remitente CPF solo aparece en el grupo emit del XML y en el bloque REMETENTE del DACE.
• Nombre fijo del destinatario en el entorno de certificación: con tpAmb=2 el nombre del destinatario en el XML y el DACE es DCE EMITIDA EM AMBIENTE DE HOMOLOGACAO (validación SEFAZ 598); el eco de la consulta conserva el original.
• Ventana de cancelación de 24 horas: contada desde el momento de la autorización; después de ella el documento solo puede mantenerse. El DC-e oficial solo tiene cancelación: sin carta de corrección, sin inutilización de numeración.
• Carrier aún no soportado: el schema oficial actual restringe tpEmit a Marketplace / emisor propio; una empresa transportadora registrada se rechaza con 10019013 en la emisión.
• DACE: A4 vertical, renderizado bajo demanda y en caché; re-renderizado con la marca de agua CANCELADA tras la cancelación; el entorno de certificación lleva la marca de agua SEM VALOR FISCAL - HOMOLOGAÇÃO.
• Autorizador: el DC-e de todos los estados va al autorizador SEFAZ-PR; el código QR apunta a https://www.fazenda.pr.gov.br/dce/qrcode?chDCe={chave}&tpAmb={tpAmb}.

Lista de verificación de integración

1. En el entorno de certificación: empresa registrada (con emissaoDCe, respuesta dceHabilitado=true confirmada), certificado vinculado, webhook registrado (el receptor acepta token / x-token).
2. Emita un DC-e mínimo (el ejemplo en Emitir DC-e), consúltelo como Autorizada, descargue el XML y el DACE, reciba el callback dce.authorized.
3. Reenvíe el mismo id una vez y confirme HTTP 200 sin segundo documento; cambie un ítem y reenvíe, confirme 10019030.
4. Cancele el documento: confirme 200 sin cuerpo, consulte CancelamentoPendente → Cancelada, reciba el callback dce.canceled, el DACE lleva la marca de agua.
5. Cancele de nuevo el documento cancelado y confirme 10019040; consulte un id inexistente y confirme 404 DCe0001.
6. Envíe errores deliberados (ambiente=Producao, cidade=9999999, remetente ausente) y confirme el array de errores 400 con los códigos DCe00004 / GW001 / DCe00005.
7. Emita para una empresa no habilitada para DC-e y confirme DCe00004; reenvíe el payload de registro con id y un sequencialDCe mayor, confirme 200 y que el próximo documento comienza desde el nuevo número; reenvíe un número menor y confirme 400 10001001.