Saltar al contenido
ShopentlyLearn

Listar — Pedidos

Consulta los datos de «Pedidos». El resultado depende de los parámetros de esta operación.

GET/api/v1/orders

Autenticación
Bearer
Disponible desde
BASIC
Permisos necesarios
orders.order:read

Ejemplos de código

Ejemplo de solicitud

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"'/api/v1/orders?limit=20'

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/orders?limit=20');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/orders?limit=20', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

Ejemplo de respuesta 200

JSON
{
  "data": [
    {
      "created_at": "2026-10-19T10:00:00Z",
      "customer": {
        "email": "customer@example.invalid",
        "first_name": "Example",
        "last_name": "Example",
        "phone": null
      },
      "delivery": {
        "amount": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "dates": {
          "dispatch_timezone": "Europe/Warsaw",
          "estimated_delivery_from": "2026-10-20",
          "estimated_delivery_to": "2026-10-21",
          "planned_dispatch_on": "2026-10-19"
        },
        "method_code": "shipping-old",
        "method_name": "Historic carrier",
        "pickup_point": null,
        "recipient_mode": "full_address"
      },
      "discount_amount": {
        "amount": "24.60",
        "currency": "PLN",
        "minor_units": 2
      },
      "id": "order-0000",
      "lifecycle_state": "placed",
      "locale": "pl",
      "market_id": "market-pl",
      "number": "0001",
      "payment": {
        "amount": {
          "amount": "329.40",
          "currency": "PLN",
          "minor_units": 2
        },
        "environment": "live",
        "method_code": "payment-old",
        "method_name": "Historic method",
        "paid_at": null,
        "status": "unpaid",
        "updated_at": "2026-10-19T10:00:00Z",
        "version": 0
      },
      "prices_include_tax": true,
      "shipping_discount_amount": {
        "amount": "24.60",
        "currency": "PLN",
        "minor_units": 2
      },
      "status": {
        "id": "status-0",
        "name": "Status 0",
        "updated_at": "2026-10-19T10:00:00Z",
        "version": 1
      },
      "subtotal": {
        "amount": "329.40",
        "currency": "PLN",
        "minor_units": 2
      },
      "tax": {
        "amount": "49.40",
        "currency": "PLN",
        "minor_units": 2
      },
      "tax_country_code": "PL",
      "total": {
        "amount": "329.40",
        "currency": "PLN",
        "minor_units": 2
      }
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "limit": 20,
      "next_cursor": null
    },
    "request_id": "example"
  }
}

Cómo funciona

  • La colección ofrece resúmenes de pedidos y filtros por número, estado, estado de pago y fecha de creación.
  • La lista y el detalle de pedidos incluyen delivery.dates. Las fechas YYYY-MM-DD son previstas y no confirman el envío. Las fechas actuales tienen prioridad; los pedidos antiguos usan la estimación guardada. Los valores borrados o desconocidos son null. El detalle también incluye todas las líneas e imágenes de productos.
  • Obtén identificadores de estado válidos de /api/v1/order-statuses.
  • El estado del pedido y el estado de pago utilizan endpoints PATCH y permisos independientes.
  • Cambiar el estado de pago registrado no realiza un cargo en una tarjeta ni emite un reembolso a través de un proveedor de pagos.

Pedido · Totales

Los importes y tipos impositivos proceden del pedido guardado, incluidas las correcciones de líneas. Los datos históricos ausentes son null y no se sustituyen por los tipos actuales del catálogo. Los importes siguen siendo cadenas decimales.

La lista devuelve resúmenes. Obtén GET /api/v1/orders/{order_id} para cada resultado y exporta el detalle financiero completo. Los reintentos GET son limitados y respetan Retry-After. La exportación por fecha de creación no sincroniza correcciones posteriores.

Parámetros

Parámetros de consulta

limitNúmero enteroOpcional

Número máximo de registros en esta página.

minimum: 1maximum: 100
Valor predeterminado: 50Ejemplo: 20
cursorCadena de texto nullOpcional

Valor de continuación opaco devuelto por la página anterior.

Cadena de texto:minLength: 1maxLength: 1024
numberCadena de texto nullOpcional

Número de pedido o solicitud mostrado al usuario.

Cadena de texto:minLength: 1maxLength: 48
status_idCadena de texto nullOpcional

Identificador obtenido del catálogo de estados correspondiente.

Restricciones · Cadena de texto 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
payment_statusCadena de texto nullOpcional

Estado de pago registrado.

