GET

Lister les commandes

Récupérer une liste paginée de commandes avec des capacités de filtrage, tri et recherche.

Point de terminaison

Requête HTTP

GET /v1/orders

Authentification

Ce point de terminaison nécessite une clé API valide avec la permission canViewOrders . La clé API doit être passée dans l'en-tête X-API-Key .

En-tête requis

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Paramètres de requête

Paramètre	Type	Requis	Défaut	Description
`page`	number	Non	1	Numéro de page pour la pagination
`limit`	number	Non	25	Résultats par page (max: 250)
`status`	string	Non	-	Filtrer par ID de statut personnalisé
`order_ids`	string	Non	-	Liste d'ID de commandes séparés par des virgules. Par défaut, attend les UUID internes. Lorsque use_shopify_order_id est activé, fournir la partie numérique du GID Shopify (ex: pour 'gid://shopify/Order/450789469', utiliser '450789469')
`use_shopify_order_id`	boolean	Non	false	Définir à 'true' pour utiliser les ID Shopify au lieu des UUID internes. Extraire le numéro du format GID Shopify (gid://shopify/Order/450789469 → 450789469) et le passer dans order_ids
`search`	string	Non	-	Rechercher dans le nom de commande, nom du client, entreprise ou email
`sort_by`	string	Non	created_at	Champ de tri: 'created_at' ou 'name'
`sort_order`	string	Non	desc	Direction du tri: 'asc' ou 'desc'
`order_type`	string	Non	ALL (v1.2), REGULAR (v1.0, v1.1)	Filtrer par type de commande : REGULAR (commandes standards), DRAFT (commandes brouillon), ou ALL (les deux types). Disponible en v1.2+
`workflow_id`	string	Non	-	Filtrer les commandes par UUID de flux de travail. Retourne uniquement les commandes assignées à ce flux de travail. Disponible en v1.3+

Réponse

Retourne un objet JSON avec la structure suivante:

200 OK - Réponse de succès

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "string",
        "shopify_order_id": "string",
        "name": "string",
        "created_at": "string",
        "custom_status": {
          "id": "string",
          "name": "string",
          "color": "string"
        },
        "custom_sub_status": {
          "id": "string",
          "name": "string"
        },
        "customer": {
          "first_name": "string",
          "last_name": "string",
          "email": "string",
          "phone": "string"
        },
        "shipping_address": {
          "company": "string",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "province": "string",
          "zip": "string",
          "country": "string",
          "latitude": "string",
          "longitude": "string"
        },
        "total_price": "string",
        "currency": "string",
        "line_items": [
          {
            "id": "string",
            "shopify_line_item_id": "string",
            "name": "string",
            "quantity": 0,
            "title": "string",
            "variant_title": "string",
            "sku": "string",
            "shopify_product_id": null,
            "shopify_variant_id": null,
            "custom_status": {
              "id": "string",
              "name": "string",
              "color": "string"
            },
            "custom_sub_status": {
              "id": "string",
              "name": "string"
            }
          }
        ],
        "note": "string",
        "cancelled": true,
        "cancelled_at": null,
        "addon_statuses": [
          {
            "id": "string",
            "name": "string",
            "display_name": "string",
            "color": "string",
            "sub_status": {
              "id": "string",
              "name": "string"
            },
            "assigned_at": "string"
          }
        ],
        "workflow_id": null,
        "workflow_name": null
      }
    ],
    "pagination": {
      "page": 0,
      "limit": 0,
      "total_count": 0,
      "total_pages": 0,
      "has_next_page": true,
      "has_previous_page": true
    }
  }
}

Champs de réponse

Objet de réponse racine

Champ	Type	Description
`success`	boolean	Toujours true pour une réponse réussie.
`data`	object	Charge utile de le point de terminaison. Ses champs sont détaillés dans les tableaux ci-dessous.
`orders`	array	Tableau d'objets de commande
`pagination`	object	Informations de pagination

Objet de commande

