Implementazione dell'API Cart

Questa guida fornisce il riferimento tecnico dell'API e gli schemi del payload per l'integrazione dell'API carrello dell'Universal Commerce Protocol (UCP) nella versione 2026-04-08.

Prima di creare gli endpoint, assicurati di aver esaminato la panoramica dell'API Cart per i concetti e i prerequisiti di alto livello.

Crea carrello

Questo endpoint consente la creazione di una nuova sessione del carrello. Per l'integrazione, implementa l'endpoint CreateCart (POST /carts). Quando un utente sceglie di trasferire il proprio carrello, Google chiama questo endpoint con tutti i dettagli delle voci di ordine. Il sistema deve rispondere con un continue_url che indirizza l'utente al carrello precompilato sul tuo sito.

  • Endpoint: POST /carts
  • Attivatore:viene attivata una singola richiesta CreateCart (POST /carts) solo quando l'utente fa clic sul pulsante di trasferimento (ad esempio, Acquisto rapido sul commerciante) per trasferire il carrello al tuo negozio.

Flusso del carrello

Il flusso e lo stato del carrello funzionano nel seguente modo:

  • Accumulo su Google: quando un utente aggiunge articoli al carrello, Google li accumula localmente. Google non attiva più chiamate API man mano che vengono aggiunti elementi.
  • Il payload:la singola richiesta POST /carts conterrà l'array completo di tutti i line_items accumulati contemporaneamente.
  • Reindirizzamento e stato:il backend del commerciante risponde con un continue_url che rimanda al carrello precompilato sul suo sito web.

Richiesta: Google invia l'array di line_items da aggiungere al carrello.

Esempio di richiesta:

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

Risposta: restituisci la sessione del carrello inizializzata, inclusi i dettagli delle voci dell'ordine, i totali e un continue_url. Il campo continue_url nella risposta deve reindirizzare l'utente a una pagina del tuo sito in cui può continuare a gestire il carrello. In genere, questo link rimanda alla pagina del carrello o di pagamento con la sessione identificata da id precaricata.

Esempio di risposta:

{
  "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"
}

Gestione degli errori

Per le linee guida complete sulla formattazione dei messaggi di errore e sulla distinzione tra errori di protocollo e di logica di business, consulta la sezione Codici di errore.

Avanti
Codici promozionali e sconti