Guía de Uso de la API de Mercado Público / ChileCompra

Documento Técnico de Referencia Unificada Cobertura completa de la API Compra Ágil v2 (Guía de Uso v3.0 - Mayo 2026), API Licitaciones v1 y API Órdenes de Compra v1. Incorpora el mapeo validado de campos y valores observados en pruebas reales contra producción, ejecutadas el 2026-08-20 (detalle en docs/technical/40-api-externa-chilecompra-mercadopublico.md, §11 Anexo de pruebas reales).

Tabla de Contenidos

1. Introducción General y Ecosistema de APIs
2. Primeros Pasos y Autenticación
   • 2.1 Requisitos Previos
   • 2.2 Proceso para Obtener el Ticket de Acceso
   • 2.3 Reglas de Autenticación por Versión de API
   • 2.4 Latencia Observada y Configuración de Timeouts
3. Control de Cuota y Manejo de Rate Limits (HTTP 429)
   • 3.1 Funcionamiento de la Cuota
   • 3.2 Comportamiento al Exceder el Límite (HTTP 429)
   • 3.3 Recomendaciones de Implementación
   • 3.4 Límite de Ráfaga (Burst) y Throttling
4. API Compra Ágil v2 (api2.mercadopublico.cl)
   • 4.1 Endpoints Disponibles
   • 4.2 Parámetros de Consulta (Query Parameters)
   • 4.3 Reglas del Modelo, Estados y Convocatorias
   • 4.4 Referencia de Campos (Esquema JSON Completo)
   • 4.5 Relación entre Compra Ágil y Órdenes de Compra
5. API Licitaciones v1 (api.mercadopublico.cl)
   • 5.1 Endpoints, Formatos y Tipos de Consulta
   • 5.2 Códigos de Estado de Licitaciones
   • 5.3 Catálogos y Anexos de Licitaciones
   • 5.4 Lógica de Valores Binarios (XML/JSON)
   • 5.5 Referencia de Campos (Diccionario de Datos Observado)
6. API Órdenes de Compra v1 (api.mercadopublico.cl)
   • 6.1 Endpoints, Formatos y Tipos de Consulta
   • 6.2 Nomenclatura y Códigos de Estado
   • 6.3 Catálogos y Anexos de Órdenes de Compra
   • 6.4 Referencia de Campos (Diccionario de Datos Observado)
7. Estructura Estándar de Errores HTTP
8. Ejemplos Prácticos de Código (Python & cURL)
   • 8.1 Ver compras publicadas en la última hora (ttl_cambio_ms)
   • 8.2 Sincronización incremental entre dos fechas
   • 8.3 Buscar por palabras clave y región
   • 8.4 Obtener el detalle de una Compra Ágil
   • 8.5 Recorrer todas las páginas de resultados
   • 8.6 Detectar emisión de OC en Compras Ágiles con proveedor seleccionado
   • 8.7 Manejo automatizado del error HTTP 429
9. Glosario de Términos
10. Políticas, Condiciones de Uso y Límites de Responsabilidad
    • 10.1 Uso de la Información
    • 10.2 Límites de Responsabilidad
11. Descarga de Documentos Adjuntos Oficiales
12. Recomendaciones de Integración

1. Introducción General y Ecosistema de APIs

El ecosistema de servicios web de Mercado Público (gestionado por ChileCompra - DCCP) permite a desarrolladores, organismos públicos y ciudadanía acceder de forma estructurada a los procesos de compra del Estado de Chile.

Actualmente existen dos dominios principales según la versión del servicio:

Casos de Uso Principales

• Monitoreo de oportunidades en tiempo real: Detectar contrataciones publicadas en los últimos minutos u horas.
• Sincronización incremental: Mantener bases de datos locales (ej. PostgreSQL) actualizadas descargando únicamente los cambios recientes (ttl_cambio_ms o cambio_desde).
• Búsqueda y analítica: Filtrar por región, estado, palabras clave y montos.
• Transparencia y auditoría: Consultar oferentes, cotizaciones presentadas, proveedores seleccionados y órdenes de compra emitidas.

2. Primeros Pasos y Autenticación

2.1 Requisitos Previos

1. Un Ticket de Acceso válido expedido por ChileCompra.
2. Conexión a Internet desde el entorno donde se ejecuten las solicitudes HTTP.
3. Cliente HTTP (cURL, Python requests, Node.js fetch, Postman, etc.).

2.2 Proceso para Obtener el Ticket de Acceso

El acceso a todas las APIs requiere un ticket (API Key UUID) que identifica al cliente y controla su cuota de consumo diaria.

Pasos oficiales para solicitarlo:

