Cupoanele de reducere pot fi de tip import (se încarcă manual coduri) sau API (codurile sunt generate on-demand). Dacă aveți Shopify, nu este nevoie să creati manual un webhook URL deoarece plugin-ul NewsMAN îl are deja încorportat, detalii în articolul următor, secțiunea Discounts.
Pentru a genera cupoane de reducere din website via API, este nevoie ca website-ul dumneavoastră să expună un webhook URL care:
- să recepționeze request-uri de tip POST
- să genereze coduri unice (cu o singură utilizare) în website-ul dumneavoastră în funcție de parametrii trimiși
Detalii request-uri:
- în POST body se trimite un json reprezentand un array cheie / valoare. Cheile sunt numele parametrilor
- parametrii sunt adăugați și ca parametrii GET la URL-ul specificat
Exemplu preluare parametrii din POST body
$payload = @file_get_contents('php://input');
$payload = json_decode($payload);
Parametrii obligatorii ce pot fi specificați sunt următorii:
type – INT – Tipul discount-ului generat de cupon, poate fi 0 (valoare fixă), 1 (procent) sau 2 (livrare gratuită)
value – INT | FLOAT – Apare pentru tip procent sau valoare fixă. Dacă discount_type este percent (1), conține procentajul pentru reducere, altfel conține valoarea fixă.
Opțional, se pot specifica și următorii parametrii:
batch_size – INT – numărul de coduri care ar trebui generate de webhook URL (Opțional, dar recomandat. Codurile pot fi generate în batch-uri pentru a reduce numărul de request-uri. Se poate întoarce un singur cod chiar dacă este prezent acest parametru)
prefix – String – prefix-ul care ar trebui să fie adăugat la începutul codurilor
expire_date – String – data în format YYYY-MM-DD HH:II:SS la care ar trebui să expire codurile
min_amount – FLOAT – valoarea minimă a sumei din coș pentru care se poate aplica cuponul (dacă se trimite ar trebui raportat la suma fără TVA)
currency – STRING – poate fi RON sau EUR (este prezent în cazul în care se trimite valoare fixă pentru discount sau valoare minimă pentru comandă)
Răspunsul returnat poate fi un string (care conține codul generat, dacă s-a generat un singur cod) sau un array (listă de coduri), în format json, care conține urmatoarele chei:
- status – 0 (pt eroare) sau 1 (pt succes)
- codes – array conținând codurile generate (în caz de succes)
- msg – mesajul erorii (în caz de eroare)
Exemple de request și response
Mai jos sunt câteva exemple de generare a codurilor de reducere, pentru diferite tipuri de discount și configurații.
1. Generarea unui singur cod de reducere de 10%
Input payload
{"type":1,"batch_size":1,"value":10,"currency":"RON"}
Output
"PER-10-cRON-1467118"
Când este generat un singur cod, răspunsul poate fi returnat direct sub forma unui string care conține codul generat.
2. Generarea a 30 de coduri cu reducere de 15% și prefix
În acest exemplu sunt generate 30 de coduri, cu o reducere de 15% și prefixul PRFX.
Input payload
{"type":1,"batch_size":30,"value":15,"prefix":"PRFX","currency":"RON"}
Output
{
"status":1,
"codes":[
"PRFXPER-15-cRON-7177243",
"PRFXPER-15-cRON-8581108",
"PRFXPER-15-cRON-6207611",
"...",
"PRFXPER-15-cRON-6565263",
"PRFXPER-15-cRON-2713358"
],
"msg":""
}
În răspunsul complet, array-ul codes va conține toate cele 30 de coduri generate.
3. Generarea a 50 de coduri cu reducere de 20%, expirare și comandă minimă
În acest exemplu sunt generate 50 de coduri cu reducere de 20%, prefixul CPNRED, comandă minimă de 150 RON și expirare la 24 februarie 2025.
Input payload
{
"type":1,
"batch_size":50,
"value":20,
"prefix":"CPNRED",
"currency":"RON",
"min_amount":150,
"expire_date":"2025-02-24 23:59:59"
}
Output
{
"status":1,
"codes":[
"CPNREDPER-20-20250224-min150-cRON-4381573",
"CPNREDPER-20-20250224-min150-cRON-6608735",
"CPNREDPER-20-20250224-min150-cRON-4193933",
"...",
"CPNREDPER-20-20250224-min150-cRON-3775844",
"CPNREDPER-20-20250224-min150-cRON-7844755"
],
"msg":""
}
Array-ul codes va conține toate cele 50 de coduri generate.
4. Generarea a 50 de coduri cu reducere fixă de 100 RON
În acest exemplu sunt generate 50 de coduri cu reducere fixă de 100 RON, comandă minimă de 500 RON și expirare la 28 februarie 2025.
Input payload
{
"type":0,
"batch_size":50,
"value":100,
"currency":"RON",
"min_amount":500,
"expire_date":"2025-02-28 23:59:59"
}
Output
{
"status":1,
"codes":[
"SUM-100-20250228-min500-cRON-9691044",
"SUM-100-20250228-min500-cRON-4237098",
"SUM-100-20250228-min500-cRON-1175281",
"...",
"SUM-100-20250228-min500-cRON-9042386",
"SUM-100-20250228-min500-cRON-1989044"
],
"msg":""
}
Array-ul codes va conține toate cele 50 de coduri generate.
5. Generarea a 50 de coduri pentru livrare gratuită
În acest exemplu sunt generate 50 de coduri pentru livrare gratuită, cu prefixul LVRGRT, comandă minimă de 300 RON și expirare la 28 februarie 2025.
Pentru livrare gratuită se folosește type: 2, iar parametrul value nu este necesar.
Input payload
{
"type":2,
"batch_size":50,
"prefix":"LVRGRT",
"currency":"RON",
"min_amount":300,
"expire_date":"2025-02-28 23:59:59"
}
Output
{
"status":1,
"codes":[
"LVRGRTFRS-20250228-min300-cRON-6476936",
"LVRGRTFRS-20250228-min300-cRON-7601607",
"LVRGRTFRS-20250228-min300-cRON-7380747",
"...",
"LVRGRTFRS-20250228-min300-cRON-2618959",
"LVRGRTFRS-20250228-min300-cRON-4885340"
],
"msg":""
}
Array-ul codes va conține toate cele 50 de coduri generate.
Pe scurt
Pentru a genera cupoane de reducere din website prin API:
- Configurează un webhook URL pe website-ul tău.
- Asigură-te că webhook-ul acceptă request-uri POST.
- Procesează parametrii primiți în request.
- Generează coduri unice, cu o singură utilizare.
- Returnează codurile în formatul JSON așteptat de NewsMAN.
- Folosește
batch_sizeatunci când ai nevoie să generezi mai multe coduri simultan.
API-ul permite generarea de cupoane pentru reduceri procentuale, reduceri cu valoare fixă și livrare gratuită, precum și configurarea unor condiții precum prefix, dată de expirare și valoare minimă a comenzii.