API Vente

Introduction #

L'API Optico Sales (Customer Order API) enregistre les commandes e-commerce et les associe aux appels pour le suivi des conversions. Votre centre d'appels peut alors attribuer le chiffre d'affaires et les conversions à des appels, agents, mots-clés et sources marketing précis, et savoir ce que chaque appel rapporte.

Transport & conventions

Démarrage #

L'API Sales est l'étape finale de l'intégration du centre d'appels Optico. Elle relie votre système de gestion de commandes e-commerce à la plateforme de call tracking pour boucler la chaîne d'attribution entre coût marketing et chiffre d'affaires.

Authentification #

Chaque requête doit inclure votre key en tant que champ POST. Il s'agit de la clé API Customer de votre domaine, la même clé que celle utilisée par l'API Cart.

key=cust_b7e2c8a14f9dcdef01234567

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

L'endpoint est idempotent sur votre id : renvoyer le même id de commande met à jour l'enregistrement existant au lieu d'en créer un doublon. Envoyez à la création de la commande et à chaque changement de statut.

Réessais & timeouts

Utilisez un timeout client de 5 secondes. Les timeouts réseau et les réponses HTTP 5xx peuvent être réessayés sans risque avec un backoff exponentiel (1s, 2s, 4s) car l'endpoint est idempotent. Ne réessayez pas sur un corps JSON {"status":"error"}. Corrigez le payload et renvoyez.

Limites de taux

Aucune limite de taux publique fixe n'est appliquée pour le trafic normal de commandes. Pour un backfill en masse (migrations, imports historiques), contactez le support Optico afin que le canal soit dimensionné pour votre compte.

Endpoints #

POST /api/customer-order #

Crée ou met à jour une commande dans Optico. Si une commande avec le même id existe déjà pour le domaine, elle est mise à jour, rendant cet endpoint idempotent. Envoyez à la création de la commande 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=cust_b7e2c8a14f9dcdef01234567" \
  -d "id=ORDER-5678" \
  -d "cart_id=CART-1234" \
  -d "visit_id=3617898c651df0f8617f70a0" \
  -d "status=confirmed" \
  -d "currency=EUR" \
  -d "agent=agent_john" \
  --data-urlencode 'products=[{"id":"PROD-001","name":"Blue Widget","quantity":2,"cost_per_unit":29.99},{"id":"PROD-007","name":"Red Gadget","quantity":1,"cost_per_unit":59.00}]'

$visitId = intval($_COOKIE['optico_visit_id'] ?? 0);

$params = [
    'key'      => 'cust_b7e2c8a14f9dcdef01234567',
    'id'       => 'ORDER-5678',
    'cart_id'  => 'CART-1234',
    'visit_id' => $visitId,
    'status'   => 'confirmed',
    'currency' => 'EUR',
    'agent'    => 'agent_john',
    'products' => json_encode([
        ['id' => 'PROD-001', 'name' => 'Blue Widget', 'quantity' => 2, 'cost_per_unit' => 29.99],
        ['id' => 'PROD-007', 'name' => 'Red Gadget',  'quantity' => 1, 'cost_per_unit' => 59.00],
    ]),
];

$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 products = [
  { id: 'PROD-001', name: 'Blue Widget', quantity: 2, cost_per_unit: 29.99 },
  { id: 'PROD-007', name: 'Red Gadget',  quantity: 1, cost_per_unit: 59.00 },
];

const body = new URLSearchParams({
  key:      'cust_b7e2c8a14f9dcdef01234567',
  id:       'ORDER-5678',
  cart_id:  'CART-1234',
  visit_id: visitId,
  status:   'confirmed',
  currency: 'EUR',
  agent:    'agent_john',
  products: JSON.stringify(products),
});

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

Objet Products #

Le paramètre products doit être une chaîne encodée en JSON contenant un tableau d'objets produit.

Statuts #

Le champ status doit correspondre à l'un des statuts configurés dans votre compte Optico sous Centre d'appels > Statuts. Chaque statut peut optionnellement être marqué is_sale.

Cycle de vie #

Le flux suivant montre comment l'API Sales s'intègre dans une intégration complète du centre d'appels Optico :