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 sonAAAA-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 }.
| Campo | Tipo | Descripción |
|---|---|---|
| limit | entero | Cantidad de elementos por página. Despachos: 1 a 100 (por defecto 50). Facturas: 1 a 50 (por defecto 25). |
| cursor | texto opaco | El nextCursor de la página anterior. No lo interpretes ni lo armes a mano: puede cambiar de formato. |
| updated_since | fecha ISO 8601 | Devuelve 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
nextCursorseanull. - Recién al terminar de paginar, guardá el
updatedAtmás alto que viste. - En la corrida siguiente, pedí
updated_since=<ese valor>. - Como
updated_sincees inclusivo, el último elemento se repite: deduplicá pordespacho(oiden facturas) másupdatedAt.
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
429con el headerRetry-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.