Skip to main content

Downloading files

Every processed DTE generates downloadable files. A single endpoint serves them all: /api/connect/file/{id_or_ref}. It works for sales (Invoice, CCF, Credit Note, Export) and SUEX — you don't need to know which type the document belongs to; the API looks up both automatically.

Dual authentication​

The download endpoint accepts two ways to send your API key:

MethodUse caseStatus
Header Authorization: Bearer odt_xxxBackend integrations, server-side codeRecommended
Query param ?key=odt_xxxShareable links, browser, emailsDeprecated fallback

The rest of the API (issue, query, invalidate) requires the header exclusively. The query param exists only here, only for downloads, and only because there are cases where you can't inject the header:

  • Sharing a ticket link with a customer so they can print it.
  • Embedding the ticket in a transactional email with a direct link.
  • Opening the ticket in the browser by clicking from a table in your app.
The ?key= query param is deprecated

Kept for compatibility with previous integrations, but will eventually be removed. For any new integration use the Authorization header. If a link must be shareable without your own backend, the best practice is to proxy the download from your server (your backend makes the call with the header, and exposes a short link of your own to the end customer).

If you use ?key= treat those URLs as secrets. Anyone with the link can download the file. Don't publish them in logs, repos, or public chats.

Technical details​

MethodGET
URLhttps://ocote.io/api/connect/file/{id_or_ref}?type=TYPE
AuthenticationHeader Authorization: Bearer odt_xxx or query ?key=odt_xxx

The {id_or_ref} can be a UUID or external_ref. The API looks up sales and SUEX automatically; you don't need to know which table the document belongs to.

File types (type=)​

type=Contents
ticket8×21 cm thermal PDF ready to print.
invoiceLetter-sized PDF of the document, with official formatting.
jsonSigned JSON (JWS) with the MH stamp.

Availability by document type​

Not every file type applies to every DTE. This is the authoritative matrix:

DTE typeticketinvoicejson
Invoice (01)YesYesYes
CCF (03)—YesYes
Credit Note (05)—YesYes
Export (11)—YesYes
SUEX (14)—YesYes
  • ticket only exists for Invoice (01). Requesting it for any other type returns 404.
  • invoice is the letter-sized PDF; useful for bookkeeping or emailing to the receiver.
  • json is the signed fiscal document; only available when dte_success: true (MH stamp received).

URLs come pre-built in responses​

When you issue or query a DTE successfully, ready-to-use URLs come in the response (ticket_url, invoice_url, json_url — depending on the type). Use them as-is with your Authorization header — no need to build them by hand.

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

Note: the URLs no longer include ?key= in the response. To download, send your API key in the header.

Examples​

Download ticket from terminal (Authorization header)​

curl
curl -o ticket.pdf \
  -H "Authorization: Bearer odt_xxx" \
  "https://ocote.io/api/connect/file/SALE-2026-0042?type=ticket"

Result: ticket.pdf file in your local directory.

Download letter PDF​

curl
curl -o invoice.pdf \
  -H "Authorization: Bearer odt_xxx" \
  "https://ocote.io/api/connect/file/SALE-2026-0042?type=invoice"

Download signed JSON​

curl
curl -o dte.json \
  -H "Authorization: Bearer odt_xxx" \
  "https://ocote.io/api/connect/file/SALE-2026-0042?type=json"

The JSON is the full JWS (JSON Web Signature) of the signed DTE, with the MH stamp. Use it for bookkeeping archives, audits, or re-sending to the recipient.

Open ticket in the browser (?key= fallback)​

Browsers don't allow setting arbitrary headers in a direct GET request. For those cases, use the deprecated fallback:

https://ocote.io/api/connect/file/SALE-2026-0042?type=ticket&key=odt_xxx

Paste it in the browser's address bar. The PDF opens directly. Remember the URL contains your API key — don't share it in public channels.

Embed in an email (?key= fallback)​

<p>Thanks for your purchase. You can download your ticket here:</p>
<a href="https://ocote.io/api/connect/file/SALE-2026-0042?type=ticket&key=odt_xxx">
  Download ticket (PDF)
</a>
Protect your API key

The email above contains your API key in the link. If the customer forwards the email, the recipient inherits access to download other files from your account if they figure out the UUID pattern. Best practice: proxy the download from your backend (your backend makes the call with the Authorization header, and exposes a short link of your own to the end customer, e.g. https://your-app.com/ticket/abc123 that your backend resolves internally).

File availability by state​

  • ticket: available as soon as the document passes through the DTE processor (is_dte: true), even in contingency. The ticket includes a note about the transmission status if not stamped.
  • invoice: available when dte_success: true (document accepted with MH stamp).
  • json: available only when dte_success: true. For documents in contingency or rejected, the endpoint responds 404 with File not available.

Errors​

HTTPMessageCause
401API key requerida (header Authorization: Bearer odt_xxx)Missing header and ?key=.
401API key invalidaKey misspelled, disabled, or belongs to another company.
400type debe ser uno de: ticket, invoice, jsonUnsupported type value.
404Documento no encontradoid_or_ref doesn't exist in your company.
404Archivo no disponibleFile not yet generated (contingency or not stamped).
404Ticket solo disponible para Factura (01)You requested type=ticket for a DTE of type 03, 05, 11, or 14.
404SUEX no genera ticket PDFYou requested type=ticket for a type 14 document.

See also​