Magazinul tău, legat la Clarvo POS

1. Pornești puntea și îți iei cheile

În Clarvo POS, la localul tău: Livrări → Setări. Pornește „Magazinul meu, legat la Clarvo”, apoi fă o cheie.

Primești o pereche: cheie (utilizatorul) și secret (parola). Secretul se arată o singură dată. Nu-l păstrăm nici noi în clar, deci nu-l putem arăta a doua oară. Dacă-l pierzi, faci altă cheie și o oprești pe cea veche.

2. Te legi cu cheia și secretul

Se trimit ca utilizator și parolă (HTTP Basic), la fiecare cerere. Nu există jetoane de reînnoit.

curl -u "CHEIA:SECRETUL" https://pos-api.clarvo.ro/api/partener/local

În Laravel:

use Illuminate\Support\Facades\Http;

$clarvo = Http::withBasicAuth(config('clarvo.cheie'), config('clarvo.secret'))
    ->acceptJson()
    ->baseUrl('https://pos-api.clarvo.ro/api/partener');

$local = $clarvo->get('/local')->json();

Dacă nu poți trimite Basic, merg și antetele X-Clarvo-Cheie și X-Clarvo-Secret.

GET /local

Cine e localul, dacă primește comenzi chiar acum și de ce nu, zonele de livrare, metodele de plată, cât durează o ridicare. Întreab-o la fiecare încărcare de pagină: de aici afli dacă arăți butonul „Comandă” sau „Suntem închiși”.

{
  "local": { "nume": "Bistro Central", "oras": "Alba Iulia", "telefon": "0258 800 800", "moneda": "RON", "program": { … } },
  "primeste": true,
  "motiv": null,
  "deschide_la": null,
  "livrare": {
    "activa": true,
    "zone": [
      {
        "id": 1,
        "nume": "Alba Iulia",
        "descriere": null,
        "localitati": ["Alba Iulia"],
        "taxa": 8.99,
        "comanda_minima": 40,
        "prag_gratuit": 60,
        "timp_estimat_min": 45
      }
    ]
  },
  "ridicare": { "activa": true, "timp_min": 20 },
  "plati": [ { "cod": "numerar", "nume": "Numerar la primire" }, … ],
  "programare": { "minim_min": 30, "maxim_ore": 24 }
}

3. Livrarea și ridicarea

Zonele se scriu în Clarvo POS, la local, și coboară de aici. Nu le ține la tine: o taxă schimbată acolo trebuie să se vadă pe site, altfel clientul plătește altceva decât scrie pe nota curierului.

Ce e o zonă

Cum potrivești adresa cu o zonă

La fel ca noi: cauți numele localității în adresă, fără diacritice și fără majuscule, ca pe un cuvânt întreg. „Str. Moților 12, Alba Iulia” cade în zona cu "localitati": ["Alba Iulia"].

function zonaPentru(array $zone, string $adresa): ?array
{
    $curat = fn (string $t) => mb_strtolower(strtr($t, [
        'ă' => 'a', 'â' => 'a', 'î' => 'i', 'ș' => 's', 'ş' => 's', 'ț' => 't', 'ţ' => 't',
    ]));

    $a = $curat($adresa);

    foreach ($zone as $zona) {
        foreach ($zona['localitati'] as $localitate) {
            if (preg_match('/\b'.preg_quote($curat($localitate), '/').'\b/u', $a)) {
                return $zona;
            }
        }
    }

    return null;   // nu livrăm acolo
}

Dacă preferi, poți să-l pui pe client să aleagă localitatea dintr-o listă, în loc s-o ghicești din text. E mai sigur și îi scutește pe amândoi de greșeli de scriere.

Cât plătește pentru livrare

Regula e scurtă: taxa zonei, în afară de cazul în care subtotalul a trecut de pragul gratuit.

$taxa = ($zona['prag_gratuit'] !== null && $subtotal >= $zona['prag_gratuit'])
    ? 0
    : $zona['taxa'];

Socotește-o și tu, ca s-o poți arăta în coș. Dar la comandă tot POS-ul o pune pe notă, din aceleași reguli — deci cele două sume ies la fel, fără să le sincronizezi.

Ridicarea din local

Dacă ridicare.activa e true, clientul poate veni el. Atunci nu ceri adresă, iar ridicare.timp_min îți spune în cât timp e gata, ca să-i dai o oră.

Comandă pentru mai târziu

Trimite programata_la (ISO 8601). Limitele sunt în programare: cel puțin minim_min minute de acum și cel mult maxim_ore ore. Ora trebuie să cadă în programul localului, altfel primești eroare pe câmpul programata_la.

