Přeskočit na hlavní obsah
Zoneo.cz Zoneo Group
V1 Technická dokumentace
Prokliky a výkon Kontaktovat Zoneo

API kontrakt V1

Doporučujeme server-to-server API. JavaScript je pouze volitelná záložní analytická cesta a funguje jen po udělení analytického souhlasu.

API kontrakt V1 Odkaz na sekci API kontrakt V1

Doporučujeme server-to-server API. JavaScript je pouze volitelná záložní analytická cesta a funguje jen po udělení analytického souhlasu.

Objednávky, tržby a odvozené metriky se zobrazují pouze při aktivním měření konverzí. Slouží k analytice a nemění vyúčtování CPC.

schema_version

1.0

payload_contract

order_v1

Content-Type

application/json

request_limit

64 KiB

Jak měření propojit Odkaz na sekci Jak měření propojit

Doporučujeme server-to-server API. JavaScript je pouze volitelná záložní analytická cesta a funguje jen po udělení analytického souhlasu.

  1. 1 Uložte parametr zclid z cílové URL ke košíku nebo objednávce na 30 dní.
  2. 2 Na serveru vytvořte stabilní HMAC-SHA-256 otisk interního ID objednávky pomocí samostatného klíče. Surové ID ani osobní údaje neposílejte.
  3. 3 Po vytvoření objednávky odešlete JSON na API a přesné tělo požadavku podepište integračním tajným klíčem.
  4. 4 Pro platbu, zrušení a kumulativní refundace znovu použijte stejné zclid a order_id_hash. Finální součty a položky objednávky už neměňte.

Integrační tajný klíč se zobrazí pouze jednou. Uložte jej do správce tajemství na serveru obchodu.

Doporučeno: server-to-server API Odkaz na sekci Doporučeno: server-to-server API

Server obchodu posílá ověřené objednávky, změny stavů a refundace přímo do Zoneo. Tajný klíč nikdy nevkládejte do prohlížeče.

POST https://zoneo.cz/api/v1/conversions
Sandbox https://zoneo.cz/api/v1/conversions/sandbox

Na serveru vytvořte stabilní HMAC-SHA-256 otisk interního ID objednávky pomocí samostatného klíče. Surové ID ani osobní údaje neposílejte.

order_id_hash · PHP 

$orderIdHash = hash_hmac(
    'sha256',
    "zoneo-order-v1\n".$internalOrderId,
    $_ENV['ZONEO_ORDER_HASH_KEY'],
);

Příklad požadavku Odkaz na sekci Příklad požadavku

Po vytvoření objednávky odešlete JSON na API a přesné tělo požadavku podepište integračním tajným klíčem.

order_v1 · JSON 

{
    "schema_version": "1.0",
    "zclid": "018fb72a-7d8e-7c3c-a4da-f37ce07ad739",
    "order_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "CZK",
    "occurred_at": "2026-08-31T12:34:56Z",
    "status": "placed",
    "refund_amount_minor": 0,
    "totals": {
        "items_gross_minor": 14000,
        "discount_minor": 1500,
        "shipping_gross_minor": 390,
        "fees_gross_minor": 100,
        "tax_minor": 2165,
        "order_total_gross_minor": 12990
    },
    "items": [
        {
            "merchant_item_id": "ITEM_ID_FROM_FEED",
            "item_group_id": "MODEL-10",
            "variant_id": "size:42",
            "name": "PRODUCT_NAME",
            "gtin": "8581234567890",
            "quantity": 2,
            "unit_price_gross_minor": 7000,
            "line_total_gross_minor": 14000
        }
    ],
    "order_locale": "cs",
    "expected_delivery_date": "2026-09-03"
}
order_v1 · JSON
JSON Povinná pole V1
schema_version ✓ = "1.0"
zclid ✓ UUID
order_id_hash ✓ HMAC-SHA-256 · [a-f0-9]{64}
currency ✓ ISO 4217 · CZK
occurred_at ✓ ISO 8601 · UTC
status ✓ placed | paid | cancelled | partially_refunded | refunded
refund_amount_minor ✓ integer ≥ 0 · Σ · monotonic
totals ✓ object · integer · gross
items ✓ array[1..100]
order_locale — BCP 47
expected_delivery_date — YYYY-MM-DD
order_v1 · items[]
items[] Povinná pole V1
merchant_item_id ✓ feed.ITEM_ID · stable
quantity ✓ integer · 1..1000
unit_price_gross_minor ✓ integer ≥ 0
line_total_gross_minor ✓ unit_price_gross_minor × quantity
item_group_id — string
variant_id — string
name — string · PRODUCT_NAME · PII = 0
gtin — [0-9]{8,14}

