Integra afiliaciones de salud paso a paso

Inicio rapido

La integracion completa se puede resumir en seis pasos. No escribas nombres libres cuando exista un catalogo: envia siempre el id entregado por la API.

Sandbox de pruebas

Antes de tocar produccion, integra contra el sandbox. Tiene las mismas rutas, los mismos campos y las mismas respuestas: cuando termines, cambias la URL base y las credenciales y ya estas en produccion.

URL base del sandbox

Credenciales publicas

Estas credenciales son compartidas y estan aqui a proposito: no tienes que pedirle una cuenta a nadie para empezar.

X-ACI-API-Key: aci_test_S4XKFEANS5PzgCtoflEgKUhrj81QEEnLOAmWYRphUwb6eMV3oW1r5uklLE5EwgYN
X-ACI-Secret-Key: aci_test_secret_Rvv2uXgqZeLJeAJOfPZwNncrWEeSiuo47Rg6qgVQIsTvXXkyadVhdv80LEpKl49pFlJJgbKZ

Probar el acceso

curl --request GET "https://acicolombia.com.co/api/external/sandbox/v1/me" \
  --header "X-ACI-API-Key: aci_test_S4XKFEANS5PzgCtoflEgKUhrj81QEEnLOAmWYRphUwb6eMV3oW1r5uklLE5EwgYN" \
  --header "X-ACI-Secret-Key: aci_test_secret_Rvv2uXgq..." \
  --header "Accept: application/json"

{
  "data": {
    "id": 966,
    "name": "SANDBOX API",
    "environment": "sandbox"
  }
}

Provocar el desenlace

En produccion el resultado lo da la EPS y tarda. En el sandbox lo provocas tu, para poder probar tu webhook sin esperar.

{ "status": "RADICADA" }

{
  "status": "RECHAZADA",
  "rejection_reason": "FALTAN_DOCUMENTOS",
  "rejection_notes": "Falta el documento de identidad."
}

El cambio dispara tu webhook por el mismo camino que en produccion, asi que lo que recibas aqui es exactamente lo que vas a recibir alla.

Empezar de cero

Borra todas tus solicitudes de prueba de una vez, sin esperar los 8 dias.

API key y secret key

Cada usuario genera sus propias credenciales desde Configuracion > Integracion API. Las dos son obligatorias y representan los permisos y el alcance de ese usuario.

Cabeceras obligatorias

X-ACI-API-Key: aci_live_TU_API_KEY
X-ACI-Secret-Key: aci_secret_TU_SECRET_KEY
Accept: application/json
Content-Type: application/json

Comprobar autenticacion

curl --request GET "https://acicolombia.com.co/api/external/v1/me" \
  --header "X-ACI-API-Key: aci_live_TU_API_KEY" \
  --header "X-ACI-Secret-Key: aci_secret_TU_SECRET_KEY" \
  --header "Accept: application/json"

{
  "data": {
    "id": 25,
    "name": "USUARIO INTEGRACION",
    "email": "integracion@empresa.com"
  }
}

Forma de las respuestas

Todo lo que devuelve esta API va envuelto en data. No hay excepciones: ni al crear, ni al consultar, ni en los catalogos. Si tu cliente lee el cuerpo directamente va a encontrar un objeto con una sola llave.

// GET /affiliation-requests/AFI-394900
{ "data": { "id": 394900, "tracking_id": "AFI-394900", ... } }

// GET /catalogs/ips?eps_id=3
{ "data": [ { "id": 1193, "code": "1193", "name": "..." }, ... ],
  "meta": { "total": 1224, "returned": 1224, "truncated": false, "limit": 5000 } }

Con que identificas una afiliacion

Hay tres cosas que la identifican y no sirven para lo mismo:

El campo links

Cada afiliacion trae links.detail, links.status y links.support_pdf ya armados, en el mismo entorno desde el que preguntaste: si consultaste el sandbox, los enlaces son del sandbox.

Armarla a mano es siempre una via valida; la URL es predecible:

https://acicolombia.com.co/api/external/v1/affiliation-requests/{tracking_id|external_id}
https://acicolombia.com.co/api/external/v1/affiliation-requests/{tracking_id|external_id}/status
https://acicolombia.com.co/api/external/v1/affiliation-requests/{tracking_id|external_id}/support-pdf

Catalogos necesarios

