# API Mereu v1 — ghid de integrare

Adresă: https://mereu.md/api/v1. Ghidul și OpenAPI sunt publice, fără cheie. Integrarea rulează pe serverul clientului, prin HTTPS.

## 1. Autentificare și chei API

Fiecare cheie oferă acces la o singură afacere și la locațiile și permisiunile alese în cabinet. Cererile se trimit de pe serverul integrării, prin HTTPS.

1. Confirmă adresa email a proprietarului înainte să creezi sau să rotești o cheie API.
2. Deschide Administrare → Integrări → Chei API.
3. Alege o denumire, locațiile autorizate și permisiunile necesare.
4. Lasă „Fără expirare” sau alege un termen de 1–365 zile.
5. Copiază cheia afișată o singură dată și salveaz-o într-un manager de secrete sau în variabila de mediu `MEREU_API_KEY`.

| Operație | Ce se întâmplă |
| --- | --- |
| Creare fără termen | Cheia nu expiră automat; `expiresAt=null`. |
| Rotație | Cheia veche este revocată imediat. Actualizează cheia pe serverul integrării. |
| Revocare | Conexiunea rămâne revocată. Pentru a restabili accesul, creează o conexiune nouă. |
| Răspuns de creare pierdut | Reîncarcă lista și rotește cheia. Repetarea cererii nu afișează secretul. |

> **Păstrează cheia pe server**
> Nu include cheia în JavaScript livrat în browser, aplicații mobile, Git sau loguri. Administrarea cheilor se face în cabinet de către administrator, nu prin cheia publică Bearer.

> **Revendicarea unui cont neconfirmat**
> Când titularul real revendică un cont self-service care nu a fost niciodată confirmat, conexiunile și cheile API existente ale afacerii sunt revocate. După revendicare, creează o conexiune nouă și actualizează cheia în POS/CRM. Această revocare de securitate se aplică și cheilor fără expirare.

O cheie cu termen expirat poate fi rotită în cabinet. Cheile fără termen nu cer reînnoire programată. Expirarea cursorului de sincronizare nu înseamnă că a expirat cheia.

### Citește datele companiei · cURL

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $MEREU_API_KEY" \
  -H 'Accept: application/json' \
  https://mereu.md/api/v1/account
```

### Citește datele companiei · JavaScript

```javascript
import {createMereuClient} from './mereu-client.mjs';

const api = createMereuClient({
  baseUrl: 'https://mereu.md/api/v1',
  apiKey: process.env.MEREU_API_KEY
});

const {data: account} = await api('GET', '/account');
console.log(account.name, account.base_currency);
```

### Citește datele companiei · Python

```python
import os
from mereu_client import MereuClient

api = MereuClient(
    'https://mereu.md/api/v1',
    os.environ['MEREU_API_KEY']
)

account = api.request('GET', '/account')['data']
print(account['name'], account['base_currency'])
```

## 2. Companie, locații și programe

Citește configurația înainte să trimiți vânzări sau să afișezi sume în CRM. Folosește întotdeauna adresa centrală `https://mereu.md/api/v1`, inclusiv pentru afacerile cu pagină publică pe subdomeniu.

| Endpoint | Date returnate | Permisiune |
| --- | --- | --- |
| GET /account | Companie, țară, monedă, fus orar, acces și locații autorizate. | account:read |
| GET /reference-data | Țări, monede acceptate și sugestii de fus orar. | account:read |
| GET /locations | Locațiile autorizate și starea lor. | locations:read |
| GET /programs | Versiunile programelor publicate și regulile expuse. | programs:read |

Listele `/locations` și `/programs` acceptă doar `limit` și `cursor`: 50 rezultate implicit, maximum 100. Urmează `next_cursor` până devine `null`. Cursorul este valabil o oră și este legat de cheia curentă; după rotație, reia lista de la prima pagină.