totals · CZK · integer 

totals.items_gross_minor = sum(items[].line_total_gross_minor)

totals.order_total_gross_minor = totals.items_gross_minor - totals.discount_minor + totals.shipping_gross_minor + totals.fees_gross_minor

line_total_gross_minor = unit_price_gross_minor × quantity

Kanonický podpis Odkaz na sekci Kanonický podpis

Uložený tajný klíč se z bezpečnostních důvodů již nezobrazuje. Pokud jej nemáte, vygenerujte nový a ihned jej bezpečně uložte.

HTTP · HMAC-SHA-256
HTTP V1
Content-Type application/json
X-Zoneo-Integration-ID zci_...
X-Zoneo-Timestamp Unix · UTC
X-Zoneo-Nonce CSPRNG · unique · len ≥ 16
Idempotency-Key order:{hash}:{status}
X-Zoneo-Signature v1=HMAC_SHA256_HEX

HMAC-SHA-256 · canonical request 

UPPERCASE_HTTP_METHOD
/exact/request/path
unix_timestamp
nonce
idempotency_key
sha256_hex_of_exact_raw_body

body_hash = SHA256(raw_body)
signature = HMAC_SHA256(api_secret, canonical_request)
X-Zoneo-Signature = "v1=" + lowercase_hex(signature)

S2S · PHP 

<?php

$path = '/api/v1/conversions';
$body = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
$timestamp = time();
$nonce = bin2hex(random_bytes(16));
$idempotencyKey = 'order:'.$orderIdHash.':'.$payload['status'];
$canonical = implode("\n", [
    'POST',
    $path,
    (string) $timestamp,
    $nonce,
    $idempotencyKey,
    hash('sha256', $body),
]);
$signature = hash_hmac('sha256', $canonical, $_ENV['ZONEO_API_SECRET']);

$headers = [
    'Content-Type: application/json',
    'X-Zoneo-Integration-ID: '.$_ENV['ZONEO_INTEGRATION_ID'],
    'X-Zoneo-Timestamp: '.$timestamp,
    'X-Zoneo-Nonce: '.$nonce,
    'Idempotency-Key: '.$idempotencyKey,
    'X-Zoneo-Signature: v1='.$signature,
];

$curl = curl_init('https://zoneo.cz/api/v1/conversions');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

Vytvořená → Refundovaná Odkaz na sekci Vytvořená → Refundovaná

Pro platbu, zrušení a kumulativní refundace znovu použijte stejné zclid a order_id_hash. Finální součty a položky objednávky už neměňte.

Vytvořená · placed Zaplacená · paid Zrušená · cancelled Částečně refundovaná · partially_refunded Refundovaná · refunded

order_v1 · lifecycle 

placed -> paid | cancelled | partially_refunded | refunded
paid -> partially_refunded | refunded
partially_refunded -> refunded
cancelled, refunded -> terminal

0 <= refund_amount_minor <= totals.order_total_gross_minor
new_refund_amount_minor >= previous_refund_amount_minor

Idempotency-Key · retry 

nonce₁ != nonce₂
retry = nonce₂ + Idempotency-Key₁ + SHA256(JSON₁)
Idempotency-Key₁ + SHA256(JSON₁) -> HTTP 200
Idempotency-Key₁ + SHA256(JSON₂) -> HTTP 409 idempotency_conflict

Sandbox V1 Odkaz na sekci Sandbox V1

