Guía de pedidos

Los pedidos indican a Revi qué clientes pueden recibir invitaciones de review y qué productos formaron parte de cada compra.

Endpoints

Método	Ruta	Uso
GET	/api/2026-04/orders	Listar pedidos sincronizados.
POST	/api/2026-04/orders	Crear o actualizar pedidos en bloque.
GET	/api/2026-04/orders/{id_order}	Consultar un pedido por ID externo.
PATCH	/api/2026-04/orders/{id_order}/status	Actualizar el estado de un pedido.
POST	/api/2026-04/orders/{id_order}/products	Asociar productos a un pedido.

Flujo recomendado

1. Crea o actualiza productos con POST /api/2026-04/products.
2. Crea o actualiza pedidos con POST /api/2026-04/orders.
3. Asocia productos con POST /api/2026-04/orders/{id_order}/products.
4. Mantén el estado al día con PATCH /api/2026-04/orders/{id_order}/status.

Valores de estado

Estado	Significado
pending	Guarda el pedido, pero no envía todavía el email de review.
ready	El pedido está listo para el flujo de invitación de review.
cancelled	No envía email de review para este pedido.

La API también acepta los valores numéricos 0, 1 y 2 al crear pedidos, pero las integraciones públicas deberían usar los valores de texto anteriores.

Crear o actualizar pedidos

Envía el código de idioma completo en lang. Por ejemplo, pt-BR y zh-Hant son distintos de pt y zh. Revi normaliza pt_BR a pt-BR y zh_TW a zh-Hant cuando esos códigos están disponibles. Si no está disponible un código regional o de escritura exacto, Revi puede resolverlo al código base disponible; si no hay ningún candidato disponible, el pedido usa el idioma predeterminado del negocio.

id_order es obligatorio y debe tener 36 caracteres o menos. El resto de campos son opcionales, pero enviar datos de cliente, importes, idioma y fecha mejora los flujos de review y reporting.

Los campos de entrada soportados son id_order, customer_name, customer_lastname, email, lang, iso_country, currency, shipping_cost, total_discount, taxes, vat, total_products, total_paid, status, order_date, date_status_upd y timezone. El alcance de tienda lo marca la API key; id_store se devuelve en endpoints de lectura, pero no se acepta en payloads de creación de pedidos.

curl "https://api.revi.io/api/2026-04/orders" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: revi_test_xxxxxxxxx" \
  -d '{
    "orders": [
      {
        "id_order": "100045",
        "lang": "en",
        "customer_name": "Jane",
        "customer_lastname": "Doe",
        "email": "jane@example.com",
        "currency": "EUR",
        "shipping_cost": "6.00",
        "total_discount": "0.00",
        "taxes": "10.50",
        "vat": "21",
        "total_products": "50.00",
        "total_paid": "66.50",
        "status": "ready",
        "order_date": "2026-05-09 10:30:00"
      }
    ]
  }'

Las respuestas batch incluyen un resultado por pedido:

{
  "success": true,
  "data": {
    "orders_count": 1,
    "results": [
      {
        "id_order": "100045",
        "success": true
      }
    ]
  },
  "meta": {
    "api_version": "2026-04"
  }
}

Si todas las filas fallan validación o procesamiento, la API devuelve 422 con los results por fila dentro de error.details.

Asociar productos

Asocia productos después de crear el pedido. Cada producto requiere id_product; las variantes pueden incluir id_combination.

{
  "products": [
    {
      "id_product": "sku-123",
      "id_combination": "sku-123-red-42",
      "price": "29.90",
      "sku": "RUN-RED-42"
    }
  ]
}

Respuesta correcta:

{
  "success": true,
  "data": {
    "id_order": "100045",
    "products_attached": 1
  },
  "meta": {
    "api_version": "2026-04"
  }
}

Actualizar estado

{
  "status": "ready",
  "date_status_upd": "2026-05-09 11:00:00"
}

Si se omite date_status_upd, Revi registra la hora actual del servidor.

Leer un pedido

GET /api/2026-04/orders/{id_order} devuelve la identidad del pedido, campos de cliente, idioma, moneda, total_paid, fechas de estado, estado de review y resúmenes de productos asociados. Los productos asociados incluyen id_product, avg_rating y num_reviews.

Listar pedidos

Filtros soportados:

Filtro	Descripción
page	Número de página, empezando en 1.
per_page	Tamaño de página, de 1 a 100. Por defecto es 25.
status	pending, ready o cancelled.
from_date	Pedidos con order_date igual o posterior a la fecha.
to_date	Pedidos con order_date igual o anterior a la fecha.
email	Coincidencia exacta del email de cliente.

Las respuestas de listado incluyen meta.pagination.