API de Panier

Vue d'ensemble

Avec l'API de Panier, les partenaires de Rokt peuvent ajouter des produits supplémentaires au panier d'un client lors d'une transaction. L'API de Panier fonctionne avec le SDK Web pour aider à rendre les placements frontend et fournir des hooks pour mettre à jour le panier d'un client. Deux intégrations sont nécessaires pour activer les ventes incitatives via Rokt :

Intégrez votre système de panier/checkout backend avec l'API de Panier de Rokt (cette documentation).
Intégrez le SDK Web dans votre frontend de panier.

Un emplacement de parking est un bon exemple de produit Rokt à ajouter au panier. Par exemple, un partenaire de billetterie peut proposer des emplacements de parking à ses clients pendant qu'ils achètent des billets pour un événement. Ces emplacements de parking sont fournis par un prestataire de parking tiers.

Intégration Minimale

Pour satisfaire les commandes des clients, vous devez vous intégrer avec le hook et l'endpoint API suivants.

Abonnez-vous aux événements V2_CART_ITEM_UPDATED pour être informé lorsqu'un utilisateur ajoute des articles à son panier.
Appelez /cart/confirm pour confirmer l'achat réussi des articles.

Réservation d'articles

Certaines articles doivent être réservés lors du passage en caisse pour garantir que le stock est toujours disponible lorsqu'ils sont finalement confirmés. Les points de terminaison suivants doivent être utilisés pour gérer la réservation.

Appelez /cart/reserve pour réserver les articles pendant une période déterminée.
Facultativement, appelez /cart/release pour annuler une réservation et permettre à d'autres clients de réserver ces articles.

Annulation des articles confirmés

Le point de terminaison suivant est disponible pour annuler des articles après qu'ils aient été confirmés.

Appelez /confirmation/cancel

Flux de requêtes en transaction

Pour satisfaire les commandes des clients, les partenaires doivent respecter le flux de transaction suivant.

Flux de requêtes en transaction

(Facultatif) Appelez /placements/any pour déterminer s'il y a des placements à afficher, afin de pouvoir passer l'étape de vente croisée/vente incitative s'il n'y a pas d'offres pertinentes.
En fonction de si /placements/any renvoie vrai ou faux, vous pouvez choisir d'afficher ou de passer la page de vente incitative dans le flux de transaction. Sur la page de vente incitative, vous devez initialiser le Web SDK, qui demande et affiche les placements disponibles.
Une fois qu'un client accepte, le Web SDK informe le frontend du partenaire en envoyant le message V2_CART_ITEM_UPDATED. Ensuite, le processus d'achat normal se poursuit.
(Facultatif) Appelez /cart/reserve pour réserver les articles pendant une période déterminée durant laquelle l'achat doit être complété et confirmé avec Rokt.
Une fois qu'un client paie pour les articles, appelez /cart/confirm pour confirmer l'achat réussi des articles. Rokt informe ensuite le fournisseur pertinent des produits pour la réalisation.
1. Pour annuler une réservation, appelez /cart/release. Ceci est facultatif car les articles réservés qui ne sont pas confirmés sont automatiquement libérés après un délai d'expiration. Cela convient aux partenaires à fort trafic qui nécessitent une libération rapide des articles réservés.
2. Pour annuler un article confirmé, appelez /confirmation/cancel. Cela convient aux partenaires qui souhaitent annuler un article après qu'il ait été confirmé.

Authentification

Veuillez contacter votre gestionnaire de compte Rokt pour configurer l'authentification pour vous.

Points de terminaison (API Endpoints)

POST Any Placements

Permet au partenaire de déterminer s'il y a des emplacements à afficher et potentiellement de passer l'étape de vente incitative/croisée si applicable.

Description

Pour décider s'il vaut la peine d'afficher la page contenant l'emplacement Rokt d'ajout au panier. En fonction de si cela retourne vrai ou faux, le partenaire peut choisir d'afficher ou de passer la page de vente incitative dans le flux de transaction.

Exemple de requête

POST /v1/placements/any
{
    "cartId": "1580265846172",
    "attributes": {
        "eventId": "1100526195FA115A",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, comme Gecko) Chrome/76.0.3809.100 Safari/537.36",
        "venueName": "Madison Square Garden",
        "eventdate": "20311212",
        "country": "US",
        "locale": "en-US"
    },
"pageIdentifier": "checkout.upsell"
}

Demande

Chemin

POST /v1/Placements/any

Paramètres