1. Ingrese a https://www.chilecompra.cl/api/ en su navegador.
2. Haga clic en el botón «Pide tu ticket».
3. Acepte los términos y condiciones de uso e inicie sesión con su ClaveÚnica.
4. Complete el formulario de solicitud y seleccione la opción «Solicitar ticket».
5. Recibirá el ticket automáticamente por correo electrónico. (Si no lo encuentra, revise la carpeta de correo no deseado / spam).

[!CAUTION] Guarde el ticket de forma segura. No lo exponga públicamente en clientes front-end ni lo incluya en repositorios públicos.

2.3 Reglas de Autenticación por Versión de API

Toda solicitud HTTP debe incluir el ticket de acceso, pero la forma de enviarlo depende de la versión del servicio. Estas reglas fueron verificadas en pruebas reales contra producción (2026-08-20):

• APIs v1 (Licitaciones / Órdenes de Compra, api.mercadopublico.cl): El ticket se envía únicamente como parámetro de Query String: ?ticket=TU_TICKET.

  [!WARNING] Si el ticket se envía como Header HTTP ticket: en las APIs v1, la API responde HTTP 203 Non-Authoritative Information con cuerpo {"Codigo": 203, "Mensaje": "Ticket no válido."}. En v1 no utilice el header.

• API Compra Ágil v2 (api2): Se envía obligatoriamente en el Header HTTP ticket. Sin este header (o si se intenta por query string), la API responde con error 401 Unauthorized.

Ejemplo de Autenticación en cURL

# v2 (Compra Ágil): ticket en el Header HTTP
curl -H "ticket: TU_TICKET_AQUI" \
  "https://api2.mercadopublico.cl/v2/compra-agil?ttl_cambio_ms=300000"

# v1 (Licitaciones / Órdenes de Compra): ticket en la Query String
curl "https://api.mercadopublico.cl/servicios/v1/publico/licitaciones.json?codigo=2284-24-L125&ticket=TU_TICKET_AQUI"

Ejemplo de Autenticación en Python

import requests

TICKET = 'TU_TICKET_AQUI'
BASE_URL = 'https://api2.mercadopublico.cl'

headers = {'ticket': TICKET}
params = {'ttl_cambio_ms': 300000}

response = requests.get(f'{BASE_URL}/v2/compra-agil', headers=headers, params=params)
print(response.json())

2.4 Latencia Observada y Configuración de Timeouts

Las mediciones reales contra producción (2026-08-20) muestran comportamientos muy distintos entre versiones:

[!WARNING] La API v2 (Compra Ágil) presenta latencias de hasta 20 segundos por la alta carga del API Gateway de ChileCompra. Un timeout por defecto de 10 s provocará fallos intermitentes en producción.

3. Control de Cuota y Manejo de Rate Limits (HTTP 429)

Para garantizar la disponibilidad del servicio, la API implementa un control de cuota diaria por ticket basado en el algoritmo Token Bucket.

3.1 Funcionamiento de la Cuota

• Cuota Diaria: Cada ticket de acceso cuenta con un límite estándar de 10.000 solicitudes diarias, el cual no es modificable.
• Reset Automático: El contador vuelve a cero al cambiar la fecha en zona horaria UTC / medianoche calendario, independientemente de la hora a la que se realizó la primera consulta.
• Cuota Ilimitada: Un valor de -1 en la cuota del ticket indica uso ilimitado (tickets especiales/institucionales).
• Monitoreo por IP: ChileCompra realiza validaciones permanentes por dirección IP, pudiendo establecer restricciones si se detectan solicitudes excesivas desde una misma dirección.

3.2 Comportamiento al Exceder el Límite (HTTP 429)

Cuando el ticket agota su cuota disponible:

• Código de respuesta HTTP: 429 Too Many Requests.
• La API retorna la siguiente estructura JSON:

{
  "success": "NOK",
  "trace": null,
  "payload": null,
  "errors": [
    {
      "codigo": "429",
      "mensaje": "Se ha alcanzado el límite de solicitudes permitido. Intente nuevamente más tarde.",
      "detalle": null
    }
  ]
}

3.3 Recomendaciones de Implementación

1. Captura del Error 429: Implementar el manejo del código 429 en el cliente antes de pasar a producción.
2. Reintento: Si recibe un 429, suspender las peticiones hasta el inicio del siguiente día calendario o consultar el valor del header Retry-After.
3. Descargas Masivas Nocturnas: Para procesos de alta demanda o descarga masiva de información, se recomienda realizar las consultas en horario nocturno (entre las 22:00 y las 07:00 horas).
4. Sincronización Incremental: Optimizar el tráfico utilizando parámetros de cambios (ttl_cambio_ms o cambio_desde) en lugar de consultas masivas repetitivas.

3.4 Límite de Ráfaga (Burst) y Throttling

Además de la cuota diaria, las pruebas reales (2026-08-20) confirmaron un límite de ráfaga: llamadas consecutivas a más de 4 req/seg gatillan HTTP 429 Too Many Requests incluso sin haber agotado la cuota diaria del ticket.

