Τεκμηρίωση συνεργατών

1. Απόκτηση κλειδιού API

Επικοινωνήστε με τον υπεύθυνο επαφής σας στο QuizzBuy (ή τη φόρμα επικοινωνίας). Δημιουργούμε για εσάς ένα κλειδί με τη μορφή zzb_live_… — σας κοινοποιείται μόνο μία φορά, φυλάξτε το σε ασφαλές μέρος. Χρησιμοποιήστε το σε κάθε αίτημα μέσα στην κεφαλίδα HTTP:

Authorization: Bearer zzb_live_VOTRE_CLE

2. Επαλήθευση του κλειδιού σας

curl https://quizzbuy.com/api/v1/me \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# Réponse
{
  "company": { "id": "…", "name": "Votre société", "slug": "votre-societe" },
  "commission_rate": 0.05,
  "click_param": "zzb_click"
}

3. Δημοσίευση των αγγελιών σας

Μια αγγελία είναι είτε προσφορά επαναγοράς (BUYBACK — αναλαμβάνετε μια συσκευή σε δεδομένη τιμή), είτε προσφορά πώλησης (SALE — ένα ανακαινισμένο προϊόν που πουλάτε). Η αποστολή είναι upsert: η επανάληψη της αποστολής με το ίδιο externalId ενημερώνει την αγγελία.

curl -X POST https://quizzbuy.com/api/v1/listings \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ref-interne-123",
    "type": "BUYBACK",
    "title": "Reprise iPhone 15 Pro 256 Go",
    "brand": "Apple",
    "model": "iPhone 15 Pro",
    "category": "SMARTPHONE",
    "storage": "256 GB",
    "condition": "GOOD",
    "priceCents": 52000,
    "currency": "EUR",
    "url": "https://votre-site.fr/reprise/iphone-15-pro",
    "country": "FR"
  }'

• category: SMARTPHONE, LAPTOP, SMARTWATCH, AUDIO ή GAMING.
• condition: LIKE_NEW, EXCELLENT, GOOD, FAIR ή BROKEN.
• priceCents: τιμή σε λεπτά (52000 = 520 €).
• Κάθε νέα αγγελία (ή τροποποίηση) περνά από έλεγχο πριν τη δημοσίευση.

Ενημέρωση, καταχώριση ή απενεργοποίηση:

# Lister vos annonces
curl "https://quizzbuy.com/api/v1/listings?type=BUYBACK&status=APPROVED" \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# Mise à jour partielle
curl -X PATCH https://quizzbuy.com/api/v1/listings/ID_ANNONCE \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "priceCents": 49000 }'

# Désactiver (soft delete)
curl -X DELETE https://quizzbuy.com/api/v1/listings/ID_ANNONCE \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

4. Παρακολούθηση κλικ

Όταν ένας επισκέπτης του QuizzBuy κάνει κλικ προς τον ιστότοπό σας, το URL προορισμού περιέχει ένα αναγνωριστικό κλικ:

https://votre-site.fr/vendre?zzb_click=6f1e0c9a-3b2d-4e8f-9a10-abcdef123456

Αποθηκεύστε αυτή την τιμή (cookie ή session στην πλευρά του ιστότοπού σας, συνιστώμενη διάρκεια: 45 ημέρες). Αυτή θα επιτρέψει την απόδοση της παραγγελίας. Το όνομα της παραμέτρου (zzb_click από προεπιλογή) είναι διαμορφώσιμο κατόπιν αιτήματος.

5. Ειδοποίηση παραγγελίας (postback S2S)

Μόλις ένας πελάτης κάνει παραγγελία (αγορά ή επικυρωμένο αίτημα επαναγοράς) και διαθέτετε ένα zzb_click, καλέστε το postback μας από τον διακομιστή σας:

curl -X POST https://quizzbuy.com/api/v1/postback \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "6f1e0c9a-3b2d-4e8f-9a10-abcdef123456",
    "type": "BUYBACK",
    "amount_cents": 52000,
    "currency": "EUR",
    "order_ref": "CMD-2026-000123"
  }'

# Réponse 201
{ "conversion_id": "…", "status": "TO_INVOICE", "commission_cents": 2600 }

