API pentru integratori

Adresă și acces

Rutele terminalelor fac parte din API-ul local, versiunea 2, la aceeași adresă: https://localhost.fiscallink.ro:65401/api/v2 sau http://{ip-local}:65400/api/v2.

• Doar pe v2. Rutele sunt sub /api/v2/payment-terminals. Versiunea 1 (/api) nu le are: /api/payment-terminals răspunde 404.
• Fără cheie. Nu trimiți nicio credențială. Fără licență pe casa conectată, orice rută răspunde 401.
• Casa de marcat conectată. Plata, anularea, închiderea de zi și testul cer o casă conectată și licențiată; altfel răspund 424 cash_register_required. Citirile (lista, detaliile, o tranzacție) merg și fără casă. Când casa se deconectează, terminalele se deconectează după operațiunea în curs, niciodată în mijlocul unei plăți.
• Formatul. La succes: { "statusCode": 200, "data": … }, câmpuri camelCase. La eroare: statusCode, message (în limba aplicației) și code, un identificator stabil; unele erori au și câmpuri în plus. Ramifică după code, nu după text.
• Doar lei. Sumele sunt în RON, cu cel mult două zecimale.
• Configurarea e în aplicație. Terminalele se adaugă, se modifică și se șterg doar din aplicație; API-ul le folosește.

Ce poate fiecare terminal

Rutele sunt comune tuturor terminalelor, dar operațiunile disponibile depind de protocol. Pentru operațiunile marcate „Nu”, API-ul returnează codul indicat în tabel.

• Test. „Întreabă terminalul”: aplicația îi cere terminalului seria și, unde o dă, versiunea software. „Doar configurația”: protocolul nu are o întrebare de identificare, așa că testul răspunde cu portul terminalului, fără să-l contacteze.
• Anulare. Anulează o plată aprobată, cu toată suma ei. Terminalul găsește plata după identificatorul primit la plată (STAN, RRN, codul de autorizare sau numărul bonului terminalului); o plată fără el nu se poate anula prin API.
• Verificare automată. Ce face aplicația cu o plată al cărei rezultat nu l-a primit: vezi Rezultat incert.
• Doar aceste operațiuni. API-ul nu are restituiri, pre-autorizări, cashback sau bacșiș.

Seria terminalului

Fiecare rută a unui terminal are seria lui: /payment-terminals/{serial}/…. Iei seria din GET /payment-terminals; un terminal apare în listă abia după ce aplicația l-a identificat. Seria nu ține cont de litere mari sau mici; spațiile de la capete se taie, iar orice caracter în afară de litere, cifre, ., _ și - devine -. Valoarea raportată de terminal e în rawSerial.

Fluxul unei plăți

1. Citești terminalele: GET /payment-terminals. Alegi serial-ul; isDefault arată terminalul ales implicit în aplicație, isConnected dacă e conectat acum.
2. Ceri plata: POST /payment-terminals/{serial}/sale cu amount și, dacă vrei, reference, referința ta.
3. Ții cererea deschisă până vine răspunsul. Clientul plătește pe terminal, iar răspunsul vine abia la final, poate după câteva minute. transactionId vine doar în răspuns. Dacă închizi cererea, plata nu se oprește.
4. Citești răspunsul. 200: plata e aprobată. 402: refuzată, suma nu a fost încasată. 409 terminal_uncertain: rezultatul nu se știe, nu încasa din nou. 409 terminal_busy: terminalul e ocupat. 424 terminal_not_connected: cererea n-a ajuns la terminal, suma nu a fost încasată.
5. Tipărești bonul fiscal cu plata cu cardul: POST /print-fiscal-receipt. Ruta de plată nu tipărește nimic pe casa de marcat.
6. Dacă vânzarea se anulează: POST /payment-terminals/{serial}/void cu transactionId-ul plății.
7. La sfârșitul zilei, unde protocolul o are: POST /payment-terminals/{serial}/settlement.

Cererea de plată

{
  "amount": 12.50,
  "reference": "POS-0001"
}

Răspunsul

{
  "statusCode": 200,
  "data": {
    "transactionId": "FL261109101500A1B2C3",
    "serial": "PT000001",
    "approved": true,
    "amount": 12.50,
    "currency": "RON",
    "responseCode": "00",
    "responseText": "APPROVED",
    "authCode": "A1B2C3",
    "rrn": "000000000001",
    "stan": "000001",
    "maskedPan": "************0000",
    "cardLabel": "VISA",
    "aid": "A0000000000000",
    "entryMode": "contactless",
    "pinEntered": false,
    "signatureRequired": false,
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "timestamp": "2026-11-09T08:15:04Z",
    "receiptText": null
  }
}

Rutele

Exemplele folosesc seria PT000001 și valori inventate.

curl -X GET 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals'

{
  "statusCode": 200,
  "data": [
    {
      "serial": "PT000001",
      "protocol": "SmartPay",
      "connectivity": "Serial",
      "label": "Casa 1",
      "isConnected": true,
      "isBusy": false,
      "isDefault": true
    },
    {
      "serial": "COM4",
      "protocol": "Payten",
      "connectivity": "Serial",
      "label": null,
      "isConnected": false,
      "isBusy": false,
      "isDefault": false
    }
  ]
}

