Cuenta y sistema

Los endpoints de Cuenta y sistema son la "sala de control" de tu integración con Alibanca: no mueven dinero ni tocan beneficiarios, solo te dicen con quién estás hablando, qué versión de la API está del otro lado y si el servicio está vivo. Son livianos, de bajo riesgo y perfectos para el arranque: los llamas antes de firmar tu primera operación, los usas para poblar un panel interno y los conectas a tu monitoreo. En esta página encontrarás la referencia completa de los tres: GET /v2/me, GET /v2/version y GET /health, con la respuesta entera de cada uno explicada campo por campo.

Los tres endpoints de esta sección

Esta sección agrupa los endpoints de identidad y estado del servicio. Dos de ellos son públicos (no requieren llave ni firma) y uno es autenticado (te dice quién eres, así que primero tiene que saber quién eres). Aquí los tienes de un vistazo:

GET /v2/me — la identidad de tu llave

GET /v2/me te devuelve la identidad asociada a la llave con la que firmaste el request. No es "tu usuario" ni "tu login": es la cédula de la llave que estás usando en ese momento. Esto importa porque una misma organización puede tener varias llaves (una de sandbox, una de producción, quizás una por ambiente de despliegue), y cada request se identifica por la llave que lo firmó. /v2/me te dice, sin ambigüedad, con cuál estás operando ahora mismo.

¿Para qué lo usas?

Es la primera llamada autenticada que deberías hacer al integrarte, por tres razones muy prácticas:

1) Confirmar que tu firma funciona. Como /v2/me exige x-api-key + x-nonce + x-signature pero no mueve dinero, es el "hola mundo" seguro de la autenticación. Si /v2/me te responde 200, tu envelope canónico, tu firma RSA-SHA256 y tu nonce están bien armados. Si falla, arreglas la firma antes de arriesgar un pago.

2) Evitar disparar en el entorno equivocado. El campo environment te dice si estás en sandbox (proveedor simulado, no mueve un centavo real) o en production. Un chequeo defensivo — "si environment no es el que espero, aborto" — te salva de mandar un pago real creyendo que estabas probando.

3) Poblar un panel interno. Nombre de la cuenta, huella de la llave pública, webhook configurado y límites vigentes: todo lo que tu equipo de operaciones necesita ver de un vistazo sale de aquí.

Autenticación

/v2/me es un endpoint autenticado. Cada request lleva x-api-key con tu llave (sk_test_… en sandbox, sk_live_… en producción) y x-signature con la firma RSA-SHA256 del envelope canónico (la concatenación determinística de método, ruta, api-key, idempotency-key, cuerpo crudo y nonce). Tu llave privada nunca sale de tu lado; Alibanca verifica con tu llave pública. Para el detalle completo del envelope y la firma, ve a Autenticación y firma →.

# GET /v2/me — necesita x-api-key + x-nonce + x-signature (no mueve dinero)
curl https://alibanca-api-production.up.railway.app/v2/me \
  -H "x-api-key: sk_test_tu_llave_aqui" \
  -H "x-signature: {firma_RSA-SHA256_del_envelope}" \
  -H "x-nonce: 1721683200123456"

Y así se ve la respuesta completa. Fíjate que viene envuelta en el sobre de éxito estándar de Alibanca (status + traceId + payload), y que todo lo interesante está en payload:

{
  "status": "success",
  "traceId": "trc_9f3a2b7c8d1e4f60",
  "payload": {
    "remitterId": "137",
    "name": "Acme Remesas C.A.",
    "environment": "sandbox",
    "keyType": "test",
    "publicKeyFingerprint": "SHA256:8b2ed669a120e97b8cf0bceb949698e7c26c1b8f1e05c8bc26a9584512f97792",
    "webhook": {
      "url": "https://acme.example.com/hooks/alibanca",
      "pendingChange": null
    },
    "limitsConfigured": true,
    "limits": [
      {
        "payoutType": "*",
        "window": "TX",
        "maxAmountMinor": "…",
        "maxCount": null,
        "isFloor": true
      },
      {
        "payoutType": "PM",
        "window": "DAY",
        "maxAmountMinor": "…",
        "maxCount": null,
        "isFloor": false
      }
    ]
  }
}

Campo por campo

Cada campo de payload tiene un propósito. Aquí está el detalle:

Si tu huella no coincide, mira primero el alfabeto

Antes de asumir que registramos la llave equivocada, descarta el desacuerdo falso más común: que los dos lados hayan calculado el mismo SHA-256 del DER SPKI y lo hayan escrito distinto. Nuestro publicKeyFingerprint va en hexadecimal — 64 caracteres del 0 a la f —, y muchas librerías entregan ese mismo digest en base64: 44 caracteres, con mayúsculas, +, / y un = al final. Es el mismo número en otra base. Conviértelo a hexadecimal y recién ahí compara.

# el -A es obligatorio y el '=' del final no se toca (ver el aviso de abajo)
echo 'rQrqzbwVJdQnMqRhxRwkpnlLS+yfjpbhCFReyuKXuko=' | openssl base64 -d -A | xxd -p -c 32
# ad0aeacdbc1525d42732a461c51c24a6794b4bec9f8e96e108545ecae297ba4a