Mitigaciones recomendadas:

1. Throttle entre llamadas: aplicar una pausa de 250 a 500 ms entre solicitudes consecutivas.
2. Rotación de tickets (round-robin): distribuir las solicitudes entre varios tickets válidos para diluir la tasa por ticket (ver Sección 12).

4. API Compra Ágil v2 (api2.mercadopublico.cl)

Compra Ágil es el mecanismo de contratación simplificada de Mercado Público para compras de menor monto. Cada proceso tiene un código único con el formato 1057539-228-COT26.

4.1 Endpoints Disponibles

4.2 Parámetros de Consulta (Query Parameters)

Grupo 1: Ventana de Cambios (Sincronización Incremental)

Define qué registros retornar según modificaciones recientes. Usar Opción A o B (nunca ambas a la vez).

Grupo 2: Fecha de Publicación

Grupo 3: Estado del Proceso

Admite múltiples valores separados por coma (ej: estado=publicada,proveedor_seleccionado).

[!WARNING] Limitación conocida — Filtro por organismo (codigo_organismo):
A diferencia de las APIs v1 de Licitaciones y Órdenes de Compra, la API Compra Ágil v2 NO dispone del parámetro codigo_organismo.
Para obtener datos de un organismo específico, se debe consultar por región (region=) y filtrar posteriormente en cliente/base de datos por institucion.rut o institucion.organismo_comprador.

[!WARNING] Comportamiento real del estado oc_emitida: El valor oc_emitida está contemplado en el modelo de datos pero en la práctica las Compras Ágiles con Orden de Compra emitida se mantienen bajo el estado proveedor_seleccionado. Para detectar si se emitió la OC, consulte el detalle del proceso y verifique si id_orden_compra (campo plano observado en respuestas reales) u orden_compra.id_orden_compra (guía oficial) es distinto de null (ver Sección 4.5).

Grupo 4: Región del Organismo Comprador

Filtra por región (entero de 1 a 16, repetible o separado por comas, ej: region=13,5).

Grupo 5: Búsqueda por Código o Texto Libre

id y q son mutuamente excluyentes (solo se debe enviar uno).

Grupo 6: Paginación

Grupo 7: Ordenamiento

4.3 Reglas del Modelo, Estados y Convocatorias

Reglas de Convocatoria (Llamados)

Una Compra Ágil puede tener un primer o un segundo llamado a cotizar:

• estado: "publicada" + estado_convocatoria: 1 $\rightarrow$ Primer llamado abierto.
• estado: "publicada" + estado_convocatoria: 2 $\rightarrow$ Segundo llamado abierto.
• estado: "cerrada" + estado_convocatoria: 1 $\rightarrow$ Primer llamado cerrado.
• estado: "cerrada" + estado_convocatoria: 2 $\rightarrow$ Segundo llamado cerrado.

Reglas para proveedores_cotizando[]

• El arreglo de proveedores cotizando retorna únicamente las cotizaciones del llamado en el que se encuentra o finalizó la Compra Ágil.
• Si el proceso está en Segundo Llamado, solo se muestran las cotizaciones recibidas en el Segundo Llamado.
• Si no se recibieron ofertas, el campo retorna un arreglo vacío [].
• El detalle completo de cotizaciones se visibiliza a partir del estado Cerrada en el llamado correspondiente.

Mapeo Numérico de Estados (estado.id_estado)

Valores confirmados en respuestas reales de la API v2 (pruebas 2026-08-20):

4.4 Referencia de Campos (Esquema JSON Completo)

Todas las respuestas exitosas de la API v2 tienen el envoltorio:

{
  "success": "OK",
  "trace": null,
  "payload": { ... },
  "errors": null
}

4.4.1 Campos del Listado (payload.items[])

4.4.2 Campos de Paginación (payload.paginacion)

4.4.3 Campos del Detalle (payload)

El endpoint GET /v2/compra-agil/{codigo} entrega los datos completos del proceso:

[!WARNING] Guía oficial vs. comportamiento real — vinculación con la OC: En las respuestas reales observadas (2026-08-20, proceso 2284-520-COT26), la OC vinculada no retorna como objeto anidado orden_compra, sino como el campo plano payload.id_orden_compra (int | null; ej: 55348066). La estructura anidada orden_compra.* se conserva en esta tabla como referencia de la guía oficial; la lógica de detección debe verificar ambas formas:

id_oc = det.get('id_orden_compra') or det.get('orden_compra', {}).get('id_orden_compra')

4.4.4 Productos Solicitados (payload.productos_solicitados[])

4.4.5 Proveedores Cotizando (payload.proveedores_cotizando[])