Nom	Dans	Description	Requis	Exemple
`rokt-api-key`	header	Clé d'authentification API	true	skeletonkey
`Content-Type`	header	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	header	Type de média attendu de la réponse, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`rokt-session-id`	header	SessionId utilisé par Rokt en interne pour le suivi, la référence, la journalisation et le débogage. Optionnel pour ce point de terminaison (sessionId généré si non fourni).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	ID de Tag Rokt unique	true	253_439d21r21r21321
`Accept-Language`	header	Locale attendue du consommateur. Cela peut être la locale complète incluant la langue et le pays, ou une locale neutre qui ne contient que la langue. Lorsque la locale est spécifiée, seuls les placements et offres correspondant à la locale sont pris en compte.		en-US

Corps de la demande

{
  "cartId": "string",
  "pageIdentifier": "string",
  "url": "string",
  "attributes": {
    "attribute": "string"
  }
}

Réponse

200 OK

{
  "result": true
}

Erreur

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Réserver les Articles du Panier

Permet au partenaire de réserver/mettre de côté les articles pour une période définie pendant laquelle l'achat doit être complété et confirmé avec Rokt. Cela permet aux partenaires de s'assurer que le stock et le prix sont garantis pendant la durée de la réservation.

Description

Lorsque l'utilisateur a finalisé la sélection des articles du catalogue mais n'a pas encore payé, la réservation des articles du panier garantit l'approvisionnement en stock et verrouille le prix selon les valeurs retournées. Si plusieurs articles du panier sont passés dans cette méthode, certains d'entre eux peuvent être réservés avec succès, tandis que d'autres peuvent être rejetés.

Exemple de requête

    POST /v1/cart/reserve
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": 1
            }
        ]
    }

Requête

Chemin

POST /v1/cart/reserve

Paramètres

Nom	Dans	Description	Requis	Exemple
`rokt-api-key`	header	Clé d'authentification API	true	skeletonkey
`Content-Type`	header	Type de média de la requête, 'application/json' est la seule valeur supportée pour le moment		application/json
`Accept`	header	Type de média attendu de la réponse, 'application/json' est la seule valeur supportée pour le moment		application/json
`rokt-session-id`	header	SessionId utilisé par Rokt en interne pour le suivi, la référence, la journalisation et le débogage.	true	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	ID unique de Tag Rokt	true	253_439d21r21r21321
`Accept-Language`	header	Locale attendue du consommateur. Cela peut être la locale complète incluant la langue et le pays, ou une locale neutre qui n'a que la langue. Lorsque la locale est spécifiée, seuls les placements et offres correspondant à la locale sont pris en compte.		en-US

Corps de la requête

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "quantity": 0
    }
  ],
  "isPayPalPayment": true,
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

Réponse

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0,
      "unitPrice": 0,
      "totalPrice": 0,
      "currency": "string",
      "expirationDateTimeUtc": "2025-10-04T10:00:00.000Z",
      "success": true
    }
  ],
  "payPalOrderId": "string"
}

Erreur

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Confirmer les Articles du Panier

Permet au partenaire de confirmer l'achat réussi des articles. Rokt informera ensuite le fournisseur pertinent des produits pour la réalisation.

Description

Après que le paiement soit traité pour tous les articles du panier. Rokt conseille que cela soit appelé pour tous les événements d'achat, y compris sur toutes les plateformes, appareils, environnements (web/app), pays et canaux.

Exemple de requête #1

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

Exemple de requête #2

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": "15"
            }
        ]
    }

La collection items doit contenir au moins soit - cartItemId et itemReservationId ou - cartItemId et quantity

Requête

Chemin

POST /v1/cart/confirm

Paramètres

Nom	Dans	Description	Requis	Exemple
`rokt-api-key`	header	Clé d'authentification API	true	skeletonkey
`Content-Type`	header	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	header	Type de média attendu de la réponse, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`rokt-session-id`	header	SessionId utilisé par Rokt en interne pour le suivi, la référence, la journalisation et le débogage. Optionnel lorsque aucun article n'est inclus (sessionId généré si non fourni).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	ID unique du tag Rokt	true	253_439d21r21r21321
`Accept-Language`	header	Locale attendue du consommateur. Cela peut être la locale complète incluant la langue et le pays, ou une locale neutre qui ne comporte que la langue. Lorsque la locale est spécifiée, seuls les emplacements et offres correspondant à la locale sont pris en compte.		en-US

Corps de la requête

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0
    }
  ],
  "payPalOrderId": "string",
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

Réponse

