Supersubsidio: afiliaciones a cajas de compensación

Todo empleador formal en Colombia afilia a sus trabajadores a una Caja de Compensación Familiar (CCF) y paga cada mes un aporte sobre su nómina. La Superintendencia del Subsidio Familiar, que vigila las cajas, lleva el historial de afiliación de todas ellas. Este endpoint devuelve el historial de una persona en los últimos cuatro años, mes a mes, con la caja y la empresa que la afilió: una vista de su empleo formal, que entidades de crédito, empleadores y equipos de verificación de antecedentes usan para confirmar dónde trabaja y dónde ha trabajado alguien. Necesita el número de documento, el primer apellido y la fecha de nacimiento de la persona, y conserva una copia del PDF del reporte. POST /co/ssf/affiliation-history/v1 Live Una persona, por tres datos que deben coincidir todos con el registro. No hace falta indicar la caja: todas las cajas llegan en una sola consulta.

Campo	Tipo	Notas
`document_number`	string	Obligatorio. La cédula de ciudadanía de la persona, solo dígitos.
`first_surname`	string	Obligatorio. El primer apellido exactamente como en el registro. No distingue mayúsculas de minúsculas.
`birth_date`	string	Obligatorio. Fecha de nacimiento, `aaaa-mm-dd`.

curl https://api.croma.run/co/ssf/affiliation-history/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "document_number": "1234567890",
        "first_surname": "PEREZ",
        "birth_date": "1990-01-01"
      }'

La respuesta repite el número de documento y trae el historial de la persona:

Campo	Notas
`found`	`false` cuando ninguna persona coincide a la vez con el número de documento, el primer apellido y la fecha de nacimiento. Un apellido o una fecha que no coinciden con el registro responden igual que un documento desconocido.
`full_name`, `document_type`	La persona, como aparece en el reporte.
`affiliate_type`	El tipo de afiliado (dependiente, por ejemplo), como aparece impreso. El reporte puede cortar este texto.
`affiliations`	Una fila por mes, caja y empresa, de la más antigua a la más reciente, en los últimos cuatro años registrados: `period` (`aaaa-mm`), `fund` (la Caja de Compensación Familiar) y `employer` (`null` cuando el reporte no nombra ninguna). Un mes con dos empleadores tiene dos filas, y el historial cubre todas las cajas a las que estuvo afiliada la persona.
`document_url`	Nuestra copia del PDF del historial de afiliación, idéntica byte a byte a la que expidió la fuente.
`source_document_url`	Siempre `null`: la fuente expide el reporte al consultarlo y no publica un enlace a él.

El reporte orienta la solicitud de un certificado; no es una certificación oficial. Para un certificado de afiliación, o para historial de más de cuatro años, acuda a la Caja de Compensación Familiar o a la Superintendencia del Subsidio Familiar.

Conservar el PDF del reporte toma un momento, así que esta consulta es un trabajo asíncrono. Por defecto la solicitud espera en línea y devuelve { data }, o puedes hacer polling o enviar un callback_url. La mayoría de las consultas terminan en unos segundos.

Referencia completa

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

Primeros pasos

Tipos de solicitud

Monitores

Comentarios

Países

Supersubsidio: afiliaciones a cajas de compensación

Referencia completa