Contiene las ofertas ingresadas por los proveedores en el llamado correspondiente. Los nombres y tipos de clave fueron validados contra respuestas reales (2026-08-20, proceso 2284-520-COT26: 3 cotizaciones, ganadora "SOC DE INGENIERIA Y SERVICIOS HOGG Y SERRANO LIMITADA", RUT 79.555.420-3, oferta $2.250.000 neto / $2.677.500 total, OC vinculada 55348066):

Detalle de Ítems Cotizados (proveedores_cotizando[].productos_cotizados[])

• codigo_producto (int | string): Código del producto cotizado.
• nombre_producto (string): Nombre del producto.
• descripcion (string | null): Especificación ofertada.
• cantidad (number): Cantidad ofertada.
• precio_unitario (number | null): Precio unitario neto.
• monto_total_producto (number | null): Total neto de la línea (cantidad * precio_unitario).

4.4.6 Resumen, Motivos y Flags

4.5 Relación entre Compra Ágil y Órdenes de Compra

Cuando un organismo adjudica una Compra Ágil, se emite una Orden de Compra (OC). En la API de Compra Ágil v2:

1. Según la guía oficial, orden_compra.id_orden_compra o orden_compra.id_oc tendrá un valor numérico entero (distinto de null).
2. ⚠ Según el comportamiento real observado (2026-08-20), la vinculación retorna como el campo plano payload.id_orden_compra (int | null; ej: 55348066 para el proceso 2284-520-COT26), sin el objeto anidado orden_compra. La lógica de detección debe cubrir ambas formas (ver advertencia en 4.4.3).
3. Para obtener el código textual de la OC (ej: "2284-672-AG26") y su detalle completo, utilice el ID id_orden_compra para consultar la API v1 de Órdenes de Compra (ver Sección 6) o mapearlo contra el listado de transacciones históricas (ver Sección 12).

5. API Licitaciones v1 (api.mercadopublico.cl)

Permite consultar licitaciones públicas y privadas del Estado de Chile.

5.1 Endpoints, Formatos y Tipos de Consulta

Base URL: https://api.mercadopublico.cl/servicios/v1/publico/licitaciones.{formato}

Formatos disponibles: .json, .jsonp, .xml.

Tipos de Consulta HTTP GET

1. Por código exacto de licitación:

   GET /servicios/v1/publico/licitaciones.json?codigo=1509-5-L114&ticket=TU_TICKET
   

2. Licitaciones activas (publicadas el día de hoy):

   GET /servicios/v1/publico/licitaciones.json?estado=activas&ticket=TU_TICKET
   

3. Por fecha específica (formato ddmmaaaa):

   GET /servicios/v1/publico/licitaciones.json?fecha=02022026&ticket=TU_TICKET
   

4. Por estado y fecha específica:

   GET /servicios/v1/publico/licitaciones.json?fecha=02022026&estado=adjudicada&ticket=TU_TICKET
   

5. Por código de organismo público:

   GET /servicios/v1/publico/licitaciones.json?fecha=02022026&CodigoOrganismo=6945&ticket=TU_TICKET
   

6. Por código de proveedor:

   GET /servicios/v1/publico/licitaciones.json?fecha=02022026&CodigoProveedor=17793&ticket=TU_TICKET
   

5.2 Códigos de Estado de Licitaciones

En la respuesta de la API v1, los estados de las licitaciones se representan mediante códigos numéricos:

5.3 Catálogos y Anexos de Licitaciones

5.3.1 Tipos de Licitación

5.3.2 Unidades Monetarias

• CLP: Peso Chileno
• CLF: Unidad de Fomento (UF)
• USD: Dólar Americano
• UTM: Unidad Tributaria Mensual
• EUR: Euro

5.3.3 Monto Estimado

• 1: Presupuesto Disponible
• 2: Precio Referencial

5.3.4 Modalidad de Pago

• 1: Pago a 30 días
• 2: Pago a 30, 60 y 90 días
• 3: Pago al día
• 4: Pago Anual
• 5: Pago a 60 días
• 6: Pagos Mensuales
• 7: Pago Contra Entrega Conforme
• 8: Pago Bimensual
• 9: Pago Por Estado de Avance
• 10: Pago Trimestral

5.3.5 Unidades de Tiempo (Evaluación y Duración de Contrato)

• 1: Horas
• 2: Días
• 3: Semanas
• 4: Meses
• 5: Años

5.3.6 Tipo de Acto Administrativo de Adjudicación

• 1: Autorización
• 2: Resolución
• 3: Otros
• 4: Decreto
• 5: Acuerdo

5.4 Lógica de Valores Binarios (XML/JSON)

Varios campos de la API v1 utilizan codificación binaria/numérica:

5.5 Referencia de Campos (Diccionario de Datos Observado)