4. Iei meniul

GET /meniu

Grupele și produsele marcate „vizibil online” în POS, cu prețuri, descrieri, poze, alergeni și opțiuni (garnituri, mărimi). Ce ascunde localul în POS nu ajunge la tine.

Ce trebuie ales la comandă: observatii. Unele produse cer o alegere fără preț, cum ar fi Gătire la vită: [{"titlu": "Gătire", "unic": true, "obligatoriu": true, "valori": ["În sânge", "Medium rare", "Medium", "Medium well", "Bine făcut"]}]. Arată-le clientului ca pe o opțiune obligatorie și trimite valoarea aleasă în note la produs, prima, despărțită prin virgulă de ce a mai scris el ("Medium rare, fără sos"). Așa ajunge la bucătărie, ca de pe telefonul ospătarului. La produsele fără nimic de ales, lista e goală.

Categoriile cu program: program și comanda_oricand. O categorie se poate comanda online doar la anumite ore, ca Mic dejun între 08:00 și 12:00: "program": {"de": "08:00", "pana": "12:00", "zile": [1, 2, 3, 4, 5]}. Zilele merg de la 1 (luni) la 7 (duminică); o listă goală înseamnă în fiecare zi, iar null înseamnă oricând. Capetele sunt incluse. Un interval ca 22:00–02:00 trece peste miezul nopții și ține de ziua în care începe. În afara programului, arată categoria doar cu produsele care au "comanda_oricand": true; dacă nu are niciunul, ascunde-o. O comandă cu un produs din afara programului e refuzată cu 422, pe câmpul produse, sau pe programata_la când ora aleasă iese din program. Mesajul se poate arăta clientului așa cum e. Meniul stă în memoria ta cu tot cu program, deci verifică ora la fiecare afișare, nu doar când îl descarci.

Bucătărie sau bar: sectie. Fiecare categorie spune de unde pleacă: "bucatarie" sau "bar" (la o subcategorie fără secție, cea a categoriei de deasupra). Folosește-o ca să împarți meniul, de pildă în Mâncare și Bar. null înseamnă că localul n-a ales încă.

Alergenii: alergeni și urme_alergeni. Pe fiecare produs, două liste de texte: ce conține (["Gluten", "Lapte", "Ouă"]) și ce poate conține în urme (["Susan"], «Poate conține urme de»). O listă goală înseamnă că localul n-a scris nimic, nu că produsul n-ar avea alergeni. Arată-le în fișa produsului.

Meniul în engleză: traduceri. Categoriile, produsele, grupele de opțiuni și fiecare alegere au cheia traduceri, cu textele pe limbi (deocamdată doar en). Româna rămâne în câmpurile obișnuite; în traduceri e doar ce s-a tradus:

// categoria și grupa de opțiuni, alegerea
"traduceri": {"en": {"nume": "Burgers", "descriere": "Grilled on charcoal"}}
"traduceri": {"en": {"nume": "Size"}}
// produsul
"traduceri": {"en": {"nume": "Classic burger", "descriere": "Beef 180 g, cheddar", "alergeni": ["Gluten", "Milk", "Eggs"], "urme_alergeni": ["Sesame"], "unitate": "pc"}}
// nimic tradus
"traduceri": {}

nume și descriere apar doar dacă localul le-a tradus; altfel arată textul românesc. alergeni, urme_alergeni și unitate vin gata în engleză ori de câte ori produsul le are în română: ce a scris localul, altfel traducerea noastră (cei 14 alergeni din UE și unitățile uzuale: buc → pc, porție → portion), altfel textul românesc. Nimic tradus înseamnă un obiect gol, {}, niciodată o listă. Comanda se trimite la fel, cu aceleași id-uri, oricare ar fi limba în care a ales clientul: la bucătărie ajunge în română.

Modificările din POS se văd la tine fără să faci nimic. Localul schimbă prețul în Clarvo, tu citești meniul, ai prețul nou. Nu ține o copie a meniului în baza ta de date mai mult decât ca memorie temporară.

Ca să nu descarci meniul degeaba, ai două căi:

$versiune = cache()->get('clarvo_meniu_versiune');
$r = $clarvo->withHeaders($versiune ? ['If-None-Match' => '"'.$versiune.'"'] : [])->get('/meniu');

if ($r->status() === 304) {
    $meniu = cache()->get('clarvo_meniu');       // n-a mișcat nimic
} else {
    $meniu = $r->json();
    cache()->put('clarvo_meniu', $meniu, now()->addHour());
    cache()->put('clarvo_meniu_versiune', $meniu['versiune'], now()->addHour());
}