> **Configurația nu este un export de modificări**
> Câmpul `sync_token` din aceste liste este rezervat. Pentru sincronizarea CRM folosește `/data/*`. Calculul autoritar al beneficiului se face prin `/checkouts/preview`.

### Lista locațiilor · cURL

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $MEREU_API_KEY" \
  -H 'Accept: application/json' \
  --get \
  --data-urlencode 'limit=100' \
  https://mereu.md/api/v1/locations
```

## 3. Identificarea cardului în POS

Trimite codul complet scanat la `POST /cards/resolve`. Răspunsul conține `card_id`, `program_version_id` și `currency`, fără date de contact.

- Folosește codul de bare complet sau codul public exact al cardului; nu îl transforma într-un UUID.
- Cheia trebuie să aibă `checkouts:write` și acces la locația transmisă.
- Cardurile inactive, de test sau din altă afacere răspund cu 404.
- Această căutare nu cere `Idempotency-Key`. Păstrează asocierea cu clientul POS în sistemul tău.

## 4. Integrarea POS: beneficiu înainte de plată

Folosește acest flux când POS-ul aplică reducerea sau consumă puncte înainte să încaseze plata. Cere permisiunea `checkouts:write` și autorizează explicit operațiunile financiare în cabinet.

| Asociere în cabinet | Valoarea din sistemul tău |
| --- | --- |
| source | Identificator stabil al integrării, de exemplu `my_pos`. |
| accountId | Identificatorul comerciantului sau contului POS. |
| externalLocationId | Identificatorul magazinului în POS. |
| locationId | UUID-ul locației corespunzătoare din Mereu. |
| eligiblePolicy | Folosește `paid_excluding_tips_surcharges`. |

Această asociere leagă referințele documentelor; nu oferă acces Mereu la contul unui furnizor POS. Păstrează aceleași valori după rotația cheii.

1. Calculează beneficiul cu `POST /checkouts/preview`. Trimite sumele și `reward.mode`: `none`, `points` sau `visit_reward`. Pentru `points`, valoarea este un șir zecimal, de exemplu `10.25`.
2. Citește `discount` și `expected_paid_total` din ofertă. Oferta este valabilă 120 secunde. Nu recalcula aceste valori în POS.
3. Rezervă beneficiul cu `POST /checkouts`, folosind `quote_id` și referința stabilă a vânzării.
4. Trimite `POST /checkouts/{id}/payment-started` cu `expected_revision` din rezervare și așteaptă succesul.
5. Abia acum aplică beneficiul și încasează plata în POS-ul sau sistemul tău de plăți.
6. După verificarea încasării, confirmă prin `POST /checkouts/{id}/commit`. Folosește revizia din `payment-started`, suma reală egală cu `expected_paid_total`, ora plății și referința sa. Salvează `transaction_id`.

> **Salvează cererile înainte de trimitere**
> Fiecare pas financiar are propriul UUID `Idempotency-Key`. Păstrează UUID-ul și corpul exact al cererii în baza ta. Repetă același pas cu aceleași valori, fără să creezi o vânzare nouă.

Un card poate avea o singură rezervare, comună cu Casa. Rezervarea pentru care plata nu a început expiră după 10 minute. Pentru a afla starea, citește `GET /checkouts/{id}`.

Dacă plata nu a avut loc, anularea cere revizia curentă și un motiv. După ce plata ar fi putut începe, `payment_not_completed:true` este o confirmare explicită de neplată, nu o presupunere după timeout.

> **Plată incertă**
> Un răspuns pierdut nu dovedește că plata a eșuat. Nu încasa din nou și nu crea altă rezervare. Verifică POS-ul, citește rezervarea și, când este necesar, folosește Integrări → Reconciliere în cabinet.

### Ordinea operațiunilor POS · Flux

```text
1. POST /checkouts/preview
2. POST /checkouts
3. POST /checkouts/{id}/payment-started

   Încasează în POS și verifică plata.

