Documentație API

Viramente ramburs

Banii încasați de curier de la destinatar ajung la tine în loturi. Aceste rute îți spun ce ți-a fost virat, pentru care expediții, și ce mai este de primit.

Cum circulă banii

Lanțul are trei verigi: curierul încasează rambursul de la destinatar, îl virează către Livrǎria, iar noi îl virăm în contul tău. Virarea se face în loturi — un virament grupează rambursurile mai multor expediții, de obicei de la același curier și din aceeași zi.

Pentru explicația pe larg a procesului, cu ce vezi în aplicație, vezi ghidul de ramburs.

Lista viramentelor

GET/payoutsBearer JWT

Întoarce numai viramentele contului autentificat — filtrul se aplică pe server, nu îl poți ocoli.

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`page / limit`	number	opțional	Paginare.
`status`	PENDING \| COMPLETED \| CANCELLED	opțional	`COMPLETED` înseamnă virat.
`startDate / endDate`	string (ISO 8601)	opțional	Interval de timp.
`search`	string	opțional	Potrivire parțială, fără diferență între majuscule și minuscule, pe `docId` sau pe `reference`.
`amountMin / amountMax`	number	opțional	Limite pe suma viramentului, în RON, inclusive. Pot fi folosite și separat.

Răspuns 200 OK

json

