# Convenciones ## URL base y formato Todas las rutas cuelgan de `https://pricto.dev/v1`. Las respuestas son JSON con `data` (el resultado), `meta` (costo, fuente, idioma, moneda, avisos) y, en las listas, `pagination`. Los campos nuevos se agregan sin aviso: ignora los que no conozcas. ## Paginación Por cursor. Si `pagination.has_more` es `true`, pide la página siguiente con `cursor=` y los mismos filtros. `limit` tiene un máximo por endpoint (20 en búsqueda). ```json { "pagination": { "has_more": true, "next_cursor": "eyJvIjoyfQ" } } ``` ## Filtros comunes | Parámetro | Qué filtra | Ejemplo | |---|---|---| | `country` | País, ISO 3166-1 | `CL` | | `retailer` | Una o más tiendas, separadas por coma | `cl-jumbo,cl-unimarc` | | `category` | Categoría, incluye subcategorías | `food.dairy` | | `brand` | Marca, por id o nombre | `colun` | | `location` | Comuna, `CL:` o tienda, en tiendas que cambian precio por ubicación | `Las Condes` | | `as_of` | Precios vigentes en una fecha pasada | `2026-10-01` | | `from`, `to`, `interval` | Rango e intervalo del historial | `interval=week` | | `min_confidence`, `match_kinds` | Qué ofertas se agrupan con el producto (ver [Modelo de datos](/docs/modelo-de-datos#match)) | `identical,pack` | ## Idioma `lang=es` o `lang=en` (o la cabecera `Accept-Language`) cambia el idioma de nombres, categorías, mensajes y errores. Un idioma sin soporte responde en inglés con un aviso, nunca con error. El título original de la tienda siempre viene sin traducir en `title_original`. ## Moneda Los montos vienen en la moneda de la tienda (CLP, sin decimales). Con `currency=USD` (o EUR) cada precio trae además un bloque `converted` con el monto, la tasa, su fecha y su fuente. En el historial, cada punto se convierte con la tasa de su fecha (`fx_policy: point_date`), o con una sola tasa si pasas `fx_date`. ## Fechas e identificadores - Fechas y horas en ISO 8601 y UTC (`observed_at`); `observed_local_date` es la fecha en la zona de la tienda. - Los ids son opacos y llevan prefijo de tipo: `prd_` producto, `ofr_` oferta, `str_` tienda, `exp_` exportación. Tiendas y categorías usan nombres legibles: `cl-jumbo`, `food.dairy.milk`. - Donde se pide un producto se acepta también su código de barras (GTIN). ## Cabeceras | Cabecera | Qué trae | |---|---| | `X-Request-Id` | Id del pedido, para soporte | | `X-Credits-Charged`, `X-Credits-Deduplicated`, `X-Credits-Remaining`, `X-Credits-Period-Reset` | Costo y saldo | | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | Límite de consultas | | `Retry-After` | En `429` y `503`: cuántos segundos esperar | ## Versionado La versión mayor va en la ruta (`/v1`). Dentro de ella solo hay cambios que agregan: campos, parámetros u operaciones nuevas. Un cambio incompatible crea `/v2`, y `/v1` se mantiene al menos 12 meses, avisado con las cabeceras `Deprecation` y `Sunset`. En MCP, el nombre de una herramienta es parte del contrato: si cambia de forma incompatible, sale con otro nombre. Los cambios se publican en el [changelog](/docs/changelog). ## Estado `GET /v1/status` (sin key) dice si la API responde y la fecha de los datos. La página de [estado](/estado) muestra lo mismo para personas.