Saltar al contenido principal

Changelog

En curso​

  • Documentación nueva (este sitio).
  • Flags extendidos en responses (contingency, rejected, dte_success, dte_state, dte_message, observaciones, codigo_msg).
  • Retry idempotente en invalidaciones.
  • Mejora: el campo customer.phone ahora se refleja en el registro del cliente y en el teléfono del receptor del DTE firmado.
  • URLs de archivos unificadas bajo /api/connect/file/{id} — antes las respuestas de status y de NC/Exportación/SUEX apuntaban a rutas distintas (/api/v2/sales-history/{id}/file para ventas y /api/v2/suex-history/{id}/file para SUEX). Ahora todos los responses retornan URLs bajo el endpoint unificado /api/connect/file/{id}?type=..., que busca en ventas y SUEX automáticamente.
  • Nuevo campo invoice_url en responses de /invoice y /status/{id} — URL al PDF carta del documento. Complementa los ya existentes ticket_url (térmico 8×21 cm, solo Factura 01) y json_url (DTE firmado).
  • Autenticación dual en /file/{id} — el endpoint de descarga acepta Authorization: Bearer odt_xxx (recomendado) o ?key=odt_xxx como fallback deprecado. El fallback se preserva por compatibilidad pero eventualmente será removido. Los URLs que el API retorna ya no incluyen ?key= — usa el header.
  • Mejora de documentación: corregida la descripción de deadline y period en la página de Factura (01) y en Catálogos MH. deadline es la unidad del plazo (CAT-018 MH): 1=Días, 2=Meses, 3=Años — no la cantidad de días. La cantidad va en period. Ejemplos actualizados en Factura 01, CCF 03 y Factura de Exportación 11 para reflejar la semántica correcta ("deadline": 1, "period": 30 para 30 días de crédito).
  • Nuevo campo district en customer de /invoice y subject de /suex — UUID del distrito obtenido de /catalogs/districts/search. Cuando lo envías, el API resuelve automáticamente el departamento y municipio MH del distrito padre. Es el flujo recomendado porque no tenés que manejar códigos MH. Si no lo envías, department y municipality siguen funcionando igual que antes.
  • Nuevo endpoint /catalogs/districts/search — busca distritos por nombre para poblar dropdowns/autocompletares en tu UI. Misma experiencia que en el panel de Ocote desktop.
  • municipality acepta formato corto o largo — además del histórico formato corto ("24"), ahora podés enviar el código de 4 dígitos que devuelve el catálogo ("1124") directamente en el payload. Ambos resuelven al mismo municipio. Integraciones que usan formato corto siguen funcionando sin cambios.
  • Nuevo campo short_code en la respuesta de /catalogs/departments — los 2 últimos dígitos del municipio (el town puro). Se expone junto al code de 4 dígitos para claridad.
  • Búsquedas accent-insensitive en todos los endpoints de catálogos (/activities, /departments, /districts/search, /units) — programacion encuentra PROGRAMACIÓN INFORMÁTICA, berlin encuentra Berlín, etc.

Compatibilidad hacia atrás​

Si ya consumes el API, no necesitas cambiar tu código. Los campos nuevos son aditivos:

  • El flag success sigue significando "operación registrada", lo cual ahora incluye explícitamente contingencia (antes ambiguo).
  • Los campos deprecados amount y amount_ret en /status/{id} se mantienen como alias de amount_gross y amount_retention.
  • Esquemas de entrada sin cambios.
  • URLs viejos /api/v2/sales-history/{id}/file y /api/v2/suex-history/{id}/file siguen funcionando — si tu integración los construye directamente no romperá. El refactor solo cambia lo que el API retorna en los campos *_url; si los usabas tal cual vienen del response, basta con dejar que tu cliente siga leyéndolos.
  • El fallback ?key=odt_xxx en /file/{id} sigue funcionando — integraciones que ya embebían ese formato en correos o links compartibles no rompen. Se recomienda migrar al header Authorization para cuentas nuevas o endpoints servidor-a-servidor.
Migración opcional

Si quieres aprovechar los nuevos flags para distinguir éxito MH de contingencia en tu lógica, lee Respuestas y estados y Retry e idempotencia.