GET /v2/version — descubrimiento (discovery)

GET /v2/version es un endpoint público de descubrimiento: no lleva llave ni firma, y te dice qué hay del otro lado de la línea. Su rol en tu integración es ser la primera llamada de todas, antes de firmar nada. Piénsalo como marcar un número y escuchar el tono: confirmas que hay conexión, qué versión atiende, en qué entorno estás y dónde encontrar los recursos que necesitas (el contrato OpenAPI y las llaves públicas de verificación de webhooks).

¿Por qué llamarlo antes de firmar?

Firmar un request tiene varios pasos (armar el envelope, calcular la firma RSA-SHA256, avanzar el nonce). Si algo de red está mal — DNS, un proxy, una URL base equivocada — no quieres descubrirlo después de gastar esfuerzo firmando. /v2/version es la prueba de vida sin credenciales: si te responde, la conectividad y la URL base están bien, y recién entonces te pones a firmar. Además, el campo environment te confirma a qué mundo estás apuntando, y rails te dice qué rieles de dispersión están disponibles hoy.

# GET /v2/version — público, sin llave ni firma
curl https://alibanca-api-production.up.railway.app/v2/version

{
  "status": "success",
  "traceId": "trc_2b9c5b1986fc",
  "payload": {
    "version": "0.24.0",
    "buildId": "b2760f1414431ed4",
    "apiVersion": "v2",
    "environment": "sandbox",
    "rails": ["PM", "CCE"],
    "simulado": false,
    "links": {
      "openapi": "/v2/openapi.json",
      "jwks": "/v2/webhook/keys"
    }
  }
}

Campo por campo

GET /health — ¿está viva la API?

GET /health es un chequeo de salud público: responde 200 cuando el servicio está operativo y puede dispersar, y 503 con un status que distingue la causa. No lleva llave, no lleva firma, no revela nada de tu cuenta — su único trabajo es decir "estoy viva". Está pensado para conectarlo a tu sistema de monitoreo (uptime, balanceadores de carga, alertas): un sondeo cada cierto tiempo que espera un 200 y levanta una alarma si deja de recibirlo.

# GET /health — público, para tu monitoreo
curl https://alibanca-api-production.up.railway.app/health

{ "status": "ok" }

La regla para tu monitoreo: trata cualquier cosa que no sea un 200 como "servicio degradado" y dispara tu alerta — pero sí parsea el cuerpo, porque el 503 tiene dos causas muy distintas y una de ellas no es una caída:

Ese 503 con la API viva es deliberado: sin él, una parada total de dispersión sería silenciosa de nuestro lado y te enterarías tú, con 422 en cada pago.

Cómo encajan los tres en tu integración

Estos endpoints no compiten: se complementan en una secuencia natural de arranque y operación. Este es el flujo recomendado la primera vez que te conectas:

Buenas prácticas

Usa /v2/me como prueba de humo, no como parte del camino caliente. Es ideal al arrancar tu proceso o en un test de integración para verificar credenciales. No lo llames antes de cada pago: no aporta nada al camino de emisión y agrega latencia.

Chequea environment defensivamente. Antes de emitir en producción, confirma que environment de /v2/me (o de /v2/version) sea production. Ese pequeño if es la diferencia entre "mandé un pago de prueba" y "mandé un pago real por error".

Lee los recursos desde links, no los hardcodees. Toma las URLs de openapi y jwks del cuerpo de /v2/version. Es el punto de discovery precisamente para que tu código no se rompa si esas rutas cambian.

Registra el traceId. Cuando /v2/me te responde, guarda su traceId en tus logs. Si algo sale raro y necesitas soporte, ese identificador de traza le permite a Alibanca ubicar exactamente tu request.

Sondea /health con moderación. Un intervalo razonable (por ejemplo cada 30–60 segundos) es suficiente para monitoreo. No lo martilles cada segundo: no gana precisión y sí gana ruido.

Errores comunes

401 en /v2/me

Si /v2/me te responde 401, el problema es de autenticación, no del endpoint. Las causas más frecuentes: (a) el orden del envelope canónico no coincide — recuerda que es método, ruta, api-key, idempotency-key, cuerpo crudo y nonce, en ese orden; (b) el nonce no creció respecto al anterior (la marca de agua creciente por llave rechaza replays); o (c) la llave pública que Alibanca tiene registrada no corresponde a la privada con la que firmaste — compara publicKeyFingerprint con la huella de tu propia llave. La respuesta de error viene en el formato estándar:

{ "error": "firma inválida" }

Llamar a /v2/me sin firma

A diferencia de /v2/version y /health, /v2/me no es público. Si lo abres en el navegador sin x-api-key, x-nonce ni x-signature, obtendrás un error de autenticación. Es a propósito: la respuesta describe tu cuenta, así que la API tiene que saber quién eres primero.

Apuntar a la URL base equivocada

Si /v2/version te devuelve un environment que no esperabas, revisa tu URL base: el sandbox es https://alibanca-api-production.up.railway.app (proveedor simulado, no mueve dinero real) y producción es https://api.alibanca.com. Cruzarlas es la causa número uno de "mi llave de test no funciona en prod" y viceversa: una llave sk_test_… solo opera contra el sandbox, y una sk_live_… solo contra producción.