API Panier

Introduction #

L'API Cart envoie à Optico les données de panier et de commande en temps réel. Couplée au service Optico Tracking, elle relie chaque achat à la session visiteur, à la source, aux mots-clés et aux appels passés. Les agents voient le panier en cours, l'historique des commandes et le parcours de navigation de l'appelant directement dans l'interface du centre d'appels, et Optico rattache le chiffre d'affaires au coût marketing qui l'a généré.

Transport & conventions

Authentification #

Chaque requête doit inclure votre key en tant que champ POST. La clé est unique pour l'ensemble de vos domaines enregistrés et elle est délivrée à la création de votre compte sur www.optico.fr.

key=b7e2c8a14f9d3650a1e7c4d8b2f6a395e

Erreurs #

Enveloppe de réponse

Chaque requête renvoie 200 OK avec une enveloppe JSON. Branchez-vous sur le champ status plutôt que sur le code HTTP.

{ "status": "success" }

{ "status": "error",
  "message": "Invalid API key" }

Messages d'erreur courants

Idempotence

Les deux endpoints sont idempotents sur votre champ id : renvoyer le même id de panier ou de commande met à jour l'enregistrement existant au lieu d'en créer un doublon. C'est un choix de conception pour que votre intégration puisse réessayer sans risque sur les défaillances transitoires.

Réessais & timeouts

Utilisez un timeout client de 5 secondes. Un timeout réseau ou une réponse HTTP 5xx peut être réessayé sans risque avec un backoff exponentiel (par exemple 1s, 2s, 4s) car les endpoints sont idempotents. Ne réessayez pas sur un corps JSON {"status":"error"}. La requête a été reçue puis rejetée ; inspectez le message et corrigez le payload.

Limites de taux

Aucune limite de taux publique fixe n'est appliquée pour le trafic normal. L'API est conçue pour être appelée à chaque modification de panier et de commande. Si vous prévoyez un backfill en masse ou un trafic soutenu au-delà de quelques centaines de requêtes par seconde, contactez Optico à l'avance pour dimensionner le canal pour votre compte.

Endpoints #

POST /api/customer-cart #

Insère ou met à jour un panier. Appelez cet endpoint à chaque modification du panier.

Paramètres

Exemple de requête

curl -X POST https://www.optico.fr/api/customer-cart \
  --max-time 5 \
  -d "key=b7e2c8a14f9d3650a1e7c4d8b2f6a395e" \
  -d "id=1" \
  -d "currency=EUR" \
  -d "visit_id=3617898c651df0f8617f70a0" \
  -d "is_logged_in=1" \
  --data-urlencode 'products[0][id]=1' \
  --data-urlencode 'products[0][name]=Product 1' \
  --data-urlencode 'products[0][quantity]=2' \
  --data-urlencode 'products[0][price]=29.99'

// Lecture du visit ID depuis le cookie (JS : optico_visitId / API : optico_visit_id)
$visitId = $_COOKIE['optico_visit_id'] ?? '';

$params = [
    'key'          => 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
    'id'           => '1',
    'currency'     => 'EUR',
    'visit_id'     => $visitId,
    'is_logged_in' => 1,
    'products'     => [[
        'id'       => 1,
        'name'     => 'Product 1',
        'quantity' => 2,
        'price'    => 29.99,
        'details'  => 'some product details',
    ]],
];

$ch = curl_init('https://www.optico.fr/api/customer-cart');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($params),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Node 18+ (fetch natif). Lisez visit_id depuis votre stockage de cookies.
const params = new URLSearchParams();
params.append('key', 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e');
params.append('id', '1');
params.append('currency', 'EUR');
params.append('visit_id', visitId);
params.append('is_logged_in', '1');
params.append('products[0][id]', '1');
params.append('products[0][name]', 'Product 1');
params.append('products[0][quantity]', '2');
params.append('products[0][price]', '29.99');

const res = await fetch('https://www.optico.fr/api/customer-cart', {
  method: 'POST',
  body:   params,
  signal: AbortSignal.timeout(5000),
});
const data = await res.json();

Réponse

{ "status": "success" }

{ "status": "error",
  "message": "..." }

POST /api/customer-order #

Insère ou met à jour une commande. Appelez cet endpoint lorsqu'une commande est créée et à chaque changement de statut.

Paramètres

Exemple de requête

curl -X POST https://www.optico.fr/api/customer-order \
  --max-time 5 \
  -d "key=b7e2c8a14f9d3650a1e7c4d8b2f6a395e" \
  -d "id=1" \
  -d "cart_id=1" \
  -d "currency=EUR" \
  -d "visit_id=3617898c651df0f8617f70a0" \
  -d "status=Completed" \
  --data-urlencode 'products[0][id]=1' \
  --data-urlencode 'products[0][name]=Product 1' \
  --data-urlencode 'products[0][quantity]=2' \
  --data-urlencode 'products[0][price]=29.99'

$visitId = $_COOKIE['optico_visit_id'] ?? '';

$params = [
    'key'      => 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
    'id'       => '1',
    'cart_id'  => '1',
    'currency' => 'EUR',
    'visit_id' => $visitId,
    'status'   => 'Completed',
    'products' => [[
        'id'       => 1,
        'name'     => 'Product 1',
        'quantity' => 2,
        'price'    => 29.99,
    ]],
];

$ch = curl_init('https://www.optico.fr/api/customer-order');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($params),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const params = new URLSearchParams();
params.append('key', 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e');
params.append('id', '1');
params.append('cart_id', '1');
params.append('currency', 'EUR');
params.append('visit_id', visitId);
params.append('status', 'Completed');
params.append('products[0][id]', '1');
params.append('products[0][name]', 'Product 1');
params.append('products[0][quantity]', '2');
params.append('products[0][price]', '29.99');

const res = await fetch('https://www.optico.fr/api/customer-order', {
  method: 'POST',
  body:   params,
  signal: AbortSignal.timeout(5000),
});
const data = await res.json();

Réponse

{ "status": "success" }

{ "status": "error",
  "message": "..." }

Objet Products #

Chaque élément du tableau products est un objet produit avec les clés suivantes :

Exemples du champ details

'details' => 'some product details'

'details' => [
  'color'      => 'blue',
  'dimensions' => [
    'width'  => '20cm',
    'height' => '20cm',
    'length' => '20cm'
  ]
]

Notes d'intégration #

Obtenir le visit_id

Le visit_id provient du service Optico Tracking et identifie la session du visiteur. Lisez-le depuis le cookie approprié selon votre méthode de tracking :

Flux d'intégration

Relier les paniers et les commandes aux appels

Lorsqu'un visiteur appelle alors que l'API Call Center est active, vous pouvez avoir accès au call_id courant et au nom d'utilisateur de l'agent qui prend l'appel. Transmettez ces champs optionnels pour associer directement l'enregistrement panier ou commande à l'appel et à l'agent ; cela enrichit la timeline d'appel visible côté agent.