Partneru dokumentācija

1. Iegūt API atslēgu

Sazinieties ar savu QuizzBuy kontaktpersonu (vai izmantojiet kontaktformu). Mēs jums izveidojam atslēgu formātā zzb_live_… — tā jums tiek nosūtīta tikai vienu reizi, glabājiet to drošā vietā. Norādiet to katrā pieprasījumā HTTP galvenē:

Authorization: Bearer zzb_live_VOTRE_CLE

2. Pārbaudīt savu atslēgu

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. Publicēt savus sludinājumus

Sludinājums ir vai nu atpirkšanas piedāvājums (BUYBACK — jūs pārņemat ierīci par noteiktu cenu), vai pārdošanas piedāvājums (SALE — atjaunots produkts, ko pārdodat). Nosūtīšana ir upsert: atkārtoti nosūtot to pašu externalId, sludinājums tiek atjaunināts.

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 vai GAMING.
• condition: LIKE_NEW, EXCELLENT, GOOD, FAIR vai BROKEN.
• priceCents: cena centos (52000 = 520 €).
• Katrs jauns sludinājums (vai izmaiņas tajā) pirms publicēšanas iziet moderāciju.

Atjaunināt, uzskaitīt vai deaktivizēt:

# 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. Klikšķu izsekošana

Kad QuizzBuy apmeklētājs noklikšķina uz jūsu vietni, galamērķa URL satur klikšķa identifikatoru:

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

Saglabājiet šo vērtību (sīkfailā vai sesijā savā vietnē, ieteicamais glabāšanas ilgums: 45 dienas). Tieši tā ļaus attiecināt pasūtījumu. Parametra nosaukums (pēc noklusējuma zzb_click) ir konfigurējams pēc pieprasījuma.

5. Paziņot par pasūtījumu (postback S2S)

Tiklīdz klients veic pasūtījumu (pirkumu vai apstiprinātu atpirkšanas pieprasījumu) un jums ir pieejams zzb_click, izsauciet mūsu postback no sava servera:

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 }

• Attiecināšanas periods: 45 dienas pēc klikšķa; pēc tam atbilde ir 422 attribution_window_expired.
• order_ref jābūt unikālam: dublikāts atgriež 409 duplicate_order_ref (idempotence — varat droši mēģināt vēlreiz).
• type: SALE pirkumam, BUYBACK atpirkšanai.
• currency: tikai EUR — jebkura cita valūta tiek noraidīta (422 unsupported_currency).

6. Testēt smilškastē (sandbox)

Pievienojiet "test": true postback pieprasījumam: pieprasījums tiek pilnībā validēts (atslēga, click_id, 45 dienu periods), taču neviena konversija netiek reģistrēta vai apmaksāta.

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

7. Kļūdu kodi

8. Norēķini

Katra attiecinātā konversija ģenerē komisiju (līgumā noteiktā likme, redzama caur /api/v1/me). QuizzBuy periodiski nosūta jums kopsavilkuma rēķinu par apstiprinātajām konversijām. Ar jautājumiem: sazinieties ar mums.

9. Tirdzniecības vieta — pārdot QuizzBuy platformā

Sludinājumi SALE ar quantity > 0 tiek pārdoti tieši QuizzBuy platformā (klienta maksājumu saņemam mēs, komisijas neto summu pārskaitām jums). Papildu lauki: quantity (krājums), color, grade (A/B/C), batteryHealth (%), warrantyMonths. Sludinājums automātiski tiek piesaistīts atbilstošajai produkta kartītei (zīmols + modelis + ietilpība + krāsa).

# 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. Tīmekļa āķi (webhooks) — saņemt paziņojumus par pārdošanu

Reģistrējiet HTTPS galapunktu; mēs jums paziņojam par katru pasūtījuma posmu, kas satur jūsu produktus (order.created, order.paid, order.cancelled). Slepenā atslēga tiek atgriezta tikai izveides brīdī — saglabājiet to.

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"

Katra piegāde ir parakstīta. Pārbaudiet galveni 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

Neveiksmes gadījumā (≠ 2xx) mēs mēģinām vēlreiz ar pieaugošu intervālu: 1 min, 5 min, 30 min, 2 h, 12 h. Jūs saņemat arī e-pasta paziņojumu par pārdošanu.

11. Apstrādāt savus pasūtījumus

