Desarrolladores
Claves, permisosy límites
Cómo funciona la autenticación, qué cubre la API, cómo se limitan las solicitudes y cómo conseguir una clave para tu tienda.
Autenticación
Un token Bearer, vinculado a una sola tienda
Las claves se emiten por tienda y llevan permisos explícitos. Una clave puede leer productos sin poder emitir reembolsos: esa es la diferencia entre integrar un feed de inventario y entregar el negocio.
- Tokens Bearer en la cabecera Authorization
- Permisos por recurso, lectura y escritura por separado
- Claves revocables desde el panel en cualquier momento
- Cada llamada queda registrada en el historial de auditoría de la tienda
POST /v1/orders/{id}/fulfilments
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"outletId": "out_3f9",
"lines": [{ "orderLineId": "ol_88", "quantity": 2 }],
"deliveryMethod": "RIDER"
}Referencia
Qué puedes llamar
Los grupos de recursos disponibles hoy. Los esquemas completos de solicitud y respuesta llegarán con la referencia pública.
| Recurso | Ruta | Operaciones |
|---|---|---|
| Productos | /v1/products | listar · crear · actualizar · eliminar |
| Variantes | /v1/products/{id}/variants | listar · crear · actualizar |
| Colecciones | /v1/collections | listar · crear · actualizar |
| Inventario | /v1/inventory/levels | listar · ajustar · transferir |
| Pedidos | /v1/orders | listar · crear · actualizar · cancelar |
| Preparaciones | /v1/orders/{id}/fulfilments | listar · crear |
| Devoluciones | /v1/returns | listar · crear · aprobar |
| Clientes | /v1/customers | listar · crear · actualizar |
| Pagos | /v1/payments | listar · reembolsar |
| Facturas | /v1/invoices | listar · crear · enviar |
| Sucursales | /v1/outlets | list |
| Webhooks | /v1/webhooks | listar · crear · eliminar |
Límites y comportamiento
Qué esperar de la API
Límite de solicitudes
Límites por clave, con el cupo restante devuelto en cada respuesta. Una solicitud limitada devuelve 429 con una indicación de reintento en lugar de fallar en silencio.
Paginación
Los endpoints de listas usan paginación por cursor. Avanza con el cursor de la respuesta anterior en lugar de obtener los registros de uno en uno.
Idempotencia
Las solicitudes de escritura aceptan una clave de idempotencia, así que un reintento tras un tiempo de espera no creará un segundo pedido ni un segundo reembolso.
Errores
Los fallos devuelven un código estable y legible por máquina junto al mensaje, para que tu integración se base en el código y no en la redacción.
Versionado
La versión va en la ruta. Los cambios incompatibles se publican como una versión nueva; los cambios aditivos se aplican sobre la actual y se anuncian antes.
Entrega de webhooks
Las cargas se firman y se reintentan con espera progresiva. Las entregas y sus respuestas son visibles, así que se puede diagnosticar un endpoint que falla.