Afli pe loc când s-a schimbat meniul. Dacă cheia are o adresă de anunț, îți trimitem acolo un POST imediat după ce localul schimbă ceva din meniu, din zonele de livrare sau din setările livrării (ambalajul, de exemplu), semnat la fel ca anunțul de stare:

X-Clarvo-Eveniment: meniu.schimbat
X-Clarvo-Semnatura: sha256=<hmac_sha256(corpul cererii, secretul adresei de anunț)>

{"eveniment": "meniu.schimbat", "la": "2026-10-20T19:05:00+03:00", "versiune": "3f9c2a1b7d4e8f60"}

Răspunde repede cu 200 și descarcă meniul după răspuns (GET /meniu, GET /local). Dacă adresa ta nu răspunde cu 2xx, repetăm anunțul în fiecare minut până ajunge. O verificare rară (de exemplu, o dată pe oră) rămâne utilă ca plasă de siguranță.

5. Trimiți comanda

POST /comenzi

$r = $clarvo->post('/comenzi', [
    'nume' => 'Maria Pop',
    'prenume' => 'Maria',
    'nume_familie' => 'Pop',
    'telefon' => '0722 111 222',
    'tip' => 'livrare',
    'adresa' => 'Str. Moților 12, Alba Iulia',
    'detalii_adresa' => 'Bl. 3, ap. 7',
    'plata' => 'numerar',
    'note' => 'Fără ceapă.',
    'produse' => [
        ['produs_id' => 12, 'cantitate' => 2, 'optiuni' => [4, 9]],
        ['produs_id' => 31, 'cantitate' => 1, 'note' => 'Medium rare, fără sos'],   // «Gătire» din observatii
    ],
    'acord_marketing' => true,
    'acord_marketing_la' => now()->toIso8601String(),   // clipa bifei
    'acord_marketing_sursa' => 'magazinul-tau.ro/comanda',
]);

$comanda = $r->json('comanda');   // ->['uuid'], ->['total'], ->['stare']

Localul acceptă comanda

Dacă acceptare din GET /local e manuala, comanda apare pe casa localului și nu pleacă la bucătărie până nu apasă cineva «Acceptă». Până atunci starea e primita. Spune-i clientului că localul o confirmă în câteva minute; mesajul din răspuns (mesaj) spune deja asta. Dacă localul o refuză, starea devine anulata, iar în mesaj apare motivul.

GET /comenzi/{uuid}

Unde a ajuns comanda. Stările, în ordine:

Afli pe loc când se schimbă starea

Pune la cheie o adresă de anunț (în Clarvo POS → Livrări → Puntea). La fiecare schimbare de stare trimitem acolo un POST cu comanda, în aceeași formă ca GET /comenzi/{uuid}:

POST https://magazinul-tau.ro/clarvo/stare
X-Clarvo-Eveniment: comanda.stare
X-Clarvo-Semnatura: sha256=<hmac_sha256(corpul cererii, secretul adresei de anunț)>

{"eveniment": "comanda.stare", "la": "2026-09-26T18:20:00+03:00", "comanda": {"uuid": "…", "referinta": "A19-260926-0001", "stare": "in_pregatire", "stare_nume": "În pregătire", "mesaj": "…", …}}

Verifică semnătura înainte să crezi anunțul (hash_equals), apoi trimite-i clientului emailul stării noi. Dacă adresa ta nu răspunde, anunțul nu se repetă: întreabă din când în când GET /comenzi/{uuid} cât e comanda în lucru, ca plasă de siguranță.

6. Plata cu cardul

Dacă localul are plata cu cardul pornită (vezi plati din GET /local) și trimiți plata: "card_online", răspunsul are și un bloc plata cu o adresă:

$plata = $r->json('plata');
if ($plata) {
    return redirect()->away($plata['url']);   // pagina de plată
}

Clientul plătește acolo și se întoarce. Comanda nu pleacă la bucătărie până când plata nu e confirmată de procesator — noi nu o credem plătită pe cuvântul nimănui. Starea o vezi cu GET /comenzi/{uuid}. Fără plată în 30 de minute, comanda se anulează singură.

7. Erorile

Toate mesajele de eroare sunt scrise ca să poată fi arătate clientului ca atare, fără să le traduci.

Ce NU face puntea

• Nu îți dă lista de clienți a localului. Datele lor sunt ale lui, nu ale magazinului.
• Nu îți lasă să schimbi meniul. Meniul se ține în POS, într-un singur loc.
• Nu îți dă vânzările, bonurile sau rapoartele. Ele sunt în Clarvo POS.