Skip to main content

Changelog

In progress​

  • New documentation (this site).
  • Extended response flags (contingency, rejected, dte_success, dte_state, dte_message, observaciones, codigo_msg).
  • Idempotent retries on invalidations.
  • Improvement: the customer.phone field is now reflected on the customer record and in the recipient phone of the signed DTE.
  • Unified file URLs under /api/connect/file/{id} — previously the status responses and NC/Export/SUEX endpoints pointed to different paths (/api/v2/sales-history/{id}/file for sales and /api/v2/suex-history/{id}/file for SUEX). Now all responses return URLs under the unified endpoint /api/connect/file/{id}?type=..., which looks up sales and SUEX automatically.
  • New invoice_url field on /invoice and /status/{id} responses — URL to the letter-sized PDF of the document. Complements the existing ticket_url (8×21 cm thermal, Invoice 01 only) and json_url (signed DTE).
  • Dual authentication on /file/{id} — the download endpoint accepts Authorization: Bearer odt_xxx (recommended) or ?key=odt_xxx as a deprecated fallback. The fallback is preserved for compatibility but will eventually be removed. URLs returned by the API no longer include ?key= — use the header.
  • Documentation improvement: corrected the description of deadline and period in the Invoice (01) page and in MH catalogs. deadline is the term unit (MH CAT-018): 1=Days, 2=Months, 3=Years — not the number of days. The numeric amount goes in period. Examples updated across Invoice 01, CCF 03 and Export Invoice 11 to reflect the correct semantics ("deadline": 1, "period": 30 for 30 days of credit).
  • New district field in customer for /invoice and subject for /suex — district UUID obtained from /catalogs/districts/search. When sent, the API automatically resolves the MH department and municipality from the parent district. This is the recommended flow because you don't deal with MH codes. If not sent, department and municipality work exactly as before.
  • New /catalogs/districts/search endpoint — searches districts by name, useful for dropdowns/autocomplete in your UI. Same experience as the Ocote desktop panel.
  • municipality accepts short or long format — besides the historical short format ("24"), you can now send the 4-digit code the catalog returns ("1124") directly in the payload. Both resolve to the same municipality. Integrations using the short format continue to work unchanged.
  • New short_code field in the /catalogs/departments response — the last 2 digits of the municipality code (the raw town). Exposed alongside the 4-digit code for clarity.
  • Accent-insensitive search across all catalog endpoints (/activities, /departments, /districts/search, /units) — programacion matches PROGRAMACIÓN INFORMÁTICA, berlin matches Berlín, etc.

Backwards compatibility​

If you already consume the API, you do not need to change your code. New fields are additive:

  • The success flag still means "operation registered", which now explicitly includes contingency (previously ambiguous).
  • The deprecated amount and amount_ret fields in /status/{id} remain as aliases of amount_gross and amount_retention.
  • Input schemas unchanged.
  • Old URLs /api/v2/sales-history/{id}/file and /api/v2/suex-history/{id}/file continue to work — if your integration builds them directly, nothing breaks. The refactor only changes what the API returns in the *_url fields; if you consumed them as-is from the response, your client will just pick up the new values.
  • The ?key=odt_xxx fallback on /file/{id} still works — integrations that already embed that format in emails or shareable links don't break. Migration to the Authorization header is recommended for new accounts or server-to-server endpoints.
Optional migration

If you want to take advantage of the new flags to distinguish MH success from contingency in your logic, read Responses and states and Retry and idempotency.