Seguridad Social

Servicio para consultar la información de seguridad social de una persona en Colombia. Retorna información personal y el historial de aportes a seguridad social.

POST /validate/social-security HTTP/1.1
HOST: {{api_auco}}
Authorization: {{private_key}}

info

Este servicio usa la llave privada de la compañía

Solo disponible para Colombia

Este servicio está disponible únicamente para consultas de seguridad social en Colombia. Los tipos de documento aceptados son Cédula de Ciudadanía (CC) y Cédula de Extranjería (CE) colombianas.

Nombre	Descripción
email String	Obligatorio. Correo electrónico del creador del proceso. Este correo debe estar registrado en la plataforma de Auco y debe pertenecer a la compañía.
type String	Obligatorio. Tipo de documento de identidad. Valores aceptados: CC, CE
identification String	Obligatorio. Número de documento de identidad a consultar.

🧪 Ejemplos de uso

Curl

curl -X POST '{{api_auco}}/validate/social-security' \
  -H 'Authorization: {{private_key}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "usuario@empresa.com",
    "type": "CC",
    "identification": "123456781"
  }'

Python

import requests

response = requests.post(
  '{{api_auco}}/validate/social-security',
  headers={
    'Authorization': '{{private_key}}',
    'Content-Type': 'application/json'
  },
  json={
    "email": "usuario@empresa.com",
    "type": "CC",
    "identification": "123456781"
  }
)
print(response.json())

Node.js

const axios = require('axios');

axios.post('{{api_auco}}/validate/social-security', {
  email: 'usuario@empresa.com',
  type: 'CC',
  identification: '123456781'
}, {
  headers: {
    Authorization: '{{private_key}}',
    'Content-Type': 'application/json'
  }
})
.then((response) => console.log(response.data));

📥 Estructura de respuesta

Campos principales

Campo	Tipo	Descripción
code	String	Código único de la validación generada
documentType	String	Tipo de documento consultado
documentNumber	String	Número de documento consultado
personalInfo	Object	Información personal del titular
contributionPeriods	Array	Lista de periodos de aportes a seguridad social

Objeto personalInfo

Campo	Tipo	Descripción
firstName	String	Primer nombre
middleName	String	Segundo nombre
lastName	String	Primer apellido
secondLastName	String	Segundo apellido

Objeto contributionPeriods[]

Campo	Tipo	Descripción
period	String	Periodo de aporte en formato YYYYMM
baseIncome	Number	Ingreso base de cotización en COP
employer	Object	Información del empleador o aportante
contributorType	Object	Tipo de cotizante
monthsWithEmployer	Number	Meses acumulados con el empleador
hasChange	Boolean	Indica si hubo cambio de empleador en este periodo
lastChangeDate	String	Fecha del último cambio de empleador (YYYYMM o null)

Objeto employer

Campo	Tipo	Descripción
name	String	Nombre o razón social del empleador
documentType	String	Tipo de documento (NI = NIT, CC = Cédula)
documentNumber	String	Número de documento del empleador

Objeto contributorType

Campo	Tipo	Descripción
code	String	Código del tipo de cotizante
description	String	Descripción del tipo de cotizante

Tipos de cotizante comunes

Código	Descripción
1	Dependiente
3	Independiente
57	Independiente voluntario al Sistema de Riesgos Laborales
59	Independiente con contrato de prestación de servicios mayor a 1 mes

📥 Ejemplos de respuesta

200: Consulta exitosa

{
  "code": "VAL1234ABC",
  "documentType": "CC",
  "documentNumber": "1000000001",
  "personalInfo": {
    "firstName": "JUAN",
    "middleName": "CARLOS",
    "lastName": "GARCIA",
    "secondLastName": "MARTINEZ"
  },
  "contributionPeriods": [
    {
      "period": "202501",
      "baseIncome": 3000000,
      "employer": {
        "name": "EMPRESA EJEMPLO SAS",
        "documentType": "NI",
        "documentNumber": "900123456"
      },
      "contributorType": {
        "code": "1",
        "description": "Dependiente"
      },
      "monthsWithEmployer": 18,
      "hasChange": false,
      "lastChangeDate": null
    }
  ]
}

400: Usuario no encontrado

{
  "message": "USER_NOTFOUND"
}

400: Documento no encontrado

{
  "message": "SOCIAL_SECURITY_NOT_FOUND"
}

400: Servicio no disponible

{
  "message": "SOCIAL_SECURITY_SERVICE_ERROR"
}

⚠️ Respuestas de error

Código	Mensaje	Descripción
400	USER_NOTFOUND	El email no existe en la compañía.
400	SOCIAL_SECURITY_NOT_FOUND	No se encontró información de seguridad social para el documento.
400	SOCIAL_SECURITY_SERVICE_ERROR	El servicio de seguridad social no se encuentra disponible temporalmente.
401	-	Autenticación inválida o ausente.

🧪 Datos de prueba (Ambiente de desarrollo)

Para pruebas en ambiente de desarrollo, se pueden usar los siguientes documentos:

Documento	Tipo	Descripción
1000000001	CC	Empleado dependiente con historial estable
1000000002	CC	Independiente con cambio a dependiente
1000000003	CC	Múltiples cambios de empleador

ℹ️ Notas adicionales

• El servicio retorna el historial de aportes de los últimos 12 meses aproximadamente.
• Un mismo periodo puede tener múltiples registros si la persona tiene varios empleadores o tipos de aporte simultáneos.
• El campo hasChange indica si en ese periodo específico hubo un cambio de empleador.
• El campo monthsWithEmployer representa la antigüedad acumulada con ese empleador específico.
• El email debe corresponder a un usuario activo de la compañía.