Mapeo exhaustivo de las claves de la respuesta JSON, validado contra el proceso real 2284-24-L125 — "INSUMOS CLINICOS DESTINADOS AL AREA DE SALUD MUNICIPAL. SOLICITUD Nº 4646-2025", I MUNICIPALIDAD VALDIVIA (pruebas del 2026-08-20). Los valores "" o null corresponden a estados vacíos observados en ese proceso.

5.5.1 Estructura Raíz de la Respuesta

5.5.2 Objeto Licitación — Identificación y Clasificación (Listado[])

5.5.3 Objeto Comprador (Listado[].Comprador)

5.5.4 Objeto Fechas del Proceso (Listado[].Fechas)

5.5.5 Objeto Adjudicación (Listado[].Adjudicacion)

5.5.6 Ítems Licitados (Listado[].Items.Listado[])

6. API Órdenes de Compra v1 (api.mercadopublico.cl)

Permite consultar las Órdenes de Compra (OC) emitidas en Mercado Público.

6.1 Endpoints, Formatos y Tipos de Consulta

Base URL: https://api.mercadopublico.cl/servicios/v1/publico/ordenesdecompra.{formato}

Formatos: .json, .jsonp, .xml.

Tipos de Consulta HTTP GET

1. Por código exacto de Orden de Compra:

   GET /servicios/v1/publico/ordenesdecompra.json?codigo=2097-241-SE14&ticket=TU_TICKET
   

2. Por fecha específica (formato ddmmaaaa):

   GET /servicios/v1/publico/ordenesdecompra.json?fecha=02022026&ticket=TU_TICKET
   

3. Por todos los estados del día actual:

   GET /servicios/v1/publico/ordenesdecompra.json?estado=todos&ticket=TU_TICKET
   

4. Por estado y fecha específica:

   GET /servicios/v1/publico/ordenesdecompra.json?fecha=02022026&estado=aceptada&ticket=TU_TICKET
   

5. Por código de organismo público:

   GET /servicios/v1/publico/ordenesdecompra.json?fecha=02022026&CodigoOrganismo=6945&ticket=TU_TICKET
   

6. Por código de proveedor:

   GET /servicios/v1/publico/ordenesdecompra.json?fecha=02022026&CodigoProveedor=17793&ticket=TU_TICKET
   

6.2 Nomenclatura y Códigos de Estado

Para filtrar en la URL (?estado=...) se utiliza la nomenclatura textual. En la respuesta JSON/XML los estados se retornan como códigos numéricos:

6.3 Catálogos y Anexos de Órdenes de Compra

6.3.1 Tipos de Orden de Compra

6.3.2 Tipos de Despacho (OC)

• 7: Despachar a Dirección de envío
• 9: Despachar según programa adjuntado
• 12: Otra Forma de Despacho, Ver Instrucción
• 14: Retiramos de su bodega
• 20: Despacho por courier o encomienda aérea
• 21: Despacho por courier o encomienda terrestre
• 22: A convenir

6.3.3 Tipos de Pago (OC)

• 1: 15 días contra la recepción de la factura
• 2: 30 días contra la recepción de la factura
• 39: Otra forma de pago
• 46: 50 días contra la recepción de la factura
• 47: 60 días contra la recepción de la factura
• 48: A 45 días
• 49: A más de 30 días

6.4 Referencia de Campos (Diccionario de Datos Observado)

Mapeo exhaustivo de las claves de la respuesta JSON, validado contra la OC real 2284-672-AG26 — "MEDICAMENTOS BOTIQUIN — SOLICITUD Nº 6346" (Compra Ágil, I MUNICIPALIDAD VALDIVIA → proveedor ECOMCH, $749.700 CLP; pruebas del 2026-08-20). Los valores "" o null corresponden a estados vacíos observados en ese proceso.

6.4.1 Estructura Raíz de la Respuesta

6.4.2 Objeto Orden de Compra — Identificación y Estado (Listado[])

6.4.3 Montos e Impuestos de la OC (Listado[])

6.4.4 Fechas de la Orden de Compra (Listado[].Fechas)

6.4.5 Objeto Comprador (Listado[].Comprador)

6.4.6 Objeto Proveedor (Listado[].Proveedor)

6.4.7 Ítems de la OC (Listado[].Items.Listado[])

7. Estructura Estándar de Errores HTTP

Cuando ocurre un error en cualquier endpoint, la API responde con success: "NOK", payload: null y un arreglo errors[] descriptivo:

{
  "success": "NOK",
  "trace": null,
  "payload": null,
  "errors": [
    {
      "codigo": "401",
      "mensaje": "El ticket no existe, es inválido o no tiene permisos.",
      "detalle": null
    }
  ]
}

Tabla de Códigos de Error HTTP

8. Ejemplos Prácticos de Código (Python & cURL)

8.1 Ver compras publicadas en la última hora (ttl_cambio_ms)

