POST

Mettre à jour le statut

Mettre à jour le statut personnalisé d'une commande spécifique. Envoie automatiquement des notifications basées sur la configuration du statut.

Point de terminaison

Requête HTTP

POST /v1/orders/:order_id/status

Authentification

Ce point de terminaison nécessite une clé API valide avec la permission canChangeOrderStatus . 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 chemin

Paramètre	Type	Requis	Défaut	Description
`order_id`	string	Oui	-	Identifiant de commande (UUID par défaut, ou partie numérique de l'ID Shopify si use_shopify_order_id est true dans le corps de la requête). Pour les ID de commande Shopify, extraire le numéro du format GID (par ex., pour 'gid://shopify/Order/450789469', utiliser '450789469').

Corps de la requête

Paramètre	Type	Requis	Défaut	Description
`status_id`	string	Oui	-	L'UUID du statut personnalisé
`sub_status_option_id`	string	Conditionnel	-	L'UUID de l'option de sous-statut. Requis si le statut a des options de sous-statut.
`use_shopify_order_id`	boolean	Non	false	Définir à 'true' pour rechercher la commande en utilisant l'ID Shopify au lieu de l'UUID. Extraire le numéro du format GID Shopify (gid://shopify/Order/450789469 → 450789469) et l'utiliser dans le paramètre de chemin order_id.
`fulfillment_selections`	objet	Non	-	Réponse facultative (v1.5) à un bloc fulfillment_readiness : { [shopOrderId]: { [fulfillmentOrderId]: locationId } }.

Réponse

Retourne une confirmation avec les détails de la commande mise à jour:

200 OK - Réponse de succès

{
  "success": true,
  "data": {
    "message": "string",
    "order": {
      "id": "string",
      "shopify_order_id": "string",
      "name": "string",
      "status": {
        "id": "string",
        "name": "string",
        "color": "string"
      },
      "sub_status": null,
      "workflow_id": "string",
      "workflow_name": "string"
    },
    "notifications": {
      "total_sent": 0,
      "total_failed": 0,
      "by_channel": {}
    },
    "orders_fulfilled": 0,
    "fulfillment_errors": [
      {
        "channel": "string",
        "code": "string",
        "message": "string"
      }
    ]
  }
}

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.
`message`	string	Message de confirmation
`order`	object	Objet contenant les détails de la commande mise à jour
`notifications`	object	Objet contenant les statistiques de notification
`orders_fulfilled`	number	Nombre de commandes dont l'exécution a été appliquée.
`fulfillment_errors`	array	Erreurs d'exécution ; une exécution bloquée ne s'applique jamais à moitié.
`fulfillment_readiness`	object \| null	Présent lorsque l'exécution est refusée ; bloc de choix pour la résoudre (v1.5 uniquement).
`fulfillment_move_results`	array	Résultat d'un déplacement demandé (v1.5 uniquement).

Objet de commande

Champ	Type	Description
`id`	string	UUID de la commande
`shopify_order_id`	string	ID de commande Shopify
`name`	string	Nom/numéro de commande Shopify
`status`	object	Objet de statut avec id, nom et couleur
`sub_status`	object \| null	Objet de sous-statut avec id et nom (si applicable)
`workflow_id`	string	UUID du workflow auquel la commande appartient (v1.3+ uniquement)
`workflow_name`	string	Nom du workflow auquel la commande appartient (v1.3+ uniquement)

Champs d'objet de statut

Champ	Type	Description
`id`	string	UUID du statut
`name`	string	Nom d'affichage du statut
`color`	string	Code couleur hexadécimal du statut

Objet de sous-statut

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

Champs d'objet de notifications

Champ	Type	Description
`total_sent`	number	Nombre total de notifications envoyées avec succès
`total_failed`	number	Nombre total de notifications ayant échoué
`by_channel`	object	Objet avec les statistiques par canal (par ex., email, sms)

Champs d'objet de statistiques par canal

Champ	Type	Description
`sent`	number	Nombre de notifications envoyées avec succès pour ce canal
`failed`	number	Nombre de notifications ayant échoué pour ce canal

Champs d'un objet d'erreur d'exécution

Champ	Type	Description
`channel`	string	Canal d'exécution en échec.
`code`	string	Code d'erreur lisible par la machine.
`message`	string	Message d'erreur lisible par l'humain.

Champs de l'objet de préparation d'exécution

Champ	Type	Description
`required`	boolean	Indique si un choix d'emplacement est nécessaire.
`code`	string	Code de refus lisible par la machine.
`cause`	string	Cause sous-jacente.
`message`	string	Message à montrer à l'opérateur.
`orders_to_fulfillment_orders_map`	object	Map identifiant de commande → identifiants d'ordres d'exécution.
`moveable_fulfillment_order_ids`	array	Ordres d'exécution pouvant être déplacés.
`location_choices`	array	Emplacements de destination candidats.
`submit_with`	string	Champ de requête dans lequel envoyer la réponse — fulfillment_selections.

Champs d'un résultat de déplacement d'exécution

Champ	Type	Description
`shop_order_id`	string	GID de la commande Shopify concernée par le déplacement.
`fulfillment_order_id`	string	GID de l'ordre d'exécution déplacé.
`location_id`	string	Identifiant de l'emplacement de destination.
`success`	boolean	Indique si le déplacement a réussi.
`error`	string \| null	Message d'erreur en cas d'échec du déplacement.

Exemples

Requête de base (UUID)

Requête cURL

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10/status" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","use_shopify_order_id":false,"status_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","sub_status_option_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","fulfillment_selections":{}}'

Utilisation de l'ID de commande Shopify

Requête cURL

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/5460132438316/status" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "status-uuid-abc123",
    "sub_status_option_id": "sub-status-uuid-def456",
    "use_shopify_order_id": true
  }'

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

Corps de requête invalide, échec de validation ou le statut nécessite un sous-statut

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 ou l'application de la chaîne de produits empêche ce changement de statut

403 Interdit

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

404 Non trouvé

Commande, statut ou sous-statut non trouvé

404 Non trouvé

{
  "success": false,
  "error": "Order not found"
}

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"
  }
}