Journal des modifications de l'API (v1.6)

Nouveautés

Statuts additionnels des articles dans la liste et le détail des commandes

Depuis novembre 2026, un article peut porter ses propres statuts additionnels. Jusqu'à la 1.5, la liste et le détail des commandes ne les affichaient pas ; à partir de la 1.6, chaque entrée de line_items contient addon_statuses, avec la même structure que le champ addon_statuses de la commande.

Points de terminaison concernés :

• GET /v1/orders - Les articles de chaque commande contiennent addon_statuses
• GET /v1/orders/:order_id - Les articles de la commande contiennent addon_statuses

Chaque entrée du champ addon_statuses d'un article comporte les champs suivants :

• id - L'identifiant du statut additionnel.
• name - Son nom interne.
• display_name - Le nom public lorsque le statut en utilise un, sinon name.
• color - Sa couleur.
• sub_status - Le sous-statut sélectionné, ou null.
• assigned_at - Le moment où le statut additionnel a été ajouté à cet article.

• Les entrées vont de la plus ancienne à la plus récente. Un article sans statut additionnel, y compris tout article d'une boutique qui ne suit pas les statuts par article, a addon_statuses: [].
• Le champ addon_statuses de la commande elle-même est inchangé : il liste les statuts additionnels de la commande et ne répète jamais ceux de ses articles.
• Les statuts additionnels d'un article se définissent avec les points de terminaison d'articles existants, dans toute version à partir de la 1.4.

{
  "id": "0d3c6f8e-5b1a-4e2c-9f7d-2a8b4c6e1f30",
  "shopify_line_item_id": "gid://shopify/LineItem/14587654321",
  "name": "Custom frame - 8x10",
  "quantity": 1,
  "custom_status": {
    "id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
    "name": "In production",
    "color": "#2c6ecb"
  },
  "custom_sub_status": null,
  "addon_statuses": [
    {
      "id": "5e7a1c3b-9d24-4f60-8b1e-3c5a7d9f2b46",
      "name": "Rush",
      "display_name": "Rush order",
      "color": "#d72c0d",
      "sub_status": {
        "id": "a4b6c8d0-1e3f-4a5b-9c7d-2e4f6a8b0c12",
        "name": "Same day"
      },
      "assigned_at": "2026-11-12T15:04:05.000Z"
    }
  ]
}

Corrections applicables à toutes les versions

Ces corrections sont livrées avec la 1.6 mais ne dépendent pas de la version demandée. Elles corrigent un comportement qui ne correspondait pas à cette documentation, ou qui laissait une requête atteindre des données qu'elle ne devait pas atteindre.

• Les commandes supprimées ne sont jamais servies ni modifiées. Une commande retirée de l'application (un brouillon supprimé dans Shopify, des brouillons écartés lorsque le suivi des brouillons est désactivé, ou un doublon fusionné) renvoie désormais un 404 sur tous les points de terminaison de commande. Auparavant, GET /orders/:orderId la renvoyait encore, et une recherche par ID Shopify pouvait aboutir à un doublon supprimé au lieu de la commande active.
• Un ID Shopify trouve les commandes brouillon sur chaque écriture. Avec use_shopify_order_id, les points de terminaison de changement de statut, de changement de statut en masse, de notification et de notification en masse trouvent désormais aussi une commande brouillon par son ID Shopify, comme la liste et le détail des commandes le font depuis la 1.2.
• Les requêtes de commandes en masse acceptent de 1 à 100 ID. POST /orders/status-bulk et POST /orders/notify-bulk refusent une liste vide ou plus de 100 order_ids avec une erreur de validation 400. Une liste vide renvoyait auparavant un 404, et il n'y avait pas de limite supérieure.
• use_shopify_order_id accepte true, false, "true" ou "false". La chaîne "false" était auparavant lue comme true. Toute autre valeur est une erreur de validation.
• Les statuts supprimés et archivés sont refusés clairement. Un status_id supprimé renvoie un 404 (Status not found), un statut archivé un 400 (Status is archived and cannot be applied). Les deux passaient auparavant la vérification de l'API et revenaient en 400 depuis le moteur de statuts, avec l'identifiant interne du réglage de la boutique.
• notifications.by_channel liste tous les canaux. Les réponses de changement de statut (simple et en masse) contiennent toujours email, sms et whatsapp, chacun sous la forme { sent, failed }. Auparavant, il ne listait que les canaux en échec, avec sent: 0 quel que soit le nombre d'envois, ou une seule entrée total lorsque rien n'échouait. Sur le changement de statut simple, total_sent valait aussi 0 dès qu'un canal échouait.
• Les order_ids répétés fonctionnent sur GET /orders. ?order_ids=a&order_ids=b renvoie les deux commandes ; seule la première était utilisée auparavant. Les valeurs séparées par des virgules fonctionnent comme avant.
• Les versions non prises en charge nomment les versions acceptées sur tous les points de terminaison. L'erreur est "Unsupported API version. This endpoint supports: …" avec details.supported_versions ; dix points de terminaison renvoyaient auparavant un simple "Unsupported API version: <value>".

