Contractul de integrare
Recoma stă între trei părți: tu, cumpărătorul care primește reducerea, și omul care ți l-a trimis pe cumpărător. Primele două se văd la checkout. A treia nu — și de aceea integrarea ta este singura care poate spune că a existat.
Patru reguli. Fiecare are un motiv, iar motivul contează mai mult decât regula: dacă înțelegi de ce, nu ai cum să o încalci din greșeală.
1. Fiecare reducere acordată se înregistrează
validate decide dacă un cod se aplică. redeem înregistrează comanda. Sunt două apeluri pentru că sunt două momente diferite — dar reducerea nu se acordă fără al doilea.
redeem, omul care ți-a trimis clientul nu este plătit. Nu apare o eroare nicăieri: cumpărătorul e mulțumit, tu ai vândut, și singurul care pierde este cel care nu se uită.De aceea redeem cere validation_id-ul primit de la validate. O ofertă și o comandă sunt o pereche, iar o ofertă rămasă fără pereche este un rând în baza noastră de date — nu o discuție despre procente.
2. Înregistrezi la plată, nu la coș
Leagă redeem de evenimentul „comandă plătită”, nu de momentul în care clientul scrie codul în coș.
Un coș nu este o comandă. Dacă înregistrezi acolo, plătești comision pe coșuri abandonate, apoi trebuie să le anulezi pe toate — și ajungi să ai mai multe anulări decât vânzări, ceea ce arată exact ca o integrare care încearcă să ascundă ceva.
O validare rămâne valabilă 30 de zile. Salvezi validation_id pe comandă și îl folosești când intră banii. E suficient și pentru plata ramburs, unde curierul încasează peste câteva zile.
3. Retururile se anulează
Comandă returnată înseamnă POST /v1/redemptions/{id}/void. Comisionul se întoarce, iar codul își recapătă utilizarea.
Regula asta e în interesul tău: fără ea plătești comision pe bani pe care i-ai dat înapoi. O menționăm pentru că e singura din cele patru pe care oamenii o uită din grabă, nu din calcul.
4. Cheia nu pleacă de pe server
Cheile rk_live_… și rk_test_… sunt secrete de server. Niciodată în JavaScript-ul paginii, niciodată într-o aplicație mobilă, niciodată într-un repo public.
Origin a fost făcut dintr-un browser, și blochează trecerea în producție.Dacă ai nevoie de validare în pagină, proxează prin serverul tău. Un endpoint al tău care apelează validate este corect; o cheie în fetch() nu este.
Ce măsurăm, și cine află
Nu îți cerem să ai încredere că regulile de mai sus contează. Le măsurăm, iar ce măsurăm este scris aici — nu într-un document intern.
| Semnal | Ce înseamnă |
|---|---|
redeem_stopped | Validările continuă, comenzile au ajuns la zero. Cel mai grav, pentru că reducerile pleacă în continuare. |
never_redeemed | Două săptămâni în producție, validări multe, nicio comandă. Aproape întotdeauna un webhook legat greșit. |
selective_commission | Codurile cu comision se înregistrează mult mai rar decât cele fără. O eroare de cod nu știe care e care. |
conversion_drop | Raportul comenzi/validări a scăzut mult sub media ta din ultimele patru săptămâni. |
amount_shift | Comanda tipică înregistrată a scăzut brusc față de propriul tău istoric. |
void_spike | Multe comenzi înregistrate și anulate imediat după. |
Comparația este cu istoricul tău, nu cu o medie a platformei. Un magazin de mobilă nu convertește ca unul de cosmetice, și nu ne interesează să pretindem altceva.
Ce se întâmplă dacă ceva nu e în regulă
Presupunerea de la care pornim: cele mai multe comenzi neînregistrate sunt uitate, nu ascunse. Un hook legat greșit e mult mai frecvent decât o decizie — și banii se pierd la fel în ambele cazuri. Deci primul pas e întotdeauna un ajutor.
| Când | Ce se întâmplă |
|---|---|
| Imediat | Primești un email și o notificare în cont, cu cifrele. Nimeni altcineva nu vede nimic. |
| După 3 zile | Ajunge la noi, dacă nu s-a rezolvat între timp. |
| După ce ne uităm | Dacă e real, cifra apare colaboratorilor conectați. Niciodată automat — un om se uită întâi. |
| Rar, și greu | Suspendarea accesului la producție. Cere două semnale independente, două săptămâni, două încercări de contact, un motiv scris, și anunțarea colaboratorilor înainte. |
Numărul simplu — câte validări au devenit comenzi — este oricum vizibil colaboratorilor conectați, de la prima zi, lângă mediana platformei. La fel ca la recomandările din magazin. Ce nu se vede fără confirmarea noastră este acuzația.
Mai departe
Sandbox și chei — mediul de test, codurile fixe și valorile magice. Trecerea în producție — cele zece verificări, explicate una câte una.