---
title: "Integraciones"
description: "Cómo llamar a las integraciones de Arbol con aseguradoras, registros públicos y sistemas clínicos, qué necesitas antes de la primera llamada y cómo leer los resultados."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integraciones

Una integración le permite a tu organización trabajar con los datos de una aseguradora, un registro público o un sistema clínico a través de la API de Arbol: consultar derechos y afiliaciones, buscar pacientes, leer disponibilidad, agendar citas. Tú llamas a las operaciones de la integración; Arbol se encarga del lado del proveedor.

## Cómo se llama una integración

Cada integración es un servicio de la API y se llama como cualquier otro: la misma URL base, la misma credencial y el mismo envoltorio de respuesta.

| | |
|---|---|
| Ruta | `https://api.getarbol.com/v1/<service>/…`, como `/v1/sura/…` |
| Referencia | `/api/<service>/`, como la [referencia de SURA](/api/sura/) |
| Permisos (scopes) | Con el nombre del servicio, como `sura:appointments:write`. La referencia de cada operación lista los que acepta. |
| Credencial | Las mismas de toda la API: consulta [Autenticación](/developers/authentication/). Al crear una API key con [`account.apiKeys.create`](/api/account/api-keys/create/), también puedes limitarla a algunas operaciones y conexiones de una integración. |

## Integraciones disponibles

## Antes de la primera llamada

Tu organización necesita tener la integración activa:

