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=<pagination.next_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:<código CUT>` 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)	`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.

Estado#

GET /v1/status (sin key) dice si la API responde y la fecha de los datos. La página de estado muestra lo mismo para personas.

Conventions

Base URL and format#

Every path hangs from https://pricto.dev/v1. Responses are JSON with data (the result), meta (cost, source, language, currency, notices) and, for lists, pagination. New fields are added without notice: ignore the ones you don't know.

Pagination#

By cursor. If pagination.has_more is true, ask for the next page with cursor=<pagination.next_cursor> and the same filters. limit has a maximum per endpoint (20 for search).

json

{
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJvIjoyfQ"
  }
}

Common filters#

Parameter	Filters by	Example
`country`	Country, ISO 3166-1	`CL`
`retailer`	One or more stores, comma separated	`cl-jumbo,cl-unimarc`
`category`	Category, including subcategories	`food.dairy`
`brand`	Brand, by id or name	`colun`
`location`	Comuna, `CL:<CUT code>` or store, for stores that price by location	`Las Condes`
`as_of`	Prices in effect on a past date	`2026-10-01`
`from`, `to`, `interval`	History range and interval	`interval=week`
`min_confidence`, `match_kinds`	Which offers are grouped with the product (see Data model)	`identical,pack`

Language#

lang=es or lang=en (or the Accept-Language header) changes the language of names, categories, messages and errors. An unsupported language answers in English with a notice, never with an error. The store's original title always comes untranslated in title_original.

Currency#

Amounts come in the store's currency (CLP, no decimals). With currency=USD (or EUR) every price also carries a converted block with the amount, the rate, its date and its source. In history, each point is converted at its own date's rate (fx_policy: point_date), or with a single rate if you pass fx_date.

Dates and identifiers#

Dates and times in ISO 8601, UTC (observed_at); observed_local_date is the date in the store's time zone.
Ids are opaque and carry a type prefix: prd_ product, ofr_ offer, str_ store, exp_ export. Stores and categories use readable names: cl-jumbo, food.dairy.milk.
Wherever a product is asked for, its barcode (GTIN) is accepted too.

Headers#

Header	What it carries
`X-Request-Id`	Request id, for support
`X-Credits-Charged`, `X-Credits-Deduplicated`, `X-Credits-Remaining`, `X-Credits-Period-Reset`	Cost and balance
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`	Request limit
`Retry-After`	On `429` and `503`: how many seconds to wait

Versioning#

The major version is in the path (/v1). Within it there are only additive changes: new fields, parameters or operations. An incompatible change creates /v2, and /v1 stays for at least 12 months, announced with the Deprecation and Sunset headers. In MCP, a tool's name is part of the contract: if it changes incompatibly, it ships under another name. Changes are published in the changelog.

Status#

GET /v1/status (no key) says whether the API is up and the date of the data. The status page shows the same for people.