curl -X GET 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001'

{
  "statusCode": 200,
  "data": {
    "serial": "PT000001",
    "rawSerial": "PT000001",
    "protocol": "SmartPay",
    "connectivity": "Serial",
    "address": "COM3",
    "label": "Casa 1",
    "isConnected": true,
    "isBusy": false,
    "isDefault": true,
    "softwareVersion": "1.0.0",
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "unresolvedTransactions": []
  }
}

curl -X POST 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001/sale' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 12.5,
  "reference": "POS-0001"
}'

{
  "statusCode": 200,
  "data": {
    "transactionId": "FL261109101500A1B2C3",
    "serial": "PT000001",
    "approved": true,
    "amount": 12.50,
    "currency": "RON",
    "responseCode": "00",
    "responseText": "APPROVED",
    "authCode": "A1B2C3",
    "rrn": "000000000001",
    "stan": "000001",
    "maskedPan": "************0000",
    "cardLabel": "VISA",
    "aid": "A0000000000000",
    "entryMode": "contactless",
    "pinEntered": false,
    "signatureRequired": false,
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "timestamp": "2026-11-09T08:15:04Z",
    "receiptText": null
  }
}

{
  "statusCode": 402,
  "message": "The card payment was declined: DECLINED",
  "code": "terminal_declined",
  "responseCode": "05",
  "transaction": {
    "transactionId": "FL261109101500A1B2C3",
    "serial": "PT000001",
    "approved": false,
    "amount": 12.50,
    "currency": "RON",
    "responseCode": "05",
    "responseText": "DECLINED",
    "authCode": null,
    "rrn": "000000000001",
    "stan": "000001",
    "maskedPan": "************0000",
    "cardLabel": "VISA",
    "aid": null,
    "entryMode": "chip",
    "pinEntered": true,
    "signatureRequired": false,
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "timestamp": "2026-11-09T08:15:04Z",
    "receiptText": null
  }
}

{
  "statusCode": 409,
  "message": "Payment terminal PT000001 did not confirm the outcome of transaction FL261109101500A1B2C3. It is being checked; do not charge the card again.",
  "code": "terminal_uncertain",
  "transactionId": "FL261109101500A1B2C3"
}

curl -X POST 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001/void' \
  -H 'Content-Type: application/json' \
  -d '{
  "transactionId": "FL261109101500A1B2C3"
}'

{
  "statusCode": 200,
  "data": {
    "transactionId": "FL261109101500A1B2C3",
    "serial": "PT000001",
    "approved": true,
    "amount": 12.50,
    "currency": "RON",
    "responseCode": "00",
    "responseText": "APPROVED",
    "authCode": "A1B2C4",
    "rrn": "000000000002",
    "stan": "000002",
    "maskedPan": "************0000",
    "cardLabel": "VISA",
    "aid": null,
    "entryMode": null,
    "pinEntered": false,
    "signatureRequired": false,
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "timestamp": "2026-11-09T08:20:11Z",
    "receiptText": null
  }
}

{
  "statusCode": 409,
  "message": "Transaction FL261109101500A1B2C3 cannot be voided: it is Voided.",
  "code": "transaction_not_voidable",
  "transactionId": "FL261109101500A1B2C3"
}

curl -X POST 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001/settlement'

{
  "statusCode": 200,
  "data": {
    "serial": "PT000001",
    "approved": true,
    "responseCode": "00",
    "responseText": "OK",
    "transactionCount": 3,
    "totalAmount": 37.50,
    "batchNumber": "000001",
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "timestamp": "2026-11-09T20:00:12Z"
  }
}

curl -X POST 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001/test'

{
  "statusCode": 200,
  "data": {
    "rawSerial": "PT000001",
    "serial": "PT000001",
    "softwareVersion": "1.0.0",
    "terminalId": null,
    "merchantId": null
  }
}

curl -X GET 'https://localhost.fiscallink.ro:65401/api/v2/payment-terminals/PT000001/transactions/FL261109101500A1B2C3'

{
  "statusCode": 200,
  "data": {
    "transactionId": "FL261109101500A1B2C3",
    "serial": "PT000001",
    "state": "Approved",
    "amount": 12.50,
    "approvedAmount": 12.50,
    "currency": "RON",
    "reference": "POS-0001",
    "responseCode": "00",
    "responseText": "APPROVED",
    "authCode": "A1B2C3",
    "rrn": "000000000001",
    "stan": "000001",
    "maskedPan": "************0000",
    "cardLabel": "VISA",
    "entryMode": "contactless",
    "signatureRequired": false,
    "terminalId": "TID00001",
    "merchantId": "MID000000001",
    "createdAt": "2026-11-09T08:15:00Z",
    "updatedAt": "2026-11-09T08:15:04Z"
  }
}

{
  "statusCode": 404,
  "message": "Payment terminal PT000001 has no transaction FL000000000000XXXXXX.",
  "code": "transaction_not_found",
  "transactionId": "FL000000000000XXXXXX"
}