Guide de migration

• Aucun changement incompatible — addon_statuses sur les articles est un nouveau champ, et la 1.5 et les versions antérieures conservent la forme de leurs articles.
• Une requête sans en-tête est désormais servie en 1.6 ; 1.6 est donc la version par défaut. Envoyez X-API-Version: 1.5 pour conserver la version par défaut précédente.
• Tous les points de terminaison acceptent 1.6. Seuls la liste des commandes et le détail d'une commande diffèrent de la 1.5 ; tous les autres points de terminaison renvoient leur réponse 1.5.

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.6"

Changements incompatibles

Aucun. Le champ est nouveau, et la 1.5 et les versions antérieures conservent la forme de leurs articles. Les corrections ne modifient les réponses que là où elles contredisaient cette documentation ou exposaient des données supprimées.

Nouveautés

Réaffectation de workflow

Un nouveau point de terminaison déplace explicitement une commande vers un autre workflow. Les workflows étant pilotés par les statuts, le déplacement s'effectue en appliquant un statut de départ du workflow cible.

Nouveau point de terminaison :

POST /v1/orders/:order_id/workflow - Déplacer une commande vers un autre workflow

• starting_status_id est facultatif et correspond par défaut au premier statut du workflow. Il doit s'agir d'un statut principal du workflow cible — les statuts additionnels et indépendants sont refusés.
• Le workflow cible et le statut de départ doivent appartenir à la boutique et être actifs.
• Le déplacement entraîne le changement de statut et l'exécution qu'il déclenche ; orders_fulfilled et fulfillment_errors rapportent le résultat.
• Requiert la permission canOverrideProductChainEnforcement.

Exemple de requête

{
  "workflow_id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "starting_status_id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
  "use_shopify_order_id": false
}

Exemple de réponse

{
  "success": true,
  "data": {
    "success": true,
    "order_id": "6b2da49e-84ef-439e-ad99-c3d7b2e6c64f",
    "shop_order_id": "gid://shopify/Order/5234567890",
    "workflow": {
      "id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
      "name": "Pharmaceutical"
    },
    "status": {
      "id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
      "name": "Approved"
    },
    "orders_fulfilled": 1,
    "fulfillment_errors": []
  }
}

Champs de relation de workflow

GET /v1/workflows gagne des champs de relation qui décrivent la façon dont les workflows de la boutique s'enchaînent :

• relationship_type - sequential ou isolated.
• relationship_configured - Indique si la boutique possède un réglage de relation explicite.
• previous_workflow_id / next_workflow_id - Voisins dérivés dans la chaîne ; les workflows isolés sont ignorés.
• workflow_transitions - Passations à sens unique dérivées : from_workflow_id, to_workflow_id, trigger: "on_final_status".
• enforce_workflow_order - En 1.5, il est dérivé du modèle de relation ; les versions antérieures conservent la valeur issue des réglages.

Les requêtes en 1.3/1.4 conservent la réponse d’origine sans champs de relation.

{
  "id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "name": "Pharmaceutical",
  "relationship_type": "sequential",
  "relationship_configured": true,
  "previous_workflow_id": null,
  "next_workflow_id": "a7732dfd-e636-4fe1-a66d-9fb43d2e92a8"
}

Sélections d'exécution lors des changements de statut

POST /v1/orders/:orderId/status et POST /v1/orders/status-bulk acceptent une map fulfillment_selections facultative. Elle répond à la seule cause d'exécution qu'un appelant peut résoudre : une commande dont l'exécution est affectée à un emplacement incapable de la réaliser.

{
  "fulfillment_selections": {
    "gid://shopify/Order/5234567890": {
      "gid://shopify/FulfillmentOrder/987654321": "gid://shopify/Location/123456"
    }
  }
}

