API pentru integrări software

API – integrare simplă cu POS, software de comenzi și alte sisteme

Cardora este „creierul” programelor de loialitate: gestionează carduri digitale, ștampile, recompense, notificări și integrarea cu Apple Wallet și Google Wallet.

De astăzi, deschidem și „ușa de integrare” pentru ecosistemul tău: API pentru clienți si parteneri, un API REST JSON, gândit pentru integrări curate între Cardora și:

sisteme POS / case de marcat,
platforme de comenzi, livrari,
CRM-uri, aplicații interne sau alte instrumente de marketing.

Scopul: să poți folosi Cardora acolo unde lucrezi deja – în aplicațiile tale – fără exporturi manuale, fișiere CSV și improvizații.

📖 Documentație completă, specificații OpenAPI și exemple de cod:
app.cardora.ro/docs/api/

De ce un API Cardora?

Tot mai multe companii care folosesc Cardora au deja infrastructura lor:

un POS propriu în locație (restaurant, cafenea, beauty salon),
o platformă de comenzi online sau aplicație mobilă proprie,
un CRM sau un sistem intern de raportare.

Fără un API, datele de loialitate rămân „închise” în Cardora și nu pot fi afișate sau folosite în timp real în celelalte sisteme. Asta duce la:

muncă manuală: export / import de liste de clienți,
lipsă de context: operatorul din POS nu vede câte ștampile are clientul,
experiență fragmentată: clientul nu vede în aplicația restaurantului ce card de loialitate are.

API-ul Cardora rezolvă exact acest lucru: permite sistemelor externe să „vorbească” direct cu Cardora, în mod sigur și standardizat.

Ce poate face API-ul Cardora (v1)

API-ul acoperă ciclul complet de loialitate:
de la identificarea clientului, la acordarea de ștampile la fiecare achiziție, până la revendicarea recompenselor – totul direct din sistemul tău.

Capabilități cheie

Identificarea clientului din codul QR al cardului digital
Scanezi cardul digital din Apple Wallet / Google Wallet, trimiți token-ul către Cardora și primești:
- ID-ul clientului în Cardora ,
- eventualul ID extern deja mapat,
- informații despre card (tip, ștampile, recompense disponibile etc.).
Crearea sau actualizarea unui client după ID-ul tău intern
Poți trimite ID-ul din POS / platformă, împreună cu nume, email, telefon.
API-ul se ocupă să creeze sau să actualizeze clientul în Cardora și să lege profilul de ID-ul tău extern (inclusiv dacă îl găsește după email sau telefon).
Obținerea unui client și a soldurilor de carduri după ID-ul tău extern
Ideal când vrei să afișezi în aplicația ta:
- câte ștampile are clientul,
- ce carduri de loialitate deține,
- câte ștampile mai are până la următoarea recompensă.
Listarea și vizualizarea șabloanelor de carduri
Primești lista tuturor cardurilor active (ex: „Coffee Stamp Card”, „Membership Card”) și regulile lor (ștampile per vizită, praguri de recompense etc.). Poți obține și detalii complete despre un singur șablon, inclusiv configurația de recompense.
Procesarea comenzilor și acordarea automată de ștampile/puncte
Trimite o comandă din POS sau platforma de comenzi, iar Cardora acordă automat ștampilele sau punctele corespunzătoare. Funcționează pentru:
- carduri cu ștampile – trimiți numărul de ștampile direct,
- carduri cashback – trimiți suma comenzii, iar punctele se calculează automat,
- carduri membership – punctele se acordă pe baza valorii tranzacției.
Dacă clientul nu are încă un card, acesta se creează automat. Comenzile sunt idempotente: dacă trimiți aceeași comandă de două ori, ștampilele nu se dublează.
Revendicarea recompenselor
Când un client a acumulat suficiente ștampile, poți revendica recompensa direct din POS sau aplicația ta. API-ul verifică automat dacă pragul este atins, resetează cardul și returnează detaliile recompensei (ex: „Cafea gratuită la alegere”).
Emiterea de carduri noi pentru clienți
Poți emite un card de loialitate pentru un client existent, direct din sistemul tău, fără ca acesta să acceseze interfața Cardora. Dacă clientul are deja un card de acel tip, API-ul semnalează duplicatul.

Cum funcționează – pe scurt, pentru dezvoltatori

1. Autentificare simplă, fără sesiuni

Toate cererile către API se fac printr-o cheie API trimisă în header:

Cheile se generează din panoul de administrare Cardora, secțiunea Setări → Chei API.
Nu există sesiuni sau cookie-uri – fiecare cerere este stateless și ușor de integrat din orice limbaj sau platformă.

2. Doar JSON, clar și predictibil

Răspunsurile sunt tot JSON: fie obiectele de date, fie un obiect de eroare cu error și code.
Codurile de status HTTP sunt standard (200, 400, 401, 403, 404, 415, 429, 500) și pot fi tratate ușor în aplicație.

3. Versionare stabilă – `/api/public/v1`

Toate endpoint-urile publice stau sub /api/public/v1.
Evoluțiile ulterioare vor fi backwards compatible în cadrul v1, astfel încât integrările tale să nu se „strice” la următoarele release-uri.

Scenarii reale de integrare

1. POS în locație: fluxul complet de loialitate

Context: Ai un POS în cafenea / restaurant. Clientul comandă, plătește și beneficiază automat de programul de loialitate – fără pași manuali.

Flux tipic:

