Convenciones

Reglas comunes a todos los endpoints.

URL base y formato

  • URL base: https://mgt.marimpex.com.ar/api/v1. Solo HTTPS.
  • Todos los endpoints son GET (la API es de solo lectura).
  • Las respuestas son JSON, salvo errores de transporte. Ninguna respuesta se cachea (Cache-Control: no-store).
  • Las fechas con hora son ISO 8601 en UTC (2026-10-02T14:03:11.000Z). Las fechas de calendario son AAAA-MM-DD.
  • Los campos sin dato vienen como null; no se omiten.
  • Los importes son números (no texto), con punto decimal.

Paginación

Los listados (/despachos y /facturas) devuelven { data, nextCursor }.

CampoTipoDescripción
limitenteroCantidad de elementos por página. Despachos: 1 a 100 (por defecto 50). Facturas: 1 a 50 (por defecto 25).
cursortexto opacoEl nextCursor de la página anterior. No lo interpretes ni lo armes a mano: puede cambiar de formato.
updated_sincefecha ISO 8601Devuelve solo lo modificado desde esa fecha, inclusive (>=). Ej.: 2026-10-01T00:00:00Z.

Mientras nextCursor no sea null, hay más páginas: volvé a llamar con ese cursor. Los resultados vienen ordenados por updatedAt ascendente.

En facturas, una página puede venir corta o vacía

limit cuenta documentos de origen, y cada uno se expande a su factura, adicionales y notas de crédito. Una página puede traer más o menos elementos que limit, o ninguno, y aun así tener nextCursor. Seguí hasta que sea null.

Sincronización incremental

Para mantener tu sistema al día sin releer todo cada vez:

  • Paginá hasta que nextCursor sea null.
  • Recién al terminar de paginar, guardá el updatedAt más alto que viste.
  • En la corrida siguiente, pedí updated_since=<ese valor>.
  • Como updated_since es inclusivo, el último elemento se repite: deduplicá por despacho (o id en facturas) más updatedAt.

No guardes el máximo a mitad de la paginación

Si tu proceso se corta en la página 3 y ya guardaste el máximo, la corrida siguiente se saltea lo que faltaba. En facturas el orden es por origen (aduana y después flete), así que el máximo parcial puede engañar. Guardalo solo al final.
Ciclo
desde = <updatedAt máximo guardado la última vez, o vacío la primera vez>
máximo = desde
cursor = nada
repetir:
  página = GET /despachos?updated_since=desde&cursor=cursor&limit=100
  procesar(página.data)        # upsert por despacho
  máximo = max(máximo, updatedAt más alto de la página)
  cursor = página.nextCursor
hasta que cursor sea null
guardar(máximo)

Límites de uso

  • 60 llamadas por minuto por clave.
  • 300 llamadas por minuto por IP de origen (se mide antes de autenticar).
  • Si superás un límite, la API responde 429 con el header Retry-After (segundos a esperar). Esperá ese tiempo y reintentá.
  • Las llamadas rechazadas con 403 por falta de permiso también cuentan contra el límite de la clave.