4. POST /checkouts/{id}/commit

   Salvează transaction_id pentru retururi.
```

## 5. Vânzări deja achitate

Folosește `POST /purchases` când plata a avut deja loc și vrei să înregistrezi cumpărătura pentru acumularea beneficiilor. Cere `purchases:write` și o asociere financiară autorizată.

- Trimite `location_id`, `card_id`, `external_ref` și UUID-ul operațiunii.
- `paid_total` este suma efectiv achitată; `eligible_amount` este partea eligibilă achitată, fără bacșiș și suprataxe.
- `paid_at` și `provider_payment_id` trebuie să provină din plata verificată în sistemul tău.
- Dacă observi o vânzare deja confirmată prin checkout, folosește aceleași referințe ale vânzării și plății.

> **Fără beneficii retroactive**
> Acest endpoint nu aplică retroactiv reduceri și nu consumă puncte. Vânzările anterioare activării asocierii sau creării cardului se înregistrează fără acumulare retroactivă (`accrual_enabled=false`).

Existența unui bon nu dovedește plata. Verifică încasarea înainte de import. Mereu nu încasează bani prin acest endpoint.

## 6. Retururi și anulări integrale

Verifică tranzacția cu `GET /transactions/{id}` și permisiunea `transactions:read`. Pentru retururi, folosește `refunds:write` și UUID-ul financiar al vânzării.

| Endpoint | Când îl folosești |
| --- | --- |
| POST /transactions/{id}/refunds | Retur parțial sau integral verificat. |
| POST /transactions/{id}/reversal | Anulare integrală; este refuzată după un retur deja aplicat. |

| Câmp | Ce trimiți |
| --- | --- |
| external_ref | Referința stabilă și distinctă a documentului de retur. |
| refunded_total | Banii efectiv restituiți. Poate fi zero la o achiziție achitată integral prin beneficii. |
| refunded_eligible_amount | Valoarea ORIGINALĂ eligibilă a bunurilor returnate, înainte de beneficiul Mereu. |
| occurred_at / provider_refund_id | Momentul și identificatorul real al returului din sistemul tău. |
| reason | Motivul verificat, fără date personale. |

Folosește alocările articolelor din vânzarea inițială, nu regulile curente ale programului. La un import obișnuit `/purchases`, fără beneficii consumate, valoarea eligibilă returnată corespunde valorii eligibile achitate.

Retururile parțiale se alocă cumulativ, cu rotunjire întreagă exactă; ultima alocare închide vânzarea. Suma restituită poate include și partea neeligibilă returnată, în limita plății inițiale. Moneda și programul inițial se păstrează.

> **Retur care cere verificare**
> `needs_review` înseamnă un caz deja salvat. Nu retrimite returul cu alt UUID. Punctele sau vizitele deja consumate/expirate pot cere acceptarea explicită a compensării în Reconciliere.

Citește `GET /transactions/{refund_id}` pentru starea returului. Mereu nu trimite bani către bancă sau POS: înregistrează returul numai după verificarea restituirii în sistemul tău.

## 7. Integrarea CRM: export și sincronizare

CRM-ul preia datele din Mereu prin cereri GET. Nu există creare sau modificare de clienți prin acest API.

| Resursă | Ce sincronizezi | Permisiune |
| --- | --- | --- |
| /data/customers | Identitatea locală, numele, datele de contact disponibile și acordul de marketing. | customers:read |
| /data/cards | Carduri, program, stare și soldurile calculate la citire. | cards:read |
| /data/transactions | Operațiunile aplicate în Casa/POS și valorile expuse ale beneficiilor. | transactions:read |

1. Începe fiecare resursă cu `mode=snapshot&limit=100`. Citește toate paginile folosind `next_cursor` până devine `null`.
2. Salvează paginile într-un set intermediar. Înlocuiește setul activ din CRM numai după terminarea exportului.
3. Păstrează `sync_cursor` al exportului inițial. Cere apoi ACEEAȘI resursă cu `mode=changes` și acel cursor.
4. Aplică modificările în ordinea paginilor: actualizează sau inserează după ID; pentru `operation=delete`, șterge după `record_id`.
5. Salvează datele și noul cursor în ACEEAȘI tranzacție a bazei CRM. La un eșec al salvării, reia de la cursorul salvat anterior.

> **Un cursor separat pentru fiecare resursă**
> Nu folosi cursorul clienților pentru carduri sau tranzacții. Cursorii sunt legați de conexiune, resursă și locațiile autorizate, rezistă rotației cheii și expiră după 7 zile.

La `410 CURSOR_EXPIRED`, pornește un export complet nou și înlocuiește setul local. Dacă se schimbă autorizarea sau conexiunea, refă exportul și elimină datele la care nu mai ai acces. Nu există cotă totală de rânduri exportate; respectă limita de cereri.

Modificările descriu starea curentă, nu un jurnal istoric imuabil. Un eveniment repetat poate avea un conținut mai nou: nu ignora corpul doar fiindcă ai văzut același `event_id`. Procesează secvențial și aplică `operation=delete` / `deleted=true`, inclusiv ștergerea contactelor locale.

Exportul citește rândurile curente; modificările de după punctul său de pornire acoperă și actualizările din timpul paginării. Tranzacțiile încă nefinalizate pot întârzia temporar vizibilitatea schimbărilor. `changed_at` nu este un număr de versiune.

`customer.id` este UUID-ul cardului în această afacere. Nu uni automat persoane din afaceri diferite. În istoricul contabil, `id` și `original_id` sunt ID-uri native; numai `financial_transaction_id`, dacă nu este `null`, funcționează la endpointurile financiare de tranzacție și retur. Operațiunile făcute de echipă pot să nu aibă acest ID.

Verifică periodic `/account` pentru moneda și fusul orar curente. Păstrează asocierile CRM în sistemul tău; `/resource-links` este retras (410). Nu include date de contact în identificatori sau loguri.

### 1. Exportul inițial al clienților · cURL

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $MEREU_API_KEY" \
  -H 'Accept: application/json' \
  --get \
  --data-urlencode 'mode=snapshot' \
  --data-urlencode 'limit=100' \
  https://mereu.md/api/v1/data/customers
```

