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.

Integraciones disponibles

• SURA12 operaciones

  Derechos, pacientes, servicios, profesionales, disponibilidad, citas, autorizaciones y copagos a través de tus conexiones con SURA.

  ReferenciaOpenAPI/v1/sura

• Nueva EPS1 operación

  La afiliación de un afiliado, a través de tus conexiones con Nueva EPS.

  ReferenciaOpenAPI/v1/nueva-eps

• gMedic23 operaciones

  Pacientes y sus notas, agendas, disponibilidad y citas, sesiones, sedes y listas de referencia de gMedic.

  ReferenciaOpenAPI/v1/gmedic

• Visoft12 operaciones

  Clínicas, contratos y servicios, profesionales, pacientes, disponibilidad y citas de Visoft.

  ReferenciaOpenAPI/v1/visoft

• AXA3 operaciones

  Derechos de los beneficiarios, autorizaciones médicas y el perfil del prestador en AXA.

  ReferenciaOpenAPI/v1/axxa

• Salud Total5 operaciones

  La afiliación, las autorizaciones y las radicaciones de un afiliado, las facturas y las glosas y devoluciones, a través de las conexiones IPS de tu organización con Salud Total.

  ReferenciaOpenAPI/v1/salud-total

• ADRES1 operación

  Una persona y todas sus afiliaciones a EPS, desde la base de datos nacional de afiliados de Colombia.

  ReferenciaOpenAPI/v1/adres

• Policía Colombia1 operación

  La declaración judicial que publica la Policía Nacional de Colombia para un documento, palabra por palabra.

  ReferenciaOpenAPI/v1/policia-colombia

• Sisbén1 operación

  El registro de una persona en el Sisbén IV, con su grupo y subgrupo oficiales.

  ReferenciaOpenAPI/v1/sisben

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, 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), o se activan con account.registryInstallations.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. Cada una tiene:

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:

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:

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, 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:

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.

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: 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).

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).

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 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.

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 a medida que la API las agrega.