Saltar al contenido principal

Autenticación

Casi toda la API exige un JWT de Keycloak en Authorization: Bearer <token>. Un comercio ya aprobado lo obtiene con client credentials.

Obtener un token (recomendado)​

POST /api/auth/token cambia las credenciales del comercio por un JWT sin que el integrador conozca ni alcance el servidor de identidad. Es anónimo (las credenciales van en el cuerpo), solo admite client_credentials y está limitado por IP (30 solicitudes por minuto por defecto).

curl -s -X POST "$API/api/auth/token" \
-H "Content-Type: application/json" \
-d '{"client_id":"'"$MERCHANT_ID"'","client_secret":"'"$MERCHANT_SECRET"'"}'
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 300 }

También acepta application/x-www-form-urlencoded. Pide un token nuevo antes de que venza (no hay refresh_token). Los errores usan el formato OAuth 2.0: 400 invalid_request / unsupported_grant_type, 401 invalid_client, 429 y 503 temporarily_unavailable.

El client_secret no va en una app móvil

Quien llama a este endpoint tiene el secreto del comercio. Úsalo desde un servidor tuyo; una app instalada en el teléfono del pagador no debe contenerlo.

Obtener un token directamente de Keycloak​

Solo aplica donde Keycloak es alcanzable (desarrollo local o desde dentro del cluster).

  • Realm: payment-engine.
  • client_id: el UUID de tu comercio.
  • client_secret: el secreto de tu comercio (se muestra una sola vez al crearlo o rotarlo).
curl -s -X POST "$KEYCLOAK/realms/payment-engine/protocol/openid-connect/token" \
-d grant_type=client_credentials \
-d client_id="$MERCHANT_ID" \
-d client_secret="$MERCHANT_SECRET"
{ "access_token": "eyJhbGciOi…", "expires_in": 300, "token_type": "Bearer" }

Úsalo en cada llamada:

curl -s "$API/api/payment-links" -H "Authorization: Bearer $TOKEN"
Pide el token en la dirección pública de Keycloak

Esto no aplica a POST /api/auth/token, que emite un token válido para el API. El API solo acepta tokens cuyo emisor (iss) sea el de la dirección pública configurada de Keycloak. Si pides el token por una dirección interna o por un proxy que reenvía otro host, el API responde 401 con The issuer '…' is invalid. Usa la dirección que Crezcamos te indique para tu ambiente.

Cómo obtienes las credenciales​

CaminoQuién lo disparaEstado
Alta por un administrador de CrezcamosAdministrador (POST /api/admin/merchants)Disponible
Aprobación de un comercio que se registró solo (onboarding + KYC)AdministradorDisponible
Autoservicio para integradores externos—No existe todavía

Las credenciales de un comercio activo se consultan y rotan desde el portal de comercios (sección Configuración → Acceso a la API) o por API.

Rotar credenciales​

curl -s -X POST "$API/api/merchants/$MERCHANT_ID/credentials/rotate" \
-H "Authorization: Bearer $TOKEN"

El secreto nuevo viene una sola vez en meta.secret. GET /api/merchants/{id}/credentials solo devuelve el client_id, los últimos 4 caracteres del secreto (secret_hint) y la fecha de la última rotación.

Lista de IP permitidas​

Puedes restringir los tokens de servicio a tus direcciones de salida. Con una lista no vacía, una llamada desde otra IP responde 403.

Te puedes bloquear a ti mismo

En cuanto agregas la primera entrada, el API rechaza con 403 los tokens del comercio desde cualquier otra IP, incluida la tuya. Agrega primero la IP de salida desde la que estás llamando (y la de todos tus servidores) y comprueba que sigues teniendo acceso. Para quitar una entrada hay que llamar desde una IP todavía permitida, desde el portal de comercios o pedir ayuda a Crezcamos. No pruebes esto con las credenciales de un comercio que usan otros.

curl -s -X POST "$API/api/merchants/$MERCHANT_ID/ip-allowlist" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"data":{"type":"ip_allowlist_entry","attributes":{"address":"203.0.113.10/32","description":"servidor de producción"}}}'

address es una IP (IPv4/IPv6) o un rango CIDR. Máximo 50 entradas. Ver la referencia para GET y DELETE.

Versionado​

Cabecera opcional X-API-VERSION; sin ella se asume 1.0. Hoy solo existe la versión 1.0; no hay política de depreciación publicada.