Journal des modifications de l'API (v1.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 par défaut dans v1.4
• 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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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: your_api_key_here" \
  -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
• Pour accéder aux données des statuts complémentaires, ajoutez l'en-tête X-API-Version: 1.1 à vos requêtes
• Les requêtes sans en-tête continuent de retourner le format v1.0
• 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 'Authorization: Bearer ucos_live_your_api_key' \
  -H 'X-API-Version: 1.1'

Changements incompatibles

Aucun - cette version est rétrocompatible.