Boutik Pam — Dokimantasyon API pou revandè yo

Dokiman sa a pèmèt yon sit ekstèn (WordPress, Shopify, sit ki fèt ak kòd, oswa yon bot) konekte ak Boutik Pam. Pa gen plugin obligatwa. Sèlman yon sèvè ki ka fè yon demann HTTPS.

Dokiman sa a dekri vrè konpòtman kòd API a (reseller-api v3.5.7). Kote yon bagay pa ko fèt nan kòd la, nou di l klèman.

0. Telechaje dokiman an

• Li an liy: https://boutik-pam.com/?rsa_docs=1
• Telechaje HTML: https://boutik-pam.com/?rsa_docs=html
• Telechaje Markdown: https://boutik-pam.com/?rsa_docs=md

1. Enfòmasyon debaz

Enpòtan:

• Rele API a sèlman sou sèvè ou (backend). Pa janm mete X-API-Secret nan JavaScript ki kouri nan navigatè kliyan an.
• Tout apèl mande https.
• Admin Boutik Pam bay ou kle ak sekrè a. Ou ka wè sekrè a ankò nan paj « API mwen » nan portal la, men li sansib: pa janm pataje l, epi sove l sèlman sou sèvè ou.

2. Otantifikasyon

Chak demann mande de header:

X-API-Key: <kle ou a>
X-API-Secret: <sekrè ou a>
Content-Type: application/json

3. Wout yo

3.1 GET /catalog

Repons: { "success": true, "catalog": [...], "catalogs": [...] }.

• catalog — lis plat tout pwodwi ki disponib pou ou.
• catalogs — menm pwodwi yo, gwoupe pa katalòg (catalog_id, catalog_title, position, products).

Pwodwi ki nan yon katalòg sèlman parèt. Yon pwodwi ki pa nan okenn katalòg aktif pa parèt, epi ou pa ka kòmande l.

Chak pwodwi gen:

Egzanp yon pwodwi jwèt nan catalog (valè yo se egzanp):

{
  "product_id": 13858,
  "sku": "FF-100",
  "name": "100 + 10 bonis",
  "price": 139.99,
  "currency": "HTG",
  "categories": ["110"],
  "catalog_id": "free-fire-amerik",
  "catalog_title": "Free Fire Amerik",
  "requires_player_id": true,
  "requires_server_id": false,
  "customer_fields": [
    { "key": "player_id", "label": "Player ID", "required": true, "type": "text" }
  ],
  "verify_player_endpoint": "https://boutik-pam.com/wp-json/reseller/v1/catalog/13858/verify-player",
  "in_stock": true
}

customer_fields: chak chan gen key, label, required (default true), ak type (default text). Chan yo soti nan meta founisè pwodwi a. Nòmalizasyon an fèt otomatikman:

Fè fòm kliyan an ak customer_fields. Si yon chan gen required: true, mande l.

Règ chan yo:

• player_id toujou prezan pou yon pwodwi jwèt, menm si meta a pa bay li.
• server_id / zone_id obligatwa sèlman si chan an gen required: true. Si l obligatwa e w pa voye l: 400 rsa_missing_server_id.
• charname pa obligatwa, sof si chan an gen required: true. Si l obligatwa e vid: 400 rsa_missing_charname.
• Si yon pwodwi gen yon chan required: true ki pa nan lis ki sipòte pa API a (player_id, server_id, zone_id, charname), /catalog/{id}/verify-player ak /order retounen 422 rsa_unsupported_required_field (ak non chan an). Pa gen okenn kòmand kreye nanka sa a. Kontakte Boutik Pam pou korije konfigirasyon pwodwi a.
• Lòt chan ki pa obligatwa yo pa transmèt bay sistèm nan.

3.2 POST /catalog/{id}/verify-player

{id} se product_id (nan /catalog), pa catalog_id. Se yon nonb (egzanp 13858).

Kò JSON:

{
  "player_id": "123456789",
  "server_id": "",
  "charname": ""
}

Non jwè a (name) soti nan sistèm verifikasyon an, pa nan kliyan an. Kliyan an pa bezwen tape non an.

Ki jan verifikasyon an mache (dapre kòd la):

1. Pwodwi a dwe aktif, nan yon katalòg, avèk yon pri, e disponib pou kont ou. Si non, 404.
2. Pwodwi a dwe yon jwèt ki konfigire pou verifikasyon Player ID. Si non, 422 rsa_not_game.
3. Sistèm nan rele sèvis verifikasyon an ak { game, user_id, server_id?, charname? }. Delè a se 20 segonn.
4. Entèpretasyon an strik: si youn nan chan valid, success, exists oswa exists_in_game di false (oswa "false", "0", "invalid"), ID an pa valid, menm si yon lòt chan di wi. Sinon, ID an konsidere kòm valid si youn nan chan sa yo di wi: valid = "valid" oswa true; success, exists oswa exists_in_game = true; oswa si li gen yon non (name, player_name, username).
5. Non an pran nan name, player_name, username, oswa account_name (premye ki egziste).

