Last updated 24 oct. 2023

API de Panier

Aperçu

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

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

Une place de parking est un bon exemple de produit ajouté au panier Rokt. Par exemple, un partenaire de billetterie peut proposer des places de parking supplémentaires à ses clients lors de l'achat de billets d'événement. Ces places de parking sont fournies par un prestataire de stationnement tiers.

Intégration minimale

Pour répondre aux commandes des clients, vous devez intégrer les hooks et les points d'API suivants.

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

Réservation des articles

Certains articles doivent être réservés lors du paiement pour garantir que l'inventaire est toujours disponible lorsqu'ils confirment finalement leur achat. Les points d'extrémité suivants doivent être utilisés pour gérer la réservation.

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

Annulation d'articles confirmés

L'endpoint suivant est disponible pour annuler des articles après leur confirmation.

Appeler /confirmation/cancel

Flux de demande en cours de transaction

Pour répondre aux commandes des clients, les partenaires doivent suivre le flux de transaction suivant.

Flux de demande en cours de transaction

(Facultatif) Appeler /placements/any pour déterminer s'il y a des emplacements à afficher, afin de pouvoir passer l'étape de vente croisée/survente s'il n'y a pas d'offres pertinentes.
En fonction du résultat renvoyé par /placements/any, vous pouvez choisir d'afficher ou de sauter la page de survente dans le flux de transaction. Sur la page de survente, vous devez initialiser le Web SDK, qui demande et affiche les emplacements disponibles.
Une fois qu'un client a opté pour l'achat, 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) Appeler /cart/reserve pour réserver les articles pendant une période définie, pendant laquelle l'achat doit être effectué et confirmé avec Rokt.
Une fois qu'un client a payé les articles, appeler /cart/confirm pour confirmer l'achat réussi des articles. Rokt informe ensuite le fournisseur concerné des produits à livrer.
1. Pour annuler une réservation, appeler /cart/release. Cela 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é, appeler /confirmation/cancel. Cela convient aux partenaires qui souhaitent annuler un article après sa confirmation.

Authentification

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

Points d'accès de l'API

POST Tous les emplacements

Permet au partenaire de déterminer s'il existe des emplacements à afficher et éventuellement de sauter 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 pour ajouter au panier. En fonction de la valeur renvoyée (true ou false), le partenaire peut choisir d'afficher ou de sauter 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, like 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 de l'API	vrai	skeletonkey
`Content-Type`	header	Type de média de la demande, '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, le parrainage, les journaux et le débogage. Facultatif pour ce point de terminaison (sessionId généré s'il n'est pas fourni).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	Identifiant de balise Rokt unique	vrai	253_439d21r21r21321
`Accept-Language`	header	Locale attendue du consommateur. Il peut s'agir de la locale complète incluant la langue et le pays, ou d'une locale neutre qui ne contient que la langue. Lorsque la locale est spécifiée, seules les emplacements et les offres correspondant à la locale sont inclus pour considération.		en-US

Corps de la demande

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

Réponse

200 OK

{
  "resultat": true
}

Erreur

400 BadRequest