Consulta los catalogos antes de construir el formulario. Conserva en cache los resultados y actualizalos periodicamente; las respuestas incluyen cabeceras de cache para evitar llamadas innecesarias.

Como mapear tus catalogos con los nuestros

Es la duda mas frecuente, asi que aqui va completa. Cada catalogo devuelve tres campos y cada uno tiene su oficio:

Los dos que van encadenados

Dos catalogos dependen de otro y no se pueden pedir sueltos con sentido:

• Ciudades: cuelgan del departamento. Pide GET /catalogs/departments, y para cada uno GET /catalogs/cities?department_id={id}. Cada ciudad trae su department_id, asi que tambien puedes pedirlas todas de una vez y agrupar.
• IPS: cuelgan de la EPS y de la ciudad. GET /catalogs/ips?eps_id={id}&city_id={id}. La IPS que mandes tiene que ser de la EPS de la afiliacion; si no, la creacion falla con un error de validacion.

Comprueba que recibiste el catalogo completo

Los catalogos grandes traen la cuenta en meta. Miralo antes de dar tu mapeo por bueno:

{ "data": [ ... ],
  "meta": { "total": 2161, "returned": 2161, "truncated": false, "limit": 5000 } }

Dos avisos sobre el codigo DANE de las ciudades

• El catalogo solo devuelve lo activo. Un municipio que se desactiva desaparece de la lista: si lo tenias mapeado, deja de mandarlo.
• Quedan unas pocas ciudades con un code que no es DANE (empieza por CO-). Son variantes mal escritas que arrastra una importacion vieja y las estamos depurando. Si tu cruce por code no encuentra alguna, es casi seguro una de esas: cruza ese caso por nombre a mano o preguntanos.

Tipos de documento

Estos 6 son los que acepta document_type_id hoy. La tabla se arma leyendo el catalogo, asi que siempre esta completa.

ARL

Las 10 administradoras de riesgos laborales autorizadas para operar el ramo en Colombia. Va en arl_id.

Fondos de pension

Va en pension_fund_id. Si el afiliado no tiene fondo, envia el que aparece como NINGUNO.

EPS

Ejemplo: EPS e IPS

GET https://acicolombia.com.co/api/external/v1/catalogs/eps
GET https://acicolombia.com.co/api/external/v1/catalogs/ips?eps_id=2&city_id=477

Tu identificador externo

Puedes enviar external_id para relacionar la afiliacion con el consecutivo de tu sistema. Es opcional, pero muy recomendado.

• Puede ser texto o numero y admite letras, numeros, punto, guion, guion bajo y dos puntos.
• Longitud maxima: 120 caracteres.
• Es unico dentro de tu usuario.
• Tambien se acepta id como alias, pero recomendamos usar external_id.
• Si repites el mismo valor, la API responde 409 y devuelve la afiliacion existente. No cobra otro credito ni crea un duplicado.

{
  "external_id": "VENTA-2026-000184",
  "eps_id": 2,
  "...": "otros campos"
}

Idempotencia

Si se te cae la red despues de enviar una afiliacion, no sabes si quedo creada. Reintentar a ciegas la crearia dos veces y te cobraria dos creditos. Para eso esta la cabecera Idempotency-Key.

Como se usa

Genera un valor unico por cada solicitud que envias (un UUID sirve) y mandalo en el POST. Si tienes que reintentar, manda el mismo valor.

POST https://acicolombia.com.co/api/external/v1/affiliation-requests
Idempotency-Key: 6f1b7a4e-2c53-4f0b-9a8e-7d1c2b3a4f55
Content-Type: application/json

Limites de uso

Hay un tope de peticiones por minuto. No es contra ti: es para que el consumo de un cliente no deje sin servicio a los demas.

El limite se cuenta por credencial, no por IP: si sales por la misma IP que otro cliente, su consumo no te afecta.

Cuando te pasas

Recibes 429 Too Many Requests con la cabecera Retry-After en segundos. Espera ese tiempo y reintenta; no insistas en bucle.

HTTP/1.1 429 Too Many Requests
Retry-After: 37

Referencia de campos

Datos de la solicitud

Persona principal

Empresa para dependientes

El objeto company es obligatorio cuando contributor_type es DEPENDIENTE y se omite para independientes.

Documentos PDF en base64

Los documentos se envian dentro del objeto documents. Cada archivo debe ser un PDF real, tener una sola pagina y pesar maximo 4 MB una vez decodificado.