Repons pou yon ID valid (egzak, sa kòd la retounen):

{
  "success": true,
  "valid": true,
  "player_id": "123456789",
  "server_id": null,
  "name": "PlayerName"
}

Repons lan retounen tou server_id (sa ou te voye a), epi region ak server sèlman si sèvis la bay yo. Kòd la pa garanti yo.

Repons pou erè yo (fòma WordPress: code, message, data.status):

Erè sèvis yo (401, 403, 429, 5xx) parèt toujou kòm 503, pa kòm « ID pa valid », kèlkeswa kò repons lan. Kliyan an pa dwe wè yo kòm erè ID.

3.3 GET /balance

Repons: { "success": true, "balance": 1250.00, "currency": "HTG", "site_name": "Non sit ou a" }.

currency la montre devis balance la (menm devis ak price nan /catalog ak debit nan /order).

3.4 POST /order

Kò JSON:

{
  "sku": "FF-100",
  "quantity": 1,
  "player_id": "123456789",
  "server_id": "",
  "charname": "",
  "external_order_id": "maCommande-000123",
  "webhook_url": "https://monsite.com/api/boutikpam-webhook"
}

Si motè livrezon pwodwi a pa disponib sou sèvè a, /order retounen 503 rsa_delivery_service_unavailable ANVAN okenn debit. Eseye ankò pita.

Pou pwodwi ki gen verify_player_endpoint, /order egzije yon verifikasyon ki resan pou menm product_id ak menm revandè a. Si ou pa rele verify-player ak menm player_id, server_id ak charname nan 3 èdtan anvan, /order retounen 422 rsa_player_not_verified. Si kliyan an chanje ID, sèvè oswa non karaktè a, verifye ankò. Pou kat kado, pa gen verifikasyon.

Idempotence: si ou voye menm external_order_id ak menm done yo ankò, ou jwenn menm kòmand lan epi ou pa peye de fwa. Si done yo chanje, ou resevwa 409 rsa_idempotency_conflict.

Ou ka voye menm valè a nan header Idempotency-Key. Si ou voye tou de, yo dwe menm bagay.

Repons nòmal (201 oswa 200): gen success, message, order_id, wc_order_id, external_order_id, product_id, sku, quantity, player_id, server_id, charname, status, payment_status, total_price, currency, new_balance, refunded, refund_status, response_note, history, codes, updated_at.

Erè espesifik: 402 rsa_insufficient_balance, 422 rsa_product_unavailable (pa nan stòk, pa nan katalòg, oswa pa gen pri), 422 rsa_not_linked, 400 rsa_missing_idempotency, 400 rsa_missing_player_id / rsa_missing_server_id, 400 rsa_invalid_quantity, 400 rsa_identifier_too_long, 400 rsa_missing_product, 409 rsa_idempotency_conflict, 409 rsa_previous_attempt_failed, 429 rsa_rate_limited, 503 rsa_rate_busy, 503 rsa_storage_unsafe. Erè anplis: 400 rsa_idempotency_mismatch, 404 rsa_invalid_product, 409 rsa_product_mismatch, 409 rsa_unexpected_order_status, 500 rsa_order_failed, 500 rsa_payment_failed, 500 rsa_delivery_start_failed, 503 rsa_woocommerce_missing, 503 rsa_no_wallet_plugin.

3.5 GET /order/{id}

{id} ka external_order_id ou a oswa order_id Boutik Pam lan.

Erè: 404 rsa_order_not_found.

4. Webhook

Si ou bay webhook_url, Boutik Pam voye yon POST chak fwa estati a chanje.

Kò a gen: event_id, order_id, external_order_id, wc_order_id, product_id, sku, quantity, status, payment_status, refunded, refund_status, message, history, codes, updated_at.

Header yo:

• X-Reseller-Timestamp — lè a (Unix, segonn)
• X-Reseller-Signature — sha256= + HMAC-SHA256 de timestamp + "." + kò_brit_la, ak API Secret ou a kòm kle (ansyen header, pou kompatibilite)
• X-Reseller-Signature-V2 — menm fòmilasyon, men ak kle verifikasyon webhook ou a (nan paj « API mwen »). Nouvo entegrasyon dwe sèvi ak V2.

