Convenciones de la API

Reglas transversales que aplican a todas las APIs de Max Capital. Valen para cualquier endpoint salvo que su documentación indique lo contrario.

Ambientes

Ambiente	Base URL	Uso
Desarrollo (sandbox)	https://openapi-dev.max.capital	Pruebas de integración
Producción	https://openapi.max.capital	Operaciones reales, con impacto financiero

Dentro de la Base URL, cada servicio cuelga de su propio prefijo y la ruta del endpoint arranca con la versión:

Servicio	Prefijo	URL completa (desarrollo)
Autenticación (login)	/auth/api	https://openapi-dev.max.capital/auth/api/v1/login
Endpoints de negocio	/gateway-openapi/api	https://openapi-dev.max.capital/gateway-openapi/api/v1/holdings/instruments

Las credenciales son específicas de cada ambiente: usá las de desarrollo contra la Base URL de desarrollo.

Autenticación

Todas las solicitudes requieren un token JWT válido en el encabezado Authorization, con el formato Bearer {token}. El token se obtiene en el endpoint de login y tiene una vigencia limitada (ver Autenticación).

Versionado

La versión de la API va en la URL. La versión actual es v1, por lo que todos los endpoints comienzan con /v1/. Los cambios incompatibles se publican bajo una versión nueva; los cambios compatibles se agregan dentro de la versión vigente.

Formato de fechas

Todas las fechas usan ISO 8601:

• Fechas simples: YYYY-MM-DD (por ejemplo, 2025-04-01).
• Marcas de tiempo: con zona horaria en formato UTC (por ejemplo, 2024-06-01T14:15:59.999Z).

Tipo de contenido

Las solicitudes con cuerpo usan Content-Type: application/json y las respuestas se devuelven en JSON.

Manejo de errores

Ante un error, la API responde con el código HTTP correspondiente y un cuerpo con esta estructura:

{
  "statusCode": "400",
  "errorCode": "INVALID_PARAMETER",
  "title": "Bad Request",
  "detail": "El parámetro 'dateType' es inválido."
}

Códigos más frecuentes:

Código	Significado
400	Solicitud inválida (parámetros mal formados).
401	Credenciales o token inválidos.
403	Sin permiso sobre el recurso solicitado.
404	El recurso no existe.
422	La solicitud no cumple una regla de negocio.
500	Error interno del servidor.

Límites de uso

Para proteger el servicio, la API limita la cantidad de solicitudes que acepta por unidad de tiempo. Cuando se supera el límite, las solicitudes se rechazan con el código 429 hasta que la tasa vuelva a estar dentro de lo permitido. Los valores concretos se acuerdan con cada integración.

Cómo integrarse bien con el límite:

• Reintentá con backoff exponencial. Esperá antes del primer reintento y duplicá la espera en cada intento siguiente. Reintentar en loop inmediato sostiene el exceso y prolonga el rechazo.
• Escaloná los procesos por lote. Si recorrés muchos comitentes para conciliar o cerrar el día, enviá las solicitudes de forma espaciada en lugar de todas juntas.
• Evitá el polling continuo. Para seguir el estado de una operación, consultá con intervalos de segundos o minutos, no sin pausa.
• Un 429 no dice nada sobre la operación anterior. Si estabas consultando el estado de algo que ya enviaste, esa operación sigue su curso: volvé a consultar después de la espera.

Datos y monedas

Los valores descriptivos que devuelve la API (por ejemplo, la descripción de una moneda) vienen en español. Los códigos de moneda dependen de cada API: consultá la sección correspondiente en Cuenta corriente.