Partnerių dokumentacija

1. Gauti API raktą

Susisiekite su savo QuizzBuy kontaktiniu asmeniu (arba kontaktine forma). Sugeneruosime jums raktą formatu zzb_live_… — jis jums pateikiamas tik vieną kartą, saugokite jį saugioje vietoje. Perduokite jį su kiekviena užklausa HTTP antraštėje:

Authorization: Bearer zzb_live_VOTRE_CLE

2. Patikrinti savo raktą

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. Publikuoti savo skelbimus

Skelbimas yra arba supirkimo pasiūlymas (BUYBACK — jūs perkate įrenginį už nurodytą kainą), arba pardavimo pasiūlymas (SALE — atnaujintas produktas, kurį parduodate). Siuntimas yra upsert tipo: pakartotinai siunčiant tą patį externalId skelbimas atnaujinamas.

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 arba GAMING.
• condition: LIKE_NEW, EXCELLENT, GOOD, FAIR arba BROKEN.
• priceCents: kaina centais (52000 = 520 €).
• Kiekvienas naujas skelbimas (ar pakeitimas) prieš publikavimą pereina moderavimą.

Atnaujinti, išvardyti arba deaktyvuoti:

# 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. Paspaudimų sekimas

Kai QuizzBuy lankytojas paspaudžia nuorodą į jūsų svetainę, atėjimo URL adrese yra paspaudimo identifikatorius:

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

Išsaugokite šią reikšmę (slapukas ar sesija jūsų svetainės pusėje, rekomenduojama trukmė: 45 dienos). Būtent ji leis priskirti užsakymą. Parametro pavadinimas (zzb_click pagal numatytuosius nustatymus) yra konfigūruojamas pagal pageidavimą.

5. Pranešti apie užsakymą (postback S2S)

Kai tik klientas pateikia užsakymą (pirkimas arba patvirtintas supirkimo prašymas) ir turite zzb_click, iškvieskite mūsų postback iš savo serverio:

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 }

• Priskyrimo langas: 45 dienos po paspaudimo; vėliau — atsakymas 422 attribution_window_expired.
• order_ref turi būti unikalus: dublikatas grąžina 409 duplicate_order_ref (idempotentiškumas — galite saugiai bandyti iš naujo).
• type: SALE pirkimui, BUYBACK supirkimui.
• currency: tik EUR — bet kuri kita valiuta atmetama (422 unsupported_currency).

6. Testuoti sandbox aplinkoje

Pridėkite "test": true prie postback: užklausa visiškai validuojama (raktas, click_id, 45 d. langas), tačiau jokia konversija nei registruojama, nei apmokestinama.

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

7. Klaidų kodai

8. Atsiskaitymas

Kiekviena priskirta konversija generuoja komisinį atlyginimą (sutartinis tarifas, matomas per /api/v1/me). QuizzBuy jums periodiškai siunčia patvirtintų konversijų suvestinę sąskaitą. Jei turite klausimų: susisiekite su mumis.

9. Marketplace — pardavimas QuizzBuy platformoje

SALE tipo skelbimai su quantity > 0 parduodami tiesiogiai QuizzBuy platformoje (kliento mokėjimas pas mus, grynosios sumos, atskaičius komisinį, pervedimas). Papildomi laukai: quantity (atsargos), color, grade (A/B/C), batteryHealth (%), warrantyMonths. Skelbimas automatiškai susiejamas su atitinkama produkto kortele (prekės ženklas + modelis + talpa + spalva).

# 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 — pranešimai apie pardavimus

Užregistruokite HTTPS galutinį tašką; pranešime jums apie kiekvieną žingsnį užsakymo, kuriame yra jūsų produktų (order.created, order.paid, order.cancelled). Slaptas raktas grąžinamas tik sukūrimo metu — išsaugokite jį.

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"

Kiekvienas pristatymas yra pasirašytas. Patikrinkite antraštę 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

Nesėkmės atveju (≠ 2xx) bandome dar kartą su atidėjimu: 1 min, 5 min, 30 min, 2 val., 12 val. Taip pat gausite el. laišką su pranešimu apie pardavimą.