200 OK

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "itemConfirmationId": "string",
      "itemConfirmationUrl": "string",
      "success": true
    }
  ]
}

Erreur

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Annuler un article acheté

Permet au partenaire d'annuler un article précédemment acheté (confirmé). Rokt appellera le fournisseur concerné pour effectuer une annulation et transmettra sa réponse.

Description

Exemple de requête

    POST /v1/confirmation/cancel
    {
        "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
    }

Requête

Chemin

POST /v1/confirmation/cancel

Paramètres

Nom	Dans	Description	Requis	Exemple
`rokt-api-key`	header	Clé d'authentification API	true	skeletonkey
`Content-Type`	header	Type de média de la requête, 'application/json' est la seule valeur supportée pour le moment		application/json
`Accept`	header	Type de média attendu de la réponse, 'application/json' est la seule valeur supportée pour le moment		application/json
`Accept-Language`	header	Locale attendue du consommateur. Cela peut être la locale complète incluant la langue et le pays, ou une locale neutre qui n'a que la langue. Lorsque la locale est spécifiée, seuls les placements et offres correspondant à la locale sont pris en compte.		en-US

Corps de la requête

{
  "itemReservationId": "string"
}

Réponse

200 OK

Erreur

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Libérer les Articles du Panier

Permet au partenaire d'annuler une réservation sur un ensemble d'articles. Cela est optionnel car les articles réservés qui ne sont pas confirmés sont automatiquement libérés après un délai d'expiration. Cela convient aux partenaires ayant un trafic très variable nécessitant une libération rapide des articles réservés.

Description

Lorsque l'utilisateur retire un article réservé de son panier ou annule complètement son panier/transaction. Les articles réservés du panier finiront par expirer et être automatiquement libérés, mais un partenaire peut vouloir accélérer ce processus s'il a un environnement à trafic élevé ou variable pour éviter une épuisement prématuré ou temporaire de l'offre.

Exemple de requête

 POST /v1/cart/release
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

Requête

Chemin

POST /v1/cart/release

Paramètres

Nom	Dans	Description	Requis	Exemple
`rokt-api-key`	header	Clé d'authentification API	true	skeletonkey
`Content-Type`	header	Type de média de la requête, 'application/json' est la seule valeur supportée pour le moment		application/json
`Accept`	header	Type de média attendu de la réponse, 'application/json' est la seule valeur supportée pour le moment		application/json
`rokt-session-id`	header	SessionId utilisé par Rokt en interne pour le suivi, la référence, la journalisation et le débogage.	true	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	ID unique du Tag Rokt	true	253_439d21r21r21321
`Accept-Language`	header	Locale attendue du consommateur. Cela peut être la locale complète incluant la langue et le pays, ou une locale neutre qui ne comporte que la langue. Lorsque la locale est spécifiée, seuls les emplacements et offres correspondant à la locale sont pris en compte.		en-US

Corps de la requête

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string"
    }
  ],
  "attributes": {
    "attribute": "string"
  }
}

Réponse

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "success": true
    }
  ]
}

Erreur

400 MauvaiseRequête (BadRequest)

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 NonAutorisé (Unauthorized)

403 Interdit (Forbidden)

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 EntitéNonTraitée (UnprocessableEntity)

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 ErreurInterneDuServeur (InternalServerError)

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 TempsD'attentePassé (GatewayTimeout)

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

Vue d'ensemble​

Intégration Minimale​

Réservation d'articles​

Annulation des articles confirmés​

Flux de requêtes en transaction​

Authentification​

Points de terminaison (API Endpoints)​

POST Any Placements​

Description​

Demande​

Réponse​

Erreur​

POST Réserver les Articles du Panier​

Description​

Requête​

Réponse​

Erreur​

POST Confirmer les Articles du Panier​

Description​

Requête​

Réponse​

Erreur​

POST Annuler un article acheté​

Description​

Requête​

Réponse​

Erreur​

POST Libérer les Articles du Panier​

Description​

Requête​

Réponse​

Erreur​

Vue d'ensemble

Intégration Minimale

Réservation d'articles

Annulation des articles confirmés

Flux de requêtes en transaction

Authentification

Points de terminaison (API Endpoints)

POST Any Placements

Description

Demande

Réponse

Erreur

POST Réserver les Articles du Panier

Description

Requête

Réponse

Erreur

POST Confirmer les Articles du Panier

Description

Requête

Réponse

Erreur

POST Annuler un article acheté

Description

Requête

Réponse

Erreur

POST Libérer les Articles du Panier

Description

Requête

Réponse

Erreur