### 2. Modificările de la cursorul salvat · cURL

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $MEREU_API_KEY" \
  -H 'Accept: application/json' \
  --get \
  --data-urlencode 'mode=changes' \
  --data-urlencode "cursor=$CUSTOMERS_SYNC_CURSOR" \
  --data-urlencode 'limit=100' \
  https://mereu.md/api/v1/data/customers
```

## 8. Permisiuni și locații

Acordă numai accesul necesar. Permisiunile și locațiile sunt explicite; nicio cheie nu acordă acces la altă afacere.

| Permisiune | Permite |
| --- | --- |
| account:read | Datele companiei și nomenclatoarele. |
| locations:read | Lista locațiilor autorizate. |
| programs:read | Lista programelor publicate. |
| customers:read | Citire/sincronizare date de contact. |
| cards:read | Citire/sincronizare carduri și solduri. |
| transactions:read | Istoric și citirea stării tranzacțiilor financiare. |
| checkouts:write | Identificarea cardului și fluxul de rezervare/confirmare. |
| purchases:write | Înregistrarea vânzărilor deja achitate. |
| refunds:write | Retururi și anulări integrale. |

> **Limita accesului public**
> API-ul nu modifică clienți, nu emite carduri, nu editează manual solduri și nu controlează automatizări, oferte sau notificări. Nu schimbă setările companiei. Scrierile sunt doar pentru fluxurile de vânzare și retur.

## 9. Exemple JavaScript, Python și Postman

Descarcă exemplele din secțiunea Resurse. Rulează-le pe serverul tău, cu `MEREU_API_URL=https://mereu.md/api/v1` și cheia în `MEREU_API_KEY`.

