POST

Déplacer une commande vers un autre workflow

Réaffectez une commande à un autre workflow. Le déplacement applique un statut de départ du workflow cible et entraîne le changement de statut ainsi que l'exécution qu'il déclenche.

Point de terminaison

POST /v1/orders/:order_id/workflow

Authentification

Ce point de terminaison requiert la permission canOverrideProductChainEnforcement permission. Envoyez votre clé API dans l'en-tête X-API-Key à chaque requête.

En-tête d'authentification

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ce que le déplacement fait

Les workflows étant pilotés par les statuts, un déplacement s'effectue en appliquant un statut de départ du workflow cible. Le changement de statut peut déclencher une exécution — par exemple lorsque le statut cible marque la commande comme exécutée.

Il ne s'agit pas d'une réaffectation silencieuse : le statut de la commande change et l'exécution qu'il déclenche est tentée. Une exécution bloquée ne s'applique jamais à moitié — le changement de statut est conservé et la réponse rapporte les erreurs. Un appelant qui exécute aussi de son côté traiterait la commande deux fois.

Paramètres de chemin

Paramètre	Type	Requis	Par défaut	Description
`order_id`	string	Oui	-	UUID de la commande, ou identifiant de commande Shopify lorsque use_shopify_order_id est vrai.

Corps de la requête

Paramètre	Type	Requis	Par défaut	Description
`use_shopify_order_id`	boolean	Non	false	Traiter le segment de chemin comme un identifiant de commande Shopify au lieu de l'UUID de commande de l'application.
`workflow_id`	string	Oui	-	Workflow cible. Doit exister dans cette boutique.
`starting_status_id`	string	Non	-	Statut principal (ni addon, ni indépendant) du workflow cible à appliquer. Par défaut, le premier statut du workflow.

Réponse

Retourne le workflow et le statut appliqués, ainsi que le résultat de l'étape d'exécution :

200 OK - Réponse de succès

{
  "success": true,
  "data": {
    "success": true,
    "order_id": "string",
    "shop_order_id": "string",
    "workflow": {
      "id": "string",
      "name": "string"
    },
    "status": {
      "id": "string",
      "name": "string"
    },
    "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 du point de terminaison. Ses champs sont détaillés dans les tableaux ci-dessous.
`order_id`	string	UUID de la commande.
`shop_order_id`	string	Identifiant de commande Shopify (GID).
`workflow`	object	Objet du workflow appliqué.
`status`	object	Objet du statut appliqué.
`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).

Champs d'objet de flux de travail

Champ	Type	Description
`id`	string	Identifiant unique du flux de travail
`name`	string	Nom d'affichage du flux de travail

Champs d'objet de statut

Champ	Type	Description
`id`	string	UUID du statut
`name`	string	Nom interne du statut

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

Exemple de requête

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10/workflow" \
  -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,"workflow_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","starting_status_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10"}'

Avec un identifiant de commande Shopify

Exemple de requête

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/5234567890/workflow" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
    "starting_status_id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
    "use_shopify_order_id": true
  }'

Limitation de débit

Ce point de terminaison est soumis aux mêmes limites par clé que tous les autres points de terminaison.

X-RateLimit-Limit-Minute: Nombre maximal de requêtes par minute
X-RateLimit-Remaining-Minute: Requêtes restantes dans la minute en cours
X-RateLimit-Reset-Minute: Horodatage Unix (secondes) de réinitialisation de la minute
X-RateLimit-Limit-Day: Nombre maximal de requêtes par jour
X-RateLimit-Remaining-Day: Requêtes restantes dans la journée en cours
X-RateLimit-Reset-Day: Horodatage Unix (secondes) de réinitialisation du jour
Retry-After: Secondes à attendre avant de réessayer (présent en cas de limitation)

Réponses d'erreur

400 Requête invalide

Corps invalide, statut de départ hors du workflow cible, statut additionnel ou indépendant, workflow sans statut, ou refus du moteur de statuts.

400 Requête invalide

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

401 Non autorisé

Clé d'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 ne possède pas la permission canOverrideProductChainEnforcement

403 Interdit

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

404 Introuvable

Commande, workflow ou statut de départ introuvable dans cette boutique

404 Introuvable

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

500 Erreur interne du serveur

Erreur serveur inattendue

500 Erreur interne du serveur

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