Livrări cu încasare pe BlueCash 50

1. Pe scurt

Terminalul nu așteaptă comenzi „împinse” spre el. Aplicația eRGiss de pe BlueCash 50 cere singură comenzile prin internet, prin HTTPS, ca orice browser. De aceea merge pe 4G, în spatele rețelei operatorului, fără IP public și fără calculator.

• Comenzile zilei apar ca listă pe terminal. Livratorul o alege pe cea de la ușa clientului.
• Bonul se emite doar când livratorul încasează, nu când comanda ajunge pe terminal.
• La card, plata se face prin DatecsPay pe același aparat. Bonul fiscal iese numai dacă plata e aprobată, iar datele tranzacției se tipăresc pe același bon.
• Numărul bonului, numărul raportului Z și datele plății se întorc în aplicația voastră.

2. eRGiss sau DatecseRG?

Avem două aplicații pentru casele Datecs BlueCash. Arată asemănător, dar rezolvă probleme diferite.

3. Ce face livratorul pe terminal

1. Deschide eRGiss. Vede lista comenzilor de livrat pentru ziua respectivă, cu client, adresă, interval și total.
2. La client, atinge comanda. Terminalul aduce varianta la zi a comenzii și arată produsele cu cantități și prețuri.
3. Apasă NUMERAR sau CARD. La card, clientul apropie cardul sau introduce PIN-ul pe ecranul BlueCash 50 (DatecsPay).
4. Se tipărește bonul fiscal. La card, datele tranzacției apar pe același bon.
5. Comanda devine „încasată” pe terminal și în aplicația voastră, cu numărul bonului.

4. Varianta recomandată: ecranul de livrări eRGiss + 3 endpoint-uri la voi

Noi facem ecranul de pe terminal, plata, bonul și urmărirea confirmărilor. Voi expuneți în aplicația voastră trei endpoint-uri JSON prin HTTPS. Le apelează serverul nostru, nu terminalul, deci nu aveți nimic de instalat pe aparat.

Autentificare

• Fiecare cerere vine cu antetul Authorization: Bearer <token>. Tokenul îl generați voi și ni-l transmiteți pe un canal separat.
• Adresa de bază o alegeți voi, de exemplu https://app.exemplu.ro/api/ergiss/v1.
• Toate răspunsurile sunt application/json; charset=utf-8. Orice eroare întoarce un cod HTTP diferit de 2xx și un mesaj în {"error": "..."}.

GET/orders?date=AAAA-LL-ZZ&driver=<cod>

Lista comenzilor de livrat într-o zi, opțional filtrată pe livrator. Se cere la deschiderea ecranului și la reîmprospătare.

{
  "orders": [
    {
      "id": "10234",
      "number": "K-10234",
      "delivery_date": "2026-10-16",
      "window": "08:00-10:00",
      "customer": { "name": "Ana Pop", "phone": "07xx xxx xxx", "address": "Str. Lungă 10, Brașov" },
      "total": 86.90,
      "payment_hint": "card",
      "status": "de_livrat",
      "updated_at": "2026-10-15T18:02:11+03:00"
    }
  ]
}

• status poate fi de_livrat, incasata sau anulata. Comenzile anulate sau încasate apar pe terminal, dar nu mai pot fi încasate.
• payment_hint e informativ: cash, card sau null. Livratorul alege metoda reală la ușă.

GET/orders/{id}

Comanda completă, cerută chiar înainte de încasare. Așa, o modificare făcută la birou după plecarea mașinii ajunge pe bon.

{
  "id": "10234",
  "number": "K-10234",
  "status": "de_livrat",
  "updated_at": "2026-10-15T18:02:11+03:00",
  "customer": { "name": "Ana Pop", "cui": null },
  "lines": [
    { "sku": "PM800", "name": "Pâine cu maia 800 g", "qty": 2,     "unit": "buc", "price": 18.50, "vat": 11 },
    { "sku": "PRJ01", "name": "Prăjitură cu nuci",   "qty": 0.750, "unit": "kg",  "price": 66.53, "vat": 11 }
  ],
  "total": 86.90,
  "notes": "Interfon 12"
}

POST/orders/{id}/receipt

Rezultatul încasării. Îl trimitem după fiecare bon emis și după fiecare încercare eșuată.

{
  "event_id": "7c1f0d2e-5b8a-4e7e-9d55-1f2a3b4c5d6e",
  "order_id": "10234",
  "status": "emis",
  "receipt": { "number": "57", "z_number": "112", "issued_at": "2026-10-16T09:14:05+03:00" },
  "payment": {
    "method": "card",
    "amount": 86.90,
    "card": { "approved": true, "masked_pan": "************1234", "auth_code": "123456", "rrn": "628912345678", "tid": "12345678" }
  },
  "terminal": { "serial": "P6A1202508289348", "driver": "D03" },
  "error": null
}

• status = emis sau eroare. La eroare, receipt e null și error conține mesajul casei.
• event_id e același la fiecare retrimitere a aceluiași rezultat. Dacă îl primiți a doua oară, răspundeți tot 200 și nu procesați din nou.
• Răspuns așteptat: 200 {"ok": true}. La orice alt răspuns sau la lipsă de răspuns, retrimitem automat și vă anunțăm dacă problema persistă.
• Pentru numerar, payment.method e cash și card lipsește.

