Synchroniser les données de commande par le back-end (recommandé)
Pour envoyer des données de commande à CitrusAd, utilisez une commande similaire à celle ci-dessous. Notez que les données inscrites dans le champ orders ci-dessous sont fictives et ne sont fournies qu'à titre d'exemple. Ces exemples sont tous affichés dans l'intégration standard.
Intégrer un ID de vendeur Marketplace ?
N'oubliez pas de lire la section ID de vendeur Marketplace ci-dessous.
Commande d'un seul article
Vous trouverez ci-dessous le contexte d'un client qui a acheté un seul article :
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
}
]
}
En cas de succès, l'objet suivant sera renvoyé :
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
Format orderDate
OrderDate au format ci-dessus est lu comme heure UTC. Vous devrez effectuer une synchronisation en UTC.
Vous pouvez également définir un décalage pour votre fuseau horaire, en remplaçant
Zpour+HH:MMcorrespondant à votre fuseau horaire. Par exemple, « orderDate » :“2021-12-02T15:00:00+10:00"spécifiera que le fuseau horaire est UTC+10.
Commande de plusieurs articles
Vous trouverez ci-dessous le contexte d'un client qui a acheté plusieurs articles. Le tableau orderItems contient plusieurs articles :
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
En cas de succès, l'objet suivant sera renvoyé :
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "a7e5cat7-9964-4ff3-bbb1-94bf9b53a366",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
},
{
"regularUnitPrice": 2.50,
"citrusDiscountAmount": null,
"gtin": "351998532P",
"adId": "",
"quantity": 1,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 2.50
}
],
"orderDate": "2021-12-02T15:00:00Z",
}
]
}
Synchroniser plusieurs commandes
Si vous synchronisez plusieurs commandes, vous pouvez envoyer jusqu'à 100 articles par lot avec chaque demande. Le nombre de requêtes que vous pouvez effectuer est illimité. La commande de la charge utile envoyée est la même que celle du résultat renvoyé. Cela garantit que les données restent conformes à la présentation des commandes dans votre back-end.
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00"
}
]
},
{
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"gtin": "5431998566P",
"quantity": 2,
"regularUnitPrice": "2.00",
"totalOrderItemPriceAfterDiscounts": "4.00"
}
]
}
]
}
En cas de succès, l'objet suivant sera renvoyé :
HTTP/2 200
{
"orders": [
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"id": "3h30e938-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"regularUnitPrice": 1.00,
"citrusDiscountAmount": null,
"gtin": "9891998566P",
"adId": "",
"quantity": 3,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 3.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
},
{
"adIds": null,
"teamId": "8616fcd8-5821-4465-9609-401d93fdc800",
"customerId": "rw3-v3ag-ol0",
"sessionId": "2m342-2dfe-0f",
"id": "i32dm3e4-c158-43d78-43ww32x-m2ide3e3",
"orderItems": [
{
"regularUnitPrice": 2.00,
"citrusDiscountAmount": null,
"gtin": "5431998566P",
"adId": "",
"quantity": 2,
"substitutedFor": null,
"totalOrderItemPriceAfterDiscounts": 4.00
}
],
"orderDate": "2021-12-02T15:00:00Z"
}
]
}
ID de vendeur Marketplace
Si vous souhaitez intégrer des vendeurs Marketplace, vous devez synchroniser le sellerId le cas échéant lors de la comptabilisation des commandes. Si le produit acheté n'est pas associé à un sellerId, il peut être omis.
Si vous n'intégrez aucun vendeur Marketplace, vous n'avez pas besoin de spécifier l'ID de vendeur dans le rapport de commande
Vous trouverez ci-dessous un exemple de commande contenant un produit qui provient d'un vendeur Marketplace et un autre non :
POST $BASE_URL/v1/orders HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
"orders": [
{
"customerId": "npc-s243-ir",
"catalogId": "6adb93d0-7he4-4d4e-9b47-e5d3714c976a",
"sessionId": "5cat7-9964-4f",
"orderDate": "2021-12-02T15:00:00Z",
"id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
"orderItems": [
{
"gtin": "9891998566P",
"quantity": 3,
"regularUnitPrice": "1.00",
"totalOrderItemPriceAfterDiscounts": "3.00",
"sellerId": "10sa-3s33-j8e3"
}
]
},
{
"gtin": "351998532P",
"quantity": 1,
"regularUnitPrice": "2.50",
"totalOrderItemPriceAfterDiscounts": "2.50"
}
]
}
]
}
Synchroniser les données de commande par le front-end (non recommandé)
Si vous n'êtes pas en mesure de synchroniser les données de commande via le back-end, CitrusAd propose une API ouverte tel qu'indiqué ci-dessous. Il est toutefois recommandé de l'utiliser uniquement si l'intégration back-end et la synchronisation par fichier ne sont pas possibles.
La comptabilisation des données via le front-end présente un risque plus élevé qu'une intégration back-end standard.
Les intégrateurs doivent être conscients du risque que le domaine de reporting puisse être bloqué ultérieurement par des logiciels anti-publicité, auquel cas CitrusAd ne pourra être tenu responsable des éventuelles données perdues.
Spécification de l'API ouverte :
openapi: 3.0.1
info:
title: Citrus
version: 1.0.0
paths:
/v1/resource/third-o:
get:
tags:
- resource
summary: Report an order.
operationId: resource-third-o
parameters:
- in: query
name: key
description: |
(Publishable) API key.
schema:
type: string
required: true
- in: query
name: teaid
description: |
Team id.
schema:
type: string
required: false
- in: query
name: catid
description: |
Catalog id.
schema:
type: string
required: true
- in: query
name: ordid
description: |
Order id.
schema:
type: string
required: true
- in: query
name: ordts
description: |
Order timestamp as a string in RFC3339.
schema:
type: string
required: true
- in: query
name: sesid
description: |
Session id.
schema:
type: string
required: true
- in: query
name: cusid
description: |
Customer id.
schema:
type: string
- in: query
name: procods
description: |
Product codes. Related by index to pris and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "procods=7913494","procods=6815686" ]
summary: "product code list"
required: true
- in: query
name: pris
description: |
Prices as strings. Related by index to itsids and quas. The length must match pris and quas.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "pris=7913494","pris=6815686" ]
summary: "prices list"
required: true
- in: query
name: quas
description: |
Quantities as strings. Related by index to itsids and pris. The length must match itsids and pris.
schema:
type: array
items:
type: string
examples:
uat:
value: [ "quas=7913494","quas=6815686" ]
summary: "quantity list"
required: true
responses:
200:
description: Successful operation.
content:
application/json:
schema:
type: object
400:
description: Invalid input.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
401:
description: Invalid credentails.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: Insufficient permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- apiKey: []
components:
schemas:
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
securitySchemes:
apiKey:
type: apiKey
name: Authorization
in: header
Si vous avez un doute sur les termes utilisés dans cette section, veuillez consulter la page Référence.
Récupération des informations de commande
Si vous souhaitez vérifier les informations de commande dans CitrusAd, vous devez effectuer une requête GET sur l'API /orders/ à l'aide de l'ID de commande.
GET $BASE_URL/v1/orders/<ORDER_ID> HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
Vous récupérerez toutes les informations relatives à la commande stockée dans le système CitrusAd.
Si la commande est introuvable, c'est qu'elle n'a pas été importée dans le système CitrusAd.