Aplicaciones
Una aplicación es el acceso de un sistema a una tienda: sus scopes, los locales con los que trabaja y, si se configuran, las direcciones desde las que puede llamar. Las aplicaciones se crean en Configuración → API y webhooks; puede hacerlo quien tiene permiso para gestionar la API — por defecto, el dueño — y nadie le da a una aplicación más de lo que tiene.
La aplicación actúa en la tienda como un integrante propio. Los pedidos que crea y el stock que cambia llevan su nombre, así la tienda ve en su historial qué hizo la integración.
La API es parte del plan. Si la tienda pasa a un plan sin ella, las solicitudes reciben 403 integration_api_not_in_plan hasta que vuelva; las aplicaciones y los tokens quedan como estaban.
Scopes
Un scope abre un recurso para leer o para escribir: catalog:read, orders:write. Un scope de escritura incluye el de lectura de su recurso. La tabla de scopes muestra qué endpoints abre cada uno.
Dos scopes agregan campos a las respuestas de otro recurso: costs:read agrega los costos a las variantes del catálogo y a los ítems de los pedidos, y customers:read agrega a los pedidos los contactos, la dirección y el comentario del cliente, y a los comprobantes fiscales el receptor. Sin el scope esos campos no están en la respuesta, no vienen vacíos.
Una solicitud sin el scope de su endpoint recibe 403 insufficient_scope. La respuesta nombra el scope que falta, y la tienda se lo agrega a la aplicación:
curl "https://api.saleya.app/v1/orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:read"
{
"type": "insufficient_scope",
"title": "Scope is missing",
"status": 403,
"detail": "This request needs the orders:read scope. The store owner grants it in the app access settings.",
"required_scope": "orders:read",
"accepted_scopes": [
"orders:read"
]
}Tokens
- Un token empieza con
saleya_at_. Sus últimos seis caracteres son una suma de control: un token con un error de tipeo se rechaza antes de buscarlo, y los escáneres de secretos reconocen uno filtrado. - La tienda guarda solo un hash del token y sus primeros caracteres, por eso el token se muestra una sola vez, al emitirlo.
- La fecha de vencimiento es opcional. El dueño de la tienda recibe un email antes de que un token venza.
- Una aplicación tiene como máximo 2 tokens vigentes: uno en uso y otro en reemplazo.
Para rotar un token, emití uno nuevo que reemplace al anterior y elegí cuánto sigue funcionando el anterior. Desplegá el nuevo dentro de ese plazo. La revocación rige desde la siguiente solicitud; eliminar una aplicación revoca todos sus tokens.
type del 401 | Significado |
|---|---|
api_token_missing | No hay encabezado Authorization: Bearer. |
api_token_invalid | El formato o la suma de control no coinciden, o no existe ese token. |
api_token_expired | Pasó la fecha de vencimiento. |
api_token_revoked | El token fue revocado, la aplicación eliminada o la tienda cerrada. |
Cuidá los tokens
- Guardá el token en tu servidor. Un token en un navegador, una app móvil o un repositorio es un token filtrado.
- Limitá la aplicación a las direcciones de tus servidores: una solicitud desde otra dirección recibe 403
ip_not_allowed. - El dueño de la tienda recibe un email cuando se emite o revoca un token y cuando cambia el acceso de una aplicación.
- El registro de solicitudes de la aplicación en el panel guarda cada solicitud durante 30 días: método, ruta, estado y el
typede un rechazo, sin cuerpos. - Si un token se filtra, revocalo enseguida: la revocación no espera a un reemplazo.