5. Bonuri duplicate și semnal slab

Cum evităm bonul dublu

• O comandă se încasează o singură dată. După confirmare, terminalul arată numărul bonului în locul butoanelor de plată.
• Cât timp o comandă e în curs de încasare pe un terminal, alt terminal nu o poate încasa.
• Dacă bonul a ieșit dar confirmarea nu a ajuns, comanda rămâne „neconfirmată”. Reemiterea cere o confirmare explicită a livratorului, după ce verifică ultimul bon tipărit.
• La voi, event_id face ca aceeași confirmare primită de două ori să conteze o singură dată.
• La card, bonul se emite numai după ce DatecsPay aprobă plata. O plată refuzată sau anulată nu produce bon.

Ce se întâmplă la semnal slab

• Lista comenzilor se încarcă la plecare și se poate reîmprospăta oricând.
• Detaliul comenzii are nevoie de câteva secunde de internet la ușa clientului, ca să fie la zi.
• Plata cu cardul are nevoie de internet pentru autorizarea băncii, ca orice POS mobil.
• Bonul fiscal se tipărește local, din modulul fiscal al aparatului, fără internet.
• Confirmarea se păstrează pe terminal și se retrimite automat când revine semnalul. Apoi serverul nostru o livrează la voi, cu reîncercări.

6. Varianta 2: pagina voastră direct în eRGiss

Dacă vreți control complet asupra ecranului de pe terminal, eRGiss poate deschide o pagină din aplicația voastră. Pagina rulează într-un WebView pe BlueCash 50 și folosește câteva comenzi speciale pentru plată și bon. Noi doar înrolăm terminalul cu adresa paginii voastre.

Bon fiscal

Pagina navighează la un URL care întoarce un document .inp cu antetul Content-Type: application/dgpfabf și cu Content-Length setat. eRGiss îl descarcă cu cookie-urile sesiunii, îl tipărește pe casa internă și apelează funcția JavaScript window.ergBonResult.

S,1,______,_,__;Paine cu maia 800 g;18.50;2;0;0;11%;0;0;buc
S,1,______,_,__;Prajitura cu nuci;66.53;0.750;0;0;11%;0;0;kg
T,1,______,_,__;0;86.90;;;;
U;https://app.exemplu.ro/ergiss/cb.php?order=10234&key=...

• S = articol: denumire; preț cu TVA; cantitate; 0; 0; cota TVA; discount; 0; unitate.
• T = plată: 0 numerar, 1 card; apoi suma.
• P,1,______,_,__;TEXT;;;;; = text liber pe bon. K,1,______,_,__;CUI; = codul fiscal al cumpărătorului.
• U = opțional, URL apelat de terminal după bon cu &bon_nr=57&status=OK sau &bon_nr=0&status=EROARE&msg=.... URL-ul trebuie să conțină deja un ?.

window.ergBonResult = function (r) {
  // r = { bon_nr: "57", z: "", status: "OK" | "EROARE", msg: "..." }
};

Plata cu cardul

location.href = 'app://card?amount=8690';   // suma în bani

window.ergCardResult = function (r) {
  // r = { approved: true|false, resultCode, error, currency,
  //       fiscalFirst, fiscalSecond, nonFiscal, rj }
  if (r.approved) {
    // emiteți .inp cu T,1 (card) și liniile din fiscalFirst / fiscalSecond ca text P pe bon
  }
};

• eRGiss pornește DatecsPay cu suma cerută. Clientul plătește pe ecranul aparatului.
• Emiteți bonul numai dacă approved e true.
• Nu folosiți alert, confirm sau prompt în pagină. În WebView nu apar.

Varianta 2 vă cere mai multă muncă: ecranul, anti-dublarea și retrimiterea confirmărilor le faceți voi. De aceea recomandăm varianta 1.

7. Coexistența cu DUDE și BlueCash Design

• Nu dezinstalați nimic. eRGiss se instalează alături, din Danubius.Store, în versiunea semnată de Datecs.
• eRGiss vorbește direct cu modulul fiscal al aparatului, prin SDK-ul oficial Datecs. Nu are nevoie de DUDE ca să tipărească.
• Folosiți o singură aplicație pentru un bon dat. Bonurile din ambele aplicații ajung în aceeași memorie fiscală și în același raport Z.
• Puteți păstra BlueCash Design pentru vânzările fără comandă și eRGiss pentru livrările din aplicația voastră.

8. Testul pe un singur terminal

1. Ne trimiteți adresa de bază a celor 3 endpoint-uri, un token de test și 3–5 comenzi de probă: una cu produse la kilogram, una cu două cote de TVA, una anulată.
2. Instalați eRGiss din Danubius.Store pe un BlueCash 50.
3. Vă trimitem un cod QR de înrolare. Îl scanați din eRGiss și terminalul se leagă de contul vostru.
4. Încasați comenzile de probă numerar și cu cardul. Verificați bonul tipărit și rezultatul primit în aplicația voastră.
5. Testați și cazurile grele: plată refuzată, hârtie terminată, semnal pierdut după bon, aceeași comandă deschisă pe două terminale.

9. Întrebări frecvente