Champ	Type	Description
`id`	string	Identifiant unique de la commande (UUID)
`shopify_order_id`	string	ID global Shopify de la commande
`name`	string	Numéro de commande (par ex., #1001)
`created_at`	string \| null	Horodatage ISO 8601 de création de la commande dans Shopify
`custom_status`	object	Informations sur le statut personnalisé
`custom_sub_status`	object	Informations sur le sous-statut personnalisé
`customer`	object	Informations du client
`shipping_address`	object	Informations d'adresse de livraison
`total_price`	string \| null	Prix total de la commande
`currency`	string \| null	Code de devise (par ex., USD, CAD)
`line_items`	array	Tableau d'objets d'articles de ligne
`addon_statuses`	array	Tableau d'objets de statuts additionnels (v1.1+ seulement)
`note`	string \| null	Note/commentaires de la commande
`cancelled`	boolean	Indique si la commande est annulée
`cancelled_at`	string \| null	Horodatage ISO 8601 de l'annulation de la commande
`workflow_id`	string \| null	UUID du flux de travail auquel cette commande appartient (v1.3+ uniquement)
`workflow_name`	string \| null	Nom du flux de travail auquel cette commande appartient (v1.3+ uniquement)

Champs d'objet de statut

Champ	Type	Description
`id`	string	Identifiant unique du statut personnalisé
`name`	string	Nom d'affichage du statut (utilise le nom public si configuré)
`color`	string	Code couleur hexadécimal du statut

Objet de sous-statut

Champ	Type	Description
`id`	string	Identifiant unique du sous-statut
`name`	string	Nom du sous-statut

Champs d'objet client

Champ	Type	Description
`first_name`	string \| null	Prénom du client
`last_name`	string \| null	Nom de famille du client
`email`	string \| null	Adresse email du client
`phone`	string \| null	Numéro de téléphone du client

Champs d'objet d'adresse de livraison

Champ	Type	Description
`company`	string \| null	Nom de l'entreprise
`address1`	string \| null	Ligne d'adresse principale
`address2`	string \| null	Ligne d'adresse secondaire
`city`	string \| null	Nom de la ville
`province`	string \| null	Code d'état/province
`zip`	string \| null	Code postal
`country`	string \| null	Nom du pays
`latitude`	string \| null	Coordonnée de latitude
`longitude`	string \| null	Coordonnée de longitude

Champs d'objet d'article de ligne

Champ	Type	Description
`id`	string	Identifiant unique pour l'article de ligne
`shopify_line_item_id`	string	ID global Shopify pour l'article de ligne
`name`	string	Nom du produit
`quantity`	number	Quantité commandée
`title`	string \| null	Titre du produit
`variant_title`	string \| null	Titre de la variante, ou null
`sku`	string \| null	UGS, ou null
`shopify_product_id`	string \| null	GID du produit Shopify, ou null
`shopify_variant_id`	string \| null	GID de la variante Shopify, ou null

Champs d'objet de statut additionnel

Champ	Type	Description
`id`	string	Identifiant unique du statut additionnel
`name`	string	Nom d'affichage du statut additionnel
`display_name`	string	Nom d'affichage public du statut additionnel
`assigned_at`	string	Horodatage de l'attribution du statut additionnel à la commande
`color`	string	Code couleur hexadécimal du statut additionnel
`sub_status`	object	Sous-statut optionnel pour l'addon

Objet de sous-statut additionnel

Champ	Type	Description
`id`	string	Identifiant unique du sous-statut additionnel
`name`	string	Nom du sous-statut additionnel

Champs d'objet de pagination

Champ	Type	Description
`page`	number	Numéro de page actuel
`limit`	number	Résultats par page
`total_count`	number	Nombre total de commandes correspondant à la requête
`total_pages`	number	Nombre total de pages
`has_next_page`	boolean	Indique s'il y a une page suivante
`has_previous_page`	boolean	Indique s'il y a une page précédente

Exemples

Requête de base

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?page=1&limit=25&use_shopify_order_id=false&sort_by=created_at&sort_order=desc&order_type=ALL" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Filtrer par statut

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?status=abc123&sort_by=created_at&sort_order=desc" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Obtenir des commandes spécifiques par UUID

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_ids=uuid1,uuid2,uuid3" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Obtenir des commandes spécifiques par ID de commande Shopify

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_ids=5460132438316,5460132438317&use_shopify_order_id=true" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Rechercher des commandes

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?search=john@example.com&page=1&limit=50" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Obtenir les commandes brouillon (v1.2+)

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=DRAFT&page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Obtenir les commandes régulières (v1.2+)

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=REGULAR&page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Obtenir toutes les commandes (v1.2+)

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=ALL&page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Filtrer par flux de travail (v1.3+)

Requête cURL

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?workflow_id=uuid-workflow-1&page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Limitation de débit

Ce point de terminaison est soumis à des limites de débit par minute et par jour en fonction de votre clé API. Les informations de limite de débit sont renvoyées dans les en-têtes de réponse:

X-RateLimit-Limit-Minute: Nombre maximum de requêtes par minute
X-RateLimit-Remaining-Minute: Requêtes restantes dans la minute en cours
X-RateLimit-Reset-Minute: Horodatage Unix de réinitialisation de la fenêtre minute
X-RateLimit-Limit-Day: Nombre maximum de requêtes par jour
X-RateLimit-Remaining-Day: Requêtes restantes dans le jour en cours
X-RateLimit-Reset-Day: Horodatage Unix de réinitialisation de la fenêtre jour
Retry-After: Secondes à attendre avant de réessayer (en cas de limitation)

Réponses d'erreur

400 Mauvaise requête

Paramètres de requête invalides

400 Mauvaise requête

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": [
          "status_id"
        ],
        "message": "Required"
      }
    ]
  }
}

401 Non autorisé

Clé API manquante ou invalide

401 Non autorisé

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

403 Interdit

La clé API manque de permissions requises

403 Interdit

{
  "success": false,
  "error": "Insufficient permissions. Required: canViewOrders"
}

500 Erreur interne du serveur

Une erreur du serveur s'est produite

500 Erreur interne du serveur

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}