Convenciones
Las mismas reglas aplican a todos los endpoints.
Lo básico
- URL base
https://api.stilo.io/v1. Solo HTTPS y JSON. - Los ids son textos opacos con un prefijo de tipo:
prd_producto,var_variante,ret_tienda,lnk_link. Las marcas usan su slug (nars). - Los montos vienen como
{"amount": "15990.00", "currency": "CLP"}: un número decimal en texto más su moneda ISO 4217. Nunca asumas una moneda y nunca sumes montos de monedas distintas. - Las comisiones son números decimales en texto entre 0 y 1 (
"0.12"= 12%), como fracción de la venta sin IVA. Son las vigentes, no una garantía: cada venta se decide en el momento en que ocurre. - Las fechas y horas van en ISO 8601, en UTC.
- Ves las marcas y productos de tu país (el país de tu cuenta de stilo).
Paginación
Las listas devuelven data y next_cursor. Envía next_cursor como cursor hasta que sea null. limit va de 1 a 100 (por defecto 50).
GET /v1/products?brand=nars&limit=100
GET /v1/products?brand=nars&limit=100&cursor=WyIyMDI2LTEw...Errores
Todos los errores tienen la misma forma. Decide según type, que es estable; message es para personas (en inglés).
{
"error": {
"type": "not_commissionable",
"message": "This store is not in the stilo network.",
"param": "url",
"request_id": "req_a8e9c161ff2a89b85743a8be"
}
}| Estado | Cuándo |
|---|---|
| 400 | La solicitud está mal formada (invalid_request). |
| 401 / 403 | Problemas de autenticación o permisos. Ver Autenticación. |
| 404 | No existe o no es visible para ti (not_found). |
| 409 | Idempotency-Key reutilizada con otra solicitud (idempotency_conflict). |
| 422 | Solicitud válida rechazada por una regla de negocio, p. ej. not_commissionable, product_not_found. |
| 429 | Superaste el límite (rate_limited). Espera los segundos de Retry-After. |
| 5xx | Error nuestro. Puedes reintentar con espera progresiva. |
Toda respuesta trae el encabezado Stilo-Request-Id. Inclúyelo cuando nos escribas.
Límites de uso
| Límite | Por defecto |
|---|---|
| Solicitudes | 600 por minuto, sumando todas tus llaves |
| Links nuevos | 20.000 por día (UTC). Los links que ya existen siempre se devuelven. |
| Tamaño del lote | 100 elementos por POST /v1/links/batch |
Las respuestas traen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos). Un 429 incluye Retry-After. ¿Necesitas más? Escríbenos a contacto@stilo.io.
Idempotencia
Crear links ya es idempotente: un link por producto y por tienda. Para reintentar llamadas en lote, envía el encabezado Idempotency-Key (cualquier texto único). La misma llave con el mismo cuerpo dentro de 24 horas devuelve la primera respuesta, con Idempotent-Replayed: true.
Versiones
La versión va en la ruta (/v1). Dentro de v1 solo agregamos cosas: endpoints, campos y tipos de error nuevos. Escribe tu integración para que ignore los campos que no conoce. Un cambio incompatible sale como /v2, con al menos 90 días de aviso en el registro de cambios.