CT-e

Visión general

La API de CT-e emite documentos electrónicos de transporte (CT-e, modelo 57, modal por carretera) en nombre de transportistas, consulta su estado, los cancela y registra eventos posteriores a la autorización (carta de corrección, comprobante de entrega, insuceso en la entrega, prestación en desacuerdo). El registro de la empresa, la vinculación del certificado y el registro del webhook se comparten con la NF-e y aquí solo se referencian.

Convención de ruta: el segmento de recurso es la categoría del documento cte; toda operación a nivel de documento vive bajo /openapi/v2/empresas/{empresaId}/cte/{cteId}, donde cteId es el id enviado en la emisión.

Flujo de integración

Requisitos previos

• La empresa debe estar aprobada con un certificado utilizable, y su CNPJ debe estar habilitado para CT-e en la autoridad tributaria estatal (IE registrada como prestadora de servicios de transporte y acreditación de CT-e completada). Sin ello la SEFAZ devuelve 230 - IE do emitente não cadastrada, lo que la plataforma no puede resolver.
• La empresa debe tener una serie de numeración de CT-e (modelo 57). Si no hay ninguna configurada, o hay varias habilitadas y la solicitud no elige una, la API devuelve 10017007.
• La fase uno admite solo el modal por carretera (Rodoviario); otros modales se rechazan en la aceptación (10017018).
• ambienteEmissao debe coincidir con el entorno actual de la empresa (10017010), vea Entornos.

Autenticación

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 cadena de consulta; GET sin cuerpo usa la cadena vacía; POST firma el JSON bruto sin CR/LF (un POST sin cuerpo firma la cadena vacía). Los detalles del algoritmo, las implementaciones de referencia y la solución de problemas están en Autenticación.

Endpoints

Todas las rutas son relativas a /openapi/v2/empresas/{empresaId}/cte.

Todo evento se envía de forma síncrona y, en caso de éxito, devuelve el objeto del evento (chaveAcesso, tipo, codigo, sequencia, status, motivo, protocolo, data, linkXml). Los campos de texto se sanitizan (acentos eliminados, espacios en blanco consolidados) antes de la validación de longitud; las coordenadas se registran con seis decimales.

Aviso: los endpoints de prestación en desacuerdo son los únicos direccionados por la clave de acceso de un CT-e emitido por otra empresa: esta empresa actúa como receptora / tomadora de ese documento, y el evento se encamina al estado de ese documento.

Carga del webhook

El registro del webhook y las cabeceras de firma se comparten con la NF-e, vea Webhooks. Se emiten cuatro códigos de evento para CT-e:

cte.authorized, cte.rejected, cte.canceled

Los tres eventos de resultado del documento usan la carga de compatibilidad (tipo="CT-e", orden fijo de campos), paralela a los campos nfe* de la NF-e:

{ "tipo": "CT-e", "empresaId": "1934811222334455", "cteId": "CTE-ORD-1", "cteStatus": "Autorizada", "cteMotivoStatus": null,
  "cteLinkDacte": "https://.../openapi/files/dacte/3526...?token=...", "cteLinkXml": "https://.../openapi/files/xml/7?token=...", "cteNumero": "1", "cteSerie": "1",
  "cteChaveAcesso": "3526...", "cteDataEmissao": "2026-09-06T12:00:00Z", "cteDataAutorizacao": "2026-09-06T12:00:03Z",
  "cteNumeroProtocolo": "135260000000001", "cteDigestValue": "..." }

cteLinkDacte y cteLinkXml son utilizables en cuanto llega el callback de autorización; los enlaces no necesitan cabeceras de firma, redirigen con 302, y su validez y códigos de error se describen en Descarga de archivos.

cte.event.registered

Se emite cuando se registra cualquier evento posterior a la autorización distinto de la cancelación (carta de corrección, comprobante de entrega, insuceso en la entrega, prestación en desacuerdo y sus cancelaciones). Usa el sobre de la plataforma (version / event_id / event_type / occurred_at / data):

{
  "version": "1.0",
  "event_id": "7312345678901234567",
  "event_type": "cte.event.registered",
  "occurred_at": "2026-09-06T13:00:00Z",
  "data": {
    "cte_id": "1001",
    "chave": "35260940673061000134570010000000011000000016",
    "external_ref": "CTE-ORD-1",
    "event_code": "110110",
    "n_seq": 1,
    "protocolo": "135260000000099"
  }
}

Modelo de errores

Mismas formas que la NF-e: los errores de negocio son [{ "codigo", "mensagem" }] (HTTP 400; un documento / tarea inexistente es HTTP 404 con codigo CTe0001); los errores de la capa de autenticación usan el sobre de la plataforma (401 / 403 / 429, vea Autenticación).

Los rechazos de la SEFAZ durante la emisión no son errores HTTP: aparecen como estado Negada en la consulta y como el webhook cte.rejected.

Alcance y limitaciones

• CT-e modelo 57 versión 4.00, modal por carretera; documentos normales / complementarios / sustitutos; los cinco tipos de servicio.
• Grupos tributarios ICMS 00 / 20 / 40 / 41 / 51 / 60 / 90 / OutraUF / SN + ICMSUFFim + vTotTrib; IBS/CBS en la fase dos.
• Contingencia: SVC (SVC-RS / SVC-SP) y EPEC los activa la plataforma por estado, de forma transparente para los integradores; tipoEmissao en la consulta lo muestra. Los eventos de documentos autorizados en contingencia se siguen enviando al autorizador regular del estado.
• No soportado: otros modales, multimodal, GTV, CT-e OS (modelo 67), distribución de documentos recibidos (DistDFe).

Lista de verificación de integración

1. En el entorno de homologación: empresa registrada, certificado vinculado, serie de numeración de CT-e configurada.
2. Emita un CT-e mínimo (el ejemplo en Emitir CT-e), consúltelo como Autorizada, descargue el XML y el DACTE.
3. Reenvíe el mismo id una vez y confirme HTTP 200 sin que se cree un segundo documento.
4. Registre una carta de corrección y un comprobante de entrega, véalos en la lista de eventos, luego cancele el comprobante de entrega.
5. Emita un segundo CT-e y cancele ese, consúltelo como Cancelada, reciba el callback cte.canceled. Un documento con carta de corrección registrada ya no puede cancelarse, por eso este paso usa otro documento.
6. Envíe errores deliberados (modal Aereo, suma de componentes divergente) y confirme el array de errores 400.