Verifye siyati a

Toujou verifye siyati a anvan ou kwè mesaj la. Fè konparezon an ak hash_equals oswa nan tan konstan.

Node.js:

const crypto = require('crypto');
function verify(rawBody, timestamp, signature, secret) {
  if (typeof rawBody !== 'string' || typeof timestamp !== 'string' || typeof signature !== 'string' || !secret) return false;
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) >= 300) return false;
  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody).digest('hex'));
  const received = Buffer.from(signature);
  // timingSafeEqual lanse yon erè si longè yo pa egal: verifye longè a anvan.
  if (expected.length !== received.length) return false;
  return crypto.timingSafeEqual(expected, received);
}

Python:

import hmac, hashlib, time
def verify(raw_body: str, timestamp: str, signature: str, secret: str) -> bool:
    if not isinstance(raw_body, str) or not isinstance(timestamp, str) or not isinstance(signature, str) or not secret:
        return False
    try:
        ts = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - ts) >= 300:
        return False
    expected = 'sha256=' + hmac.new(secret.encode(), (timestamp + '.' + raw_body).encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

PHP:

function rsa_verify_webhook($raw_body, $ts, $signature, $secret) {
    if (!is_string($raw_body) || !is_string($ts) || !is_string($signature) || $secret === '') return false;
    if (!ctype_digit($ts) || abs(time() - (int) $ts) >= 300) return false;
    $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw_body, $secret);
    return hash_equals($expected, $signature);
}

Pran raw_body tèks brit la (pa re-kodaj JSON an).

Sispann si event_id deja trete, pou evite doub livrezon. Kò mesaj la ak event_id la rete MENM nan tout relansman yo (sèlman X-Reseller-Timestamp ak X-Reseller-Signature chanje). Si ou resevwa menm event_id yon dezyèm fwa, konfime l epi pa trete l ankò.

Konpòtman livrezon:

• Ou dwe reponn ak yon kòd HTTP 2xx nan 5 segonn. Si ou pa reponn, oswa ou reponn ak lòt kòd, Boutik Pam konsidere l kòm echwe.
• Si l echwe, Boutik Pam relanse l jiska 5 fwa: 1 minit, 5 minit, 15 minit, 1 è, apre 3 èdtan. Apre sa, li abandone.
• Voye webhook yo ak relansman yo fèt pa WP-Cron, sou sit la. Si sit la gen ti trafik oswa WP-Cron dezaktive, yo ka reta. Pwosesis kreyasyon kòmand lan pa tann yo.
• Evènman yo sere nan yon tablo pèmanan, avèk kò mesaj ak event_id ki pa chanje ant tantativ yo. Si planifikasyon yon travay echwe, yon travay rekiperasyon chak 5 minit replanifye evènman ki pare yo. Yon travay ki bloke plis pase 2 minit kapab rekipere. Yon reseptè dwe toujou dedouble ak event_id, paske yon timeout ka rive apre li fin resevwa mesaj la. Mesaj ka rive nan yon lòt lòd; verifye estati aktyèl la atravè GET /order/{id} anvan yon desizyon final.
• Si ou rate yon webhook (oswa ou pa sèten ou resevwa l), rele GET /order/{id} pou jwenn estati aktyèl kòmand lan. Sa toujou mache.

5. Modèl jesyon erè ak repetisyon

• Timeout oswa erè rezo sou POST /order: ou pa konnen si kòmand lan kreye. Rele POST /order ANKÒ ak menm external_order_id ak menm done. Si li te kreye deja, ou jwenn menm repons lan (200 oswa 202), san nouvo debit.
• 202: kòmand lan ap kreye. Tann, epi rele GET /order/{id}.
• 409 rsa_idempotency_conflict: menm external_order_id ak done diferan. Pa repete l. Itilize yon nouvo external_order_id.
• 409 rsa_previous_attempt_failed: lòd sa a gen yon debit oswa yon ranbousman deja (oswa yon rezilta final). Kreye yon nouvo external_order_id.
• 402 rsa_insufficient_balance: pa gen debit. Mande kliyan an rechaje kont la. Apre sa, ou ka rele POST /order ANKÒ ak menm external_order_id: lòd la re-ouvri otomatikman (3.5.7).
• 500 rsa_order_failed / rsa_payment_failed: si lòd la pa gen payment_reference (pa gen debit), menm external_order_id la mache ankò.
• 503 rsa_delivery_service_unavailable sou /order: motè livrezon an pa disponib. Pa gen okenn debit. Retry ak yon ti reta, ak menm external_order_id.
• Ranbousman: ranbousman fèt yon sèl fwa. Si estati a refunded, lajan an retounen sou balans ou. Verifye ak GET /order/{id} olye de kreye yon nouvo acha.

