Partneri dokumentáció

1. API-kulcs beszerzése

Vegye fel a kapcsolatot a QuizzBuy kapcsolattartójával (vagy a kapcsolatfelvételi űrlappal). Generálunk Önnek egy zzb_live_… formátumú kulcsot — ezt csak egyszer közöljük Önnel, őrizze meg biztonságos helyen. Minden kérésnél adja át a HTTP fejlécben:

Authorization: Bearer zzb_live_VOTRE_CLE

2. Kulcs ellenőrzése

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. Hirdetések közzététele

Egy hirdetés vagy visszavásárlási ajánlat (BUYBACK — Ön egy adott áron visszavesz egy készüléket), vagy értékesítési ajánlat (SALE — egy felújított termék, amelyet Ön értékesít). A küldés egy upsert művelet: ugyanazon externalId újraküldése frissíti a hirdetést.

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 vagy GAMING.
• condition: LIKE_NEW, EXCELLENT, GOOD, FAIR vagy BROKEN.
• priceCents: ár centben (52000 = 520 €).
• Minden új hirdetés (vagy módosítás) moderáción megy át közzététel előtt.

Frissítés, listázás vagy deaktiválás:

# 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. Kattintáskövetés

Amikor egy QuizzBuy látogató az Ön oldalára kattint, az érkezési URL tartalmaz egy kattintásazonosítót:

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

Tárolja ezt az értéket (cookie vagy munkamenet az Ön oldalán, ajánlott időtartam: 45 nap). Ez teszi lehetővé a rendelés attribúcióját. A paraméter neve (alapértelmezetten zzb_click) kérésre konfigurálható.

5. Rendelés bejelentése (S2S postback)

Amint egy ügyfél rendelést ad le (vásárlás vagy jóváhagyott visszavásárlási igény), és rendelkezik egy zzb_click értékkel, hívja meg postback végpontunkat az Ön szerveréről:

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 }

• Attribúciós ablak: 45 nap a kattintás után; azon túl 422 attribution_window_expired válasz érkezik.
• order_ref egyedi kell legyen: duplikáció esetén 409 duplicate_order_ref érkezik (idempotencia — kockázat nélkül újrapróbálkozhat).
• type: SALE vásárlás esetén, BUYBACK visszavásárlás esetén.
• currency: kizárólag EUR — bármely más devizát elutasítunk (422 unsupported_currency).

6. Tesztelés sandbox környezetben

Adja hozzá a "test": true mezőt a postbackhez: a kérés teljes mértékben ellenőrzésre kerül (kulcs, click_id, 45 napos ablak), de semmilyen konverzió nem kerül rögzítésre vagy számlázásra.

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

7. Hibakódok

8. Számlázás

Minden nekünk tulajdonított konverzió jutalékot generál (szerződéses mérték, megtekinthető a /api/v1/me végponton). A QuizzBuy időszakos összesítő számlát küld Önnek a jóváhagyott konverziókról. Kérdés esetén: lépjen kapcsolatba velünk.

9. Piactér — értékesítés a QuizzBuy-on

A quantity > 0 értékű SALE hirdetések közvetlenül a QuizzBuy-on kerülnek értékesítésre (az ügyfél fizetése nálunk történik, a jutalék levonása utáni nettó összeg kerül átutalásra Önnek). További mezők: quantity (készlet), color, grade (A/B/C), batteryHealth (%), warrantyMonths. A hirdetés automatikusan hozzárendelődik a megfelelő terméklaphoz (márka + modell + kapacitás + szín).

# 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. Webhookok — értesítés az eladásokról

Regisztráljon egy HTTPS végpontot; értesítjük Önt az Ön termékeit tartalmazó rendelés minden lépéséről (order.created, order.paid, order.cancelled). A titkos kulcsot csak létrehozáskor adjuk vissza — tárolja el.

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"

