Aller au contenu
ShopentlyLearn

Obtenir — Retours, réclamations et échanges

Consultez les données de « Retours, réclamations et échanges ». Le résultat dépend des paramètres de cette opération.

GET/api/v1/requests/{request_id}

Authentification
Bearer
Disponible à partir de
BASIC
Autorisations requises
returns.request:read

Exemples de code

Exemple de requête

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/requests/example

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/requests/example');
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/requests/example', 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))

Exemple de réponse 200

JSON
{
  "data": {
    "created_at": "2026-01-01T12:00:00Z",
    "customer": {
      "email": "customer@example.invalid",
      "name": "Example"
    },
    "id": "example",
    "items": [
      {
        "id": "example",
        "name": "Example",
        "order_line_id": "example",
        "product_id": "example",
        "quantity": 1,
        "returned_quantity": 1,
        "sku": "example",
        "total": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "unit_price": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "variant_id": "example",
        "variant_options": [
          {
            "name": "Example",
            "value": "example"
          }
        ]
      }
    ],
    "number": "example",
    "order_id": "example",
    "order_number": "example",
    "products_value": {
      "amount": "0.00",
      "currency": "PLN",
      "minor_units": 2
    },
    "refund": {
      "amount": {
        "amount": "0.00",
        "currency": "PLN",
        "minor_units": 2
      },
      "completed_at": null,
      "status": "pending",
      "updated_at": "2026-01-01T12:00:00Z",
      "version": 1
    },
    "resolution_state": "unknown",
    "status": {
      "id": "example",
      "locale": "en",
      "name": "Example"
    },
    "type": "return",
    "updated_at": "2026-01-01T12:00:00Z",
    "version": 1
  },
  "meta": {
    "request_id": "example"
  }
}

Fonctionnement

  • Les collections et détails fournissent le numéro et le type de demande, la commande associée, les articles concernés, les données client et le remboursement.
  • Les types autorisés sont return, exchange et complaint.
  • Obtenez les identifiants de statut via /api/v1/request-statuses.
  • Le statut et le montant de remboursement sont des écritures distinctes avec contrôle de version.
  • Modifier le montant enregistré met à jour la demande ; cela n'effectue pas de transfert d'argent.

Paramètres

Paramètres de chemin

request_idChaîneObligatoire

Identifiant de demande ; dans les métadonnées, identifiant de la requête HTTP.

Contraintes
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Exemple: "example"

Cette opération n'accepte pas de corps JSON.

Réponses

Réponse 200

dataRequestDetailData Obligatoire

Données d'une réponse réussie.

Champs · data
created_atChaîneObligatoire

Date et heure de création.

format: "date-time"
customerRequestCustomerData Obligatoire

Données du client enregistrées pour cette ressource.

Champs · customer
emailChaîneObligatoire

Adresse e-mail.

nameChaîneObligatoire

Nom de la ressource dans le contexte concerné.

idChaîneObligatoire

Identifiant de ressource ; conserver la valeur renvoyée.

itemsTableau <RequestItemData > Obligatoire

Éléments inclus dans la ressource.

Champs · items
numberChaîneObligatoire

Numéro de commande ou de demande visible par l'utilisateur.

order_idChaîneObligatoire

Identifiant de la commande associée.

order_numberChaîneObligatoire

Numéro de la commande associée.

products_valueMoneyData Obligatoire

Valeur des produits de la commande.

Champs · products_value
amountChaîneObligatoire

Montant décimal sous forme de chaîne JSON ; null uniquement lorsque cela est autorisé.

currencyChaîneObligatoire

Code de la devise du montant.

Contraintes
pattern
"^[A-Z]{3}$"
minor_unitsEntierObligatoire

Nombre de décimales utilisées par la devise.

minimum: 0maximum: 4
refundRefundData Obligatoire

Informations de remboursement enregistrées.

Champs · refund
amountMoneyData nullObligatoire

Montant décimal sous forme de chaîne JSON ; null uniquement lorsque cela est autorisé.

completed_atChaîne nullObligatoire

Date et heure de fin.

Chaîne:format: "date-time"
statusChaîneObligatoire

Statut accepté par cette opération précise.

Contraintes
enum
["pending", "completed"]
updated_atChaîne nullObligatoire

Date et heure de la dernière modification.

Chaîne:format: "date-time"
versionEntierObligatoire

Version de ressource utilisée pour le contrôle de concurrence.

resolution_stateChaîneObligatoire

État de résolution d'une demande client.

Contraintes
enum
["unknown", "open", "completed", "rejected", "cancelled"]
statusRequestStatusData Obligatoire

Statut accepté par cette opération précise.

Champs · status
idChaîneObligatoire

Identifiant de ressource ; conserver la valeur renvoyée.

localeChaîneObligatoire

Langue sélectionnée pour cette requête.

nameChaîne nullObligatoire

Nom de la ressource dans le contexte concerné.

typeRequestType Obligatoire

Type de ressource.

updated_atChaîneObligatoire

Date et heure de la dernière modification.

format: "date-time"
versionEntierObligatoire

Version de ressource utilisée pour le contrôle de concurrence.

metaContextPageMeta ContextMeta PageMeta RequestMeta Obligatoire

Métadonnées de la réponse.

Champs · meta

ContextPageMeta

localeChaîneObligatoire

Langue sélectionnée pour cette requête.

market_codeChaîneObligatoire

Code de marché renvoyé par le point d'accès au contexte.

market_idChaîneObligatoire

Identifiant de marché renvoyé par le point d'accès au contexte.

paginationPagination Obligatoire

Métadonnées de pagination par curseur.

request_idChaîneObligatoire

Identifiant de demande ; dans les métadonnées, identifiant de la requête HTTP.

minLength: 1maxLength: 100

ContextMeta

localeChaîneObligatoire

Langue sélectionnée pour cette requête.

market_codeChaîneObligatoire

Code de marché renvoyé par le point d'accès au contexte.

market_idChaîneObligatoire

Identifiant de marché renvoyé par le point d'accès au contexte.

request_idChaîneObligatoire

Identifiant de demande ; dans les métadonnées, identifiant de la requête HTTP.

minLength: 1maxLength: 100

PageMeta

paginationPagination Obligatoire

Métadonnées de pagination par curseur.

request_idChaîneObligatoire

Identifiant de demande ; dans les métadonnées, identifiant de la requête HTTP.

minLength: 1maxLength: 100

RequestMeta

request_idChaîneObligatoire

Identifiant de demande ; dans les métadonnées, identifiant de la requête HTTP.

minLength: 1maxLength: 100
Exemple de réponse

Statut HTTP

200
Réponse réussie Schéma
400
Requête invalide
401
Authentification requise
403
Accès refusé
404
Ressource introuvable
409
Conflit de version
422
Échec de validation
429
Limite de requêtes dépassée
Autres statuts HTTP (7)
405
Méthode non autorisée
413
Requête trop volumineuse
415
Format non pris en charge
500
Erreur du serveur
502
Erreur de passerelle API
503
Service indisponible
504
Délai de passerelle dépassé

Catalogue des erreurs: ErrorResponse

En-têtes

401

WWW-AuthenticateChaîneFacultatif

Schéma d'authentification exigé par le serveur.

405

AllowChaîneFacultatif

Méthodes HTTP prises en charge par cette ressource.

429, 503

Retry-AfterEntierFacultatif

Délai minimal avant une nouvelle tentative, en secondes.

minimum: 0