Ideal para bots o procesos daemon que ejecutan polling cada hora.

cURL

curl -H "ticket: TU_TICKET_AQUI" \
  "https://api2.mercadopublico.cl/v2/compra-agil?ttl_cambio_ms=3600000"

Python

import requests

TICKET = 'TU_TICKET_AQUI'
BASE_URL = 'https://api2.mercadopublico.cl'

resp = requests.get(
    f'{BASE_URL}/v2/compra-agil',
    headers={'ticket': TICKET},
    params={'ttl_cambio_ms': 3_600_000}
)
data = resp.json()

for item in data['payload']['items']:
    print(item['codigo'], '|', item['nombre'], '|', item['estado']['glosa'])

8.2 Sincronización incremental entre dos fechas

Útil para mantener sincronizada una base de datos local desde el último timestamp procesado.

cURL

curl -H "ticket: TU_TICKET_AQUI" \
  "https://api2.mercadopublico.cl/v2/compra-agil?cambio_desde=2026-04-01T00:00:00Z&cambio_hasta=2026-04-02T00:00:00Z&ordenar_por=FechaUltimaModificacion"

Python

import requests
from datetime import datetime, timezone, timedelta

TICKET = 'TU_TICKET_AQUI'
BASE = 'https://api2.mercadopublico.cl'

ahora = datetime.now(timezone.utc)
hace_un_dia = ahora - timedelta(days=1)

resp = requests.get(
    f'{BASE}/v2/compra-agil',
    headers={'ticket': TICKET},
    params={
        'cambio_desde': hace_un_dia.strftime('%Y-%m-%dT%H:%M:%SZ'),
        'cambio_hasta': ahora.strftime('%Y-%m-%dT%H:%M:%SZ'),
        'ordenar_por': 'FechaUltimaModificacion'
    }
)
print('Paginación:', resp.json()['payload']['paginacion'])

8.3 Buscar por palabras clave y región

Busca Compras Ágiles de "materiales eléctricos" en la Región Metropolitana (13) abiertas o adjudicadas.

cURL

curl -H "ticket: TU_TICKET_AQUI" \
  "https://api2.mercadopublico.cl/v2/compra-agil?q=materiales%20electricos&region=13&estado=publicada,proveedor_seleccionado"

Python

import requests

TICKET = 'TU_TICKET_AQUI'
BASE = 'https://api2.mercadopublico.cl'

resp = requests.get(
    f'{BASE}/v2/compra-agil',
    headers={'ticket': TICKET},
    params={
        'q': 'materiales electricos',
        'region': 13,
        'estado': 'publicada,proveedor_seleccionado'
    }
)

items = resp.json()['payload']['items']
print(f'Resultados encontrados: {len(items)}')
for item in items:
    monto = item['montos']['monto_disponible_clp']
    print(f" - {item['codigo']} | {item['nombre']} | ${monto:,.0f} CLP")

8.4 Obtener el detalle de una Compra Ágil

cURL

curl -H "ticket: TU_TICKET_AQUI" \
  "https://api2.mercadopublico.cl/v2/compra-agil/1195-39-COT26"

Python

import requests

TICKET = 'TU_TICKET_AQUI'
BASE = 'https://api2.mercadopublico.cl'
codigo = '1195-39-COT26'

resp = requests.get(
    f'{BASE}/v2/compra-agil/{codigo}',
    headers={'ticket': TICKET}
)
ca = resp.json()['payload']

print(f"Nombre       : {ca['nombre']}")
print(f"Estado       : {ca['estado']['glosa']}")
print(f"Institución  : {ca['institucion']['organismo_comprador']}")
print(f"Presupuesto  : ${ca['presupuesto']['monto_disponible_clp']:,} {ca['presupuesto']['moneda']}")
print(f"Productos    : {len(ca['productos_solicitados'])}")
print(f"Cotizaciones : {len(ca['proveedores_cotizando'])}")

8.5 Recorrer todas las páginas de resultados

Script completo para iterar sobre todas las páginas devueltas por la paginación de la API.

import requests

TICKET = 'TU_TICKET_AQUI'
BASE = 'https://api2.mercadopublico.cl'

params = {
    'publicado_desde': '2026-04-01T00:00:00Z',
    'publicado_hasta': '2026-04-02T23:59:59Z',
    'tamano_pagina': 50,
    'numero_pagina': 1
}

todos_los_items = []

while True:
    resp = requests.get(
        f'{BASE}/v2/compra-agil',
        headers={'ticket': TICKET},
        params=params
    )
    payload = resp.json()['payload']
    paginacion = payload['paginacion']
    
    todos_los_items.extend(payload['items'])
    print(f"Página {paginacion['numero_pagina']} de {paginacion['total_paginas']}")
    
    if paginacion['numero_pagina'] >= paginacion['total_paginas']:
        break
        
    params['numero_pagina'] += 1

