Journal des modifications de l'API

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-Current et X-API-Version-Default indiquent tous deux 1.5. Une requête sans X-API-Version est désormais servie en 1.5 ; 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 désormais la version par défaut et les réponses 1.4 restent inchangées.
• Une requête sans en-tête est désormais servie en 1.5 ; 1.5 est donc la version par défaut. 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 en 1.5 sur tous les points de terminaison ; 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 — une requête sans en-tête obtient désormais 1.5, 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 avec support des notifications
• 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 individuel déclenchent des notifications lorsqu'elles sont configurées sur le statut cible. Les points de terminaison en masse et d'effacement ne déclenchent pas de notifications.
• 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.5)
• 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.