{
  "data": [
    {
      "id": "4c8e1f03-9a27-4b65-8d10-3e7f2a6b5c94",
      "status": "COMPLETED",
      "amount": 1248.5,
      "currency": "RON",
      "docId": "COD-BATCH-27-10",
      "reference": "Transfer ramburs Dpd",
      "transactionDate": "2026-10-27T10:12:00.000Z",
      "createdAt": "2026-10-27T06:05:00.000Z",
      "updatedAt": "2026-10-27T10:12:00.000Z",
      "recipientUserId": "a334e842-...",
      "recipient": {
        "id": "7f1c...",
        "email": "contact@firma.ro",
        "name": "Firma Mea SRL",
        "authProviderId": "a334e842-..."
      },
      "payoutItems": [
        {
          "id": "b6d2...",
          "amount": 250,
          "status": "COMPLETED",
          "expeditionId": "9d1e5b77-...",
          "description": "Ramburs AWB 81356295593",
          "createdAt": "2026-10-27T06:05:00.000Z",
          "updatedAt": "2026-10-27T10:12:00.000Z",
          "expedition": {
            "id": "9d1e5b77-...",
            "awbNumber": "81356295593",
            "trackingNumber": "81356295593",
            "createdAt": "2026-10-28T09:05:12.000Z"
          }
        }
      ]
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Câmpurile unui virament

Câmp	Tip	Cerut	Descriere
`amount`	number	mereu	Totalul lotului, în RON.
`status`	string	mereu	`PENDING`, `COMPLETED` sau `CANCELLED`.
`docId`	string \| null	opțional	Identificatorul lotului de decontare al curierului, din care provine suma.
`transactionDate`	string \| null	opțional	Data transferului bancar. Lipsește cât timp viramentul nu a plecat.
`payoutItems`	array	mereu	Câte o linie pe expediție, cu `amount`, `expeditionId` și blocul `expedition` care poartă AWB-ul. Aici găsești legătura cu comanda ta.

Suma lotului nu este suma unei expediții

Ca să reconciliezi o comandă, însumează liniile din payoutItems care o referă:

// Cât ai încasat efectiv pe o expediție cu ramburs:
// suma liniilor de virament care o referă.
const payouts = await getAllPayouts(); // GET /payouts, paginat
const paid = payouts
  .flatMap(p => p.payoutItems)
  .filter(item => item.expeditionId === expeditionId)
  .reduce((sum, item) => sum + item.amount, 0);

// Nu citi suma din BatchPayout.amount pentru o singură expediție:
// este totalul lotului, nu al liniei.

Un singur virament

GET/payouts/{id}Bearer JWT

Detaliul complet al unui virament. Un virament al altui cont întoarce 403.

Ce mai ai de primit

GET/payouts/outstandingBearer JWT

Expedițiile cu ramburs livrate pentru care încă nu ai primit banii, plus totalul.

Răspuns 200 OK

json

{
  "totalOutstanding": 1430.75,
  "currency": "RON",
  "count": 6,
  "expeditions": [
    {
      "expeditionId": "9d1e5b77-...",
      "awbNumber": "81356295593",
      "trackingNumber": "81356295593",
      "deliveryDate": "2026-10-29T11:34:00.000Z",
      "amount": 250,
      "recipientName": "Ion Popescu",
      "recipientCity": "CLUJ-NAPOCA"
    }
  ]
}

Aceasta este ruta de folosit pentru un indicator „de încasat” în propriul tău panou. În aplicație, aceleași date apar în Virament ramburs → De primit.

Export și documente

CSV

GET/payouts/exportBearer JWT

Toate viramentele tale, ca fișier CSV. Acceptă aceiași parametri de filtrare ca lista.

GET/payouts/{id}/exportBearer JWT

Un singur virament, cu o linie pe expediție.

Nota de decontare

GET/payouts/{id}/settlement-noteBearer JWT

PDF-ul notei de decontare: data decontării, câte o linie pe AWB cu suma virată și lotul curierului din care provine, totalul transferat și clauza contractuală care guvernează virarea rambursului.

Cod	Ce înseamnă
200	PDF-ul notei.
400	Viramentul nu este finalizat. Nota se emite doar pentru viramente COMPLETED.
404	Viramentul nu există.

Ai nevoie de ajutor?

Dacă o sumă încasată nu apare în nicio linie de virament, trimite-ne AWB-ul și data livrării.

Contactează-ne

Cum circulă banii

Pentru explicația pe larg a procesului, cu ce vezi în aplicație, vezi ghidul de ramburs.

Lista viramentelor

GET/payoutsBearer JWT

Întoarce numai viramentele contului autentificat — filtrul se aplică pe server, nu îl poți ocoli.

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`page / limit`	number	opțional	Paginare.
`status`	PENDING \| COMPLETED \| CANCELLED	opțional	`COMPLETED` înseamnă virat.
`startDate / endDate`	string (ISO 8601)	opțional	Interval de timp.
`search`	string	opțional	Potrivire parțială, fără diferență între majuscule și minuscule, pe `docId` sau pe `reference`.
`amountMin / amountMax`	number	opțional	Limite pe suma viramentului, în RON, inclusive. Pot fi folosite și separat.

Răspuns 200 OK

json

{
  "data": [
    {
      "id": "4c8e1f03-9a27-4b65-8d10-3e7f2a6b5c94",
      "status": "COMPLETED",
      "amount": 1248.5,
      "currency": "RON",
      "docId": "COD-BATCH-27-10",
      "reference": "Transfer ramburs Dpd",
      "transactionDate": "2026-10-27T10:12:00.000Z",
      "createdAt": "2026-10-27T06:05:00.000Z",
      "updatedAt": "2026-10-27T10:12:00.000Z",
      "recipientUserId": "a334e842-...",
      "recipient": {
        "id": "7f1c...",
        "email": "contact@firma.ro",
        "name": "Firma Mea SRL",
        "authProviderId": "a334e842-..."
      },
      "payoutItems": [
        {
          "id": "b6d2...",
          "amount": 250,
          "status": "COMPLETED",
          "expeditionId": "9d1e5b77-...",
          "description": "Ramburs AWB 81356295593",
          "createdAt": "2026-10-27T06:05:00.000Z",
          "updatedAt": "2026-10-27T10:12:00.000Z",
          "expedition": {
            "id": "9d1e5b77-...",
            "awbNumber": "81356295593",
            "trackingNumber": "81356295593",
            "createdAt": "2026-10-28T09:05:12.000Z"
          }
        }
      ]
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Câmpurile unui virament

Câmp	Tip	Cerut	Descriere
`amount`	number	mereu	Totalul lotului, în RON.
`status`	string	mereu	`PENDING`, `COMPLETED` sau `CANCELLED`.
`docId`	string \| null	opțional	Identificatorul lotului de decontare al curierului, din care provine suma.
`transactionDate`	string \| null	opțional	Data transferului bancar. Lipsește cât timp viramentul nu a plecat.
`payoutItems`	array	mereu	Câte o linie pe expediție, cu `amount`, `expeditionId` și blocul `expedition` care poartă AWB-ul. Aici găsești legătura cu comanda ta.

Suma lotului nu este suma unei expediții

Ca să reconciliezi o comandă, însumează liniile din payoutItems care o referă:

// Cât ai încasat efectiv pe o expediție cu ramburs:
// suma liniilor de virament care o referă.
const payouts = await getAllPayouts(); // GET /payouts, paginat
const paid = payouts
  .flatMap(p => p.payoutItems)
  .filter(item => item.expeditionId === expeditionId)
  .reduce((sum, item) => sum + item.amount, 0);

// Nu citi suma din BatchPayout.amount pentru o singură expediție:
// este totalul lotului, nu al liniei.

Ce mai ai de primit

GET/payouts/outstandingBearer JWT

Expedițiile cu ramburs livrate pentru care încă nu ai primit banii, plus totalul.

Răspuns 200 OK

json

{
  "totalOutstanding": 1430.75,
  "currency": "RON",
  "count": 6,
  "expeditions": [
    {
      "expeditionId": "9d1e5b77-...",
      "awbNumber": "81356295593",
      "trackingNumber": "81356295593",
      "deliveryDate": "2026-10-29T11:34:00.000Z",
      "amount": 250,
      "recipientName": "Ion Popescu",
      "recipientCity": "CLUJ-NAPOCA"
    }
  ]
}

Aceasta este ruta de folosit pentru un indicator „de încasat” în propriul tău panou. În aplicație, aceleași date apar în Virament ramburs → De primit.

Export și documente

CSV

GET/payouts/exportBearer JWT

Toate viramentele tale, ca fișier CSV. Acceptă aceiași parametri de filtrare ca lista.

GET/payouts/{id}/exportBearer JWT

Un singur virament, cu o linie pe expediție.

Nota de decontare

GET/payouts/{id}/settlement-noteBearer JWT

Cod	Ce înseamnă
200	PDF-ul notei.
400	Viramentul nu este finalizat. Nota se emite doar pentru viramente COMPLETED.
404	Viramentul nu există.