| Fișier | Rol |
| --- | --- |
| mereu-client.mjs / mereu-client.py | Autentificare, cereri și codificarea parametrilor GET. |
| crm-sync.mjs / crm-sync.py | O pagină de export sau modificări, cu un cursor salvat durabil. |
| pos-checkout.mjs | Rezervare, confirmarea vânzării, import și retur. |
| mereu-postman.json | Cereri manuale cu referințe, UUID-uri și sume de completat. |

Pentru importuri Python, redenumește modulele în `mereu_client.py` și `crm_sync.py`. În numele modulelor Python nu se folosesc cratime.

- CRM: citește starea salvată și apelează `syncMereuPage(api, resource, state, commitPage)` sau `sync_mereu_page(api.request, resource, state, commit_page)`.
- `state=null` / `None` începe exportul. Funcția procesează O SINGURĂ pagină și returnează `phase` și `cursor`.
- În callback, resetează setul intermediar la `reset=true`, adaugă rândurile neșterse și înlocuiește setul activ numai la `complete=true`. În modul changes, aplică inserările/actualizările/ștergerile.
- Salvează cursorul împreună cu datele, într-o singură tranzacție. Lasă erorile de salvare să se propage. Planifică pagina următoare în coada ta de lucrări, în limita de cereri.

- POS: `prepareCheckout` trimite doar preview, rezervare și payment-started, prin callbackul tău durabil `persist`.
- Furnizează UUID-urile din comanda salvată. Începe plata în sistemul tău numai după succesul funcției și salvarea jurnalului.
- După verificarea plății, apelează `commitVerifiedPayment`. Pentru importuri achitate folosește `recordVerifiedPurchase`; pentru retururi verificate, `recordVerifiedReturn`.
- Un eșec al jurnalului după răspuns poate însemna că operația s-a aplicat deja. Recuperează cererea salvată și verifică starea înainte să o repeți.

În Postman completează variabilele goale și sumele numerice întregi. La commit, copiază `expected_paid_total` din ofertă și revizia din payment-started. La retur, folosește alocarea eligibilă inițială și banii real restituiți.

> **Exemplele nu pornesc plăți**
> Niciun modul nu încasează sau restituie bani, nu contactează furnizori și nu repetă automat scrierile. UUID-urile și sumele ilustrative din OpenAPI se înlocuiesc cu referințe autorizate și fapte verificate.

## 10. Erori și recuperare

Erorile includ `error.code`, `error.message` și `error.request_id`; validarea poate include `field_errors`. Păstrează `X-Request-Id` pentru suport, fără chei sau date personale.

| Cod | Ce faci |
| --- | --- |
| 401 INVALID_API_KEY | Verifică cheia, revocarea sau termenul ales în cabinet. Cheile indefinite nu cer reînnoire. |
| 403 INSUFFICIENT_SCOPE | Verifică permisiunile, locațiile, autorizarea/asocierea financiară și fereastra de export a afacerii. |
| 404 | Verifică resursa autorizată. Un ID nativ din istoric nu este automat un ID financiar. |
| 409 IDEMPOTENCY_CONFLICT | Recuperează UUID-ul și corpul original; nu schimba UUID-ul ca să ocolești un rezultat incert. |
| 409 STALE_QUOTE / QUOTE_EXPIRED | Citește starea și cere o ofertă nouă înaintea unei încercări noi verificate. |
| 409 STALE_REVISION / CARD_RESERVED | Citește rezervarea și verifică operația existentă; nu începe altă plată. |
| 409 REFUND_ALLOCATION_MISMATCH | Folosește valorile brute inițiale și alocarea cumulativă, inclusiv banii neeligibili returnați. |
| 410 CURSOR_EXPIRED | Refă exportul complet. Endpointurile retrase au propriul cod 410. |
| 422 INVALID_CURSOR / VALIDATION_ERROR | Corectează parametrii. La listele de configurație, reîncepe de la pagina 1 după expirarea cursorului de o oră. |
| 423 SERVICE_SUSPENDED | Operațiunile financiare nu sunt disponibile; rezolvă starea serviciului în cabinet. |
| 429 RATE_LIMITED | Respectă Retry-After și împarte cererile în bugetul comun al conexiunii. |
| 503 sau timeout | Păstrează UUID-ul și corpul, mărește intervalul de așteptare și verifică/reconciliază operațiunea incertă înainte de repetare. |

