Mis cuentas Bancolombia

Bancolombia es el banco más grande de Colombia. La Sucursal Virtual Personas de un cliente guarda sus cuentas, saldos y movimientos. Estos endpoints leen esa banca en línea con la conexión propia del cliente.

Conecta tu cuenta

Bancolombia solo responde a un cliente con sesión iniciada: su usuario y clave de la Sucursal Virtual Personas. Cada consulta corre con la conexión propia de tu organización, así que registra una antes de tu primera consulta. Registra la cuenta una vez; Croma inicia sesión en cada consulta y nunca guarda las credenciales en claro. POST /co/bancolombia/connections/v1 Registra una conexión una vez. Croma la verifica con la fuente antes de guardarla y responde con su id y un nombre enmascarado.

Campo	Tipo	Notas
`username`	string	Obligatorio. The username (usuario) of that Bancolombia Sucursal Virtual Personas account.
`password`	string	Obligatorio. The password (clave) of that Bancolombia account.
`authorized`	boolean	Obligatorio. `true`: confirmas que eres el titular de la cuenta o que tienes su autorización para usarla.

curl https://api.croma.run/co/bancolombia/connections/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "username": "your-username",
        "password": "your-password",
        "authorized": true
      }'

{
  "data": {
    "id": "conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3",
    "source": "bancolombia",
    "status": "active",
    "display_name": "J*** P*** G***",
    "usage": {
      "sign_ins_today": 1,
      "daily_limit": null,
      "resets_at": "2026-10-01T05:00:00.000Z"
    },
    "available_again_at": null,
    "created_at": "2026-09-30T20:00:00.000Z",
    "last_used_at": "2026-09-30T20:00:00.000Z"
  }
}

Desde entonces, cada consulta corre como una de las conexiones de tu organización. Croma elige una, mantiene su sesión abierta entre consultas y pasa a la siguiente cuando una alcanza su cupo diario. Registra más de una para tener más capacidad al día. Para usar una en particular, envía su id como connection_id. Cómo funciona el flujo, paso a paso: Conexiones. Lístalas y elimínalas:

curl https://api.croma.run/co/bancolombia/connections/v1 -H "Authorization: Bearer $CROMA_API_KEY"
curl -X DELETE https://api.croma.run/co/bancolombia/connections/v1/conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3 -H "Authorization: Bearer $CROMA_API_KEY"

Por MCP, los mismos verbos son las herramientas bancolombia_connect, bancolombia_list_connections, bancolombia_delete_connection. Conectar desde un agente nunca pasa las credenciales por la conversación: el agente recibe un enlace seguro y el usuario ingresa los datos de la cuenta en la consola de Croma. Cuando una consulta no puede correr con ninguna conexión:

Estado	Código	Significado
409	`connection_required`	La organización aún no tiene una conexión para esta fuente.
422	`connection_rejected`	La fuente ya no acepta las credenciales de la conexión.
429	`connections_exhausted`	Todas las conexiones usaron su cupo diario. `Retry-After` indica cuándo vuelve a haber una disponible.
409	`connection_exists`	La misma cuenta ya está conectada (al registrar).
422	`connection_limit_reached`	La organización ya tiene 5 conexiones para esta fuente (al registrar).

Las credenciales se cifran en cuanto llegan a Croma, quedan ligadas a tu organización y solo puede abrirlas el servicio aislado que inicia sesión en la fuente en tu nombre. La API nunca las devuelve ni se muestran a nadie. Eliminar una conexión la destruye de forma permanente.

Cuentas

POST /co/bancolombia/accounts/v1

Campo	Tipo	Notas
`connection_id`	string	La conexión con la que se consulta. Cada conexión Bancolombia lee su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/bancolombia/accounts/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta

Campo	Notas
`count`	Cantidad de cuentas devueltas.
`accounts[]`	Una por cuenta (abajo).

Cada cuenta tiene su number, name y custom_name (el apodo que puso el cliente), su type (savings, checking, credit_card u other) y type_raw (la etiqueta propia del banco), currency, status, plan_name, los tres saldos available_balance, current_balance y effective_balance, las banderas allow_credit y allow_debit, holder_relation, joint_holder, opening_date y su office.

{
  "data": {
    "count": 1,
    "accounts": [
      {
        "number": "12345678901",
        "name": "JUAN PEREZ",
        "custom_name": "Mi ahorro",
        "type": "savings",
        "type_raw": "CUENTA_DE_AHORRO",
        "currency": "COP",
        "status": "ACTIVO",
        "plan_name": "PLAN PREMIUM",
        "available_balance": 4200000,
        "current_balance": 4200000,
        "effective_balance": 4200000,
        "allow_credit": true,
        "allow_debit": true,
        "holder_relation": "TITULAR",
        "joint_holder": false,
        "opening_date": "2020-01-15",
        "office": { "code": "698", "name": "CALLE 79" }
      }
    ]
  }
}

Cada llamada lee Bancolombia en vivo con tu conexión, así que la respuesta está al día y nunca se comparte entre organizaciones.

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Movimientos

POST /co/bancolombia/transactions/v1

Campo	Tipo	Notas
`account_number`	string	Obligatorio. La cuenta cuyos movimientos se leen, su número tal como aparece en la lista de cuentas.
`date_from`	string	Obligatorio. Primer día de la ventana, inclusive, `yyyy-mm-dd`.
`date_to`	string	Obligatorio. Último día de la ventana, inclusive, `yyyy-mm-dd`.
`connection_id`	string	La conexión con la que se consulta. Cada conexión Bancolombia lee su propia cuenta, así que con más de una en tu organización es obligatorio; sin él la llamada responde `409 connection_id_required`.

curl https://api.croma.run/co/bancolombia/transactions/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "account_number": "12345678901",
        "date_from": "2026-01-01",
        "date_to": "2026-03-31"
      }'

Respuesta

Campo	Notas
`account_number`	Repite la cuenta.
`from`, `to`	Repiten la ventana, `yyyy-mm-dd`.
`count`	Cantidad de movimientos devueltos.
`transactions[]`	Uno por movimiento (abajo).

Cada movimiento tiene su date, description, amount (con el signo que reporta Bancolombia), movement_type (la etiqueta propia de Bancolombia), reference y su office.

{
  "data": {
    "account_number": "12345678901",
    "from": "2026-01-01",
    "to": "2026-03-31",
    "count": 1,
    "transactions": [
      {
        "date": "2026-02-10",
        "description": "COMPRA ALMACENES EXITO",
        "amount": -120000,
        "movement_type": "DEBITO",
        "reference": "9912",
        "office": { "code": null, "name": "CALLE 79" }
      }
    ]
  }
}

Cada llamada lee Bancolombia en vivo con tu conexión, así que la respuesta está al día y nunca se comparte entre organizaciones.

Esta consulta puede tardar más que una solicitud típica. Es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling / usar un callback_url.

Referencia completa

Esquemas, todos los campos de respuesta y un playground interactivo.

Primeros pasos

Tipos de solicitud

Monitores

Países

Mis cuentas Bancolombia

Conecta tu cuenta

Cuentas

Respuesta

Movimientos

Respuesta

Referencia completa

​Conecta tu cuenta

​Cuentas

​Respuesta

​Movimientos

​Respuesta

Referencia completa

Conecta tu cuenta

Cuentas

Respuesta

Movimientos

Respuesta