POSLink API Docs — Documentație REST

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), 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.

Returnează parametrii hardware curenți. Routing automat: MQTT prioritar dacă device-ul e online, fallback RabbitMQ. Timeout 20 secunde.

QUERY PARAMETERS

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API (Guid)
DeviceID	string	req	Identificator unic al terminalului

RESPONSE 200

{
 "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.

Activează terminalul cu suma exactă. Operatorul nu mai introduce nimic. Suport MAIB, Victoriabank, OTP, MICB. Timeout extins la 5 min (clientul are nevoie de timp pentru PIN/contactless).

REQUEST BODY (PaymentPay)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID terminal POS
amount	decimal	req	Suma în MDL (ex: 150.00)
documentNr	uuid	opt	Numărul documentului intern (Guid)

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

RESPONSE 200

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

Returnează detaliile ultimei tranzacții procesate de terminal. Util pentru reconcilieri și verificări post-plată. Timeout 30 secunde.

QUERY PARAMETERS

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceId	uuid	req	ID terminal POS

Obligatoriu după fiecare plată cu success — eliberează memoria terminalului și permite o tranzacție nouă. Timeout 60 secunde.

REQUEST BODY (PaymentCloseDoc)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID terminal POS
documentNr	string	req	Numărul documentului tranzacției
operationId	string	req	ID operațiune (returnat de Pay)

Trimite Settlement către bancă — finalizează ziua bancară și transmite toate tranzacțiile autorizate. Echivalent cu „Z bancar". Timeout 60 secunde.

REQUEST BODY

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID terminal POS

Retur parțial sau total al unei tranzacții autorizate (ziua e încă deschisă). După închiderea zilei (closeDay) folosiți CancelTransaction. Timeout 60 secunde.

REQUEST BODY (PaymentRefund)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID terminal POS
documentNr	string	req	Numărul documentului original
operationId	string	req	ID operațiune originală
rrn	string	req	Reference Retrieval Number
amount	decimal	req	Suma de returnat (≤ original)
currency	string	opt	Cod valută (default „MDL")

Anulează (void) o tranzacție autorizată dar nedecontată. Diferit de Refund — anularea se face în ziua tranzacției, nu blochează fonduri. Timeout 60 secunde.

REQUEST BODY (PaymentCancelTransaction)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID terminal POS
documentNr	string	req	Numărul documentului
operationId	string	req	ID operațiune
token	string	req	Token autorizare bancă
amount	decimal	req	Suma tranzacției originale

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/Cancelled.

Salvează receipt-ul în Cloud, generează un OID unic și un QR Base64 codificat. QR-ul rămâne valabil până la ValidTo sau prima plată reușită.

REQUEST BODY (InvoiceData)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	opt	ID terminal preferat (opțional)
CallbackURI	string	opt	URL pentru notificări (vezi Callbacks)
ValidTo	datetime	opt	Termen valabilitate QR (default: nelimitat)
PointOfSalesCode	string	opt	Cod punct de vânzare
Receipt	object	req	Conținutul facturii (vezi schema Receipt)

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

RESPONSE 200

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

Verifică starea curentă a unui QR fără să-l marcheze ca „Scanned". Util pentru polling din ERP. Marchează automat ca Expired dacă termenul ValidTo a trecut.

QUERY PARAMETERS

Parametru	Tip	Req.	Descriere
QR	string	req	Codul QR Base64 (returnat la Create)

RESPONSE 200

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

Returnează receipt-ul complet (lista de produse) pentru afișare pe MCR sau POS Android. Marchează automat tranzacția ca Scanned și declanșează callback-ul de scanare către ERP.

QUERY PARAMETERS

Parametru	Tip	Req.	Descriere
QR	string	req	Codul QR Base64

Apelat de MCR sau POS după ce plata bancară a fost confirmată. Marchează tranzacția ca Payed și trimite callback-ul de finalizare către ERP cu ReceiptID-ul fiscal.

QUERY PARAMETERS

Parametru	Tip	Req.	Descriere
QR	string	req	Codul QR Base64
ReceiptID	string	req	ID bon fiscal (de la MCR)
DeviceID	string	req	ID dispozitiv care a încasat

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).

Înregistrează intrarea de numerar în casierie (deschidere zi, schimb tură). Înregistrat în memoria fiscală MCR. Timeout 20 secunde.

REQUEST BODY (MoneyDataToDevice)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID dispozitiv MCR
Amount	decimal	req	Suma în MDL
Reason	string	opt	Motiv (ex: „Deschidere zi")
CallbackURI	string	opt	URL notificare la finalizare

Înregistrează ieșirea de numerar (depunere bancă, returnare client). Aceeași schemă ca Money/In. Timeout 20 secunde.

Generează raport fiscal pe MCR. Raportul Z (închidere zi) resetează contoarele zilnice. Raportul X (intermediar) afișează totalurile fără reset. Timeout 20 secunde.

REQUEST BODY (InvoiceDataToDevice)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID dispozitiv MCR
Fiscal	boolean	req	true → Raport Z (închidere) · false → Raport X (intermediar)
CallbackURI	string	opt	URL notificare

Tipărește bonul fiscal pe MCR — strict după confirmarea bancară pentru plățile cu cardul. Timeout adaptiv: 5 min dacă receipt-ul conține plată cu cardul (PaymentCode 1, 2, 7 sau 1000), 1 min altfel. Conformitate cu legislația fiscală RM.

REQUEST BODY (InvoiceData)

Parametru	Tip	Req.	Descriere
APIKey	uuid	req	Cheia API
DeviceID	uuid	req	ID dispozitiv MCR
CallbackURI	string	opt	URL notificare
Receipt	object	req	Receipt complet cu Items + Payments

Callback-uri (webhooks)

POSLink trimite notificări către CallbackURI la fiecare schimbare de stare. URL-ul suportă placeholders pentru substituție automată — devine în webhook real cu valori concrete.

Worker-ul POSLink execută GET către URL-ul configurat, cu placeholder-urile înlocuite. Retry automat la eșec (5 încercări la 1, 5, 30 minute, 1h, 6h).

PLACEHOLDERS

Placeholder	Înlocuit cu	Descriere
#OID#	UUID	OID-ul intern al facturii
#State#	enum	Status: NewItem / Scanned / Payed / Expired / Cancelled
#ReceiptID#	string	Doar la State=Payed — ID bon fiscal
#DeviceID#	string	Doar la State=Payed — terminal care a încasat

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

https://erp.firma.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.

errorCode	EnErrorCode	Descriere
0	NoError	Operațiune reușită
1	Internal_error	Eroare internă pe server
2	Error_Connection_Database	Bază de date offline
3	Timeout_or_no_response	Dispozitivul nu a răspuns în timpul alocat
10	Invalid_API_Key	Cheia API lipsă, expirată sau invalidă
11	API_Key_Wrong_Product	Cheia nu are acces la modulul POSLink
20	Record_not_exist	QR / invoice / tranzacție inexistentă
21	Invalid_QR	Format QR invalid sau corupt
22	The_status_cannot_be_applied	Tranziție de stare ilegală (ex: Payed → Scanned)
30	Device_Offline	Terminalul nu e disponibil pe MQTT/RabbitMQ
31	Device_Busy	Terminalul procesează altă tranzacție

POSLink Enterprise API

Autentificare

Terminal · stare hardware

POS Mode · plăți cu cardul

QR Mode · facturi digitale

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

Callback-uri (webhooks)

Coduri de eroare