Uzskaitiet savas pasūtījumu rindas, apstipriniet saņemšanu un tad nosūtiet ar izsekošanas numuru (klients tiek automātiski informēts). Piegādes adrese ir redzama tikai pēc apmaksas.

# 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. Pārvaldīta atpirkšana (trade-in)

Pārvaldīta atpirkšana sniedzas tālāk par vienkāršu atpirkšanu ar novirzīšanu: privātpersona iesniedz savu ierīci caur QuizzBuy, un jūs pārvaldāt visu procesu caur API (apstiprināšana, saņemšana, pretpiedāvājums, apmaksa). Klientam parādītā cena tiek fiksēta iesniegšanas brīdī pēc jūsu atpirkšanas cenrāža (skat. §14); jūs to varat pārskatīt uz leju tikai pēc saņemšanas, izmantojot pamatotu pretpiedāvājumu.

Visi galapunkti tiek autentificēti ar jūsu API atslēgu (Authorization: Bearer zzb_live_…) un atgriež tikai jūsu dosjē.

Dzīves cikls

SUBMITTED → ACCEPTED → SHIPPED → RECEIVED → PAID. Divi atzarojumi: REJECTED (atteikums pirms nosūtīšanas) un COUNTER_OFFER (pretpiedāvājums pēc pārbaudes, ko privātpersona vai nu pieņem — tad PAID — vai noraida — ierīces atgriešana, CANCELLED).

Uzskaitīt un skatīt

# 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 (neobligāts filtrs): kāda no augstāk esošajā tabulā minētajām vērtībām — pretējā gadījumā 400 invalid_status.
• limit: maksimums 200 (pēc noklusējuma 50); offset lapošanai.
• customer (privātpersonas kontaktinformācija) ir redzams tikai šajā partneru API, nekad tīmekļa āķos.

Pārejas

Katra darbība ir POST pieprasījums un atgriež { "ok": true, "trade_in": { … } }. Pāreja no nesaderīga statusa atgriež 409 invalid_status (ar faktisko current). Privātpersona katrā posmā tiek informēta pa e-pastu.

# 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: tikai no statusa SUBMITTED. shippingLabelUrl nav obligāts (URL, ≤ 500 rakstzīmes).
• receive: no statusa SHIPPED vai ACCEPTED (noguldījums/nosūtīšana, ko klients nav deklarējis).
• counter: no statusa RECEIVED. amountCents jābūt stingri mazākam par offer_cents, pretējā gadījumā 400 counter_not_lower; reason obligāts (1–500 rakstzīmes). Pēc tam privātpersona pieņem vai noraida to no savas izsekošanas lapas.
• pay: no statusa RECEIVED. payoutRef obligāts (pārskaitījuma atsauce, 1–120 rakstzīmes).
• reject: tikai no statusa SUBMITTED — nav vajadzīgs pieprasījuma saturs.

13. Atpirkšanas tīmekļa āķi (trade_in.*)

Tie paši tīmekļa āķi (§10, identisks X-ZZbuy-Signature paraksts) attiecas arī uz pārvaldīto atpirkšanu. Abonējiet visus vai daļu trade_in.* notikumu, izveidojot galapunktu:

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

Piegādes saturs (privātpersonas kontaktinformācija tajā nav iekļauta — iegūstiet to caur 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. Nosūtīt savu atpirkšanas cenrādi

Alternatīva „push“ plūsma mūsu vilktajai CSV plūsmai: tieši nosūtiet savu atpirkšanas cenu cenrādi. Katrā rindā ir 4 summas atkarībā no ierīces stāvokļa. Cenas tiek pievienotas tai pašai tabulai, ko izmanto automātiskā sinhronizācija — tāpēc tās nekavējoties parādās salīdzinātājā un kalpo kā fiksētā cena pārvaldītajai atpirkšanai (§12). Darbība ir upsert pēc (zīmols, kategorija, modelis, ietilpība).

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 līdz 2000 rindas vienā pieprasījumā.
• category: SMARTPHONE, TABLET, LAPTOP, SMARTWATCH, AUDIO vai GAMING.
• priceNewCents (jauns), priceGoodCents (labs), priceFairCents (nolietots), priceBrokenCents (bojāts) — centos, ≥ 0.
• storage un url nav obligāti; ietilpība tiek automātiski normalizēta (piem. „256go“ → „256 GB“).