- **Aseguradoras y sistemas clínicos**, como SURA, Nueva EPS, gMedic o Visoft: necesitan una [conexión](#conexiones), que el equipo de Arbol configura con tu organización y mantiene funcionando. Para agregar una, escríbele a tu equipo de Arbol.
- **Registros colombianos** (ADRES, Sisbén y Policía Colombia): vienen incluidos con Arbol. El **Propietario** de la organización activa cada uno en **Integraciones** de Cuenta de Arbol ([cómo hacerlo](/account/colombian-registries/)), o se activan con [`account.registryInstallations.update`](/api/account/registry-installations/update/).

## Conexiones

Tu organización llega a cada aseguradora o sistema clínico a través de una **conexión**. Las conexiones no tienen datos que debas enviar, y ninguna operación devuelve nada secreto sobre ellas.

Para ver las conexiones de tu organización, llama a [`account.connections.list`](/api/account/connections/list/). Cada una tiene:

| Campo | Significado |
|---|---|
| `id` | El id de la conexión (`con_…`). Las operaciones de integración lo reciben como `connectionId`. |
| `integration` | La integración a la que pertenece, como `sura`. |
| `name` | El nombre con el que la eligen las personas y los agentes, como `Sede Norte`. |
| `status` | `active` cuando se puede usar. |
| `tools` | Las herramientas que ofrece a un [agente de Raíz](/developers/guides/create-an-agent/). |

Cuando una conexión deja de estar `active`, escríbele a tu equipo de Arbol.

### Elegir una conexión

La mayoría de las operaciones de integración reciben un `connectionId` opcional. Mientras tu organización tenga una sola conexión con una integración, puedes omitirlo; si tiene varias, envía la que quieres usar. Algunas operaciones lo exigen siempre: su referencia lo marca como obligatorio. Cuando ninguna conexión puede ejecutar la llamada, la operación responde con un error que dice que la integración no está configurada para tu organización.

## Registros colombianos

ADRES, Sisbén y Policía Colombia son integraciones independientes, con una operación de consulta cada una:

| Registro | Qué devuelve | Operación | CLI |
| --- | --- | --- | --- |
| ADRES | Las afiliaciones a EPS de una persona | [`adres.affiliations.lookup`](/api/adres/affiliations/lookup/) | `arbol adres affiliations lookup` |
| Sisbén | El registro, el grupo y el subgrupo del Sisbén | [`sisben.classifications.lookup`](/api/sisben/classifications/lookup/) | `arbol sisben classifications lookup` |
| Policía Colombia | La declaración judicial de un documento | [`policia-colombia.judicialRecords.lookup`](/api/policia-colombia/judicial-records/lookup/) | `arbol policiacolombia judicial-records lookup` |

ADRES devuelve solo afiliaciones a EPS: para el Sisbén, llama a su propia operación. El régimen de una EPS no dice nada sobre el grupo del Sisbén.

### Hacer una consulta

Cada operación es un `POST` que recibe `documentType` y `documentNumber` en el cuerpo. Envía el número como texto, con sus ceros a la izquierda, y usa los tipos de documento que lista la referencia de la operación. Consulta solo el documento de una persona que autorizó la consulta:

```bash
curl https://api.getarbol.com/v1/adres/affiliations/lookup \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "documentType": "CC", "documentNumber": "<documentNumber>" }'
```

Con el [SDK de TypeScript](/developers/sdks/typescript/), es `arbol.adres.affiliations.lookup({ documentType, documentNumber })`; las otras dos son `arbol.sisben.classifications.lookup()` y `arbol.policiaColombia.judicialRecords.lookup()`.

Las tres aceptan cualquiera de los scopes `account:organizations:read`, `account:connections:read` o `account:connections:write`. Una API key con restricciones debe permitir además la operación exacta, como `adres.affiliations.lookup`. Un scope no instala el registro ni salta las restricciones de la key. Para consultas puntuales, crea una API key con un vencimiento corto, que eliges al crearla en Cuenta de Arbol, y guárdala fuera del código, de las instrucciones de los agentes y de los logs.

### Leer el resultado

Por defecto, `data` trae el resultado estructurado del registro:

| Registro | Campos de `data` |
| --- | --- |
| ADRES | `outcome`, `person.fullName`, todas las `affiliations` con su EPS, estado, régimen y fechas, y `consultedAt` y `verification`. |
| Sisbén | `registered`, `group`, `subgroup`, `observedAt` y `verification`. |
| Policía Colombia | `documentType`, `documentNumber`, `fullName`, `identityStatus`, `judicialStatus`, `details` y `observedAt`. |

Un resultado conocido anteriormente conserva la fecha en que se observó: en ADRES y Sisbén lo marca `verification: "last_known"`. Un error o un resultado sin verificar no prueba que algo no exista.

**Sisbén.** `registered: true` confirma el registro, `false` es un reporte negativo explícito y `null` significa que no se pudo verificar. Informa el subgrupo completo cuando llegue, como `C12`. Una afiliación a EPS no establece que la persona pueda acceder a programas sociales.

| `group` | Rango de `subgroup` |
| --- | --- |
| A | A1–A5 |
| B | B1–B7 |
| C | C1–C18 |
| D | D1–D21 |

**Policía Colombia.** `fullName` es el nombre tal como lo reporta la fuente. `identityStatus: "document_matched"` indica que el documento devuelto coincide con el consultado; no autentica a quien lo presenta. Conserva el texto oficial de `details` y distingue `no_pending_matters` de `not_currently_required`: una declaración sobre requerimientos judiciales actuales no es un historial completo de condenas. Con `judicialStatus: "unverified"` no se obtuvo una declaración verificada: nunca lo presentes como ausencia de asuntos pendientes.

### Texto para agentes de IA

Agrega `"agentMode": true` para recibir la misma observación como un texto breve en español: en `data.text` con `Accept: application/json`, o como cuerpo de texto con `Accept: text/plain`. Usa el resultado estructurado cuando tu programa necesite los campos; el SDK devuelve los datos tipados.

### Por MCP

Las mismas consultas son herramientas del [servidor MCP](/developers/mcp/): `adres_affiliations_lookup`, `sisben_classifications_lookup` y `policia_colombia_judicial_records_lookup`. Reciben los mismos campos, incluido `agentMode`, y aplican la misma instalación y las mismas restricciones de la credencial. Que una herramienta aparezca en la lista no significa que la consulta haya tenido éxito.

## Salud Total

Salud Total responde con las cuentas IPS de tu organización. El equipo de Arbol conecta cada cuenta para un uso, **postconsulta** o **facturación**, y cada consulta recibe el `connectionId` de la conexión activa que corresponde a ese uso (consulta [Conexiones](#conexiones)).

| Pregunta | Solicitud HTTP | SDK de TypeScript | CLI | Conexión |
| --- | --- | --- | --- | --- |
| ¿Está afiliada esta persona? | `POST /v1/salud-total/affiliations/lookup` | `arbol.saludTotal.affiliations.lookup(input)` | `arbol saludtotal affiliations lookup` | Postconsulta |
| ¿Hay autorizaciones de esa persona ese día? | `POST /v1/salud-total/authorizations/lookup` | `arbol.saludTotal.authorizations.lookup(input)` | `arbol saludtotal authorizations lookup` | Postconsulta |
| ¿Hay solicitudes radicadas de esa persona ese día? | `POST /v1/salud-total/filings/lookup` | `arbol.saludTotal.filings.lookup(input)` | `arbol saludtotal filings lookup` | Postconsulta |
| ¿Existe esta factura? | `POST /v1/salud-total/invoices/lookup` | `arbol.saludTotal.invoices.lookup(input)` | `arbol saludtotal invoices lookup` | Facturación |
| ¿Cuántas glosas y devoluciones hay? | `GET /v1/salud-total/notices/count` | `arbol.saludTotal.notices.count(input)` | `arbol saludtotal notices count` | Facturación |

Las consultas de una persona reciben `documentType: "CC"` y su `documentNumber` en el cuerpo; las de autorizaciones y radicaciones, además el día (`day`, `AAAA-MM-DD`).

| Respuesta | Qué significa |
| --- | --- |
| `matched` | La afiliación encontró a una sola persona; `providerStatus` es su estado de afiliación tal como lo escribe Salud Total. |
| `no_match`, `ambiguous` | No hay nadie con ese documento, o hay más de una coincidencia. No es una caída del servicio. |
| `location_required` | Para autorizaciones y radicaciones: la cuenta tiene varias sedes. Pregunta cuál aplica y repite la consulta con el id elegido en el campo que dice `field`. |
| `records_found`, `no_records` | Hay registros ese día (`recordCount`), o no hay ninguno. Un registro no aprueba un procedimiento. |
| `REPORTING_WINDOW_CLOSED` | Para facturas: el reporte de Salud Total está cerrado a esa hora. El error dice a qué hora abre y cierra (`opensAtHour`, `closesAtHour`, hora de Bogotá). |

Que una consulta falle, o que la sesión con Salud Total haya vencido, no significa que no haya registros: el error lo dice con su código, y la [referencia de Salud Total](/api/salud-total/) los lista todos.

## Integraciones en agentes de Raíz

Un agente de Raíz usa una integración a través de herramientas: cada uno de sus `integrationTools` empareja un `connectionId` con una herramienta que ofrece esa conexión, tal como las muestra `account.connections.list`. Para que un agente use un registro colombiano, asígnale también su herramienta. Consulta [Crear un agente](/developers/guides/create-an-agent/).

## Nuevas integraciones

Las nuevas integraciones llegan como nuevos servicios de la API, y aparecen en esta página y en la [referencia de la API](/api/) a medida que la API las agrega.

Source: https://docs.getarbol.com/developers/integrations/index.mdx