Endpoint: contratación estatal (SECOP II)

Devuelve los contratos de una persona o una empresa con el Estado colombiano según el SECOP II de Colombia Compra Eficiente. Se busca por documento o por nombre del proveedor, y el documento manda si llegan los dos. La respuesta trae un resumen agregado sobre el histórico completo —total de contratos, valor contratado, valor pagado, entidades distintas y conteo por estado— y una página de hasta 50 contratos con entidad, objeto, modalidad, valores y fechas.

POST/api/secop1 crédito

Contratos de una persona o una empresa con el Estado colombiano, del SECOP II de Colombia Compra Eficiente. Se busca por `documento` (NIT o cédula) o por `nombre` del proveedor; el documento manda si llegan los dos. Devuelve un **resumen agregado sobre el histórico completo** —total de contratos, valor contratado, valor pagado, entidades distintas y conteo por estado— y una página de hasta 50 contratos con entidad, objeto, modalidad, valores y fechas. Es la respuesta a "¿este proveedor ya le ha contratado al Estado, a quién y por cuánto?", el dato que se pide en una debida diligencia. **Sin contratos también responde 200 con datos y cobra**: "no ha contratado con el Estado" es exactamente lo que se vino a comprobar. Cuesta 1 crédito.

Cuerpo de la solicitud

body (JSON)
{
  "documento": "900123456"
}
Parámetros del cuerpo de la solicitud
CampoTipoQué es
documentostringNIT o cédula del proveedor, solo dígitos y sin el dígito de verificación. Se requiere `documento` o `nombre`; si llegan los dos manda este, que identifica sin ambigüedad. Alias aceptados: `doc` y `nit`.
nombrestringNombre o razón social del proveedor, o parte de ella (búsqueda parcial, sin distinguir mayúsculas). Útil cuando no se tiene el NIT. Mínimo 3 caracteres.
estadostringFiltra por el estado del contrato tal como lo publica la fuente: `En ejecución`, `Terminado`, `Cerrado`, `Cancelado`, `Modificado`. Sin este parámetro vienen todos.
offsetnumberPaginación en filas, no en número de página (0, 50, 100…). Cada página trae hasta 50 contratos; `paginacion.hayMas` dice si vale la pena pedir la siguiente.
refreshbooleanIgnora la caché y vuelve a consultar la fuente oficial. Ojo: una consulta refrescada con datos siempre cobra (el hit de caché no).

Ejemplos por lenguaje

cURL
curl -X POST 'https://placapi.com/api/secop' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"documento":"900123456"}'
JavaScript (fetch)
const res = await fetch("https://placapi.com/api/secop", {
  method: "POST",
  headers: {
    "x-api-key": "pk_live_TU_CLAVE",
    "content-type": "application/json",
  },
  body: JSON.stringify({"documento":"900123456"}),
});
const data = await res.json();
Python (requests)
import requests

res = requests.post(
    "https://placapi.com/api/secop",
    headers={"x-api-key": "pk_live_TU_CLAVE"},
    json={"documento":"900123456"},
)
data = res.json()

Respuesta exitosa

200 OK — datos ficticios de ejemplo
{
  "source": "contratacion-estatal",
  "status": "info",
  "data": {
    "proveedor": {
      "nombre": "CONSTRUCTORA EJEMPLO S.A.S.",
      "documento": "900123456",
      "tipoDocumento": "NIT"
    },
    "resumen": {
      "tieneContratos": true,
      "totalContratos": 21,
      "valorTotal": 491032542,
      "valorPagado": 305118000,
      "totalEntidades": 4,
      "porEstado": {
        "En ejecución": 3,
        "Terminado": 18
      },
      "primerContrato": "2019-04-02",
      "ultimoContrato": "2026-06-18"
    },
    "contratos": [
      {
        "id": "CO1.PCCNTR.4168447",
        "referencia": "CPS-3548-2022",
        "entidad": "GOBERNACIÓN DEL QUINDÍO",
        "nitEntidad": "890000464",
        "objeto": "Prestación de servicios profesionales para la interventoría de la obra",
        "tipoContrato": "Prestación de servicios",
        "modalidad": "Contratación directa",
        "estado": "En ejecución",
        "valorContrato": 16000000,
        "valorPagado": 8000000,
        "valorPendiente": 8000000,
        "fechaFirma": "2026-02-01",
        "fechaInicio": "2026-02-05",
        "fechaFin": "2026-12-31",
        "departamento": "Quindío",
        "ciudad": "Armenia",
        "urlProceso": "https://community.secop.gov.co/Public/Tendering/OpportunityDetail/Index?noticeUID=CO1.NTC.0000"
      }
    ],
    "paginacion": {
      "offset": 0,
      "limit": 50,
      "hayMas": false
    }
  },
  "mode": "live",
  "fetchedAt": "2026-07-24T15:04:05.000Z",
  "cost": 1
}

Errores y cobro

Cuesta 1 crédito cuando devuelve datos. Códigos posibles: 400 401 402 404 429 500 502 — qué significa cada uno, cuál reintentar y cuál cobra, en errores y rate limits. Autenticación por x-api-key: cómo generar la clave.

Última revisión: 23 de agosto de 2026 · PlacApi opera desde Colombia. PlacApi no es una entidad oficial del Gobierno.

Contacto