print(f'Total descargado: {len(todos_los_items)} registros')

8.6 Detectar emisión de OC en Compras Ágiles con proveedor seleccionado

Como la API no retorna el estado textual oc_emitida en las búsquedas masivas, este script consulta los procesos en proveedor_seleccionado y revisa el detalle individual para separar aquellos que ya cuentan con Orden de Compra emitidamente vinculada (id_orden_compra no nulo).

import requests

TICKET = 'TU_TICKET_AQUI'
BASE = 'https://api2.mercadopublico.cl'

params = {
    'estado': 'proveedor_seleccionado',
    'tamano_pagina': 50,
    'numero_pagina': 1
}

con_oc = [] # Tienen OC emitida
sin_oc = [] # Proveedor seleccionado, pero OC aún pendiente

while True:
    resp = requests.get(f'{BASE}/v2/compra-agil', headers={'ticket': TICKET}, params=params)
    payload = resp.json()['payload']
    paginacion = payload['paginacion']
    
    for item in payload['items']:
        det_resp = requests.get(
            f"{BASE}/v2/compra-agil/{item['codigo']}",
            headers={'ticket': TICKET}
        )
        det = det_resp.json()['payload']
        # Verificar ambas formas: campo plano (observado) y objeto anidado (guía oficial)
        id_oc = det.get('id_orden_compra') or det.get('orden_compra', {}).get('id_orden_compra')
        
        if id_oc is not None:
            con_oc.append({'codigo': item['codigo'], 'id_orden_compra': id_oc})
        else:
            sin_oc.append(item['codigo'])
            
    if paginacion['numero_pagina'] >= paginacion['total_paginas']:
        break
    params['numero_pagina'] += 1

print(f'Con OC emitida : {len(con_oc)}')
print(f'Sin OC emitida : {len(sin_oc)}')

for ca in con_oc:
    print(f"  {ca['codigo']} -> id_orden_compra={ca['id_orden_compra']}")

8.7 Manejo automatizado del error HTTP 429

Función de envoltura en Python para gestionar inteligentemente la cuota diaria consumida:

import requests
from datetime import datetime, timezone, timedelta

def consultar_compra_agil_segura(url, ticket, params=None):
    headers = {'ticket': ticket}
    resp = requests.get(url, headers=headers, params=params)
    
    if resp.status_code == 429:
        ahora = datetime.now(timezone.utc)
        proxima_medianoche = (ahora + timedelta(days=1)).replace(hour=0, minute=1, second=0, microsecond=0)
        espera_seg = int((proxima_medianoche - ahora).total_seconds())
        
        print(f"[HTTP 429] Cuota diaria agotada. Reintento en {espera_seg // 3600} horas ({espera_seg} segundos).")
        raise Exception("Cuota diaria de API sobrepasada. Reintentar mañana.")
        
    resp.raise_for_status()
    return resp.json()

9. Glosario de Términos

10. Políticas, Condiciones de Uso y Límites de Responsabilidad

10.1 Uso de la Información

1. Niveles de Servicio: Los niveles de servicio de la API de Mercado Público se definen conforme a los estándares establecidos por la Dirección ChileCompra.
2. Obtención del Ticket: El acceso a la API se realiza mediante un ticket, el cual debe ser solicitado a través del formulario disponible en la web oficial de ChileCompra, seleccionando la opción “Solicitud de Ticket”.
3. Identificación Única por Persona: El formulario debe ser completado con datos reales de la persona solicitante (nombre y apellido, RUT y correo electrónico), ya que se entrega un único ticket por persona. Si la Dirección ChileCompra detecta inconsistencias en la información proporcionada, podrá limitar o suspender el acceso asociado a dicho ticket.
4. Protección y Privacidad de Datos: ChileCompra utilizará estos datos personales únicamente para fines de operación, control y administración del servicio de la API de Mercado Público, y no los compartirá con terceros, salvo por mandato judicial.
5. Monitoreo y Control por Dirección IP: El funcionamiento y uso de la API es monitoreado de forma permanente por la Dirección ChileCompra para asegurar su correcto uso y estabilidad. Este monitoreo incluye validaciones por dirección IP, pudiendo establecerse restricciones de acceso según la cantidad de solicitudes realizadas desde una misma IP.
6. Canal Oficial de Soporte: El soporte para el uso de la API debe solicitarse exclusivamente a través del formulario de sugerencias disponible en el sitio web oficial de ChileCompra. Todas las consultas y solicitudes serán respondidas en un plazo máximo de 3 días hábiles. No se considerarán solicitudes informales ni aquellas enviadas directamente a correos institucionales. No existen otros canales de soporte distintos a los señalados en estas Políticas y Condiciones.
7. Límite Diario Inflexible: Cada ticket de acceso cuenta con un límite diario de 10.000 solicitudes. Este límite no es modificable y tiene como finalidad resguardar la estabilidad del servicio. Las personas usuarias se comprometen a no exceder ni eludir estas limitations. El uso excesivo o abusivo de la API podrá derivar en la suspensión temporal o el bloqueo permanente del acceso.
8. Horario Recomendado para Descargas Masivas: Para procesos de alta demanda o descarga masiva de información, se recomienda realizar las consultas en horario nocturno, entre las 22:00 y las 07:00 horas.