Stările tranzacției

Aplicația salvează tranzacția înainte de a trimite cererea la terminal, apoi actualizează rezultatul. Astfel, poți verifica o plată și după repornire sau după pierderea răspunsului. Citește câmpul state din GET /payment-terminals/{serial}/transactions/{transactionId}.

Tranzacțiile încheiate se păstrează 180 de zile; cele nerezolvate nu se șterg.

Rezultat incert

Dacă se întrerupe conexiunea sau terminalul nu confirmă rezultatul, aplicația marchează plata ca incertă. Cererea poate fi ajuns la terminal și suma poate fi deja încasată.

• Plata (sau anularea) răspunde 409 terminal_uncertain, cu transactionId. Nu încasa din nou aceeași vânzare.
• Cât terminalul are o tranzacție nerezolvată (Pending, Uncertain sau VoidPending), o plată nouă și închiderea de zi pe acel terminal răspund 409 terminal_recovery_pending, cu lista transactionIds. Închiderea de zi e refuzată fiindcă șterge jurnalul terminalului, singura dovadă a ce s-a întâmplat.
• SmartPay și GPE: aplicația întreabă singură terminalul, când acesta se conectează și apoi periodic, tot mai rar, până la o dată la 10 minute, fără să renunțe. O plată găsită aprobată e anulată, cum cer protocoalele; una care nu s-a făcut devine NotPerformed. O anulare cu rezultat necunoscut se verifică la fel.
• Ingenio, Mellon, Payten, ePay, Printec și FIP11: aplicația nu poate citi jurnalul acestor terminale, deci nu poate rezolva singură tranzacția. Ea rămâne nerezolvată, iar terminalul refuză plăți noi și închiderea de zi.
• Verificarea rulează doar cât terminalul e conectat, deci cât e conectată și casa de marcat.
• Urmărești rezultatul cu GET /payment-terminals/{serial}/transactions/{transactionId}; unresolvedTransactions din GET /payment-terminals/{serial} arată ce se verifică încă.

{
  "statusCode": 409,
  "message": "Payment terminal PT000001 did not confirm the outcome of transaction FL261109101500A1B2C3. It is being checked; do not charge the card again.",
  "code": "terminal_uncertain",
  "transactionId": "FL261109101500A1B2C3"
}

{
  "statusCode": 409,
  "message": "Payment terminal PT000001 is still checking an earlier transaction (FL261109101500A1B2C3). Try again once it is resolved.",
  "code": "terminal_recovery_pending",
  "transactionIds": ["FL261109101500A1B2C3"]
}

O operațiune pe terminal

• Fără coadă. Dacă terminalul este ocupat, o cerere nouă primește imediat 409 cu terminal_busy. Așteaptă rezultatul primei operațiuni înainte de a trimite alta. Terminalul este eliberat înainte de transmiterea răspunsului.
• Terminalele nu se așteaptă între ele. Două terminale încasează în același timp, iar casa de marcat tipărește în timp ce un terminal încasează.
• Citirile nu ocupă terminalul. Lista, detaliile și o tranzacție răspund oricând, și în timpul unei plăți. isBusy arată dacă terminalul rulează acum o operațiune.
• Fără `Idempotency-Key`. Rutele terminalelor nu citesc antetul: fiecare POST …/sale e o plată nouă, cu alt transactionId. Nu retrimite o plată al cărei răspuns nu l-ai primit: suma poate fi deja încasată.

{
  "statusCode": 409,
  "message": "Payment terminal PT000001 is busy with another operation. Wait for it to finish, then try again.",
  "code": "terminal_busy"
}

Erori și coduri

Verifică întotdeauna câmpul code, nu doar statusul HTTP. De exemplu, 409 cu terminal_busy permite o încercare ulterioară, în timp ce terminal_uncertain cere verificarea plății înainte de o nouă încasare.

Codurile serial_in_use, port_in_use, identity_changed, unresolved_transactions, invalid_configuration și protocol_not_available țin de adăugarea unui terminal în aplicație; rutele de aici nu le întorc.

{
  "statusCode": 424,
  "message": "Payment terminals work only while a cash register is connected.",
  "code": "cash_register_required"
}

Diferențe între terminale

Toate terminalele răspund cu aceleași câmpuri. Ce completează fiecare depinde de protocol; un câmp pe care protocolul nu îl dă e null (sau false), iar un terminal anume poate lăsa goale și câmpuri din listă.

• `entryMode` e chip, contactless sau magstripe, când terminalul o spune.
• `signatureRequired` (SmartPay, GPE) te anunță doar că bonul cardului trebuie semnat; verificarea semnăturii revine casierului.
• `receiptText` (doar GPE, când terminalul e setat să tipărească prin casă): bonul cardului, formatat de terminal pe linii de 24 de caractere, cu marcajele lui de formatare. Aplicația nu îl tipărește.
• Suma aprobată. amount din răspunsul plății e suma aprobată de terminal; în tranzacție e approvedAmount. Pe SmartPay, o aprobare pe altă sumă decât cea cerută e tratată ca rezultat incert.