• Παράθυρο απόδοσης: 45 ημέρες μετά το κλικ· πέρα από αυτό, απάντηση 422 attribution_window_expired.
• Το order_ref πρέπει να είναι μοναδικό: ένα διπλότυπο επιστρέφει 409 duplicate_order_ref (ιδεμποτεντία — μπορείτε να επαναλάβετε χωρίς κίνδυνο).
• type: SALE για αγορά, BUYBACK για επαναγορά.
• currency: μόνο EUR — οποιοδήποτε άλλο νόμισμα απορρίπτεται (422 unsupported_currency).

6. Δοκιμή σε sandbox

Προσθέστε "test": true στο postback: το αίτημα επικυρώνεται πλήρως (κλειδί, click_id, παράθυρο 45 ημερών) αλλά καμία μετατροπή δεν καταγράφεται ούτε χρεώνεται.

{ "click_id": "…", "type": "SALE", "amount_cents": 10000, "order_ref": "TEST-1", "test": true }
# → 200 { "test": true, "valid": true, "commission_cents": 500 }

7. Κωδικοί σφάλματος

8. Χρέωση

Κάθε αποδιδόμενη μετατροπή δημιουργεί προμήθεια (συμβατικό ποσοστό, ορατό μέσω /api/v1/me). Το QuizzBuy σας αποστέλλει περιοδικό συγκεντρωτικό τιμολόγιο των επικυρωμένων μετατροπών. Για οποιαδήποτε ερώτηση: επικοινωνήστε μαζί μας.

9. Marketplace — πωλήστε στο QuizzBuy

Οι αγγελίες SALE με quantity > 0 πωλούνται απευθείας στο QuizzBuy (πληρωμή πελάτη σε εμάς, απόδοση του καθαρού ποσού μετά την προμήθεια). Επιπλέον πεδία: quantity (απόθεμα), color, grade (A/B/C), batteryHealth (%), warrantyMonths. Η αγγελία συνδέεται αυτόματα με την αντίστοιχη καρτέλα προϊόντος (μάρκα + μοντέλο + χωρητικότητα + χρώμα).

# Mettre à jour le stock (sans re-modération)
curl -X PATCH https://quizzbuy.com/api/v1/listings/ID_ANNONCE/stock \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 12 }'

# Ajouter une photo (multipart, max 5 × 5 Mo, jpeg/png/webp)
curl -X POST https://quizzbuy.com/api/v1/listings/ID_ANNONCE/images \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -F "file=@photo.jpg"

10. Webhooks — ειδοποίηση για πωλήσεις

Καταχωρίστε ένα endpoint HTTPS· σας ειδοποιούμε σε κάθε στάδιο μιας παραγγελίας που περιέχει τα προϊόντα σας (order.created, order.paid, order.cancelled). Το μυστικό επιστρέφεται μόνο κατά τη δημιουργία — αποθηκεύστε το.

curl -X POST https://quizzbuy.com/api/v1/webhooks \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://votre-site.fr/webhooks/quizzbuy", "events": ["order.paid"] }'

# Réponse (secret affiché une seule fois)
{ "webhook": { "id": "…", "secret": "whsec_…", "events": ["order.paid"] } }

# Tester
curl -X POST https://quizzbuy.com/api/v1/webhooks/ID_WEBHOOK/test \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

Κάθε παράδοση είναι υπογεγραμμένη. Ελέγξτε την κεφαλίδα X-ZZbuy-Signature (t=timestamp,v1=hex):

// Node.js
const [t, v1] = signature.split(",").map((p) => p.split("=")[1]);
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid =
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) &&
  Math.abs(Date.now() / 1000 - Number(t)) < 300; // anti-replay 5 min

Σε περίπτωση αποτυχίας (≠ 2xx), επαναλαμβάνουμε με backoff: 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες, 12 ώρες. Λαμβάνετε επίσης email ειδοποίησης πώλησης.

11. Διαχείριση των παραγγελιών σας

Καταχωρίστε τις γραμμές παραγγελίας σας, επιβεβαιώστε την παραλαβή και έπειτα αποστείλετε με αριθμό παρακολούθησης (ο πελάτης ειδοποιείται αυτόματα). Η διεύθυνση παράδοσης είναι ορατή μόνο μετά την πληρωμή.

# Lister les commandes à traiter
curl "https://quizzbuy.com/api/v1/orders?status=PENDING" \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# Accuser réception
curl -X POST https://quizzbuy.com/api/v1/orders/ID_LIGNE/ack \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# Expédier
curl -X POST https://quizzbuy.com/api/v1/orders/ID_LIGNE/ship \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "carrier": "Colissimo", "trackingNumber": "6A123456789FR" }'