Minden kézbesítés alá van írva. Ellenőrizze az X-ZZbuy-Signature fejlécet (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

Hiba esetén (≠ 2xx) újrapróbálkozunk backoff logikával: 1 perc, 5 perc, 30 perc, 2 óra, 12 óra. Emellett értesítő e-mailt is kap az eladásról.

11. Rendelések feldolgozása

Listázza a rendelési tételeit, igazolja vissza az átvételt, majd adja fel csomagját nyomkövetési számmal (az ügyfél automatikusan értesítést kap). A szállítási cím csak fizetés után látható.

# 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. Gérait visszavásárlás (trade-in)

A gérait visszavásárlás túlmutat az egyszerű, átirányításos visszavásárláson: a magánszemély a QuizzBuy-on keresztül nyújtja be készülékét, Ön pedig az API-n keresztül kezeli a teljes ügyet (elfogadás, átvétel, ellenajánlat, kifizetés). Az ügyfélnek megjelenített ár a beküldéskor zárolásra kerül az Ön visszavásárlási táblázata alapján (lásd §14); csak átvétel után, indoklással ellátott ellenajánlattal módosíthatja lefelé.

Minden végpont az Ön API-kulcsával hitelesít (Authorization: Bearer zzb_live_…), és csak az Ön ügyeit adja vissza.

Életciklus

SUBMITTED → ACCEPTED → SHIPPED → RECEIVED → PAID. Két elágazás: REJECTED (elutasítás küldés előtt) és COUNTER_OFFER (ellenajánlat vizsgálat után, amelyet a magánszemély elfogad — majd PAID — vagy elutasít — készülék visszaküldése, CANCELLED).

Listázás és lekérdezés

# 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 (opcionális szűrő): a fenti táblázat egyik értéke — egyébként 400 invalid_status.
• limit: max 200 (alapértelmezett 50); offset a lapozáshoz.
• A customer (a magánszemély elérhetősége) csak ezen a partneri API-n látható, webhookokban soha.

Átmenetek

Minden művelet egy POST, és { "ok": true, "trade_in": { … } } választ ad vissza. Egy nem kompatibilis státuszból induló átmenet 409 invalid_status választ ad (a tényleges current státusszal). A magánszemély minden lépésnél e-mail értesítést kap.

# 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: csak SUBMITTED állapotból. shippingLabelUrl opcionális (URL, ≤ 500 karakter).
• receive: SHIPPED vagy ACCEPTED állapotból (ha az ügyfél nem jelentette be a feladást/küldést).
• counter: RECEIVED állapotból. Az amountCents-nek szigorúan alacsonyabbnak kell lennie, mint az offer_cents, egyébként 400 counter_not_lower; a reason kötelező (1–500 karakter). Ezután a magánszemély fogadja el vagy utasítja el a kéréskövető oldaláról.
• pay: RECEIVED állapotból. A payoutRef kötelező (átutalási hivatkozás, 1–120 karakter).
• reject: csak SUBMITTED állapotból — nincs szükség törzsre.

13. Visszavásárlási webhookok (trade_in.*)

Ugyanazok a webhookok (§10, azonos X-ZZbuy-Signature aláírás) fedik le a gérait visszavásárlást. Iratkozzon fel a trade_in.* események egészére vagy egy részére egy végpont létrehozásakor:

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"]
  }'

A kézbesítés törzse (a magánszemély elérhetősége nem szerepel benne — kérje le a GET /api/v1/trade-ins/:id végponton keresztül):

{
  "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. Visszavásárlási táblázat feltöltése (push)

„Push” alternatíva az általunk lehívott CSV folyamathoz képest: küldje el közvetlenül a visszavásárlási árlistáját. Minden sor a készülék állapotától függően 4 összeget tartalmaz. Az árak ugyanabba a táblába kerülnek, mint az automatikus szinkronizáció — így azonnal megjelennek az összehasonlítóban és zárolt árként szolgálnak a gérait visszavásárláshoz (§12). A művelet (márka, kategória, modell, kapacitás) szerinti 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 sor kérésenként.
• category: SMARTPHONE, TABLET, LAPTOP, SMARTWATCH, AUDIO vagy GAMING.
• priceNewCents (új), priceGoodCents (jó), priceFairCents (megjelölt), priceBrokenCents (törött) — centben, ≥ 0.
• storage és url opcionális; a kapacitás automatikusan normalizálásra kerül (pl. „256go” → „256 GB”).