10.2 Límites de Responsabilidad

1. Carácter Voluntario del Servicio: La API de Mercado Público es un servicio adicional que ChileCompra pone a disposición de manera voluntaria. Su uso no genera derechos adquiridos para las personas usuarias, por lo que ChileCompra podrá modificar, suspender o dar término al servicio cuando lo estime pertinente.
2. Actualización de Políticas: ChileCompra podrá actualizar estas Políticas y Condiciones de Uso en cualquier momento, manteniendo siempre disponible la versión vigente en su sitio web.
3. Desarrollos e Integraciones de Terceros: La Dirección ChileCompra no se hace responsable de la información publicada por las personas usuarias a través de las aplicaciones o sistemas que desarrollen utilizando la API, ni de los proyectos, actividades comerciales o cobros asociados a dichos desarrollos.
4. Atribución Obligatoria de la Fuente: Las personas usuarias que publiquen información obtenida desde la API de Mercado Público, sin modificarla, deberán indicar claramente que la fuente de los datos es la Dirección ChileCompra.

11. Descarga de Documentos Adjuntos Oficiales

Diagnóstico de factibilidad (pruebas del 2026-08-20) para descargar los archivos binarios (PDFs) referenciados en el arreglo documentos de Compra Ágil (IDs 1774796 y 1774797):

1. API Pública Oficial (api.mercadopublico.cl y api2.mercadopublico.cl):
   • La API oficial no provee endpoints de descarga directa de archivos binarios.
   • Solo retorna los metadatos descriptivos (id numérico y nombre del archivo).
   • Los endpoints no documentados retornan HTTP 403 Forbidden o HTTP 404 Not Found.
2. Portal Web Tradicional (www.mercadopublico.cl):
   • Las rutas tradicionales de descarga (/Procurement/Modules/RFQ/DownloadAttachment.aspx) devuelven una redirección HTTP 302 al formulario de inicio de sesión (/portal/login.aspx), exigiendo una sesión web activa autenticada con ClaveÚnica.
3. Buscador Moderno (buscador.mercadopublico.cl):
   • La interfaz web delega la descarga en un microservicio interno (adjunto.mercadopublico.cl/adjunto-compra-agil/v1/adjuntos-compra-agil/) que requiere un flujo de cifrado (/encrypt/) y autenticación cerrada por tokens de sesión dinámica y CloudFront.

[!IMPORTANT] Conclusión: la plataforma de ChileCompra no permite la descarga programática sencilla de los adjuntos a través de la API con ticket. Para que los usuarios consulten los documentos originales, la mejor alternativa es proveer el enlace directo a la ficha pública del proceso en el buscador oficial: https://buscador.mercadopublico.cl/ficha?code={codigo}.

12. Recomendaciones de Integración

Prácticas derivadas de las pruebas reales del 2026-08-20 para integrar el ecosistema completo de APIs:

1. Timeouts diferenciados por versión:
   • v1 (api.mercadopublico.cl): 5 a 10 segundos es suficiente (ver 2.4).
   • v2 (api2.mercadopublico.cl): configurar un mínimo de 30 a 40 segundos por la alta carga del API Gateway de ChileCompra.
2. Estrategia de autenticación según versión: implementar un helper unificado fetchMercadoPublico(tipo, codigo) que:
   • Inyecte ?ticket={TICKET} en la URL para v1 (licitaciones y ordenesdecompra).
   • Inyecte headers: { ticket: TICKET } para v2 (compra-agil).
3. Pool y rotación de tickets (round-robin): distribuir las solicitudes entre los tickets disponibles (MERCADO_PUBLICO_TICKET) para repartir la cuota diaria y reducir la probabilidad de bloqueos por ráfaga (HTTP 429; ver 3.4).
4. Mapeo de Compra Ágil a Orden de Compra: la API v2 entrega id_orden_compra numérico (ej: 55348066). Para mostrar al usuario el código textual correlativo (ej: "2284-672-AG26") y el enlace al detalle, se debe relacionar contra el listado de transacciones históricas o la API v1 de Órdenes de Compra.
5. Documentos adjuntos: dado que no existe descarga programática (ver Sección 11), enlazar siempre a la ficha pública https://buscador.mercadopublico.cl/ficha?code={codigo}.