12. Διαχειριζόμενη επαναγορά (trade-in)

Η διαχειριζόμενη επαναγορά προχωρά πέρα από την απλή επαναγορά μέσω ανακατεύθυνσης: ο ιδιώτης υποβάλλει τη συσκευή του από το QuizzBuy, και εσείς διαχειρίζεστε ολόκληρο τον φάκελο μέσω του API (αποδοχή, παραλαβή, αντιπροσφορά, πληρωμή). Η τιμή που εμφανίζεται στον πελάτη είναι κλειδωμένη κατά την υποβολή σύμφωνα με τον πίνακα επαναγοράς σας (βλ. §14)· μπορείτε να την αναθεωρήσετε προς τα κάτω μόνο μετά την παραλαβή, μέσω αιτιολογημένης αντιπροσφοράς.

Όλα τα endpoints πιστοποιούνται με το κλειδί API σας (Authorization: Bearer zzb_live_…) και επιστρέφουν μόνο τους δικούς σας φακέλους.

Κύκλος ζωής

SUBMITTED → ACCEPTED → SHIPPED → RECEIVED → PAID. Δύο διακλαδώσεις: REJECTED (άρνηση πριν την αποστολή) και COUNTER_OFFER (αντιπροσφορά μετά την επιθεώρηση, την οποία ο ιδιώτης αποδέχεται — και τότε PAID — ή απορρίπτει — επιστροφή συσκευής, CANCELLED).

Καταχώριση & προβολή

# Lister vos reprises (plus récentes d'abord)
curl "https://quizzbuy.com/api/v1/trade-ins?status=SUBMITTED&limit=50&offset=0" \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# Réponse
{
  "total": 3,
  "trade_ins": [
    {
      "trade_in_id": "…",
      "reference": "TI-2026-000042",
      "status": "SUBMITTED",
      "device": {
        "brand": "Apple", "category": "SMARTPHONE", "model": "iPhone 15 Pro",
        "storage": "256 GB", "condition": "GOOD",
        "functional_status": "FULLY_WORKING", "battery_health": 92, "imei": "…"
      },
      "offer_cents": 52000,
      "currency": "EUR",
      "price_locked_until": "2026-08-05T12:00:00.000Z",
      "country": "FR",
      "customer": { "email": "…", "first_name": "…", "last_name": "…", "locale": "fr" },
      "comment": null,
      "counter_offer_cents": null, "counter_reason": null,
      "tracking_carrier": null, "tracking_number": null,
      "shipping_label_url": null, "payout_ref": null,
      "accepted_at": null, "shipped_at": null, "received_at": null,
      "paid_at": null, "cancelled_at": null,
      "created_at": "2026-07-21T12:00:00.000Z"
    }
  ]
}

# Détail d'une reprise
curl https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"
# → { "trade_in": { … } }

• status (προαιρετικό φίλτρο): μία τιμή από τον παραπάνω πίνακα — διαφορετικά 400 invalid_status.
• limit: μέγιστο 200 (προεπιλογή 50)· offset για σελιδοποίηση.
• Ο customer (στοιχεία επικοινωνίας του ιδιώτη) είναι ορατός μόνο σε αυτό το API συνεργατών, ποτέ στα webhooks.

Μεταβάσεις

Κάθε ενέργεια είναι POST και επιστρέφει { "ok": true, "trade_in": { … } }. Μια μετάβαση από ασύμβατη κατάσταση επιστρέφει 409 invalid_status (με το πραγματικό current). Ο ιδιώτης ειδοποιείται με email σε κάθε στάδιο.

# 1. Accepter (depuis SUBMITTED) — shippingLabelUrl facultatif (étiquette prépayée)
curl -X POST https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE/accept \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "shippingLabelUrl": "https://votre-site.fr/labels/ti-42.pdf" }'

# 2. Réceptionner l'appareil (depuis SHIPPED ou ACCEPTED)
curl -X POST https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE/receive \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

# 3a. Payer le montant garanti (depuis RECEIVED) — clôt la reprise
curl -X POST https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE/pay \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "payoutRef": "VIR-2026-000123" }'

# 3b. …ou contre-offrer après inspection (depuis RECEIVED) — montant < offre garantie
curl -X POST https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE/counter \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "amountCents": 42000, "reason": "Rayures écran non déclarées" }'