11. Tvarkyti savo užsakymus

Peržiūrėkite savo užsakymo eilutes, patvirtinkite gavimą, tada išsiųskite su sekimo numeriu (klientas informuojamas automatiškai). Pristatymo adresas matomas tik po apmokėjimo.

# 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. Valdoma reprizė (trade-in)

Valdoma reprizė eina toliau nei paprastas supirkimas per nukreipimą: privatus asmuo pateikia savo įrenginį per QuizzBuy, o jūs valdote visą bylą per API (priėmimas, gavimas, priešpasiūlymas, apmokėjimas). Klientui rodoma kaina yra užfiksuota pateikimo metu pagal jūsų supirkimo kainoraštį (žr. §14); ją galite peržiūrėti tik žemyn ir tik po gavimo, pateikdami motyvuotą priešpasiūlymą.

Visi galutiniai taškai autentifikuojami jūsų API raktu (Authorization: Bearer zzb_live_…) ir grąžina tik jūsų bylas.

Gyvavimo ciklas

SUBMITTED → ACCEPTED → SHIPPED → RECEIVED → PAID. Dvi šakos: REJECTED (atsisakymas prieš išsiuntimą) ir COUNTER_OFFER (priešpasiūlymas po patikros, kurį privatus asmuo priima — tada PAID — arba atmeta — įrenginio grąžinimas, CANCELLED).

Išvardyti ir peržiūrėti

# 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 (neprivalomas filtras): viena iš aukščiau esančios lentelės reikšmių — priešingu atveju 400 invalid_status.
• limit: maks. 200 (numatyta 50); offset puslapiavimui.
• customer (privataus asmens kontaktas) matomas tik šioje partnerių API, niekada webhooks pranešimuose.

Perėjimai

Kiekvienas veiksmas yra POST ir grąžina { "ok": true, "trade_in": { … } }. Perėjimas iš nesuderinamo statuso grąžina 409 invalid_status (su faktiniu current). Privatus asmuo informuojamas el. laišku kiekviename etape.

# 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: tik iš SUBMITTED. shippingLabelUrl neprivalomas (URL, ≤ 500 simb.).
• receive: iš SHIPPED arba ACCEPTED (kliento nedeklaruota siunta/pristatymas).
• counter: iš RECEIVED. amountCents turi būti griežtai mažesnis už offer_cents, priešingu atveju 400 counter_not_lower; reason privalomas (1–500 simb.). Tada privatus asmuo priima arba atmeta pasiūlymą savo sekimo puslapyje.
• pay: iš RECEIVED. payoutRef privalomas (pavedimo nuoroda, 1–120 simb.).
• reject: tik iš SUBMITTED — jokio turinio nereikalaujama.

13. Reprizės webhooks (trade_in.*)

Tie patys webhooks (§10, identiška X-ZZbuy-Signature parašo antraštė) apima valdomą reprizę. Kuriant galutinį tašką užsiprenumeruokite visus arba dalį trade_in.* įvykių:

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

Pristatymo turinys (privataus asmens kontaktas jame nenurodomas — gaukite jį per 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. Pateikti savo supirkimo kainoraštį

Alternatyvus „push“ metodas mūsų vykdomam CSV srautui: siųskite tiesiogiai savo supirkimo kainų kainoraštį. Kiekvienoje eilutėje yra 4 sumos pagal įrenginio būklę. Kainos papildo tą pačią lentelę kaip ir automatinė sinchronizacija — todėl jos iškart pasirodo palyginimo įrankyje ir naudojamos kaip užfiksuota kaina valdomai reprizei (§12). Operacija yra upsert pagal (prekės ženklą, kategoriją, modelį, talpą).

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: nuo 1 iki 2000 eilučių per užklausą.
• category: SMARTPHONE, TABLET, LAPTOP, SMARTWATCH, AUDIO arba GAMING.
• priceNewCents (naujas), priceGoodCents (geras), priceFairCents (su žymėmis), priceBrokenCents (sugadintas) — centais, ≥ 0.
• storage ir url neprivalomi; talpa automatiškai normalizuojama (pvz., „256go“ → „256 GB“).