POST

Changer le statut d'article

Changer le statut d'un article individuel. Déclenche les notifications lorsqu'elles sont configurées sur le statut cible.

Point de terminaison

Requête HTTP

POST /v1/line-items/:lineItemId/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 d'URL

Paramètre	Type	Requis	Défaut	Description
`lineItemId`	string	Oui	-	ID interne de l'article (SyncedLineItem.id)

Corps de la requête

Paramètre	Type	Requis	Défaut	Description
`status_id`	string	Oui	-	ID du statut cible. Un statut additionnel est ajouté à l'article s'il ne le porte pas, et retiré s'il le porte déjà ; son sous-statut est mis à jour lorsqu'un sous-statut est fourni.
`sub_status_option_id`	string	Non	-	Requis lorsque le statut cible a un groupe de sous-statuts avec des options

Réponse

Retourne la confirmation avec le statut d'article mis à jour:

200 OK - Réponse de succès

{
  "success": true,
  "data": {
    "message": "string",
    "line_item": {
      "id": "string",
      "shopify_line_item_id": "string",
      "name": "string",
      "quantity": 0,
      "title": null,
      "variant_title": null,
      "sku": null,
      "custom_status": {
        "id": "string",
        "name": "string",
        "color": "string"
      },
      "custom_sub_status": null
    },
    "notifications": {
      "total_sent": 0,
      "total_failed": 0,
      "errors": [
        {
          "channel": "string",
          "code": "string",
          "message": "string"
        }
      ]
    },
    "metafield_errors": []
  }
}

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.
`message`	string	Message de confirmation
`line_item`	object	Objet d'article mis à jour
`notifications`	object	Résumé de l'envoi des notifications.
`metafield_errors`	array	Déclaré comme { orderId, message }[] ; la reconstruction du métachamp ne rejette jamais, donc ce tableau est toujours vide en pratique.

Champs d'objet d'article de ligne

Champ	Type	Description
`id`	string	Identifiant unique pour l'article de ligne
`shopify_line_item_id`	string	ID global Shopify pour l'article de ligne
`name`	string	Nom du produit
`quantity`	number	Quantité commandée
`title`	string \| null	Titre du produit
`variant_title`	string \| null	Titre de la variante, ou null
`sku`	string \| null	UGS, ou null
`custom_status`	object	Objet du statut actuel, ou null.
`custom_sub_status`	object \| null	Objet du sous-statut actuel, ou null.

Champs d'objet de statut

Champ	Type	Description
`id`	string	Identifiant unique du statut personnalisé
`name`	string	Nom d'affichage du statut (utilise le nom public si configuré)
`color`	string	Code couleur hexadécimal du statut

Objet de sous-statut

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

Champs d'objet de notifications

Champ	Type	Description
`total_sent`	number	Nombre de notifications envoyées.
`total_failed`	number	Nombre de notifications en échec.
`errors`	array	Erreurs de notification par canal.

Champs d'un objet d'erreur de notification

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

Champs d'un objet d'erreur de métachamp

Champ	Type	Description
`orderId`	string	Identifiant de la commande dont le métachamp a échoué.
`message`	string	Message d'erreur lisible par l'humain.

Exemples

Requête de base

Requête cURL

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/line-items/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 '{"line_item_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","status_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","sub_status_option_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10"}'

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 Requête invalide

Statut d'article non activé, validation échouée, ou violation de la chaîne de produits

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é 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

403 Interdit

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

404 Non trouvé

Article, statut ou sous-statut non trouvé

404 Non trouvé

{
  "success": false,
  "error": "Line item 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"
  }
}