Minhas contas Bancolombia

O Bancolombia é o maior banco da Colômbia. A Sucursal Virtual Personas de um cliente guarda suas contas, saldos e movimentos. Estes endpoints leem esse internet banking com a conexão própria do cliente.

Conecte sua conta

O Bancolombia só responde a um cliente com sessão iniciada: seu usuário e senha da Sucursal Virtual Personas. Cada consulta roda com a conexão própria da sua organização, então registre uma antes da sua primeira consulta. Registre a conta uma vez; a Croma inicia sessão em cada consulta e nunca guarda as credenciais em claro. POST /co/bancolombia/connections/v1 Registre uma conexão uma vez. A Croma a verifica com a fonte antes de salvá-la e responde com seu id e um nome mascarado.

Campo	Tipo	Notas
`username`	string	Obrigatório. The username (usuario) of that Bancolombia Sucursal Virtual Personas account.
`password`	string	Obrigatório. The password (clave) of that Bancolombia account.
`authorized`	boolean	Obrigatório. `true`: você confirma que é o titular da conta ou que tem a autorização do titular para usá-la.

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"
  }
}

A partir daí, cada consulta roda como uma das conexões da sua organização. A Croma escolhe uma, mantém sua sessão aberta entre as consultas e passa para a próxima quando uma atinge sua cota diária. Registre mais de uma para ter mais capacidade por dia. Para usar uma específica, envie seu id como connection_id. Como o fluxo funciona, passo a passo: Conexões. Liste e exclua:

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, os mesmos verbos são as ferramentas bancolombia_connect, bancolombia_list_connections, bancolombia_delete_connection. Conectar a partir de um agente nunca passa as credenciais pela conversa: o agente recebe um link seguro e o usuário informa os dados da conta no console da Croma. Quando uma consulta não pode rodar com nenhuma conexão:

Status	Código	Significado
409	`connection_required`	A organização ainda não tem uma conexão para esta fonte.
422	`connection_rejected`	A fonte não aceita mais as credenciais da conexão.
429	`connections_exhausted`	Todas as conexões usaram sua cota diária. `Retry-After` indica quando uma volta a estar disponível.
409	`connection_exists`	A mesma conta já está conectada (ao registrar).
422	`connection_limit_reached`	A organização já tem 5 conexões para esta fonte (ao registrar).

As credenciais são criptografadas assim que chegam à Croma, ficam vinculadas à sua organização e só podem ser abertas pelo serviço isolado que faz login na fonte em seu nome. A API nunca as devolve nem as mostra a ninguém. Excluir uma conexão a destrói permanentemente.

Contas

POST /co/bancolombia/accounts/v1

Campo	Tipo	Notas
`connection_id`	string	A conexão com que se consulta. Cada conexão Bancolombia lê a própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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 '{}'

Resposta

Campo	Notas
`count`	Quantidade de contas retornadas.
`accounts[]`	Uma por conta (abaixo).

Cada conta tem seu number, name e custom_name (o apelido que o cliente deu), seu type (savings, checking, credit_card ou other) e type_raw (o rótulo próprio do banco), currency, status, plan_name, os três saldos available_balance, current_balance e effective_balance, as flags allow_credit e allow_debit, holder_relation, joint_holder, opening_date e seu 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 chamada lê o Bancolombia ao vivo com a sua conexão, então a resposta está atualizada e nunca é compartilhada entre organizações.

Esta consulta pode demorar mais que uma solicitação típica. É um trabalho assíncrono. Por padrão, a solicitação espera de forma síncrona e retorna { data }, ou você pode fazer polling / usar um callback_url.

Movimentos

POST /co/bancolombia/transactions/v1

Campo	Tipo	Notas
`account_number`	string	Obrigatório. A conta cujos movimentos se leem, seu número como aparece na lista de contas.
`date_from`	string	Obrigatório. Primeiro dia da janela, inclusive, `yyyy-mm-dd`.
`date_to`	string	Obrigatório. Último dia da janela, inclusive, `yyyy-mm-dd`.
`connection_id`	string	A conexão com que se consulta. Cada conexão Bancolombia lê a própria conta, então com mais de uma na sua organização é obrigatório; sem ele a chamada 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"
      }'

Resposta

Campo	Notas
`account_number`	Repete a conta.
`from`, `to`	Repetem a janela, `yyyy-mm-dd`.
`count`	Quantidade de movimentos retornados.
`transactions[]`	Um por movimento (abaixo).

Cada movimento tem sua date, description, amount (com o sinal que o Bancolombia reporta), movement_type (o rótulo próprio do Bancolombia), reference e seu 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 chamada lê o Bancolombia ao vivo com a sua conexão, então a resposta está atualizada e nunca é compartilhada entre organizações.

Referência completa

Esquemas, todos os campos de resposta e um playground interativo.

Primeiros passos

Tipos de solicitação

Monitores

Países

Minhas contas Bancolombia

Conecte sua conta

Contas

Resposta

Movimentos

Resposta

Referência completa

​Conecte sua conta

​Contas

​Resposta

​Movimentos

​Resposta

Referência completa

Conecte sua conta

Contas

Resposta

Movimentos

Resposta