Restricciones · Cadena de texto 1
enum
["unpaid", "paid", "failed", "refunded"]
created_fromCadena de texto nullOpcional

Inicio del filtro por fecha de creación.

Cadena de texto:format: "date-time"
created_toCadena de texto nullOpcional

Fin del filtro por fecha de creación.

Cadena de texto:format: "date-time"

Esta operación no acepta un cuerpo JSON.

Respuestas

Respuesta 200

dataLista <OrderSummaryData > Obligatorio

Contenido de una respuesta correcta.

Campos · data

OrderSummaryData

created_atCadena de textoObligatorio

Momento de creación.

format: "date-time"
customerCustomerData Obligatorio

Información del cliente registrada para este recurso.

deliveryShippingData Obligatorio

Método de entrega e información asociada.

discount_amountMoneyData Obligatorio

Importe decimal codificado como cadena JSON; null solo cuando se permite.

idCadena de textoObligatorio

Identificador del recurso; consérvalo tal como se devuelve.

lifecycle_stateOrderLifecycleState Obligatorio

Estado del ciclo de vida del recurso.

localeCadena de textoObligatorio

Idioma seleccionado para esta solicitud.

market_idCadena de textoObligatorio

Identificador del mercado devuelto por el endpoint de contexto.

numberCadena de textoObligatorio

Número de pedido o solicitud mostrado al usuario.

paymentPaymentData Obligatorio

Detalles del pago registrados en el pedido.

prices_include_taxBooleanoObligatorio

Indica si los precios de la lista incluyen impuestos.

shipping_discount_amountMoneyData Obligatorio

Importe decimal codificado como cadena JSON; null solo cuando se permite.

statusOrderStatusData Obligatorio

Estado admitido por esta operación concreta.

subtotalMoneyData Obligatorio

Importe anterior a los componentes adicionales indicados en la respuesta.

taxMoneyData Obligatorio

Información fiscal.

tax_country_codeCadena de texto nullObligatorio

País fiscal · Datos guardados del pedido · ISO 3166-1 alpha-2; null.

totalMoneyData Obligatorio

Importe total.

metaContextPageMeta ContextMeta PageMeta RequestMeta Obligatorio

Metadatos de la respuesta.

Campos · meta

ContextPageMeta

localeCadena de textoObligatorio

Idioma seleccionado para esta solicitud.

market_codeCadena de textoObligatorio

Código del mercado devuelto por el endpoint de contexto.

market_idCadena de textoObligatorio

Identificador del mercado devuelto por el endpoint de contexto.

paginationPagination Obligatorio

Metadatos de la paginación por cursor.

request_idCadena de textoObligatorio

Identificador de la solicitud; en los metadatos de respuesta identifica la solicitud HTTP.

minLength: 1maxLength: 100

ContextMeta

localeCadena de textoObligatorio

Idioma seleccionado para esta solicitud.

market_codeCadena de textoObligatorio

Código del mercado devuelto por el endpoint de contexto.

market_idCadena de textoObligatorio

Identificador del mercado devuelto por el endpoint de contexto.

request_idCadena de textoObligatorio

Identificador de la solicitud; en los metadatos de respuesta identifica la solicitud HTTP.

minLength: 1maxLength: 100

PageMeta

paginationPagination Obligatorio

Metadatos de la paginación por cursor.

request_idCadena de textoObligatorio

Identificador de la solicitud; en los metadatos de respuesta identifica la solicitud HTTP.

minLength: 1maxLength: 100

RequestMeta

request_idCadena de textoObligatorio

Identificador de la solicitud; en los metadatos de respuesta identifica la solicitud HTTP.

minLength: 1maxLength: 100
Ejemplo de respuesta

Estado HTTP

200
Respuesta correcta Esquema
400
Solicitud no válida
401
Autenticación necesaria
403
Permiso denegado
404
Recurso no encontrado
409
Conflicto de versión
422
Error de validación
429
Límite de solicitudes excedido
Otros estados HTTP (7)
405
Método no permitido
413
Solicitud demasiado grande
415
Formato no compatible
500
Error del servidor
502
Error de la puerta de enlace API
503
Servicio no disponible
504
Tiempo de espera agotado

Catálogo de errores: ErrorResponse

Cabeceras

401

WWW-AuthenticateCadena de textoOpcional

Esquema de autenticación exigido por el servidor.

405

AllowCadena de textoOpcional

Métodos HTTP admitidos por este recurso.

429, 503

Retry-AfterNúmero enteroOpcional

Espera mínima antes de reintentar, en segundos.

minimum: 0