{
  "description": "string",
  "erreurs": [
    {
      "code": "string",
      "message": "string",
      "valeur": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "erreurs": [
    {
      "code": "string",
      "message": "string",
      "valeur": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "erreurs": [
    {
      "code": "string",
      "message": "string",
      "valeur": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "erreurs": [
    {
      "code": "string",
      "message": "string",
      "valeur": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "erreurs": [
    {
      "code": "string",
      "message": "string",
      "valeur": {}
    }
  ]
}

POST Réserver les articles du panier

Permet au partenaire de réserver / conserver les articles pendant une période déterminée pendant laquelle l'achat doit être effectué et confirmé avec Rokt. Cela permet aux partenaires de garantir le stock et de verrouiller le prix 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 renvoyé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, et d'autres peuvent être rejetés.

Exemple de demande

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

Demande

Chemin

POST /v1/cart/reserve

Paramètres

Nom	Emplacement	Description	Requis	Exemple
`rokt-api-key`	en-tête	Clé d'authentification de l'API	vrai	skeletonkey
`Content-Type`	en-tête	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	en-tête	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`	en-tête	SessionId utilisé par Rokt en interne pour le suivi, le parrainage, la journalisation et le débogage.	vrai	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	en-tête	Identifiant de tag Rokt unique	vrai	253_439d21r21r21321
`Accept-Language`	en-tête	Langue attendue du consommateur. Il peut s'agir de la langue complète incluant la langue et le pays, ou d'une langue neutre qui n'a que la langue. Lorsque la langue est spécifiée, seules les emplacements et les offres correspondant à la langue sont inclus pour examen.		en-US

Corps de la demande

{
  "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 concerné des produits à expédier.

Description

Après le paiement effectué pour tous les articles du panier, Rokt recommande d'appeler cette méthode pour tous les événements d'achat, sur toutes les plateformes, tous les appareils, tous les environnements (web/app), tous les pays et tous les 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 l'une des combinaisons suivantes :

cartItemId et itemReservationId
cartItemId et quantity

Demande

Chemin

POST /v1/cart/confirm

Paramètres

Nom	Emplacement	Description	Requis	Exemple
`rokt-api-key`	en-tête	Clé d'authentification de l'API	vrai	skeletonkey
`Content-Type`	en-tête	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	en-tête	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`	en-tête	SessionId utilisé par Rokt en interne pour le suivi, le parrainage, l'enregistrement et le débogage. Facultatif lorsque aucun article n'est inclus (sessionId généré s'il n'est pas fourni).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	en-tête	Identifiant de tag Rokt unique	vrai	253_439d21r21r21321
`Accept-Language`	en-tête	Locale attendue du consommateur. Il peut s'agir de la locale complète comprenant la langue et le pays, ou d'une locale neutre qui n'a que la langue. Lorsque la locale est spécifiée, seules les emplacements et les offres correspondant à la locale sont inclus pour examen.		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	Emplacement	Description	Requis	Exemple
`rokt-api-key`	en-tête	Clé d'authentification de l'API	vrai	skeletonkey
`Content-Type`	en-tête	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	en-tête	Type de média attendu de la réponse, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept-Language`	en-tête	Langue attendue du consommateur. Il peut s'agir de la langue et du pays complets, ou d'une langue neutre qui ne comporte que la langue. Lorsque la langue est spécifiée, seules les emplacements et les offres correspondant à la langue 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 Non autorisé

403 Interdit

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

422 Entité non traitable

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

500 Erreur interne du serveur

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

504 Délai d'attente de la passerelle dépassé

{
  "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. 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 ayant un trafic très fluctuant nécessitant une libération rapide des articles réservés.

Description

Lorsque l'utilisateur supprime un article réservé de son panier ou annule complètement son panier/transaction. Les articles du panier réservés finiront par expirer et être automatiquement libérés, mais un partenaire peut souhaiter accélérer ce processus s'il dispose d'un environnement à trafic fluctuant ou à fort trafic 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"
            }
        ]
    }

Demande

Chemin

POST /v1/cart/release

Paramètres

Nom	Emplacement	Description	Requis	Exemple
`rokt-api-key`	en-tête	Clé d'authentification de l'API	vrai	skeletonkey
`Content-Type`	en-tête	Type de média de la requête, 'application/json' est la seule valeur prise en charge pour le moment		application/json
`Accept`	en-tête	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`	en-tête	SessionId utilisé par Rokt en interne pour le suivi, les références, les journaux et le débogage.	vrai	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	en-tête	Identifiant de balise Rokt unique	vrai	253_439d21r21r21321
`Accept-Language`	en-tête	Langue attendue du consommateur. Il peut s'agir de la langue complète incluant la langue et le pays, ou d'une langue neutre qui n'a que la langue. Lorsque la langue est spécifiée, seules les emplacements et les offres correspondant à la langue sont inclus pour examen.		en-US

Corps de la demande

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

Aperçu​

Intégration minimale​

Réservation des articles​

Annulation d'articles confirmés​

Flux de demande en cours de transaction​

Authentification​

Points d'accès de l'API​

POST Tous les emplacements​

Description​

Demande​

Réponse​

Erreur​

POST Réserver les articles du panier​

Description​

Demande​

Réponse​

Erreur​

POST Confirmer les articles du panier​

Description​

Demande​

Réponse​

Erreur​

POST Annuler un article acheté​

Description​

Requête​

Réponse​

Erreur​

POST Libérer les articles du panier​

Description​

Demande​

Réponse​

Erreur​

Aperçu

Intégration minimale

Réservation des articles

Annulation d'articles confirmés

Flux de demande en cours de transaction

Authentification

Points d'accès de l'API

POST Tous les emplacements

Description

Demande

Réponse

Erreur

POST Réserver les articles du panier

Description

Demande

Réponse

Erreur

POST Confirmer les articles du panier

Description

Demande

Réponse

Erreur

POST Annuler un article acheté

Description

Requête

Réponse

Erreur

POST Libérer les articles du panier

Description

Demande

Réponse

Erreur