> **Nu confunda expirările**
> Nu roti o cheie validă pentru o eroare de cursor. Nu repeta automat o cerere 401. La validare 400/422, corectează datele înainte de o operațiune nouă.

## 11. Sume, fus orar și limite

Monede acceptate: MDL, RON, EUR, USD, GBP, UAH, PLN, TRY, CHF, RUB, GEL, KZT. Toate au două zecimale în unitatea minoră: `10000` înseamnă `100.00`. Trimite numere întregi pentru bani; nu folosi rotunjiri în virgulă mobilă.

Operațiunile noi folosesc moneda curentă a companiei. Rezervările și retururile API păstrează moneda înregistrată. Schimbarea monedei companiei reetichetează sumele existente, fără conversie valutară. Istoricul de date expune și `recorded_currency` când există.

Trimite momente RFC3339 cu offset; este recomandat UTC `Z`. Pentru date locale folosește fusul IANA al afacerii/locației și rezolvă explicit ambiguitatea orei de vară. Nu presupune fusul serverului sau browserului.

| Limită | Valoare |
| --- | --- |
| Cereri pe conexiune | 120/minut, cumulat între apelurile API. |
| Cereri pe IP | 300/minut pentru fiecare grup: configurație, date, operațiuni financiare. |
| Pagină | 50 rezultate implicit, maximum 100. |
| Corp JSON | Maximum 100000 octeți. |
| Valori financiare | 0–100000000 unități minore; unele operațiuni cer o valoare pozitivă. |
| Conexiuni | Maximum 20 active și 10 locații autorizate per conexiune. |
| Cheie | Fără expirare implicită sau termen ales de 1–365 zile. |
| Cursor configurație / date | 1 oră / 7 zile. |
| Ofertă / rezervare neîncepută | 120 secunde / 10 minute. |

Rezultatele comenzilor financiare se păstrează. Repetarea preview-ului este păstrată cel puțin 24 ore și nu prelungește oferta. La repetare se verifică din nou cheia, revocarea, expirarea, permisiunile și asocierile autorizate.

La 429 respectă `Retry-After`. La lipsa modificărilor mărește intervalul de sincronizare. Nu loga antetul Authorization, coduri de card, identificatori de clienți sau corpuri financiare complete.

## 12. Versiuni și operare

Folosește `/api/v1`. Acceptă câmpurile opționale noi din răspuns și ignoră câmpurile necunoscute. Schimbările incompatibile cer o versiune API nouă și instrucțiuni de migrare.

Clientul sau integratorul său construiește și întreține legătura cu propriul POS/CRM. Nu sunt necesare chei sau conturi de furnizor la Mereu. Conectorii gestionați Loyverse/Square/Poster, OAuth, webhookurile furnizorilor și `/connector-events` sunt retrase cu `410 CONNECTORS_RETIRED`.

API v1 nu oferă webhookuri către client, evenimente asincrone de furnizor sau control extern al funcțiilor de marketing. Operațiunile financiare cer serviciu activ și autorizare explicită; citirea rămâne disponibilă pentru exportul autorizat când scrierile contractuale se opresc. Accesul API dezactivat sau indisponibil răspunde cu 503.

Plățile incerte și retururile care cer verificare se rezolvă în cabinet, la Integrări → Reconciliere. Nu se editează direct istoricul din Casa.