Identificare: Clientul prezintă cardul digital din Apple Wallet / Google Wallet. POS-ul scanează codul QR și trimite token-ul către Cardora. Răspunsul conține ID-ul clientului, ștampilele curente și recompensele disponibile.
Acordare ștampile: Când comanda este finalizată, POS-ul trimite comanda către Cardora (endpoint-ul /orders) cu ID-ul extern al clientului și numărul de ștampile. Dacă clientul nu are încă card, acesta se creează automat.
Afișare status: POS-ul primește înapoi soldul actualizat: „8/10 ștampile, mai ai 2 până la recompensă” sau „Recompensă disponibilă!”.
Revendicare recompensă: Când clientul are o recompensă disponibilă, operatorul apasă un buton în POS care apelează endpoint-ul /loyalty/redeem. Cardul se resetează automat, iar clientul primește recompensa.

Astfel, întreg ciclul de loialitate se întâmplă direct în POS – fără a deschide interfața Cardora, fără pași manuali. Cardul din Apple/Google Wallet se actualizează automat.

2. Platformă de comenzi online: loialitate automată la fiecare comandă

Context: Ai un sistem de comenzi online (website sau aplicație mobilă). Clienții au deja conturi cu ID-urile lor interne.

Ce vrei: la fiecare comandă, clientul să acumuleze automat ștampile/puncte de loialitate, fără import manual.

Flux tipic:

Prima comandă: Când clientul plasează prima comandă, apelezi /customers/upsert cu ID-ul tău intern, email și nume. Cardora creează sau găsește clientul.
Emitere card (opțional): Poți emite un card de loialitate via /customers/{id}/cards, sau lași endpoint-ul de comenzi să creeze cardul automat.
La fiecare comandă: Trimiți comanda la /orders cu ID-ul comenzii (pentru idempotență), ID-ul clientului și numărul de ștampile sau valoarea comenzii. Cardora acordă ștampilele automat.
Afișare în aplicație: Folosești răspunsul (sau /customers/{id}) pentru a afișa clientului: „Ai 8/10 ștampile – mai ai 2 până la cafea gratuită!”.
Revendicare recompensă: Când clientul are recompensă disponibilă, apelezi /loyalty/redeem – fie automat la checkout, fie la cerere.

3. CRM sau aplicație internă: afișezi cardurile clientului

Context: În CRM sau într-o aplicație de backoffice vrei să vezi statusul de loialitate al unui client (câte carduri are, câte ștampile, ce recompense a acumulat).

Flux tipic:

Ai identificator de client din sistemul tău (ex: POS-12345).
Apelezi API-ul Cardora
Răspunsul îți dă:
- date de contact (nume, telefon, email – în măsura în care sunt stocate),
- lista cardurilor din Cardora pentru afacerea ta, inclusiv:
  - număr de ștampile,
  - câte mai sunt până la următoarea recompensă,
  - câte recompense sunt disponibile.

Poți integra asta în fișa clientului din CRM, astfel încât echipa ta să aibă context complet la fiecare interacțiune.

4. Integrare cu alte sisteme: știi ce carduri există și ce reguli au

Context: Vrei ca aplicația ta să „înțeleagă” regulile de loialitate (de ex. pentru a afișa mesaje dinamice sau a calcula anumite statistici).

Flux tipic:

Apelezi /card-templates pentru lista tuturor cardurilor active, sau /card-templates/{id} pentru detalii complete despre un anume card.
Primești configurația completă (stamps, membership, cashback_points etc.) și regulile specifice:
- ștampile per vizită,
- ștampile per sumă cheltuită,
- praguri de recompense (ex: 10 ștampile = „Cafea gratuită la alegere”),
- rate de earning pentru cashback sau membership.

Poți folosi aceste date pentru a afișa în aplicația ta mesaje de tipul „La încă 3 cafele, clientul primește una gratis”.

Experiența pentru dezvoltatori

Testare în siguranță, fără date reale

API-ul include un mod de test foarte simplu care ajuta dezvoltatorii de aplicatii sa implementeze mult mai rapid.

Totul întoarce răspunsuri predefinite, astfel încât să poți implementa și testa integrarea fără a atinge baza ta reală de clienți.

👉 Exemple de cod (Python, JavaScript, PHP), specificații OpenAPI și ghid complet:
app.cardora.ro/docs/api/

Oferim și o specificație OpenAPI (YAML), pe care o poți importa direct în Swagger UI, Postman, Insomnia sau OpenAPI Generator pentru a genera automat clienți în diverse limbaje.

Securitate și limitare de trafic

Public Partner API este construit cu accent pe securitate:

Chei API per afacere, revocabile oricând din panou.
Whitelisting de IP (opțional) pentru a restricționa accesul doar din infrastructura ta.
Rate limiting per cheie – pentru a preveni abuzul.
Tratamente de eroare clare (coduri HTTP + code intern) pentru logare și monitorizare.

Cum începi concret

Dacă ești deja client Cardora (business):

Autentifică-te în panoul de administrare.
Mergi la Setări Afacere → Chei API și creează o cheie nouă (ex: „Integrare POS” sau „Comenzi online”).
Trimite cheia și linkul către documentația API echipei sau furnizorului tău de software.
Porniți cu endpoint-urile de test (TEST-CUSTOMER-001, token-ul de test) și apoi treceți pe date reale.

Dacă ești furnizor de POS, comenzi online sau software pentru HoReCa / retail:

Cardora poate deveni stratul de loialitate peste clienții pe care îi ai deja.
Prin API, poți oferi direct în aplicația ta:
- carduri digitale integrate cu Apple Wallet și Google Wallet,
- ștampile și recompense,
- notificări și campanii de loialitate.