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.
client_secret no va en una app móvilQuien 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"
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
| Camino | Quién lo dispara | Estado |
|---|---|---|
| Alta por un administrador de Crezcamos | Administrador (POST /api/admin/merchants) | Disponible |
| Aprobación de un comercio que se registró solo (onboarding + KYC) | Administrador | Disponible |
| 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.
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.