// Modèl sou sèvè ou (pseudo-kòd)
const r = await callApi('POST', '/order', body, { timeoutMs: 15000 })
  .catch(() => ({ status: 0 }));           // timeout / rezo
if (r.status === 0 || r.status === 503) {
  // menm external_order_id, retry ak reta (pa plis pase kèk tantativ)
}

5.1 Egzanp rapid: verifye ID epi kreye kòmand

1. Jwenn pwodwi a ak chan kliyan an bezwen (GET /catalog).

2. Verifye ID a (sèvè a, avan kliyan an peye):

curl -X POST https://boutik-pam.com/wp-json/reseller/v1/catalog/13858/verify-player \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"123456789","server_id":"","charname":""}'

Si repons lan gen "valid": true, sove player_id, server_id, ak name pou kliyan an wè l. Si valid pa vrè, bloke acha a.

3. Kreye kòmand lan (pandan kliyan an peye):

curl -X POST https://boutik-pam.com/wp-json/reseller/v1/order \
  -H "X-API-Key: $KEY" -H "X-API-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"sku":"FF-100","quantity":1,"player_id":"123456789","external_order_id":"cmd-000123"}'

Node.js:

const base = 'https://boutik-pam.com/wp-json/reseller/v1';
const headers = { 'X-API-Key': KEY, 'X-API-Secret': SECRET, 'Content-Type': 'application/json' };

const v = await fetch(`${base}/catalog/13858/verify-player`, {
  method: 'POST', headers,
  body: JSON.stringify({ player_id: '123456789', server_id: '', charname: '' }),
});
const verified = await v.json();
if (!v.ok || !verified.valid) throw new Error('ID pa valid');

Python:

import requests
base = 'https://boutik-pam.com/wp-json/reseller/v1'
h = {'X-API-Key': KEY, 'X-API-Secret': SECRET}
r = requests.post(f'{base}/catalog/13858/verify-player', headers=h,
                  json={'player_id': '123456789', 'server_id': '', 'charname': ''}, timeout=25)
data = r.json()
if not r.ok or not data.get('valid'):
    raise RuntimeError('ID pa valid')

6. Kòd erè (rezime)

7. Lis kontwòl anvan lansman

• Kle ak sekrè a nan yon kote sekirize sou sèvè a sèlman
• Ou rele verify-player sou sèvè ou (pa nan navigatè), epi ou sèvi ak product_id nan {id}
• Ou bloke acha a si valid pa vrè
• Ou verifye ankò si kliyan an chanje player_id, server_id, oswa charname
• Chak kòmand gen yon external_order_id inik
• Ou sove repons lan anvan ou montre anyen bay kliyan an
• Ou verifye siyati webhook la epi ou sispann event_id ki double
• Ou pa montre history, new_balance oswa non Boutik Pam bay kliyan final ou yo
• Ou respekte limit 60 /order pa minit
• Ou teste ak yon kòmand reyèl ki ba ou yon kòd, epi ou konfime codes parèt

8. Chanjman API

Vèsyon 3.5.7:

1. Lockout konte sèlman tantativ echwe. Yon sekrè ki kòrèk pa janm bloke pa lockout la.
2. Re-ouvri lòd: yon lòd ki echwe san debit (402, erè kreyasyon) ka re-eseye ak menm external_order_id.
3. Limit pou GET /balance (60/minit) ak GET /order/{id} (120/minit).
4. Webhook: signature legacy ka dezaktive pa filtre rsa_send_legacy_webhook_signature.
5. Mesaj piblik yo kache non BPFF/wp2p tou.

Vèsyon 3.5.6:

1. Kle verifikasyon webhook (V2): nouvo header X-Reseller-Signature-V2, siyen ak yon kle derive (pa API Secret la). Kle a parèt nan paj « API mwen ». Ansyen X-Reseller-Signature rete pou kompatibilite.
2. Revokasyon dijans: nan « Rekreye API Key/Secret », koche « revoke imedyatman » pou kontoune limit 24 èdtan lè yon kle konpwomèt. Aksyon an anrejistre nan Log API.
3. Kota chak jou pou verify-player: 2 000 demann pa jou pou chak revandè (rsa_daily_quota, 429).
4. Sekrè pa efase ankò: yon kont ki gen sekrè ki pa ka dechifre pa pèdi done li. Admin wè yon avètisman. Rekreye kle yo pou kont sa yo.
5. Rekonsiliyasyon: lòd ki bloke yo pa anpeche lòt yo verifye ankò.

