Autenticación

Solo M2M. Este portal documenta integraciones de socio a socio (machine-to-machine). Los flujos de autenticación de cliente final viven en otro lugar.

La API M2M de ARi utiliza claves de suscripción de APIM para autenticación. Cada solicitud lleva un encabezado Ocp-Apim-Subscription-Key. No hay tokens Bearer JWT ni flujos OAuth en la superficie de socios.

Inicio rápido

curl -X POST "https://sandbox-api.ariari.xyz/api/v1/fxorder/getQuote" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE_DE_SUSCRIPCION" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_currency": "USD",
    "destination_currency": "CRC",
    "origin_amount": 1000,
    "lock_rate": false
  }'

Una respuesta 200 significa que su clave de suscripción es válida y que el alcance solicitado (fxorder.read para getQuote) está concedido.

Encabezados requeridos

Alcances por endpoint

Cada endpoint requiere uno o más alcances. Su clave de suscripción es aprovisionada con un conjunto de alcances determinado por ARi según los productos contratados. Llamar a un endpoint fuera de los alcances concedidos retorna 403 Forbidden con un cuerpo RFC 7807 problem+json.

Convención de nombres de alcance: <dominio>.<acción>. División lectura/escritura.

Si un alcance que usted espera no está concedido, contacte a su gerente de cuenta de ARi — el aprovisionamiento de alcances es una acción manual de ARi, no autoservicio.

Convenciones de formato de cable

La API M2M aplica estas convenciones en cada solicitud y respuesta. Los SDK de socios se generan a partir de la especificación OpenAPI; estas reglas se reflejan en la especificación pero se documentan aquí para lectores humanos.

Por qué decimales codificados como cadena. La representación en punto flotante introduce pérdida de precisión para montos monetarios. Un socio que deserialice 1000.10 como Number en JavaScript y lo reserialice puede perder centavos. Siempre parsee montos como cadenas; use una biblioteca Decimal de su lado para aritmética.

Límites de tasa

Cada suscripción tiene una cuota por minuto aplicada en APIM con una ventana de renovación de 60 segundos. Los límites dependen de la superficie de API y el entorno, no del nivel de suscripción. Los socios con contratos empresariales pueden negociar cuotas superiores — contacte a su gerente de cuenta de ARi.

El límite de SSE aplica a operaciones de flujo (conexión / reconexión), no a los eventos que circulan en un flujo abierto. Es intencionalmente más estricto en producción para proteger contra tormentas de reconexión — haga back off antes de restablecer un flujo.

Exceder el límite retorna 429 Too Many Requests con encabezado Retry-After (segundos a esperar). Trate 429 como transitorio; haga back off y reintente. Comportamiento de cliente recomendado:

1. En 429 → duerma Retry-After segundos (o 1 segundo si el encabezado está ausente), luego reintente la solicitud original con el mismo Idempotency-Key.
2. Reintente hasta 3 veces. Si el 4° intento también retorna 429, eleve el error a su operador — su suscripción está sobrecargada de manera sostenida.
3. Agregue jitter (50–100 ms aleatorios) a los reintentos para que múltiples clientes no se sincronicen.

IDs de correlación

X-Correlation-Id es opcional pero fuertemente recomendado. Establézcalo a un UUID v4 que su cliente genera para la solicitud original. ARi lo propaga a través de cada servicio interno involucrado en el manejo de la llamada y lo emite en respuestas de error (campo trace_id en RFC 7807 problem+json). Cuando contacte soporte sobre una solicitud que falla, incluya el ID de correlación — es la ruta más rápida a una resolución.

Si usted no suministra uno, ARi genera uno automáticamente y lo retorna en trace_id de la respuesta. Aun así, debería registrar este valor del lado cliente.

Respuestas de error

Todos los errores usan RFC 7807 problem+json. Campos requeridos:

Campos opcionales cuando aplica:

Vea el Catálogo de errores completo para la lista exhaustiva de valores error_code.

Rotación de claves

Las claves de suscripción se rotan en cadencia trimestral. ARi notifica a los socios 30 días antes de la rotación; la nueva clave se aprovisiona junto con la existente durante una ventana de superposición de 7 días.

Para rotar:

1. ARi aprovisiona la nueva clave y notifica al socio.
2. El socio despliega la nueva clave en su flota de producción.
3. Ambas claves funcionan durante la superposición de 7 días.
4. Después de 7 días, la clave antigua es revocada. El uso continuado de la clave antigua retorna 401 Unauthorized.

Si usted sospecha que su clave fue comprometida, contacte soporte de ARi inmediatamente — la rotación de emergencia puede acortar la ventana de superposición a unas pocas horas. Nunca incruste la clave de suscripción en código del lado cliente, aplicaciones móviles, o repositorios accesibles públicamente.

Lo que este portal NO cubre

La autenticación de cliente final (CIAM, OAuth, flujos MFA) está fuera de alcance. Si su integración requiere identidad de cliente final (p. ej. está construyendo una aplicación dirigida al cliente que llama a ARi en nombre de un usuario autenticado), eso es una superficie diferente — contacte a su gerente de cuenta de ARi para la documentación de la API de cliente final.

Vea también

• Idempotencia — semántica de Idempotency-Key + matriz de decisión de reintentos
• Sandbox — credenciales y escenarios de prueba
• Paginación — convenciones para endpoints de colección
• Errores — catálogo completo de errores
• Webhooks — suscripciones a eventos salientes + verificación HMAC