Descargar archivos

Todo DTE procesado genera archivos descargables. El API expone un endpoint único para acceder a ellos, con una característica que lo distingue del resto: acepta la API key como query parameter en lugar de header.

Por qué key en query param

El resto del API requiere el header Authorization: Bearer odt_.... Para descargas, eso complica casos de uso comunes:

• Compartir un link de ticket con un cliente para que lo imprima.
• Embeber el ticket en un correo transaccional con un enlace directo.
• Abrir el ticket en el navegador haciendo clic desde una tabla de tu app.

En todos esos casos, no tienes forma práctica de inyectar el header. Por eso /file/{id} acepta ?key=odt_xxx como alternativa al header.

La compensación: trata esos URLs como secretos. Cualquiera con el link puede descargar el archivo. Los URLs incluyen tu API key en el query string, así que no los publiques en logs, repos o chats públicos.

Detalles técnicos

Método	GET
URL	https://ocote.io/api/connect/file/{id_or_ref}?type=TIPO&key=odt_xxx
Autenticación	API key en query param ?key= (sin header Authorization)

El {id_or_ref} puede ser UUID o external_ref. El API busca automáticamente en ventas y SUEX; no necesitas saber a qué tabla pertenece.

Tipos disponibles

type=	Contenido	Disponible para
ticket	PDF térmico 8×21 cm listo para imprimir	Solo Factura (01)
json	JSON firmado (JWS) con sello MH	Cualquier DTE con dte_success: true

Otros formatos no están en el API Connect

Documentos como CCF, NC, SUEX y Exportación tienen un PDF completo (tamaño carta) disponible en la plataforma Ocote DTE, pero no desde este endpoint. Si tu cliente lo necesita, descárgalo desde Ocote DTE o consulta a soporte.

URLs vienen precocinadas en los responses

Cuando emites o consultas un DTE exitosamente, los URLs listos para usar ya vienen en el response (ticket_url y json_url). Incluyen el ?key=odt_xxx correcto. Úsalos tal cual — no necesitas construirlos a mano.

{
  "ticket_url": "https://ocote.io/api/connect/file/a1b2c3d4-.../...?type=ticket&key=odt_xxx",
  "json_url":   "https://ocote.io/api/connect/file/a1b2c3d4-.../...?type=json&key=odt_xxx"
}

Ejemplos

Descargar ticket desde terminal

curl

curl -o ticket.pdf \
  "https://ocote.io/api/connect/file/VENTA-2026-0042?type=ticket&key=odt_xxx"

Resultado: archivo ticket.pdf en tu directorio local.

Descargar JSON firmado

curl

curl -o dte.json \
  "https://ocote.io/api/connect/file/VENTA-2026-0042?type=json&key=odt_xxx"

El JSON es el JWS (JSON Web Signature) completo del DTE firmado, con el sello MH. Sirve para archivo contable, auditorías, o re-envío al receptor.

Abrir ticket desde el navegador

Copia el ticket_url del response y pégalo en la barra del navegador. El PDF se abre directamente.

Embeber en un correo

<p>Gracias por tu compra. Puedes descargar tu ticket aquí:</p>
<a href="https://ocote.io/api/connect/file/VENTA-2026-0042?type=ticket&key=odt_xxx">
  Descargar ticket (PDF)
</a>

Protege tu API key

El correo de arriba contiene tu API key en el link. Si el cliente reenvía el correo, el destinatario hereda acceso a descargar otros archivos de tu cuenta si averigua el patrón de UUIDs. Mejor práctica para escenarios de alto riesgo: proxea la descarga desde tu backend (tu backend hace la llamada con header Authorization, y expone un link corto propio al cliente final).

Disponibilidad de archivos

• ticket: disponible desde que el documento pasa por el DTE processor (is_dte: true), aunque esté en contingencia. El ticket incluye nota del estado de transmisión si no está sellado.
• json: disponible solo cuando dte_success: true (sello MH recibido). Para documentos en contingencia o rechazados, el endpoint responde 404 con Archivo no disponible.

Errores

HTTP	Mensaje	Causa
401	API key requerida (?key=odt_xxx)	Falta ?key= en query.
401	API key invalida	Key mal escrita, desactivada, o de otra empresa.
404	Documento no encontrado	El id_or_ref no existe en tu empresa.
404	Archivo no disponible	El archivo aún no se generó (documento en contingencia o no sellado).
404	SUEX no genera ticket PDF	Pediste type=ticket para un documento tipo 14.

Ver también

• Consultar estado — para obtener los URLs actualizados de cualquier documento.
• Autenticación — detalle general del header Authorization.
• Contingencia — por qué el json_url puede venir vacío temporalmente.