Vložte V1 JSON a bezpečně ověřte pole, součty i párování položek s feedem. Test nevytvoří objednávku, neovlivní fakturaci a nepřepíše stav reálného měření.

POST https://zoneo.cz/api/v1/conversions/sandbox
persisted = false billing_impact = false

Volitelné měření přes JavaScript Odkaz na sekci Volitelné měření přes JavaScript

Knihovna uloží zclid po souhlasu a z děkovné stránky odešle pouze úvodní událost placed. Pozdější stavy posílejte bezpečně přes S2S.

Souhlas je ve výchozím stavu vypnutý. Funkce consent musí vrátit true až po platném analytickém souhlasu uživatele.

Načtení a inicializace 

<script src="https://zoneo.cz/integrations/zoneo-conversion-v1.js"></script>
<script>
const zoneo = window.ZoneoConversions.init({
  integrationId: 'zci_...',
  apiBase: 'https://zoneo.cz/api/v1/conversions',
  consent: () => analyticsConsent === true
})

zoneo.track({
  order_id_hash: 'SERVER_HMAC_SHA256',
  currency: 'CZK',
  occurred_at: new Date().toISOString(),
  status: 'placed',
  totals: {
    items_gross_minor: 12990,
    discount_minor: 0,
    shipping_gross_minor: 0,
    fees_gross_minor: 0,
    tax_minor: 2165,
    order_total_gross_minor: 12990
  },
  items: [{
    merchant_item_id: 'ITEM_ID_FROM_FEED',
    quantity: 1,
    unit_price_gross_minor: 12990,
    line_total_gross_minor: 12990
  }]
})
</script>

Stav integrace Odkaz na sekci Stav integrace

Přijaté a odmítnuté události za posledních 7 dní.

201 · created = true
200 · idempotent = true | deduplicated = true
4xx · error.code

HTTP 201 · JSON 

{
    "data": {
        "conversion_reference": "6bfca33e-3ac7-48dc-a733-c1f313853269",
        "status": "placed",
        "source": "s2s",
        "verification": "hmac_current",
        "schema_version": "1.0",
        "payload_contract": "order_v1",
        "totals": {
            "items_gross_minor": 14000,
            "discount_minor": 1500,
            "shipping_gross_minor": 390,
            "fees_gross_minor": 100,
            "tax_minor": 2165,
            "order_total_gross_minor": 12990
        },
        "refund_amount_minor": 0,
        "net_revenue_minor": 12990,
        "items": {
            "count": 1,
            "quantity_total": 2,
            "matched_count": 1,
            "match_status": "complete"
        },
        "totals_reconciled": true,
        "warnings": [],
        "currency": "CZK",
        "created": true,
        "idempotent": false,
        "deduplicated": false,
        "provisional": false,
        "billing_impact": false
    }
}

HTTP 4xx · JSON 

{
    "error": {
        "code": "order_total_mismatch",
        "field": "totals.order_total_gross_minor",
        "details": {
            "expected_minor": 12990,
            "received_minor": 13000
        }
    }
}
invalid_signature stale_timestamp replayed_nonce pii_not_allowed items_total_mismatch order_total_mismatch currency_mismatch click_not_eligible store_or_market_mismatch not_last_zoneo_click attribution_window_expired invalid_state_transition order_definition_conflict refund_amount_decreased order_attribution_conflict

Ochrana osobních údajů Odkaz na sekci Ochrana osobních údajů

Nejnovější objednávky přijaté do analytiky Zoneo. Surová ID objednávek ani osobní údaje nikdy nezobrazujeme.

Na serveru vytvořte stabilní HMAC-SHA-256 otisk interního ID objednávky pomocí samostatného klíče. Surové ID ani osobní údaje neposílejte.

Objednávky, tržby a odvozené metriky se zobrazují pouze při aktivním měření konverzí. Slouží k analytice a nemění vyúčtování CPC.

Jak měření propojit

Doporučujeme server-to-server API. JavaScript je pouze volitelná záložní analytická cesta a funguje jen po udělení analytického souhlasu.

Prokliky a výkon Zpět nahoru