Preskoči na glavno vsebino
Zoneo.si Zoneo Group
V1 Tehnična dokumentacija
Kliki in uspešnost Kontaktirajte Zoneo

Pogodba API V1

Priporočamo API server-to-server. JavaScript je le neobvezna rezervna analitična pot in deluje samo po podelitvi analitičnega soglasja.

Pogodba API V1 Povezava do razdelka Pogodba API V1

Priporočamo API server-to-server. JavaScript je le neobvezna rezervna analitična pot in deluje samo po podelitvi analitičnega soglasja.

Naročila, prihodek in izpeljane metrike so prikazani samo pri aktivnem merjenju konverzij. Namenjeni so le analitiki in ne spreminjajo obračuna CPC.

schema_version

1.0

payload_contract

order_v1

Content-Type

application/json

request_limit

64 KiB

Kako povezati merjenje Povezava do razdelka Kako povezati merjenje

Priporočamo API server-to-server. JavaScript je le neobvezna rezervna analitična pot in deluje samo po podelitvi analitičnega soglasja.

  1. 1 Parameter zclid iz ciljn URL shranite ob košarici ali naročilu za 30 dni.
  2. 2 Na strežniku ustvarite stabilen prstni odtis HMAC-SHA-256 notranjega ID-ja naročila z uporabo ločenega ključa. Ne pošiljajte neobdelanega ID-ja ali osebnih podatkov.
  3. 3 Po ustvarjanju naročila pošljite JSON v API in natančno telo zahteve podpišite z integracijskim skrivnim ključem.
  4. 4 Za plačilo, preklic in kumulativna vračila znova uporabite isti zclid in order_id_hash. Končnih vsot in postavk ne spreminjajte.

Integracijski skrivni ključ bo prikazan samo enkrat. Shranite ga v upravljalnik skrivnosti na strežniku trgovine.

Priporočeno: API server-to-server Povezava do razdelka Priporočeno: API server-to-server

Strežnik trgovine pošlje preverjena naročila, spremembe stanj in vračila neposredno v Zoneo. Skrivnega ključa nikoli ne vstavljajte v brskalnik.

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

Na strežniku ustvarite stabilen prstni odtis HMAC-SHA-256 notranjega ID-ja naročila z uporabo ločenega ključa. Ne pošiljajte neobdelanega ID-ja ali osebnih podatkov.

order_id_hash · PHP 

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

Primer zahteve Povezava do razdelka Primer zahteve

Po ustvarjanju naročila pošljite JSON v API in natančno telo zahteve podpišite z integracijskim skrivnim ključem.

order_v1 · JSON 

{
    "schema_version": "1.0",
    "zclid": "018fb72a-7d8e-7c3c-a4da-f37ce07ad739",
    "order_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "EUR",
    "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": "sl",
    "expected_delivery_date": "2026-09-03"
}
order_v1 · JSON
JSON Obvezna polja V1
schema_version ✓ = "1.0"
zclid ✓ UUID
order_id_hash ✓ HMAC-SHA-256 · [a-f0-9]{64}
currency ✓ ISO 4217 · EUR
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[] Obvezna polja 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 · EUR · 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

Kanonični podpis Povezava do razdelka Kanonični podpis

Če prvotnega skrivnega ključa nimate shranjenega, izberite Obnovi skrivni ključ in novi ključ takoj varno shranite.

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.si/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);

Oddano → Povrnjeno Povezava do razdelka Oddano → Povrnjeno

Za plačilo, preklic in kumulativna vračila znova uporabite isti zclid in order_id_hash. Končnih vsot in postavk ne spreminjajte.

Oddano · placed Plačano · paid Preklicano · cancelled Delno povrnjeno · partially_refunded Povrnjeno · 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 Povezava do razdelka Sandbox V1

Prilepite V1 JSON za preverjanje polj, vsot in povezovanja z virom brez ustvarjanja naročila ali vpliva na obračun.

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

Neobvezno merjenje prek JavaScripta Povezava do razdelka Neobvezno merjenje prek JavaScripta

Knjižnica po soglasju shrani zclid in s zahvalne strani pošlje samo začetni dogodek placed. Naslednja stanja varno pošljite prek S2S.

Soglasje je privzeto izklopljeno. Funkcija consent mora vrniti true šele po veljavnem analitičnem soglasju uporabnika.

Nalaganje in inicializacija 

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

zoneo.track({
  order_id_hash: 'SERVER_HMAC_SHA256',
  currency: 'EUR',
  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>

Stanje integracije Povezava do razdelka Stanje integracije

Sprejeti in zavrnjeni dogodki v zadnjih 7 dneh.

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": "EUR",
        "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

Varstvo osebnih podatkov Povezava do razdelka Varstvo osebnih podatkov

Najnovejša naročila, ki jih je Zoneo prejel samo za analitiko. Izvornih ID-jev naročil in osebnih podatkov ne prikazujemo.

Na strežniku ustvarite stabilen prstni odtis HMAC-SHA-256 notranjega ID-ja naročila z uporabo ločenega ključa. Ne pošiljajte neobdelanega ID-ja ali osebnih podatkov.

Naročila, prihodek in izpeljane metrike so prikazani samo pri aktivnem merjenju konverzij. Namenjeni so le analitiki in ne spreminjajo obračuna CPC.

Kako povezati merjenje

Priporočamo API server-to-server. JavaScript je le neobvezna rezervna analitična pot in deluje samo po podelitvi analitičnega soglasja.

Kliki in uspešnost Na vrh