API-szerződés V1

API-szerződés V1 Hivatkozás a(z) API-szerződés V1 szakaszra

A server-to-server API használatát javasoljuk. A JavaScript csak opcionális tartalék analitikai megoldás, és kizárólag analitikai hozzájárulás megadása után működik.

A rendelések, a bevétel és a származtatott mutatók csak aktív konverziómérés mellett jelennek meg. Kizárólag elemzési célúak, és nem módosítják a CPC-számlázást.

schema_version

1.0

payload_contract

order_v1

Content-Type

application/json

request_limit

64 KiB

A mérés összekapcsolása Hivatkozás a(z) A mérés összekapcsolása szakaszra

A server-to-server API használatát javasoljuk. A JavaScript csak opcionális tartalék analitikai megoldás, és kizárólag analitikai hozzájárulás megadása után működik.

1 Mentse el a cél-URL-ből származó zclid paramétert a kosárhoz vagy a rendeléshez 30 napig.
2 A szerveren hozzon létre stabil HMAC-SHA-256 lenyomatot a rendelés belső azonosítójából külön kulcs használatával. A nyers azonosítót és a személyes adatokat ne küldje el.
3 A rendelés létrehozása után küldjön JSON-t az API-nak, és írja alá pontosan a kérés törzsét az integrációs titkos kulccsal.
4 Fizetésnél, törlésnél és kumulatív visszatérítésnél ugyanazt a zclid és order_id_hash értéket használja. A végleges összegeket és tételeket ne módosítsa.

Az integrációs titkos kulcs csak egyszer jelenik meg. Mentse el az üzlet szerverén működő titokkezelőben.

Ajánlott: server-to-server API Hivatkozás a(z) Ajánlott: server-to-server API szakaszra

Az üzlet szervere közvetlenül a Zoneo részére küldi az ellenőrzött rendeléseket, állapotváltozásokat és visszatérítéseket. A titkos kulcsot soha ne helyezze a böngészőbe.

POST https://zoneo.hu/api/v1/conversions

Sandbox https://zoneo.hu/api/v1/conversions/sandbox

A szerveren hozzon létre stabil HMAC-SHA-256 lenyomatot a rendelés belső azonosítójából külön kulcs használatával. A nyers azonosítót és a személyes adatokat ne küldje el.

order_id_hash · PHP

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

Kérés példa Hivatkozás a(z) Kérés példa szakaszra

A rendelés létrehozása után küldjön JSON-t az API-nak, és írja alá pontosan a kérés törzsét az integrációs titkos kulccsal.

order_v1 · JSON

{
    "schema_version": "1.0",
    "zclid": "018fb72a-7d8e-7c3c-a4da-f37ce07ad739",
    "order_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "HUF",
    "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": "hu",
    "expected_delivery_date": "2026-09-03"
}

order_v1 · JSON
JSON	Kötelező mezők	V1
`schema_version`	✓	`= "1.0"`
`zclid`	✓	`UUID`
`order_id_hash`	✓	`HMAC-SHA-256 · [a-f0-9]{64}`
`currency`	✓	`ISO 4217 · HUF`
`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[]	Kötelező mezők	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 · HUF · 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

Kanonikus aláírás Hivatkozás a(z) Kanonikus aláírás szakaszra

Ha nem mentette el az eredeti titkos kulcsot, válassza a Titkos kulcs helyreállítása lehetőséget, majd az új kulcsot azonnal mentse el biztonságos helyre.

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

Létrehozva → Visszatérítve Hivatkozás a(z) Létrehozva → Visszatérítve szakaszra

Fizetésnél, törlésnél és kumulatív visszatérítésnél ugyanazt a zclid és order_id_hash értéket használja. A végleges összegeket és tételeket ne módosítsa.

Létrehozva · placed Fizetve · paid Törölve · cancelled Részben visszatérítve · partially_refunded Visszatérítve · 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 Hivatkozás a(z) Sandbox V1 szakaszra

Illesszen be V1 JSON-t a mezők, összegek és feed-egyeztetés ellenőrzéséhez rendelés vagy számlázási hatás létrehozása nélkül.

POST https://zoneo.hu/api/v1/conversions/sandbox

persisted = false billing_impact = false

Opcionális JavaScript-alapú mérés Hivatkozás a(z) Opcionális JavaScript-alapú mérés szakaszra

A könyvtár hozzájárulás után tárolja a zclid értéket, és csak a kezdeti placed eseményt küldi a köszönőoldalról. A további állapotokat biztonságosan, S2S-en küldje.

A hozzájárulás alapértelmezés szerint ki van kapcsolva. A consent funkciónak csak a felhasználó érvényes analitikai hozzájárulása után szabad true értéket visszaadnia.

Betöltés és inicializálás

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

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

Integráció állapota Hivatkozás a(z) Integráció állapota szakaszra

Elfogadott és elutasított események az elmúlt 7 napban.

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

Adatvédelem Hivatkozás a(z) Adatvédelem szakaszra

A Zoneo által kizárólag analitikai célra fogadott legutóbbi rendelések. Nyers rendelésazonosítókat és személyes adatokat nem jelenítünk meg.

A szerveren hozzon létre stabil HMAC-SHA-256 lenyomatot a rendelés belső azonosítójából külön kulcs használatával. A nyers azonosítót és a személyes adatokat ne küldje el.

A rendelések, a bevétel és a származtatott mutatók csak aktív konverziómérés mellett jelennek meg. Kizárólag elemzési célúak, és nem módosítják a CPC-számlázást.