"documents": {
  "principal": {
    "file_name": "formulario-afiliacion.pdf",
    "content_base64": "JVBERi0xLjQKJ..."
  },
  "independent_contract": null,
  "withdrawal": null,
  "sat_proof": null,
  "others": []
}

Tambien se acepta el base64 como texto directo o como data URL: data:application/pdf;base64,JVBERi0....

Crear una afiliacion de salud

Ejemplo completo para una persona dependiente sin beneficiarios:

{
  "external_id": "VENTA-2026-000184",
  "request_type": "EPS",
  "eps_id": 2,
  "ips_id": 1365,
  "arl_id": 1,
  "pension_fund_id": 1,
  "affiliation_type": "NUEVO",
  "contributor_type": "DEPENDIENTE",
  "is_sat": false,
  "salary": 2000000,
  "position": "AUXILIAR ADMINISTRATIVO",
  "entry_date": "2026-07-25",
  "person": {
    "document_type_id": 1,
    "document_number": "10101010",
    "first_name": "ANA",
    "middle_name": "MARIA",
    "first_last_name": "PEREZ",
    "second_last_name": "GOMEZ",
    "sex": "FEMENINO",
    "gender_identity": "FEMENINO",
    "birth_date": "1990-02-10",
    "expedition_department_id": 37,
    "expedition_city_id": 477,
    "expedition_date": "2010-03-15",
    "birth_country_id": 1,
    "birth_department_id": 37,
    "birth_city_id": 477,
    "residence_department_id": 37,
    "residence_city_id": 477,
    "address": "CALLE 1 2 3",
    "neighborhood": "CENTRO",
    "residence_type": "URBANA",
    "email": "ana@example.com",
    "phone": "3000000000"
  },
  "company": {
    "document_type_id": 3,
    "document_number": "900000000",
    "business_name": "EMPRESA DEMO SAS",
    "department_id": 37,
    "city_id": 477,
    "address": "AVENIDA 1 2 3",
    "phone": "6010000000",
    "email": "rrhh@example.com",
    "hr_contact": "TALENTO HUMANO"
  },
  "documents": {
    "principal": {
      "file_name": "afiliacion.pdf",
      "content_base64": "JVBERi0xLjQKJ..."
    },
    "others": []
  },
  "beneficiaries": []
}

Variantes del flujo

Afiliado independiente

Usa contributor_type: INDEPENDIENTE, omite company y envia documents.independent_contract cuando el catalogo de la EPS indique requires_independent_contract: true.

Traslado por SAT

{
  "affiliation_type": "TRASLADO",
  "is_sat": true,
  "sat_number": "SAT202607220000000000000001",
  "documents": {
    "principal": { "file_name": "afiliacion.pdf", "content_base64": "JVBERi0..." },
    "sat_proof": { "file_name": "comprobante-sat.pdf", "content_base64": "JVBERi0..." }
  }
}

Inclusion de beneficiarios

Para affiliation_type: INCLUSION debes enviar al menos un beneficiario. Los datos de residencia y contacto se heredan de la persona principal.

"beneficiaries": [
  {
    "relationship": "HIJO",
    "person": {
      "document_type_id": 5,
      "document_number": "10203040",
      "first_name": "JUAN",
      "middle_name": "",
      "first_last_name": "PEREZ",
      "second_last_name": "GOMEZ",
      "sex": "MASCULINO",
      "gender_identity": "MASCULINO",
      "birth_date": "2015-08-20",
      "birth_country_id": 1,
      "birth_department_id": 37,
      "birth_city_id": 477
    },
    "documents": {
      "DOCUMENTO_IDENTIDAD_BENEFICIARIO": {
        "file_name": "identidad.pdf",
        "content_base64": "JVBERi0..."
      },
      "REGISTRO_CIVIL_HIJO": {
        "file_name": "registro-civil.pdf",
        "content_base64": "JVBERi0..."
      }
    }
  }
]

Parentescos aceptados: CONYUGE, ESPOSO, ESPOSA, HIJO, HIJA, PADRE y MADRE. Los soportes requeridos cambian por parentesco y edad.

Respuesta al crear

Una creacion correcta responde 201 Created. Guarda tracking_id, external_id y form_number. El cuerpo viene envuelto en data y el campo de seguimiento es tracking_id, no el id numerico: esta explicado en Forma de las respuestas.

