Autenticación

La API recomendada 2026-10 utiliza clientes API de negocio y credenciales Bearer.

Authorization: Bearer rvi_live_xxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Crea el cliente en Desarrolladores → Clientes API, selecciona sus tiendas y scopes y copia la credencial cuando se muestre. El secreto completo aparece una sola vez.

Las credenciales Bearer son secretos server-side. No se aceptan en /api/2026-04, y las credenciales legacy X-API-KEY no se aceptan en /api/2026-10.

Scopes y tiendas

Cada operación exige un scope como orders:read o products:write. Los recursos de tienda siempre usan /stores/{store_id}/...; una tienda no autorizada y una inexistente devuelven el mismo 404.

personal_data:read es un scope avanzado. Sin él, los nombres y emails de clientes se omiten de las respuestas.

Una credencial sin el scope que exige la operación recibe 403 con el código de error insufficient_scope.

Scopes disponibles en 2026-10

Scope	Qué permite
stores:read	Listar las tiendas autorizadas para el cliente y leer una tienda concreta.
orders:read	Leer pedidos y su detalle.
orders:write	Crear pedidos, actualizar su estado y asociarles productos.
products:read	Leer productos y su detalle.
products:write	Crear y actualizar productos.
reviews:read	Leer opiniones y opiniones de producto.
statistics:read	Leer estadísticas de tienda y de producto.
invitation_suppressions:read	Leer la lista de supresiones de invitación; requiere también personal_data:read porque contiene direcciones de correo.
invitation_suppressions:write	Añadir y eliminar supresiones de invitación.
personal_data:read	Recibir nombres y emails de cliente en lugar de campos omitidos.

Scopes por conexión

Estos scopes aplican a los recursos por conexión bajo /stores/{store_id}/connections/{connection_id}/....

Scope	Qué permite
connections:read	Listar las conexiones concedidas al cliente en una tienda y leer una conexión concreta.
order_statuses:read	Leer el catálogo de estados de pedido sincronizado para una conexión.
order_sources:write	Reemplazar el catálogo de estados y reportar transiciones de estado fuente de un pedido.
invitation_policies:read	Leer la política de invitaciones efectiva de una conexión.
invitation_audit:read	Leer eventos de auditoría de política y eventos de elegibilidad por pedido, sin datos personales.
invitation_backfills:write	Solicitar un backfill refresh_state_only y consultar su progreso.

Ninguno de estos scopes permite cambiar la política de invitaciones. La política la configura únicamente el comercio en el panel de Revi; la API la expone en modo lectura.

Las credenciales existentes nunca reciben automáticamente los scopes por conexión. Solicita expresamente cada scope que necesite tu integración.

Grants de conexión

Una tienda puede tener varias conexiones: cada una es una integración distinta vinculada a esa tienda. Un cliente API necesita además un grant de conexión explícito para cada conexión sobre la que opere, aparte de sus scopes y de su selección de tiendas.

El grant existe porque el estado fuente de los pedidos y la elegibilidad de invitación pertenecen a una conexión concreta, no a la tienda entera. El scope describe qué puede hacer una operación; el grant de conexión describe sobre qué conexión puede hacerlo. Sin esa separación, un cliente autorizado para una integración podría reescribir el catálogo de estados de otra integración de la misma tienda.

Los grants los concede Revi por cliente y por conexión. No se derivan de la selección de tiendas ni se conceden automáticamente al añadir un scope.

Por eso cada petición por conexión se comprueba tres veces:

1. La credencial Bearer debe ser válida; si no, 401 con invalid_token.
2. El cliente debe tener el scope requerido; si no, 403 con insufficient_scope.
3. El cliente debe tener grant sobre esa conexión, y la conexión debe estar activa y pertenecer a la tienda de la ruta; si no, 404 con connection_not_found.

La tercera comprobación devuelve el mismo 404 tanto si la conexión no existe como si está inactiva, pertenece a otra tienda o simplemente no está concedida. Es deliberado: evita sondear conexiones que el cliente no está autorizado a ver. Trata connection_not_found como un problema de configuración y detén los reintentos hasta confirmar el grant.

Autenticación compatible de 2026-04

La API 2026-04 continúa utilizando API key.

X-API-KEY: revi_test_xxxxxxxxx

La key identifica la cuenta de integración y resuelve el contexto de negocio y tienda asociado. Todos los endpoints documentados bajo /api/2026-04 requieren este header.

Header de API key

Cada request autenticada requiere X-API-KEY.

Key ausente:

{
  "success": false,
  "error": {
    "code": "authentication_required",
    "message": "API key not provided. Include your API key in the X-API-KEY header."
  }
}

Key inválida:

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been deactivated."
  }
}

Contexto de tienda

Usa el contexto de negocio y tienda resuelto por la API key, salvo que el endpoint documente explícitamente un parámetro de tienda.

Si la API key está vinculada a una tienda concreta, los endpoints de listado y detalle quedan acotados automáticamente a esa tienda. Si la key es de negocio completo, los endpoints pueden devolver datos de varias tiendas; los endpoints que documentan id_store pueden filtrarse de forma explícita.

Headers de respuesta

Las respuestas correctas de 2026-10 incluyen:

Revi-Version: 2026-10
X-Request-ID: 2d87f617cd344da5ae5240cf3c049379

Cada versión informa su propio valor, de modo que las respuestas de 2026-10 mantienen Revi-Version: 2026-10 y las de 2026-04 mantienen Revi-Version: 2026-04.

Reglas de seguridad

• Nunca expongas API keys ni credenciales Bearer en JavaScript de navegador.
• Guarda las keys server-side en la configuración de tu aplicación.
• Rota una key si aparece en logs, capturas o código client-side.
• Trata las respuestas 401 y 403 como fallos de configuración y detén reintentos automáticos hasta corregirlos.