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​

  • 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

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.