Partnerdokumentation

1. Få en API-nøgle

Kontakt din QuizzBuy-kontaktperson (eller kontaktformularen). Vi genererer en nøgle til dig i formatet zzb_live_… — den udleveres kun én gang, så opbevar den sikkert. Send den med i hver forespørgsel i HTTP-headeren:

Authorization: Bearer zzb_live_VOTRE_CLE

2. Verificer din nøgle

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. Offentliggør dine annoncer

En annonce er enten et tilbagekøbstilbud (BUYBACK — du overtager en enhed til en given pris) eller et salgstilbud (SALE — et renoveret produkt, du sælger). Indsendelsen er en upsert: genindsendelse af samme externalId opdaterer annoncen.

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 eller GAMING.
• condition: LIKE_NEW, EXCELLENT, GOOD, FAIR eller BROKEN.
• priceCents: pris i øre/cent (52000 = 520 €).
• Hver ny annonce (eller ændring) gennemgår moderation før offentliggørelse.

Opdater, list eller deaktiver:

# 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. Sporing af klik

Når en QuizzBuy-besøgende klikker sig videre til din side, indeholder destinations-URL'en et klik-id:

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

Gem denne værdi (cookie eller session på din side, anbefalet varighed: 45 dage). Det er den, der gør det muligt at tilskrive ordren. Parameternavnet (zzb_click som standard) kan konfigureres efter aftale.

5. Notificer en ordre (postback S2S)

Så snart en kunde afgiver en ordre (køb eller godkendt tilbagekøbsanmodning), og du har et zzb_click, skal du kalde vores postback fra din server:

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 }

• Tilskrivningsvindue: 45 dage efter kliktidspunktet; derefter svar 422 attribution_window_expired.
• order_ref skal være unik: et duplikat giver 409 duplicate_order_ref (idempotens — du kan roligt forsøge igen).
• type: SALE for et køb, BUYBACK for et tilbagekøb.
• currency: kun EUR — enhver anden valuta afvises (422 unsupported_currency).

6. Test i sandbox

Tilføj "test": true til postbacket: forespørgslen valideres fuldt ud (nøgle, click_id, 45-dages vindue), men ingen konvertering registreres eller faktureres.

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

7. Fejlkoder

8. Fakturering

Hver tilskrevet konvertering udløser en provision (kontraktlig sats, synlig via /api/v1/me). QuizzBuy sender dig periodisk en samlet faktura for godkendte konverteringer. Ved spørgsmål: kontakt os.

9. Marketplace — sælg på QuizzBuy

Annoncer af typen SALE med en quantity > 0 sælges direkte på QuizzBuy (kundebetaling hos os, udbetaling af nettobeløb efter provision). Yderligere felter: quantity (lager), color, grade (A/B/C), batteryHealth (%), warrantyMonths. Annoncen knyttes automatisk til det tilsvarende produktkort (mærke + model + kapacitet + farve).

# 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 — bliv underrettet om salg

Registrer et HTTPS-endpoint; vi giver dig besked ved hvert trin i en ordre, der indeholder dine produkter (order.created, order.paid, order.cancelled). Hemmeligheden returneres kun ved oprettelsen — gem den.

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"

Hver levering er signeret. Kontroller headeren 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

Ved fejl (≠ 2xx) forsøger vi igen med backoff: 1 min, 5 min, 30 min, 2 t, 12 t. Du modtager også en e-mail med salgsnotifikation.

11. Behandl dine ordrer

List dine ordrelinjer, bekræft modtagelse og send derefter med et sporingsnummer (kunden underrettes automatisk). Leveringsadressen er først synlig efter betaling.

# 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. Administreret tilbagekøb (trade-in)

Administreret tilbagekøb går videre end almindeligt tilbagekøb via omdirigering: privatpersonen indsender sin enhed fra QuizzBuy, og du styrer hele sagen via API'en (accept, modtagelse, modtilbud, betaling). Prisen, der vises til kunden, er låst ved indsendelsen ud fra din tilbagekøbsprisliste (se §14); du kan kun sætte den ned efter modtagelse via et begrundet modtilbud.

Alle endpoints autentificeres med din API-nøgle (Authorization: Bearer zzb_live_…) og returnerer kun dine sager.

Livscyklus

SUBMITTED → ACCEPTED → SHIPPED → RECEIVED → PAID. To forgreninger: REJECTED (afvisning før afsendelse) og COUNTER_OFFER (modtilbud efter inspektion, som privatpersonen accepterer — herefter PAID — eller afviser — enheden returneres, CANCELLED).

List & se

# 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 (valgfrit filter): en værdi fra ovenstående tabel — ellers 400 invalid_status.
• limit: maks. 200 (standard 50); offset til paginering.
• customer (privatpersonens kontaktoplysninger) er kun synlig via denne partner-API, aldrig i webhooks.

Overgange

Hver handling er en POST og returnerer { "ok": true, "trade_in": { … } }. En overgang fra en inkompatibel status giver 409 invalid_status (med den faktiske current). Privatpersonen får besked pr. e-mail ved hvert trin.

# 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: kun fra SUBMITTED. shippingLabelUrl valgfrit (URL, ≤ 500 tegn).
• receive: fra SHIPPED eller ACCEPTED (afsendelse ikke registreret af kunden).
• counter: fra RECEIVED. amountCents skal være strengt lavere end offer_cents, ellers 400 counter_not_lower; reason obligatorisk (1–500 tegn). Herefter er det privatpersonen, der accepterer eller afviser fra sin sporingsside.
• pay: fra RECEIVED. payoutRef obligatorisk (overførselsreference, 1–120 tegn).
• reject: kun fra SUBMITTED — ingen krop påkrævet.

13. Webhooks for tilbagekøb (trade_in.*)

De samme webhooks (§10, identisk signatur X-ZZbuy-Signature) dækker administreret tilbagekøb. Abonner på alle eller nogle af trade_in.*-hændelserne ved oprettelsen af et 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"]
  }'

Leveringens indhold (privatpersonens kontaktoplysninger fremgår ikke heraf — hent dem via 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. Send din tilbagekøbsprisliste

Et "push"-alternativ til CSV-flowet, som vi selv trækker: send din tilbagekøbsprisliste direkte. Hver linje indeholder de 4 beløb afhængigt af enhedens tilstand. Priserne fødes ind i samme tabel som den automatiske synkronisering — de vises derfor med det samme i sammenligningsværktøjet og fungerer som låst pris for administreret tilbagekøb (§12). Handlingen er en upsert pr. (mærke, kategori, model, kapacitet).

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 til 2000 linjer pr. forespørgsel.
• category: SMARTPHONE, TABLET, LAPTOP, SMARTWATCH, AUDIO eller GAMING.
• priceNewCents (ny), priceGoodCents (god), priceFairCents (brugt), priceBrokenCents (i stykker) — i øre/cent, ≥ 0.
• storage og url valgfrie; kapaciteten normaliseres automatisk (f.eks. « 256go » → « 256 GB »).