Convenciones
Filtros, paginación, fechas y día de referencia en la API de Turbodato. Lo que vale igual para /data, /semaphore, /price-control y /export.
Lo que vale para todos los endpoints. Lo propio de cada uno está en la referencia.
El día de referencia
Todas las comparaciones de precios son del mismo día. Nunca ponemos tu precio de hoy contra el de un competidor de ayer: es la forma más fácil de ver un rojo que no existe.
- Sin el parámetro
date, la respuesta es la del último relevamiento de tu tablero. Ése es el día de referencia. /datalo informa enreferenceDatey/price-controlendate. Leelo, no lo asumas: si hoy todavía no corrió el relevamiento, vas a recibir el de ayer.- Con
date=2026-10-15pedís un día puntual./dateslista los días que podés pedir.
Fechas
| Qué | Formato | Ejemplo |
|---|---|---|
Parámetro date | YYYY-MM-DD | 2026-10-16 |
referenceDate, /dates, /status, /price-control | YYYY-MM-DD | 2026-10-16 |
date de cada oferta, infoCards.lastUpdate | ISO 8601 en UTC | 2026-10-16T00:00:00.000Z |
Paginación
/data y /price-control paginan; el resto no. Los dos devuelven un objeto pagination:
{ "page": 2, "limit": 50, "total": 234, "totalPages": 5 }/data | /price-control | |
|---|---|---|
| Qué pagina | productos | infracciones |
page | desde 1 | desde 1 |
limit por defecto | 20 | 200 |
limit máximo | 200 | 1000 |
Un valor fuera de rango no es un error: se recorta al límite más cercano. limit=5000 en /data
devuelve 200 productos, no un 400. pagination.limit dice con cuánto se respondió.
Para recorrer todo, pedí páginas hasta page = totalPages. Si no vas a leer infoCards, sumá
stats=false en /data: te ahorrás las dos cuentas más caras, que vienen iguales en cada página.
Filtros
/data, /semaphore, /price-control y /export aceptan los mismos filtros, con el mismo
significado: el red de /semaphore con category=Televisores cuenta con la misma regla que
usa /data para devolver category=Televisores&semaphore=red.
| Parámetro | Coincidencia | Qué hace |
|---|---|---|
brand | exacta | Marca. Varias con barra vertical: brand=Samsung|LG. |
category | exacta | Categoría. Varias con barra vertical. |
seller | exacta | Vendedor, por su nombre normalizado. Varios con barra vertical. Deja los productos que ese vendedor ofrece ese día, y sólo sus ofertas. |
site | parcial | Nombre del sitio, sin distinguir mayúsculas: site=mercado encuentra Mercado Libre. Acota las ofertas, no los productos. |
text | por términos | Búsqueda libre en nombre, marca, EAN y SKU. Ver abajo. |
semaphore | exacta | red, yellow o green. Cualquier otro valor se ignora. |
favorites | true deja los productos marcados con estrella por alguien del equipo. | |
date | exacta | El día a consultar, YYYY-MM-DD. |
order_by | priceASC, priceDESC, discountASC o discountDESC. Sin él, nombre de la A a la Z. |
Un parámetro que la API no conoce se ignora, no da error. Revisá bien los nombres: orderBy en
vez de order_by no ordena nada y tampoco avisa.
brand, category y seller son coincidencia exacta
brand=Sams devuelve cero productos, y brand=samsung también si en tu catálogo está como
"Samsung". Pedile los valores válidos a /filters antes de filtrar.
Cómo busca text
- El texto se parte en términos y todos tienen que aparecer, cada uno en alguno de los
campos:
text=smart tv 55encuentra "Smart TV Samsung 55" Crystal UHD". - Los acentos y las mayúsculas no cuentan:
text=pava electricaencuentra "Pava eléctrica". - La puntuación corta términos:
text=coca-colaencuentra "Coca Cola" y "Coca-Cola". - Un término con forma de código (un EAN, un SKU) también se busca en el ID de la publicación de ese día.
En la URL, los espacios van como + o %20, y la barra vertical como %7C si tu cliente HTTP
no la codifica solo.
Qué ordena order_by
Los cuatro valores miran tu sitio propio: price* ordena por el precio de tu publicación ese
día y discount* por su descuento (precio de lista contra precio final). Los productos que ese
día no tienen ese dato van al final en las dos direcciones. El desempate es siempre el nombre,
de la A a la Z.
exclude_international (sólo /data)
exclude_international=true deja afuera las compras internacionales: publicaciones con envío
desde el exterior. Es lo que hace la matriz del dashboard por defecto, así que si querés que tus
números coincidan con los de la pantalla, mandalo. El resto de los endpoints las incluye siempre.
Precios
| Campo | Qué es |
|---|---|
priceList | Precio de lista publicado, antes del descuento. Puede ser null. |
realPrice | Precio final publicado. Es el que se compara. |
discountPercent | Descuento entre los dos, con dos decimales. null si no hay precio de lista válido; negativo si el precio final supera al de lista. |
quantity | Unidades del pack. |
installments | Los planes de cuotas que publicaba el sitio ese día. |
Los montos son números sin símbolo ni separadores: 849999 es $ 849.999. Están en la moneda en
que publica el sitio; la API no convierte nada.
En los tableros que comparan por pack, el semáforo y el Control de PVP usan el precio
unitario, realPrice / quantity. Cada oferta trae quantity para que puedas hacer la misma
cuenta.
Identificar un producto
El id de un producto es estable entre días: usalo para cruzar respuestas. El id de una
oferta, no: cambia en cada relevamiento.
Para mostrar un identificador legible, usá sourceProductId, después sku, después ean: el
primero que tenga valor. Muchos catálogos guardan "0" donde no hay dato; tratalo como vacío.
Estabilidad del contrato
v1 es una superficie congelada. Puede aparecer un campo nuevo sin aviso; lo que no va a pasar
es que uno desaparezca o cambie de nombre. Escribí tu integración para ignorar las claves que no
conoce.
Dos campos de /data, hasOpenReport y missingReportSiteIds, son de uso interno del
dashboard. Siguen ahí para no romper a nadie. No los uses.
Qué no publica la API
- La configuración de tu vista en el dashboard: columnas ocultas, preferencia de pack, tasas de cuotas.
- El margen de ruptura de Control de PVP que cada persona elige en la pantalla. La API usa la regla estricta: un peso abajo ya rompe.
- Los favoritos de una persona puntual.
- Los reportes de mal emparejado, las equivalencias, las reglas de alerta y las listas guardadas.