{
  "data": {
    "id": 394900,
    "tracking_id": "AFI-394900",
    "external_id": "VENTA-2026-000184",
    "request_type": "EPS",
    "form_number": "987654324",
    "form_number_source": "EPS_SEQUENCE",
    "status": {
      "id": 8,
      "code": "REVISION_DOCUMENTAL",
      "name": "REVISION DOCUMENTAL"
    },
    "eps": { "id": 2, "code": "SANITAS", "name": "EPS SANITAS" },
    "filing_date": "2026-07-25",
    "links": {
      "detail": "https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184",
      "status": "https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/status",
      "support_pdf": "https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/support-pdf"
    }
  }
}

Consultar estado y detalle

Puedes usar tu external_id, el tracking_id devuelto por ACI o el ID interno numerico.

Respuesta resumida de estado

GET https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/status

Detalle completo

Agrega ?include_documents=1 solamente cuando necesites recibir los documentos en base64. Esto aumenta considerablemente el peso de la respuesta.

El detalle devuelve la persona completa: no solo el nombre y el documento, sino tambien el lugar y la fecha de expedicion, el nacimiento y la residencia. Sirve para comprobar que quedo guardado lo que mandaste.

{
  "data": {
    "tracking_id": "AFI-394900",
    "person": {
      "document_type": "CC",
      "document_number": "1000383537",
      "name": "DANIELA OSPINA ARANGO",
      "first_name": "DANIELA",
      "middle_name": null,
      "first_last_name": "OSPINA",
      "second_last_name": "ARANGO",
      "birth_date": "2000-06-17",
      "sex": "FEMENINO",
      "gender_identity": "FEMENINO",
      "email": "OSPINARANGO6@GMAIL.COM",
      "phone": "3186231240",
      "address": "CARRERA 100 # 50B SUR 45",
      "neighborhood": "CENTRO",
      "expedition_date": "2018-06-17",
      "expedition_department": { "id": 37, "code": "11", "name": "BOGOTA" },
      "expedition_city":       { "id": 477, "code": "11001", "name": "BOGOTA" },
      "birth_country":         { "id": 1, "code": "CO", "name": "COLOMBIA" },
      "birth_department":      { "id": 37, "code": "11", "name": "BOGOTA" },
      "birth_city":            { "id": 477, "code": "11001", "name": "BOGOTA" },
      "residence_department":  { "id": 37, "code": "11", "name": "BOGOTA" },
      "residence_city":        { "id": 477, "code": "11001", "name": "BOGOTA" }
    }
  }
}

Los lugares vienen con la misma forma que eps e ips -id, code y name- o null si no hay dato; nunca a medias. El code de departamentos y ciudades es el DANE, asi que puedes cotejarlo contra tu propio catalogo sin volver a pedir nada.

GET https://acicolombia.com.co/api/external/v1/affiliation-requests/AFI-394900
GET https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184?include_documents=1

Webhooks

Consultar el estado en bucle es caro para los dos. Con un webhook, te avisamos nosotros: cuando una afiliacion tuya queda radicada o rechazada, te llega un POST a la URL que registres, con la causal incluida.

Registrar tu URL

Entra a Configuracion > Integracion API, en el mismo sitio donde generas la API key, y pulsa Registrar webhook. Al guardar se genera un secreto que se muestra una sola vez: guardalo, es con lo que verificas que el aviso viene de nosotros.

Desde ahi mismo puedes mandarte un aviso de prueba para comprobar tu endpoint sin esperar a que se mueva una afiliacion real.

De que te avisamos

Al registrar el webhook eliges el alcance:

Eventos

Que recibes

POST https://tu-sistema.com/webhooks/aci
Content-Type: application/json
X-ACI-Event: affiliation.rejected
X-ACI-Delivery: 4821
X-ACI-Timestamp: 1785443901
X-ACI-Signature: sha256=d6dda0a86b8a7b2eafc7e2b58addd2ee...

{
  "event": "affiliation.rejected",
  "sent_at": "2026-07-30T15:38:17-05:00",
  "environment": "production",
  "data": {
    "id": 420413,
    "external_id": "VENTA-2026-000184",
    "status": "RECHAZADA",
    "status_name": "RECHAZADA",
    "eps": "NUEVA_EPS",
    "document_type": "CC",
    "document_number": "1010101010",
    "form_number": "ACI-420413",
    "filing_date": "2026-07-30",
    "updated_at": "2026-07-30T15:38:17-05:00",
    "rejection": {
      "code": "FALTAN_DOCUMENTOS",
      "reason": "FALTA(N) DOCUMENTO(S)",
      "notes": "Falta el documento de identidad.",
      "refunds_credit": false
    }
  }
}

