Σύμβαση API V1

Σύμβαση API V1 Σύνδεσμος προς την ενότητα Σύμβαση API V1

Συνιστούμε το API server-to-server. Η JavaScript είναι μόνο προαιρετική εναλλακτική διαδρομή αναλυτικών στοιχείων και λειτουργεί μόνο μετά τη χορήγηση συγκατάθεσης για αναλυτικά στοιχεία.

Οι παραγγελίες, τα έσοδα και οι παράγωγες μετρήσεις εμφανίζονται μόνο όταν η μέτρηση μετατροπών είναι ενεργή. Χρησιμοποιούνται μόνο για ανάλυση και δεν αλλάζουν τη χρέωση CPC.

schema_version

1.0

payload_contract

order_v1

Content-Type

application/json

request_limit

64 KiB

Πώς να συνδέσετε τη μέτρηση Σύνδεσμος προς την ενότητα Πώς να συνδέσετε τη μέτρηση

Συνιστούμε το API server-to-server. Η JavaScript είναι μόνο προαιρετική εναλλακτική διαδρομή αναλυτικών στοιχείων και λειτουργεί μόνο μετά τη χορήγηση συγκατάθεσης για αναλυτικά στοιχεία.

1 Αποθηκεύστε την παράμετρο zclid από το URL προορισμού στο καλάθι ή στην παραγγελία για 30 ημέρες.
2 Στον διακομιστή, δημιουργήστε ένα σταθερό αποτύπωμα HMAC-SHA-256 του εσωτερικού ID παραγγελίας, χρησιμοποιώντας ξεχωριστό κλειδί. Μην στέλνετε το ακατέργαστο ID ή προσωπικά δεδομένα.
3 Μετά τη δημιουργία της παραγγελίας, στείλτε JSON στο API και υπογράψτε το ακριβές σώμα του αιτήματος με το μυστικό κλειδί ενσωμάτωσης.
4 Για πληρωμή, ακύρωση και σωρευτικές επιστροφές χρησιμοποιήστε τα ίδια zclid και order_id_hash. Μην αλλάζετε τα τελικά σύνολα και τα είδη.

Το μυστικό κλειδί ενσωμάτωσης εμφανίζεται μόνο μία φορά. Αποθηκεύστε το σε διαχειριστή μυστικών στον διακομιστή του καταστήματος.

Συνιστάται: API server-to-server Σύνδεσμος προς την ενότητα Συνιστάται: API server-to-server

Ο διακομιστής του καταστήματος στέλνει επαληθευμένες παραγγελίες, αλλαγές κατάστασης και επιστροφές χρημάτων απευθείας στο Zoneo. Μην εισάγετε ποτέ το μυστικό κλειδί στο πρόγραμμα περιήγησης.

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

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

Στον διακομιστή, δημιουργήστε ένα σταθερό αποτύπωμα HMAC-SHA-256 του εσωτερικού ID παραγγελίας, χρησιμοποιώντας ξεχωριστό κλειδί. Μην στέλνετε το ακατέργαστο ID ή προσωπικά δεδομένα.

order_id_hash · PHP

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

Παράδειγμα αιτήματος Σύνδεσμος προς την ενότητα Παράδειγμα αιτήματος

Μετά τη δημιουργία της παραγγελίας, στείλτε JSON στο API και υπογράψτε το ακριβές σώμα του αιτήματος με το μυστικό κλειδί ενσωμάτωσης.

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": "el",
    "expected_delivery_date": "2026-09-03"
}

order_v1 · JSON
JSON	Υποχρεωτικά πεδία	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[]	Υποχρεωτικά πεδία	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

Κανονική υπογραφή Σύνδεσμος προς την ενότητα Κανονική υπογραφή

Αν δεν έχετε αποθηκεύσει το αρχικό μυστικό κλειδί, χρησιμοποιήστε την επιλογή «Ανάκτηση μυστικού κλειδιού» και αποθηκεύστε αμέσως με ασφάλεια το νέο κλειδί.

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

Καταχωρήθηκε → Επιστράφηκε Σύνδεσμος προς την ενότητα Καταχωρήθηκε → Επιστράφηκε

Για πληρωμή, ακύρωση και σωρευτικές επιστροφές χρησιμοποιήστε τα ίδια zclid και order_id_hash. Μην αλλάζετε τα τελικά σύνολα και τα είδη.

Καταχωρήθηκε · placed Πληρώθηκε · paid Ακυρώθηκε · cancelled Μερική επιστροφή · partially_refunded Επιστράφηκε · 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 Σύνδεσμος προς την ενότητα Sandbox V1

Επικολλήστε JSON V1 για ασφαλή έλεγχο πεδίων, συνόλων και αντιστοίχισης ροής χωρίς δημιουργία παραγγελίας ή επίδραση στη χρέωση.

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

persisted = false billing_impact = false

Προαιρετική μέτρηση μέσω JavaScript Σύνδεσμος προς την ενότητα Προαιρετική μέτρηση μέσω JavaScript

Η βιβλιοθήκη αποθηκεύει το zclid μετά τη συγκατάθεση και στέλνει μόνο το αρχικό συμβάν placed. Στείλτε τις επόμενες καταστάσεις με ασφάλεια μέσω S2S.

Η συγκατάθεση είναι απενεργοποιημένη από προεπιλογή. Η συνάρτηση consent πρέπει να επιστρέφει true μόνο μετά την έγκυρη συγκατάθεση του χρήστη για αναλυτικά στοιχεία.

Φόρτωση και αρχικοποίηση

<script src="https://zoneo.gr/integrations/zoneo-conversion-v1.js"></script>
<script>
const zoneo = window.ZoneoConversions.init({
  integrationId: 'zci_...',
  apiBase: 'https://zoneo.gr/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>

Υγεία ενσωμάτωσης Σύνδεσμος προς την ενότητα Υγεία ενσωμάτωσης

Αποδεκτά και απορριφθέντα συμβάντα των τελευταίων 7 ημερών.

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

Προστασία δεδομένων Σύνδεσμος προς την ενότητα Προστασία δεδομένων

Οι πιο πρόσφατες παραγγελίες μόνο για αναλυτικούς σκοπούς. Δεν εμφανίζονται αρχικά αναγνωριστικά ή προσωπικά δεδομένα.

Στον διακομιστή, δημιουργήστε ένα σταθερό αποτύπωμα HMAC-SHA-256 του εσωτερικού ID παραγγελίας, χρησιμοποιώντας ξεχωριστό κλειδί. Μην στέλνετε το ακατέργαστο ID ή προσωπικά δεδομένα.

Οι παραγγελίες, τα έσοδα και οι παράγωγες μετρήσεις εμφανίζονται μόνο όταν η μέτρηση μετατροπών είναι ενεργή. Χρησιμοποιούνται μόνο για ανάλυση και δεν αλλάζουν τη χρέωση CPC.