Sales API

Introduction #

The Optico Sales API (Customer Order API) records e-commerce orders and maps them to calls for conversion tracking. Your call center can then attribute revenue and conversions to specific calls, agents, keywords, and marketing sources, so you know what each call is worth.

Transport & Conventions

Getting Started #

The Sales API is the final step in the Optico call center integration. It connects your e-commerce order management system with the call tracking platform to close the attribution loop between marketing spend and revenue.

Authentication #

Every request must include your key as a POST field. This is the Customer API key for your domain, the same key used by the Cart API.

key=cust_b7e2c8a14f9dcdef01234567

Errors #

Response envelope

Every request returns 200 OK with a JSON envelope. Branch on the status field rather than the HTTP status code.

{ "status": "success" }

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

Common error messages

Idempotency

The endpoint is idempotent on your id: re-submitting the same order id updates the existing record rather than creating a duplicate. Submit on order creation and on every status change.

Retries & timeouts

Use a 5-second client timeout. Network timeouts and HTTP 5xx responses are safe to retry with exponential backoff (1s, 2s, 4s) because the endpoint is idempotent. Do not retry on a JSON {"status":"error"} body. Fix the payload and resubmit.

Rate limits

No fixed public rate limit is enforced for normal order traffic. For a bulk backfill (migrations, historical imports) contact Optico support so the channel can be sized for your account.

Endpoints #

POST /api/customer-order #

Creates or updates an order in Optico. If an order with the same id already exists for the domain, it is updated, making this endpoint idempotent. Submit on order creation and on every status change.

Parameters

Example request

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();

Products object #

The products parameter must be a JSON-encoded string containing an array of product objects.

Order statuses #

The status field must match one of the statuses configured in your Optico account under Call Center > Statuses. Each status can optionally be flagged as is_sale.

Order lifecycle #

The following flow shows how the Sales API fits into a complete Optico call center integration: