Implémentation de Cart API

Ce guide fournit la documentation de référence technique de l'API et les schémas de charge utile nécessaires à l'intégration de Cart API pour l'Universal Commerce Protocol (UCP) version 2026-04-08.

Avant de créer vos points de terminaison, veillez à consulter la présentation de Cart API pour vous familiariser avec les concepts clés et les conditions préalables.

Créer un panier

Ce point de terminaison permet de créer une session de panier. Pour l'intégrer, implémentez le point de terminaison CreateCart (POST /carts). Lorsqu'un utilisateur choisit de transférer son panier, Google appelle ce point de terminaison avec les détails de tous les articles. Votre système doit répondre avec une continue_url redirigeant l'utilisateur vers son panier prérempli sur votre site.

• Point de terminaison : POST /carts
• Déclencheur : une requête CreateCart (POST /carts) unique est déclenchée lorsque l'utilisateur clique sur le bouton de transfert (par exemple, Payer sur le site du marchand) pour transférer son panier vers votre magasin.

Flux du panier

Le flux et l'état du panier fonctionnent comme suit :

• Accumulation sur Google : lorsqu'un utilisateur ajoute des articles à son panier, Google les accumule localement. Google ne déclenche pas plusieurs appels d'API à mesure que des articles sont ajoutés.
• La charge utile : la requête POST /carts unique contiendra l'intégralité du tableau avec tous les line_items accumulés.
• Redirection et état : le backend du marchand répond avec une continue_url qui pointe vers le panier prérempli sur son site Web.

Requête : Google envoie le tableau des line_items à ajouter au panier.

Exemple de requête :

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ]
}

Réponse : vous renvoyez la session de panier initialisée, y compris les détails des éléments, les totaux et une continue_url. Le champ continue_url de la réponse doit rediriger l'utilisateur vers une page de votre site où il peut continuer à gérer le panier. Il s'agit généralement d'un lien vers votre panier ou votre page de paiement avec la session identifiée par id préchargée.

Exemple de réponse :

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces.
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid.
  "expires_at": "2026-01-16T12:00:00Z"
}

Gestion des erreurs

Pour obtenir des instructions complètes sur la mise en forme des messages d'erreur et sur la distinction entre les erreurs de protocole et de logique métier, consultez la section Codes d'erreur.