POSLink Enterprise API

Autentificare

Toate cererile necesită câmpul APIKey de tip UUID/Guid. Pentru endpoint-urile GET, APIKey se trimite ca query parameter. Pentru POST, în corpul JSON al cererii. Cheia se obține din Cabinet POSLink.

GET /POSLink/Device/Device/Status?APIKey=7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c&DeviceID=POS-001

{
 "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
 "DeviceID": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
 "amount": 150.00
}

Răspunsul standard include întotdeauna errorCode (0 = success), errorName (numele codului din EnErrorCode), errorMessage și, după caz, report (răspunsul brut de la dispozitiv).

Terminal · stare hardware

Verifică starea fizică a terminalului POS Android: dacă e online (prin MQTT/RabbitMQ), nivel baterie, hârtie disponibilă, conexiune la rețea, banca asociată. Util înainte de inițierea unei tranzacții.

Evidența dispozitivelor. Un terminal nu se înregistrează separat: apare singur în cabinet (pagina Dispozitive) la primul apel făcut cu DeviceID-ul lui, legat de compania cheii APIKey folosite. La QR se înscrie la primul Invoice/Create; la operațiunile /POSLink/Device/* abia când terminalul răspunde — un apel încheiat cu errorCode 241 (timeout) nu îl înscrie. Un apel cu DeviceID gol nu creează niciun dispozitiv. Un dispozitiv nou apare ca „neînregistrat” și funcționează normal; apelurile sunt respinse doar pentru cele suspendate sau retrase din cabinet.

DeviceID = License ID. DeviceID e License ID-ul casei (CR) sau al aplicației MCR, afișat în cabinetul casei. Intenționat se schimbă la eliberarea și reactivarea licenței — un aparat eliberat nu mai poate primi plăți pe vechiul ID. După o reactivare actualizați DeviceID în ERP. Dacă trimiteți un ID vechi sau licența e oprită, răspunsul rămâne errorCode 241, dar errorMessage spune explicit cauza (licență eliberată/reactivată sau starea ei), iar cabinetul marchează dispozitivul cu „Licență veche”.

{
 "errorCode": 0,
 "errorMessage": "",
 "report": "{\"online\":true,\"battery\":87,\"paper\":\"OK\",\"bank\":\"MAIB\",\"signal\":4}"
}

POS Mode · plăți cu cardul

Operațiuni directe pe terminalul bancar: plată cu cardul, anulare, refund, închidere zi. Routing dual MQTT/RabbitMQ — terminalul răspunde sub 5 minute pentru plăți (timpul în care clientul introduce PIN-ul) sau sub 1 minut pentru operațiuni administrative.

{
 "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
 "DeviceID": "a8b9c0d1-e2f3-4a5b-9c0d-1e2f3a4b5c6d",
 "amount": 354.50,
 "documentNr": "INV-2024-00841"
}

{
 "errorCode": 0,
 "errorMessage": "",
 "report": "{\"rrn\":\"428541236789\",\"authCode\":\"123456\",\"operationId\":\"...\",\"amount\":354.50}"
}

QR Mode · facturi digitale

Flux complet pentru generarea QR-urilor de plată din facturi ERP. POSLink stochează receipt-ul, generează QR Base64, primește scanarea, marchează plata și trimite callback la ERP. Status-uri tranzacție: NewItem → Scanned → Payed sau Expired / Canceled. Valori numerice (EnInvoiceStatus): NewItem=0, Payed=1, Canceled=2, Scanned=3, Expired=4 (NA=-1).

{
 "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
 "CallbackURI": "https://erp.compania.md/qp?Oid=#OID#&State=#State#",
 "ValidTo": "2025-05-01T18:00:00Z",
 "PointOfSalesCode": "POS-CENTRU-01",
 "Receipt": {
 "Number": "INV-2024-00841",
 "Uid": "a3f9...",
 "Lines": [
 { "Name": "Produs A", "Quantity": 2, "Price": 89.75 }
 ]
 }
}

{
 "errorCode": 0,
 "errorMessage": "",
 "QR": "eyJRUlR5cGUiOjEsIlFSIjoiYTNmOS4uLi..."
}

{
 "errorCode": 0,
 "Status": 3, // -1=NA, 0=NewItem, 1=Payed, 2=Canceled, 3=Scanned, 4=Expired
 "ReceiptID": ""
}

Fiscal Mode · MCR (mașină de casă)

Operațiuni fiscale pe MCR Intelectsoft: numerar (Money In/Out), rapoarte fiscale (Z/X) și tipărire bon fiscal după plată bancară confirmată. Toate operațiunile sunt înregistrate în memoria fiscală conform legislației din R. Moldova. Routing prin RabbitMQ RPC, timeout 20 secunde (sau extins automat la 5 min pentru plăți cu cardul).

Delivery Mode · listă de comenzi pe terminal

Sistemul dvs. trimite din timp în POSLink comenzile unui terminal de curier — o factură pe comandă, în ordinea traseului. Terminalul le afișează ca listă (denumire și sumă), curierul alege comanda, vede produsele și pornește singur plata. Terminalul nu emite nimic singur. O comandă este o factură obișnuită POSLink cu câteva câmpuri în plus, deci bonul fiscal, stările, callback-urile și Invoice/Status funcționează exact ca în QR Mode.

Regulile regimului.
• Lista se păstrează în POSLink, nu pe terminal. Cererile se primesc și când terminalul este oprit sau fără internet; un terminal pornit este anunțat de POSLink la fiecare schimbare și recitește lista în câteva secunde, iar unul oprit o preia la pornire.
• Comanda aparține unui terminal (DeviceID). Curierul vede doar comenzile trimise pe terminalul lui. O comandă retrimisă cu alt DeviceID se mută pe acel terminal.
• Ordinea o dați dvs.: lista se afișează în ordinea în care ați trimis-o și se schimbă cu Orders/Reorder, fără a anula sau recrea facturi.
• Anularea este mereu explicită (Invoice/Cancel). Comanda anulată dispare din listă și nu mai poate fi achitată. Schimbarea ordinii sau lipsa unei comenzi din Sync nu anulează nimic.
• Cât timp plata este pornită pe terminal (stare Scanned), comanda nu poate fi anulată sau modificată. Dacă plata nu se încheie, blocarea se ridică singură după 10 minute.
• Plata câștigă în fața anulării. Fără internet curierul poate încasa numerar după lista salvată. Dacă între timp ați anulat factura, iar plata a fost deja primită, bonul fiscal este emis și factura devine Payed; primiți callback-ul la reconectarea terminalului.

Numele câmpurilor. În cereri numele nu țin cont de majuscule. În răspunsuri câmpurile sunt în camelCase: errorCode, rev, orders, uid, qr, status.

Cabinetul, callback-urile și Invoice/Status arată aceeași stare.
„Nelivrată” nu este o stare, ci un marcaj pus de curier (clientul nu răspunde, a refuzat). Comanda nu se șterge și rămâne NewItem: stă în lista terminalului, marcată „Nelivrată”, și poate fi achitată dacă livrarea reușește mai târziu. Aflați de marcaj în trei feluri: prin callback — State=Undelivered, cu motivul în marcajul opțional #Reason# (în webhook-ul JSON din cabinet: evenimentul delivery.undelivered, câmpul reason, iar status rămâne NewItem); din Delivery/Orders — câmpurile undeliveredAt și undeliveredReason; și din cabinet. O comandă la care renunțați o anulați explicit, cu Invoice/Cancel.

{
  "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
  "DeviceID": "a8b9c0d1-e2f3-4a5b-9c0d-1e2f3a4b5c6d",
  "Orders": [
    {
      "Title": "str. Dacia 12/3",
      "Comment": "Scara 2, et. 5, ap. 45. Cod interfon 45K1290.",
      "Address": "Chișinău, str. Dacia 12/3",
      "ValidTo": "2026-11-13T23:59:00",
      "CallbackURI": "https://erp.compania.md/qp?Oid=#OID#&State=#State#&ReceiptID=#ReceiptID#&Pay=#PaymentCode#",
      "Receipt": {
        "Uid": "ORD-2026-000025",
        "Number": "25",
        "Amount": 386.00,
        "ClientPhone": "069123456",
        "Lines": [
          { "Code": "1001", "Name": "Pizza Margherita 32 cm", "Quantity": 1, "Price": 145.00, "VAT": "A", "UnitName": "buc" },
          { "Code": "1002", "Name": "Pizza Quattro Formaggi 32 cm", "Quantity": 1, "Price": 185.00, "VAT": "A", "UnitName": "buc" },
          { "Code": "2001", "Name": "Coca-Cola 1 L", "Quantity": 2, "Price": 28.00, "VAT": "A", "UnitName": "buc" }
        ]
      }
    }
  ]
}

{
  "errorCode": 0,
  "errorMessage": "",
  "rev": 7,
  "orders": [
    { "uid": "ORD-2026-000025", "qr": "eyJRUlR5cGUiOjEsIlFSIjoi...", "status": 0, "errorCode": 0, "errorMessage": "" }
  ]
}

{
  "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
  "DeviceID": "a8b9c0d1-e2f3-4a5b-9c0d-1e2f3a4b5c6d",
  "Uids": ["ORD-2026-000031", "ORD-2026-000025", "ORD-2026-000027"]
}

{
  "errorCode": 0,
  "errorMessage": "",
  "rev": 8,
  "ignored": []
}

{
  "errorCode": 0,
  "rev": 8,
  "notModified": false,
  "orders": [
    { "uid": "ORD-2026-000031", "qr": "eyJ...", "title": "bd. Decebal 80, of. 14", "comment": "", "address": "",
      "amount": 488.00, "status": 0, "sortIndex": 10, "validTo": "2026-11-13T23:59:00" },
    { "uid": "ORD-2026-000025", "qr": "eyJ...", "title": "str. Dacia 12/3", "amount": 386.00, "status": 1, "sortIndex": 20,
      "receiptID": "FR-00841", "paymentCode": "1", "payedAt": "2026-11-13T14:05:12" }
  ]
}

{
  "APIKey": "7f3a2b1c-9d4e-4f5a-8b1c-3d4e5f6a7b8c",
  "Uid": "ORD-2026-000027",
  "Reason": "Clientul a renunțat"
}

{
  "errorCode": 0,
  "errorMessage": "",
  "status": 2
}

{
  "errorCode": 0,
  "rev": 8,
  "notModified": false,
  "orders": [
    {
      "uid": "ORD-2026-000031", "qr": "eyJ...", "title": "bd. Decebal 80, of. 14",
      "comment": "Centrul de afaceri, intrarea din curte. Lăsați la recepție, et. 2.",
      "address": "Chișinău, bd. Decebal 80", "latitude": 46.9895, "longitude": 28.8577,
      "amount": 488.00, "status": 0, "sortIndex": 10, "validTo": "2026-11-13T23:59:00",
      "receipt": { "uid": "ORD-2026-000031", "number": "31", "amount": 488.00, "clientPhone": "078456123", "lines": [ ... ] }
    },
    { "uid": "ORD-2026-000025", "qr": "eyJ...", "title": "str. Dacia 12/3", "amount": 386.00, "status": 1,
      "receiptID": "FR-00841", "paymentCode": "1", "payedAt": "2026-11-13T14:05:12" }
  ]
}

În cabinet. Pagina Livrări arată toate terminalele care au comenzi azi, cu comenzile lor în ordinea traseului. Pagina Dispozitive arată la fiecare terminal câte comenzi are azi (rămase, achitate) și deschide lista lor în ordinea traseului, cu starea explicată și istoricul fiecărei comenzi. Dacă terminalul nu a mai citit lista de peste 5 minute, cabinetul avertizează că lista de pe terminal poate fi veche. Comenzile apar și în lista de facturi, pe canalul DELIVERY.

Callback-uri (webhooks)

POSLink trimite notificări către CallbackURI la schimbările de stare: Scanned (o singură dată, la prima scanare), Payed (cu ReceiptID și DeviceID), Expired (la detectarea expirării prin Invoice/Status sau Invoice/Get) și Canceled (la anularea facturii din cabinet). URL-ul suportă placeholders pentru substituție automată — devine un webhook real cu valori concrete.

Semnătură și URL implicit. Fiecare notificare poartă antetul X-POSLink-Signature: HMAC-SHA256 în hex (litere mici), cu secretul whsec_… din cabinet (Chei → Webhook). Pentru CallbackURI (cerere GET) semnătura se calculează peste adresa completă apelată. Dacă factura e creată fără CallbackURI, notificarea merge la URL-ul salvat în cabinet, prin POST cu JSON: {event, invoiceId, status, receiptId, deviceId, receiptNumber, receiptUid, amount, occurredAt}, unde event e invoice.scanned, invoice.paid, invoice.expired, invoice.cancelled sau webhook.test; semnătura se calculează peste corp, octet cu octet. Antetele X-POSLink-Event și X-POSLink-Delivery (identificatorul livrării, același la reîncercări) însoțesc ambele forme. Fără URL în cabinet și fără CallbackURI nu se trimite nimic.

POST https://erp.compania.md/api/webhook/poslink
Content-Type: application/json; charset=utf-8
X-POSLink-Event: invoice.paid
X-POSLink-Delivery: 5e0c6a52-7d1b-4c0e-9f3a-2b8f4d6c1a90
X-POSLink-Signature: 9f2c…e41b            (HMAC-SHA256 hex, 64 caractere)

{"event":"invoice.paid","invoiceId":"c527fe0a-902e-4853-a0fc-a2a99f17cc82","status":"Payed","receiptId":"FR-00841","deviceId":"a8b9c0d1-e2f3-4a5b-9c0d-1e2f3a4b5c6d","receiptNumber":"INV-2026-00841","receiptUid":"","amount":850.00,"paymentCode":"","occurredAt":"2026-11-11T17:33:13+02:00"}

const crypto = require('crypto');

// corpul BRUT: fără express.json() pe această rută
app.post('/api/webhook/poslink', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.POSLINK_WEBHOOK_SECRET)   // whsec_… întreg
                         .update(req.body).digest('hex');
  const got = req.get('X-POSLink-Signature') || '';
  const ok = got.length === expected.length &&
             crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.status(401).json({ error: 'invalid signature' });

  res.sendStatus(200);                                   // răspunde imediat
  const evt = JSON.parse(req.body.toString('utf8'));     // apoi procesează
  // evt.event, evt.invoiceId, evt.status, evt.receiptId …
});

<?php
$body     = file_get_contents('php://input');                               // corpul BRUT
$expected = hash_hmac('sha256', $body, getenv('POSLINK_WEBHOOK_SECRET'));   // whsec_… întreg
$got      = $_SERVER['HTTP_X_POSLINK_SIGNATURE'] ?? '';

if (!hash_equals($expected, $got)) { http_response_code(401); exit; }

http_response_code(200);
$evt = json_decode($body, true);   // $evt['event'], $evt['invoiceId'], $evt['status'] …

// CallbackURI (GET): se semnează adresa completă, exact cum a fost apelată
const url      = 'https://erp.compania.md/qp?Oid=a3f9b2c8&State=Payed&ReceiptID=FR-00841&DeviceID=POS-MAIB-001';
const expected = crypto.createHmac('sha256', process.env.POSLINK_WEBHOOK_SECRET).update(url).digest('hex');

Depanare — notificarea nu ajunge. Deschide în cabinet Jurnal webhook și apasă pe rând: vezi metoda, dacă cererea a plecat semnată, corpul trimis și răspunsul serverului tău, plus un diagnostic cu pașii de urmat.
• Jurnalul e gol — factura a fost creată fără CallbackURI și în cabinet nu e salvat niciun URL, deci nu s-a trimis nimic.
• 401 / 403 — serverul tău respinge semnătura. Semnează corpul brut, înainte de parsarea JSON; folosește secretul whsec_… întreg; compară cu hex cu litere mici, fără prefix. La notificările GET se semnează adresa completă apelată.
• 404 / 405 — adresă greșită sau metodă neacceptată: URL-ul din cabinet primește POST, CallbackURI primește GET.
• 5xx — cererea a ajuns, dar aplicația ta a căzut la procesare; cauza e în logurile tale.
• fără cod HTTP — timeout (peste 3 secunde), DNS, certificat HTTPS sau firewall. Răspunde imediat cu 200 și procesează după aceea.
• Reîncercări — după un răspuns de eroare peste 5 minute, după o eroare de rețea peste 10 minute, cel mult 11 încercări; apoi rândul devine „eșuat” și se poate retrimite din cabinet. Antetul X-POSLink-Delivery rămâne același la reîncercări — folosește-l pentru deduplicare.

https://erp.compania.md/qp?Oid=#OID#&State=#State#&ReceiptID=#ReceiptID#&DeviceID=#DeviceID#

https://erp.compania.md/qp?Oid=a3f9b2c8&State=Payed&ReceiptID=FR-00841&DeviceID=POS-MAIB-001

Coduri de eroare

Toate răspunsurile includ errorCode (integer) și errorMessage (text). Codul 0 înseamnă succes (NoError). Codurile non-zero sunt definite în enum-ul EnErrorCode.

Despre codul 10: acoperă intenționat trei situații — cheie inexistentă, cheie dezactivată din cabinet și cheie respinsă de filtrul IP. Răspunsul e identic ca să nu confirme nimănui că a nimerit o cheie validă. Dacă o integrare care mergea începe brusc să primească 10, verifică în cabinet starea cheii și lista de IP-uri: respingerea apare în jurnalul de audit.

Endpoint-urile /POSLink/Device/*: errorName urmează codul returnat (înainte era mereu APIKey_not_exist, inclusiv pentru 242 sau respingere pe IP). Când terminalul e offline sau nu răspunde, răspunsul are errorCode 241 (Timeout_or_no_response) și errorMessage de forma „Error: Device offline (...)” sau „Error: Response timeout ...” — înainte venea errorCode 0 cu textul doar în report. Răspunsurile fiscale cu ErrorCode în PascalCase sunt acum recunoscute ca erori, nu ca succes.