# Refuser avant envoi (depuis SUBMITTED uniquement)
curl -X POST https://quizzbuy.com/api/v1/trade-ins/ID_REPRISE/reject \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE"

• accept: μόνο από SUBMITTED. Το shippingLabelUrl είναι προαιρετικό (URL, ≤ 500 χαρακτήρες).
• receive: από SHIPPED ή ACCEPTED (κατάθεση/αποστολή μη δηλωμένη από τον πελάτη).
• counter: από RECEIVED. Το amountCents πρέπει να είναι αυστηρά χαμηλότερο από το offer_cents, διαφορετικά 400 counter_not_lower· το reason είναι υποχρεωτικό (1–500 χαρακτήρες). Στη συνέχεια ο ιδιώτης αποδέχεται ή απορρίπτει από τη σελίδα παρακολούθησής του.
• pay: από RECEIVED. Το payoutRef είναι υποχρεωτικό (αναφορά εμβάσματος, 1–120 χαρακτήρες).
• reject: μόνο από SUBMITTED — δεν απαιτείται σώμα.

13. Webhooks επαναγοράς (trade_in.*)

Τα ίδια webhooks (§10, ταυτόσημη υπογραφή X-ZZbuy-Signature) καλύπτουν τη διαχειριζόμενη επαναγορά. Εγγραφείτε σε όλα ή μέρος των συμβάντων trade_in.* κατά τη δημιουργία ενός endpoint:

curl -X POST https://quizzbuy.com/api/v1/webhooks \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-site.fr/webhooks/quizzbuy",
    "events": ["trade_in.created", "trade_in.shipped", "trade_in.counter_accepted"]
  }'

Σώμα της παράδοσης (τα στοιχεία επικοινωνίας του ιδιώτη δεν περιλαμβάνονται — ανακτήστε τα μέσω GET /api/v1/trade-ins/:id):

{
  "trade_in_id": "…",
  "reference": "TI-2026-000042",
  "status": "SHIPPED",
  "device": {
    "brand": "Apple", "category": "SMARTPHONE", "model": "iPhone 15 Pro",
    "storage": "256 GB", "condition": "GOOD",
    "functional_status": "FULLY_WORKING", "battery_health": 92, "imei": "…"
  },
  "offer_cents": 52000,
  "currency": "EUR",
  "price_locked_until": "2026-08-05T12:00:00.000Z",
  "country": "FR"
}

14. Αποστολή του πίνακα επαναγοράς σας

Εναλλακτική λύση «push» στη ροή CSV που αντλούμε εμείς: στείλτε απευθείας τον πίνακα τιμών επαναγοράς σας. Κάθε γραμμή φέρει τα 4 ποσά ανάλογα με την κατάσταση της συσκευής. Οι τιμές τροφοδοτούν τον ίδιο πίνακα με τον αυτόματο συγχρονισμό — εμφανίζονται συνεπώς αμέσως στο εργαλείο σύγκρισης και χρησιμεύουν ως κλειδωμένη τιμή για τη διαχειριζόμενη επαναγορά (§12). Η λειτουργία είναι upsert ανά (μάρκα, κατηγορία, μοντέλο, χωρητικότητα).

curl -X PUT https://quizzbuy.com/api/v1/buyback/prices \
  -H "Authorization: Bearer zzb_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
      {
        "brand": "Apple",
        "category": "SMARTPHONE",
        "model": "iPhone 15 Pro",
        "storage": "256 GB",
        "priceNewCents": 60000,
        "priceGoodCents": 52000,
        "priceFairCents": 40000,
        "priceBrokenCents": 15000,
        "currency": "EUR",
        "url": "https://votre-site.fr/reprise/iphone-15-pro"
      }
    ]
  }'

# Réponse
{ "ok": true, "upserted": 1 }

• prices: 1 έως 2000 γραμμές ανά αίτημα.
• category: SMARTPHONE, TABLET, LAPTOP, SMARTWATCH, AUDIO ή GAMING.
• priceNewCents (καινούριο), priceGoodCents (καλή), priceFairCents (φθαρμένο), priceBrokenCents (σπασμένο) — σε λεπτά, ≥ 0.
• storage και url προαιρετικά· η χωρητικότητα κανονικοποιείται αυτόματα (π.χ. « 256go » → « 256 GB »).