Lorsque l'exécution est refusée, la réponse contient un bloc fulfillment_readiness afin que l'appelant puisse présenter le choix sans logique de découverte :

• required — indique si un choix est nécessaire.
• code, cause et message — pourquoi l'exécution a été refusée, et quoi dire à l'utilisateur.
• orders_to_fulfillment_orders_map et moveable_fulfillment_order_ids — les commandes et les ordres d'exécution concernés.
• location_choices[] — fulfillment_order_id, movable, message et location pour chaque destination candidate.
• submit_with — le champ de requête dans lequel envoyer la réponse (fulfillment_selections).

{
  "fulfillment_readiness": {
    "required": true,
    "code": "FULFILLMENT_REQUIRES_LOCATION_SELECTION",
    "cause": "LOCATION_NOT_FULFILLABLE",
    "message": "The order's fulfilment is assigned to a location that cannot fulfil it.",
    "orders_to_fulfillment_orders_map": {
      "gid://shopify/Order/5234567890": ["gid://shopify/FulfillmentOrder/987654321"]
    },
    "moveable_fulfillment_order_ids": ["gid://shopify/FulfillmentOrder/987654321"],
    "location_choices": [
      {
        "fulfillment_order_id": "gid://shopify/FulfillmentOrder/987654321",
        "movable": true,
        "message": "Choose a location that can fulfil this order.",
        "location": {
          "id": "gid://shopify/Location/123456",
          "name": "Main warehouse"
        }
      }
    ],
    "submit_with": "fulfillment_selections"
  }
}

orders_fulfilled et fulfillment_errors rapportent le résultat, et un déplacement refusé apparaît dans fulfillment_move_results au lieu d'être ignoré. Une exécution bloquée ne s'applique jamais à moitié : le changement de statut est conservé et les champs indiquent ce qui s'est passé.

Corrections applicables à toutes les versions

• X-API-Version-Default indique la dernière version sur tous les points de terminaison, comme X-API-Version-Current (1.5 à cette sortie), et une requête sans X-API-Version est servie dans cette version. Le repli par point de terminaison ne concerne plus qu’un futur point de terminaison dont la première version est plus récente que la version actuelle globale.
• Un 429 contient désormais details.retryAfter ; il contenait auparavant une chaîne message non documentée.
• Les erreurs de validation sur GET /orders utilisent désormais le même tableau details.errors que tous les autres points de terminaison.

Guide de migration

• Aucun changement incompatible — 1.5 est devenue la version par défaut à cette sortie, et les réponses 1.4 restent inchangées.
• À partir de cette sortie, une requête sans en-tête était servie en 1.5 ; 1.5 était donc la version par défaut (c’est désormais 1.6). Envoyez X-API-Version: 1.4 pour conserver la réponse 1.4 inchangée pendant la migration.
• Une requête sans en-tête est servie dans la version par défaut sur tous les points de terminaison (1.5 à cette sortie) ; le point de terminaison de workflow n’est plus une exception.

{
  "workflow_id": "3f2a9c1e-7b64-4d21-9a3e-1c5d8f0b2a77",
  "starting_status_id": "8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10",
  "use_shopify_order_id": false
}

Changements incompatibles

Aucun — à cette sortie, une requête sans en-tête a commencé à obtenir 1.5 (elle obtient désormais 1.6), mais demander X-API-Version: 1.4 renvoie les mêmes réponses 1.4.

Nouvelles fonctionnalités

Suivi de statut par article

Ajout du suivi de statut au niveau des articles à l'API externe. Les marchands qui suivent les statuts au niveau des articles individuels peuvent maintenant gérer ces statuts via trois nouveaux points de terminaison.

Nouveaux points de terminaison:

• POST /v1/line-items/:lineItemId/status - Changer le statut d'un article individuel
• POST /v1/line-items/status-bulk - Changer les statuts de plusieurs articles en masse (jusqu'à 100)
• POST /v1/line-items/clear-status - Effacer les statuts d'un ou plusieurs articles (jusqu'à 100)

Réponse de changement de statut d'article

{
  "success": true,
  "data": {
    "message": "Line item status updated successfully",
    "line_item": {
      "id": "li-uuid-123",
      "status": {
        "id": "uuid-status-1",
        "name": "In Production",
        "color": "#FFA500"
      },
      "sub_status": {
        "id": "uuid-substatus-1",
        "name": "Cutting"
      }
    }
  }
}

Mode de spécificité du statut