En affiliation.filed el objeto rejection no viene.

Verificar la firma

No confies en un aviso solo porque llego a tu URL: cualquiera que la conozca puede enviarte uno. La firma es lo que demuestra que es nuestro.

Se calcula asi: HMAC-SHA256( X-ACI-Timestamp + "." + cuerpo_crudo, tu_secreto ). Usa el cuerpo tal como llego, sin volver a serializarlo.

// PHP
$cuerpo = file_get_contents('php://input');
$marca = $_SERVER['HTTP_X_ACI_TIMESTAMP'];
$esperada = 'sha256=' . hash_hmac('sha256', $marca . '.' . $cuerpo, $TU_SECRETO);

if (! hash_equals($esperada, $_SERVER['HTTP_X_ACI_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

// Rechaza tambien lo que venga con mas de 5 minutos, para que nadie
// pueda reenviarte manana un aviso valido de hoy.
if (abs(time() - (int) $marca) > 300) {
    http_response_code(401);
    exit;
}

http_response_code(200);

# Python
import hmac, hashlib, time

def valido(cuerpo: bytes, marca: str, firma: str, secreto: str) -> bool:
    esperada = 'sha256=' + hmac.new(
        secreto.encode(), f'{marca}.'.encode() + cuerpo, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperada, firma) and abs(time.time() - int(marca)) <= 300

Como respondes tu

El historial de envios, con lo que respondio tu servidor, queda en Configuracion > Integracion API.

Causales de rechazo

Cuando una afiliacion se rechaza, el campo rejection.code trae uno de estos valores. refunds_credit indica si te devolvemos el credito.

La lista sale del catalogo, asi que siempre esta al dia. Tambien la puedes consultar con GET /catalogs/rejection-reasons.

Que hacer con las mas comunes

Descargar el PDF soporte

La respuesta es binaria con Content-Type: application/pdf. No intentes interpretarla como JSON. Guarda el cuerpo de la respuesta directamente como archivo.

curl "https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/support-pdf" \
  --header "X-ACI-API-Key: aci_live_TU_API_KEY" \
  --header "X-ACI-Secret-Key: aci_secret_TU_SECRET_KEY" \
  --output soporte-afiliacion.pdf

Listar afiliaciones de salud

GET https://acicolombia.com.co/api/external/v1/affiliation-requests?external_id=VENTA-2026-000184
GET https://acicolombia.com.co/api/external/v1/affiliation-requests?created_from=2026-07-01&created_to=2026-07-31&per_page=50

Consecutivo automatico de Sanitas

• Dos solicitudes simultaneas no reciben el mismo formulario.
• Si la radicacion falla y la transaccion se revierte, el consecutivo no se consume.
• El numero asignado aparece en form_number y el origen en form_number_source: EPS_SEQUENCE.
• El PDF soporte se genera con ese mismo numero.

Ejemplos de codigo

JavaScript en servidor

const response = await fetch('https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/status', {
  headers: {
    'X-ACI-API-Key': process.env.ACI_API_KEY,
    'X-ACI-Secret-Key': process.env.ACI_SECRET_KEY,
    'Accept': 'application/json'
  }
});

if (!response.ok) {
  throw new Error(`ACI respondio ${response.status}: ${await response.text()}`);
}

const result = await response.json();
console.log(result.data.status);

PHP con cURL

$curl = curl_init('https://acicolombia.com.co/api/external/v1/affiliation-requests/VENTA-2026-000184/status');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACI-API-Key: '.getenv('ACI_API_KEY'),
        'X-ACI-Secret-Key: '.getenv('ACI_SECRET_KEY'),
        'Accept: application/json',
    ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status !== 200) {
    throw new RuntimeException($body);
}

$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

Errores y reintentos

Ejemplo 422

{
  "message": "The given data was invalid.",
  "errors": {
    "person.expedition_city_id": [
      "La ciudad de expedicion no pertenece al departamento seleccionado."
    ],
    "salary": [
      "El salario no puede ser menor al salario minimo vigente."
    ]
  }
}