Unaluka Hunter API v1

Catálogo importable de Amazon US, cotizado en soles. Texto libre en español o inglés; productos publicables con precio final en PEN.

Arranque

La key la entrega Unaluka y viaja en el header X-Api-Key. Nunca en la URL: una key en el query string queda en los access logs, en los nuestros y en los tuyos.

curl -H "X-Api-Key: <tu-key>" "https://apihunter.unaluka.com/v1/me"
curl -H "X-Api-Key: <tu-key>" "https://apihunter.unaluka.com/v1/search?q=cafetera+espresso"

Empezá por /v1/me: confirma que la key anda y te dice tu comisión vigente y tu límite por minuto, sin gastar nada.

Los endpoints

Ruta	Para qué
`GET /v1/search`	Buscar y cotizar. La lista liviana, para decidir qué publicar.
`GET /v1/products/{asin}`	El detalle: galería, EAN/UPC y las variantes de la familia — lo que hace falta para crear la ficha en tu catálogo.
`GET /v1/me`	Quién sos, tu comisión y tu consumo del mes.

El campo por campo, con tipos y ejemplos, está en el OpenAPI — sirve para generar un cliente en tu lenguaje sin escribirlo a mano.

Lo que prometemos sobre el precio

`price` ya incluye tu comisión

Es el precio final en PEN, con la comisión de tu contrato ya adentro y terminado en 5 o en 9. No le sumes nada encima.

`price_observed_at` — cuándo vimos el precio de origen

No describe el producto: describe la calidad de la respuesta. Normalmente son segundos. Si vas a publicar un lote grande, filtrá por este campo en vez de confiar a ciegas — es lo que te avisa si en algún momento nuestra fuente se degrada, sin que dependa de que nosotros nos acordemos de avisarte.

`valid_until` — es una promesa, no una observación

Sostenemos ese price hasta esa hora aunque el precio de origen se mueva. Es el único campo del que somos responsables.

Guardá el quote_id: es con lo que reconstruimos después qué precio te dimos y cuándo. Identifica la búsqueda, así que los ítems de una misma respuesta lo comparten — para señalar una línea, mandanos el par quote_id + asin.

Un producto que no podemos cotizar no viene con precio.

En /v1/search directamente no aparece en items, y se cuenta en meta.without_price — o sea que si ese número no es cero, encontramos más de lo que ves.

En /v1/products/{asin} sí te lo devolvemos, porque pediste ese ASIN y el producto existe, pero sin ninguno de los cinco campos del precio. Van los cinco o ninguno.

Nunca vas a recibir un precio estimado disfrazado de cotización. Preferimos no darte un número antes que darte uno que no podemos sostener.

Stock

availability es siempre "importacion": nada está en stock local, todo se importa bajo pedido.

Disponibilidad real — extensión opcional

Si Unaluka te la habilitó, GET /v1/products/{asin}?availability=1 consulta en vivo la oferta que gana el buy box y la devuelve en availability_detail.

curl -H "X-Api-Key: <tu-key>" \
  "https://apihunter.unaluka.com/v1/products/B0GV19QWX2?availability=1"

Pedila al comprometer una venta, no al armar el catálogo. Tiene un costo por consulta: confirmar cada orden es barato, recorrer 500 productos no.

Y null no significa «agotado»: significa que no pudimos preguntar. Si no lo pediste —o no lo tenés habilitado— el campo directamente no viene, y eso tampoco es un error.

Los tres valores (status, sold_by, shipping_time) son texto crudo de Amazon en inglés. No los normalizamos: cualquier traducción nuestra sería una interpretación.

Errores

Todos traen error —un código estable, apto para hacer switch— y message, cuyo texto puede cambiar.

Código	Qué pasó	Qué hacer
`401`	Falta la key, es inválida, está vencida o fue revocada. El campo `error` dice cuál.	Revisá el header. Si dice `key_revocada`, pedinos una nueva.
`404`	No encontramos ese ASIN.	Nada: no lo tenemos.
`429`	Pasaste tu límite por minuto.	Esperá lo que diga `retry_after_s`.
`503`	`source_unavailable` — no pudimos consultar la fuente.	Reintentá en unos minutos. No vacíes tu catálogo: es un problema nuestro, no una búsqueda sin resultados.

Esa última distinción es la que más te puede costar. Una búsqueda sin resultados devuelve 200 con items: []; un problema nuestro devuelve 503. Nunca vas a recibir una lista vacía porque algo se nos rompió.

Versionado

Agregamos campos sin avisar — tu cliente los tiene que ignorar. Sacar o renombrar un campo, o cambiar el significado de uno existente, es /v2.