Le paramètre statusSpecificity de la boutique détermine quels points de terminaison sont disponibles. Les modes sont: order (uniquement les points de terminaison au niveau commande), line_item (uniquement les points de terminaison au niveau article), ou combined (les deux fonctionnent indépendamment).

Comportements clés

• Les changements de statut d'article, individuels ou en masse, déclenchent des notifications lorsqu'elles sont configurées sur le statut cible. L'effacement d'un statut ne déclenche pas de notification ; depuis novembre 2026, un effacement retire aussi les statuts additionnels des articles, et chaque retrait ne déclenche une notification que si ce statut additionnel est configuré pour en envoyer une à son retrait.
• Après tout changement de statut d'article, le champ méta de la commande parente est automatiquement reconstruit pour refléter l'état agrégé des articles.
• L'application de la chaîne de produits s'applique indépendamment par article — chaque article doit suivre l'ordre de progression de statut configuré.

Guide de migration

• Aucun changement incompatible — tous les points de terminaison et réponses v1.3 sont inchangés
• Les points de terminaison d’articles sont disponibles en v1.4 ; envoyez X-API-Version: 1.4 pour les utiliser.
• Vérifiez le mode de spécificité du statut de la boutique avant d'appeler les points de terminaison d'articles
• Les ID d'articles utilisent des UUID internes (SyncedLineItem.id), pas les GID Shopify
• Entièrement rétrocompatible — les intégrations existantes continuent de fonctionner

Exemple de requête

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/line-items/li-uuid-123/status" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.4" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": "uuid-status-1",
    "sub_status_option_id": "uuid-substatus-1"
  }'

Changements incompatibles

Aucun — tous les points de terminaison v1.0–v1.3 sont inchangés.

Nouvelles fonctionnalités

Filtrage des commandes brouillon

Ajout de la possibilité de filtrer les commandes par type (commandes régulières, commandes brouillon ou toutes). Les commandes brouillon peuvent maintenant être gérées aux côtés des commandes régulières via l'API.

Points de terminaison affectés :

• GET /api/v1/orders - La liste des commandes prend maintenant en charge le paramètre de requête order_type (REGULAR, DRAFT, ALL)
• GET /api/v1/orders/:order_id - La recherche de commande détecte maintenant automatiquement les commandes brouillon vs régulières lors de l'utilisation des identifiants Shopify

Changements de la liste des commandes

Le nouveau paramètre de requête order_type permet de filtrer par type de commande :

• REGULAR - REGULAR - Retourne uniquement les commandes régulières (par défaut en v1.0/v1.1)
• DRAFT - DRAFT - Retourne uniquement les commandes brouillon
• ALL - ALL - Retourne les commandes régulières et brouillon (par défaut en v1.2)

Exemples

# Get all orders (both regular and draft) - v1.2 default
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=ALL" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

# Get only regular orders
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=REGULAR" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

# Get only draft orders
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?order_type=DRAFT" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

Changements de la commande détaillée

Lors de l'utilisation de use_shopify_order_id=true, l'API essaie maintenant automatiquement les formats d'identifiant de commande régulière et brouillon, facilitant l'intégration.

# Look up a draft order by Shopify ID - v1.2 automatically tries both formats
curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/1234567890?use_shopify_order_id=true" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.2"

Exclusion des jours fériés

Ajout du drapeau skip_holidays à la configuration max_duration des statuts. Lorsqu'il est activé, les jours fériés seront exclus du calcul des délais de durée des statuts, similaire à la fonctionnalité existante skip_weekends.

Points de terminaison affectés :

• GET /api/v1/statuses - La liste des statuts inclut maintenant skip_holidays dans l'objet max_duration
• GET /api/v1/statuses/:status_id - Le détail du statut inclut maintenant skip_holidays dans l'objet max_duration

Changements de réponse

Les réponses de statut incluent maintenant le champ skip_holidays dans l'objet max_duration :

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Fulfillment",
  "color": "#2948ff",
  "is_independent": false,
  "is_addon": false,
  "max_duration": {
    "enabled": true,
    "seconds": 432000,
    "skip_weekends": true,
    "skip_holidays": true,
    "show_public_overdue_date": true
  }
}

Améliorations du format de réponse en masse

Mise à jour du format de réponse des opérations en masse avec un rapport succès/échec plus clair et des informations d'erreur détaillées pour les entrées échouées.

Points de terminaison affectés :