Vèsyon 3.5.5:

1. Repons founisè vid ([]) pou verify-player retounen 502 rsa_delivery_bad_response, pa 422.

Vèsyon 3.5.4:

1. Repons verifikasyon ki pa yon array (tèks, nonb, boolean, objè) retounen 502 kontwole, san erè PHP. null, WP_Error ak eksepsyon sèvis yo retounen 503 san ekspoze detay entèn.
2. Chan repons ki mal fòme yo rejte anvan konvèsyon; 401/403/429/5xx toujou rete erè sèvis 503.
3. Pwoteksyon cache portal la aplike sou hooks wp ak template_redirect anvan rann template la. Li rekonèt paj ki konfigire a ak twa shortcode portal yo.
4. Nòt delivery_stalled la baze sou 60 minit depi dènye mizajou kòmand lan, menm si yon tranzaksyon livrezon egziste. Li pa pwouve livrezon an echwe.

Vèsyon 3.5.3:

1. Tablo kòd erè ak estati HTTP korije: /order pwodwi pa disponib retounen 422; erè 5xx sou verify-player retounen rsa_delivery_service_unavailable (503).
2. Katalòg konstwi yon sèl fwa pou portal la ak pou GET /catalog.
3. Ajisteman balans admin: montan an dwe diferan de 0 epi li pa ka mennen balans lan nan negatif; chak ajisteman anrejistre nan Log API.
4. Yon pwodwi ke admin dezaktive pa re-aktive pa otomatizasyon MACHANN.
5. Yon lòd ki rete processing plis pase 60 minit depi dènye mizajou li make delivery_stalled nan istwa a (pa gen ranbousman otomatik; admin verifye).
6. Paj portal la pa sere nan cache (done sekrè yo).

Vèsyon 3.5.2:

1. Ranbousman fini rete pwoteje kont tout nouvo estati WooCommerce, menm failed, cancelled ak refunded.
2. Webhook yo sere nan baz done a; yon purge cache pa retire evènman ki poko livre yo. Premye tantativ la ak relansman yo fèt an fon.
3. Planifikasyon verifye; travay rekiperasyon an repran travay ki pa t planifye oswa ki te bloke.
4. Player ID toujou make obligatwa pou pwodwi jwèt.
5. Disponibilite motè a verifye apati callbacks livrezon ki chaje yo. Adaptè espesyal bezwen yon verifikasyon entegrasyon sou sit la.

Vèsyon 3.5.1:

1. Non blokaj MySQL kout (64 karaktè) pou pa bloke API a sou sèvè ki aplike limit la.
2. Webhook: kò ak event_id fiks ant tout relansman yo. Yo voye yo nan cron, pa nan demann acha a.
3. Chan obligatwa: player_id toujou prezan pou jwèt; yon chan obligatwa ki pa sipòte refize kòmand lan (rsa_unsupported_required_field).
4. Estati WooCommerce: yon kòmand ki deja ranbouse pa chanje estati a lè WooCommerce voye yon nouvo estati.
5. Motè bpff: plugin an dwe aktif, pa sèlman tablo a.

Vèsyon 3.5.0:

1. Repetisyon kòmand: yon demann ki repete ak menm external_order_id ak menm done retounen menm kòmand lan, menm lè charname la gen valè.
2. Balans: GET /balance retounen currency.
3. Verifye jwè: repons yo entèprete strikteman. Yon chan ki di false pa janm vin valid. server_id obligatwa pou pwodwi ki mande l.
4. Erè sèvis: 5xx, 401, 403 ak 429 nan sèvis verifikasyon an parèt kòm 503, pa kòm « ID pa valid ».
5. Katalòg: varyasyon yo parèt ak bon paran yo, san doublon.
6. Webhook: relansman otomatik (5 fwa) ak log rezilta chak tantativ.
7. Limit: /catalog ak /verify-player gen chak kont pwòp yo.
8. Motè livrezon: si motè a pa disponib, /order retounen 503 anvan okenn debit.

Fèt (vèsyon anvan):

1. /order egzije verifikasyon ki resan pou pwodwi jwèt (rsa_player_not_verified, 3 èdtan).
2. Limit pousantaj separe sou /catalog ak /verify-player (60/minit chak), separe de /order.
3. Erè klarifye: erè konfigirasyon sèvis la (401, 403, 429) parèt kòm 503; repons ki pa valid parèt kòm 502. Yo pa parèt kòm « ID pa valid ».
4. zone_id aksepte kòm alternatif pou server_id.
5. Rejyon ak sèvè retounen sèlman si sèvis verifikasyon an bay yo.