API del SECOP II: contratación pública de un proveedor por NIT

Qué problema resuelve

Antes de contratar a un proveedor conviene saber si ya le ha contratado al Estado, a quién y por cuánto. Ese dato es público y está en el SECOP II, pero consultarlo significa navegar un portal de búsqueda y sumar contratos a mano, uno por uno. Este endpoint entrega el histórico ya agregado: el total contratado sale calculado del lado de la fuente, no de recorrer filas.

Para quién sirve

Equipos de compras y cumplimiento que verifican proveedores, periodistas y veedurías que rastrean contratación pública, fintechs que evalúan flujo de un contratista del Estado, y cualquier área de riesgo que arme una debida diligencia.

Datos requeridos

• documento — NIT o cédula del proveedor, solo dígitos. Es la vía exacta.
• nombre — alternativa: nombre o razón social del proveedor, búsqueda parcial.
• estado — opcional: filtra por En ejecución, Terminado, Cerrado, Cancelado o Modificado.
• offset — opcional, para paginar de 50 en 50.

Fuentes y cobertura

• SECOP II — Colombia Compra EficienteContratos electrónicos del Sistema Electrónico de Contratación Pública: entidad, NIT de la entidad, objeto, tipo de contrato, modalidad, estado, valor, valor pagado, valor pendiente, fechas y enlace al proceso.

¿Cómo saber cuántos contratos tiene una empresa con el Estado?

Con una llamada POST a /api/secop enviando el NIT en el campo documento. El objeto resumen trae totalContratos y valorTotal calculados sobre el histórico completo del proveedor, no sobre la página devuelta.

¿Se puede consultar el SECOP por cédula de una persona natural?

Sí. El campo documento acepta tanto NIT de empresa como cédula de persona natural: en el SECOP los contratistas personas naturales están identificados por su cédula.

Ejemplo de solicitud

POST https://placapi.com/api/secop. Autenticación por API key en el header x-api-key. Los datos del ejemplo son ficticios.

curl -X POST 'https://placapi.com/api/secop' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"documento":"900123456"}'

Ejemplo de respuesta

Respuesta JSON (fragmento con los campos de esta consulta; la API integral devuelve todas las fuentes en el mismo objeto).

{
  "source": "contratacion-estatal",
  "status": "info",
  "data": {
    "proveedor": {
      "nombre": "CONSTRUCTORA DE EJEMPLO S.A.S.",
      "documento": "900123456",
      "tipoDocumento": "NIT"
    },
    "resumen": {
      "tieneContratos": true,
      "totalContratos": 21,
      "valorTotal": 491032542,
      "totalEntidades": 4,
      "porEstado": {
        "En ejecución": 3,
        "Terminado": 18
      },
      "primerContrato": "2019-04-02",
      "ultimoContrato": "2026-06-18"
    },
    "contratos": [
      {
        "entidad": "GOBERNACIÓN DE EJEMPLO",
        "objeto": "Prestación de servicios profesionales",
        "modalidad": "Contratación directa",
        "estado": "En ejecución",
        "valorContrato": 16000000,
        "valorPagado": 8000000,
        "fechaFirma": "2026-02-01"
      }
    ]
  }
}

Explicación campo por campo

Limitaciones y posibles errores

• Cubre el SECOP II. La contratación anterior a su adopción, que vive en el SECOP I, no está en esta fuente.
• Devuelve hasta 50 contratos por página; los proveedores grandes del Estado tienen miles y hay que paginar con offset.
• El total de entidades distintas es una cota inferior, porque la fuente lo cuenta por grupo de estado.
• Un proveedor sin contratos responde 200 con totalContratos en 0. Esa respuesta cobra: es el dato que se vino a comprobar.

Códigos de error del endpoint (401, 402, 429, 5xx) en la referencia de errores.

Otras preguntas frecuentes

Seguir explorando

• API del RUES: registro mercantil→
• API de bienes y rentas→
• API de procesos judiciales→
• API de antecedentes judiciales→
• Documentación e integración→