• POST /api/v1/orders/status-bulk - Mise à jour en masse des statuts avec format de réponse amélioré
• POST /api/v1/orders/notify-bulk - Notification en masse avec format de réponse amélioré

Changements de mise à jour en masse des statuts :

• updated_count - Nombre total de commandes mises à jour avec succès
• failed - Nombre de commandes dont la mise à jour a échoué
• success - Booléen indiquant si toutes les mises à jour ont réussi
• failed_entries - Tableau d'objets avec order_id et détails d'erreur pour chaque échec

Changements de notification en masse :

• total_orders - Nombre total de commandes dans la demande de notification
• failed - Nombre de commandes dont la notification a échoué
• success - Booléen indiquant si toutes les notifications ont réussi
• failed_entries - Tableau d'objets avec order_id et détails d'erreur pour chaque échec

Exemples de réponses en masse

# Old format (before v1.2 update)
{
  "message": "Statuses updated successfully",
  "updated_count": 2,
  "results": [
    {
      "order_id": "uuid1",
      "status_id": "status-uuid",
      "status_name": "Processing"
    }
  ]
}

# New format (v1.2 update)
{
  "message": "Statuses updated successfully",
  "updated": 2,
  "failed": 1,
  "results": [
    {
      "order_id": "uuid1",
      "success": true,
      "status_id": "status-uuid",
      "status_name": "Processing"
    },
    {
      "order_id": "uuid2",
      "success": true,
      "status_id": "status-uuid",
      "status_name": "Processing"
    },
    {
      "order_id": "invalid-uuid",
      "success": false,
      "error": "Order not found"
    }
  ]
}

Guide de migration

• Ajoutez l'en-tête X-API-Version: 1.2 pour utiliser cette version explicitement
• Le paramètre order_type est optionnel - par défaut ALL en v1.2
• Les recherches par identifiant Shopify fonctionnent maintenant pour les commandes régulières et brouillon sans modification
• Le champ skip_holidays est maintenant disponible dans les configurations max_duration des statuts
• Mettez à jour la gestion des réponses d'opérations en masse pour utiliser les nouveaux champs success, failed et failed_entries
• Vérifiez le booléen success pour une détermination rapide de succès/échec au lieu d'analyser les résultats individuels
• Entièrement rétrocompatible - les intégrations existantes continuent de fonctionner

Exemple de requête

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

Changements incompatibles

Aucun - cette version est rétrocompatible. Le comportement par défaut de order_type a changé de REGULAR à ALL, mais c'est additif (retourne plus de données, pas moins).

Nouvelles fonctionnalités

Support des statuts complémentaires

Ajout du support des statuts complémentaires sur tous les points de terminaison liés aux commandes. Les statuts complémentaires peuvent être assignés en plus des statuts principaux.

Points de terminaison affectés:

• GET /api/v1/orders - La liste des commandes inclut maintenant un tableau addon_statuses lorsque l'en-tête X-API-Version: 1.1 est présent
• GET /api/v1/orders/:order_id - Le détail de la commande inclut maintenant un tableau addon_statuses lorsque l'en-tête X-API-Version: 1.1 est présent
• GET /api/v1/statuses - La liste des statuts inclut maintenant un indicateur is_addon lorsque l'en-tête X-API-Version: 1.1 est présent

Changements de réponse

Les commandes incluent maintenant un champ addon_statuses avec support optionnel des sous-statuts:

{
  "id": "uuid",
  "status": {
    "id": "status-uuid",
    "name": "Processing",
    "color": "#2948ff"
  },
  "addon_statuses": [
    {
      "id": "addon-uuid-1",
      "name": "Quality Check",
      "color": "#10b981",
      "sub_status": {
        "id": "addon-sub-uuid",
        "name": "Passed"
      }
    },
    {
      "id": "addon-uuid-2",
      "name": "Packaging",
      "color": "#f59e0b",
      "sub_status": null
    }
  ]
}

Les statuts incluent maintenant des indicateurs de classification:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Processing",
  "is_independent": false,
  "is_addon": false
}

Guide de migration

• Aucune modification de code requise - entièrement rétrocompatible
• Les requêtes sans en-tête de version utilisent la version par défaut (1.6)
• Pour utiliser une version antérieure, indiquez-la explicitement avec l’en-tête X-API-Version
• Aucune modification requise pour l'authentification ou la limitation de débit

Exemple de requête:

curl -X GET 'https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders' \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.1"

Changements incompatibles

Aucun - cette version est rétrocompatible.