Finans Public API

Prefixul de baza pentru toate endpoint-urile publice este /api/public/v1. Starea curenta a API-ului este suficienta pentru integrari generale care creeaza clienti, emit facturi, inregistreaza plati si descarca PDF sau XML.

Resursele disponibile acum sunt:

• Health
• Company
• Document series
• Bank accounts
• Clients
• Products
• Invoices
• Payments
• Webhooks

API base URL:

https://app.finans.ro/api/public/v1

Toate exemplele din aceasta pagina folosesc acest prefix. Pentru medii interne sau de test, prefixul poate fi acelasi API public expus sub alt domeniu, dar structura de endpoint-uri ramane identica.

API-ul foloseste chei generate din produs si trimise prin header-ul standard:

Authorization: Bearer fk_live_xxxxxxxxx

Pentru aplicatiile conectate poti folosi si token-uri OAuth:

Authorization: Bearer foat_xxxxxxxxx

Identificatorii publici folosesc prefixele:

• fk_live_...
• foat_...

Flow-ul OAuth disponibil in produs foloseste endpoint-urile:

• GET /api/public/v1/oauth/authorize
• POST /api/public/v1/oauth/authorize/decision
• POST /api/public/v1/oauth/token

Pentru verificare rapida foloseste GET /health/verify. Acesta intoarce date despre firma, conexiunea de integrare si scope-urile disponibile pe cheia curenta.

Pentru o integrare completa recomandam o cheie API dedicata, cu atat scope-uri de citire cat si de scriere.

Daca primesti raspuns de tip missing_scopes, cheia este valida, dar nu are permisiunea ceruta de endpoint-ul apelat.

Pentru a evita duplicatele la retry-uri HTTP, API-ul implementeaza idempotency persistenta pentru:

• POST /invoices
• POST /payments

Trimite un header stabil pe actiunea business, nu pe fiecare request individual:

Idempotency-Key: external-system:order_100045:create_invoice

Daca primesti 409 idempotency_in_progress, nu genera un key nou si nu schimba payload-ul. Refa acelasi request cu acelasi Idempotency-Key dupa un backoff scurt pana cand primesti replay-ul raspunsului final.

In varianta curenta nu exista endpoint separat de status pentru idempotency. Recovery-ul oficial este polling prin retrimiterea aceluiasi request idempotent.

Foloseste acest endpoint ca prim pas in onboarding. Daca el raspunde corect, cheia este valida si poti vedea exact ce scope-uri ai disponibile.

Returneaza datele firmei emitente folosite in documente: identificare fiscala, adresa, contact, TVA, moneda implicita si setarile generale ale firmei.

Poti descoperi seriile active pentru documente si le poti filtra cu ?type=INVOICE, ?type=PROFORMA sau ?type=RECEIPT.

La emitere poti trimite series sau series_id. Daca exista o singura serie activa sau una marcata implicit, API-ul o poate selecta automat.

Returneaza conturile bancare active ale firmei. Poti filtra cu ?currency=EUR sau cu alta moneda suportata pentru a alege contul corect la documentele in valuta.

Resource-ul este util pentru sincronizare clienti din ecommerce, ERP sau CRM.

Filtrarea pe lista se face cu parametrul search, care cauta in nume, CUI si email.

POST /api/public/v1/clients
Authorization: Bearer fk_live_xxxxxxxxx
Content-Type: application/json

{
  "type": "COMPANY",
  "external_id": "customer_123",
  "name": "Client Test SRL",
  "cui": "RO12345678",
  "reg_com": "J40/123/2024",
  "address": "Str. Exemplu 1",
  "city": "Bucuresti",
  "county": "Bucuresti",
  "country": "RO",
  "postal_code": "010101",
  "email": "client@example.com",
  "phone": "+40722111222",
  "iban": "RO49AAAA1B31007593840000",
  "bank_name": "Banca Demo",
  "vat_payer": true,
  "vat_number": "RO12345678"
}

GET /api/public/v1/clients?search=Client%20Test&page=1&page_size=20
Authorization: Bearer fk_live_xxxxxxxxx

Poate fi folosit pentru mapare SKU, sincronizare catalog si creare de servicii standardizate.

Filtrarea pe lista se face cu parametrul q pentru nume si cu currency pentru moneda.

POST /api/public/v1/products
Authorization: Bearer fk_live_xxxxxxxxx
Content-Type: application/json

{
  "name": "Produs demo",
  "unit": "buc",
  "currency": "RON",
  "unit_price": 100,
  "vat_rate": 19,
  "price_includes_vat": false,
  "product_code": "SKU-ABC"
}

GET /api/public/v1/products?q=Produs%20demo&currency=RON&limit=20
Authorization: Bearer fk_live_xxxxxxxxx

O factura poate fi emisa direct dintr-un sistem extern folosind un payload orientat pe integrari, cu client, source si lines.

Daca trimiti series_id, API-ul foloseste exact seria indicata. Daca omiti seria, API-ul incearca sa aleaga seria activa implicita pentru tipul documentului.

In fiecare linie, external_product_id este optional si este tratat ca alias pentru product_code. Valoarea se mapeaza la codul de produs folosit in liniile facturii si in catalogul intern, nu la un external_id separat.

Produsul nu trebuie sa existe deja in /products. Daca exista un produs activ cu acelasi cod, este reutilizat; daca nu exista, factura poate fi emisa oricum, iar catalogul este sincronizat automat din liniile documentului.

Dupa emiterea facturii poti inregistra plata si, pentru platile cash, poti descarca PDF-ul aferent chitantei.

Pentru platile cash poti trimite receipt_series sau receipt_series_id. Daca nu sunt trimise si exista o singura serie activa sau una implicita, API-ul o poate selecta automat.

Endpoint-urile actuale acopera configurarea, update-ul si testarea webhook-urilor. Livrarea initiala se face imediat la emiterea evenimentului, iar retry-urile automate sunt orchestrate de workerul dedicat care proceseaza coada protejata din backend.

URL-urile de webhook trebuie sa fie publice, pe https://, fara host-uri locale, private sau rezervate.

Daca serverul este configurat cu PUBLIC_API_WEBHOOK_ALLOWED_HOSTS, host-ul endpoint-ului trebuie sa intre si in allowlist-ul explicit permis.

La creare primesti o singura data plain_secret. Pastreaza-l securizat si verifica fiecare livrare folosind x-finans-signature: semnatura este HMAC-SHA256, in format hex, calculata peste sirul <x-finans-timestamp>.<raw_body>. Compara semnaturile in timp constant si respinge timestamp-urile mai vechi de 5 minute pentru protectie anti-replay.

Headerele trimise sunt x-finans-signature, x-finans-timestamp,x-finans-event, x-finans-event-id six-finans-delivery-id. Verificarea trebuie facuta pe corpul brut, inainte de parsarea JSON.

POST /api/public/v1/invoices
Authorization: Bearer fk_live_xxxxxxxxx
Idempotency-Key: external-system:order_100045:create_invoice
Content-Type: application/json

{
  "series": "FCT",
  "type": "INVOICE",
  "issue_date": "2026-04-19",
  "currency": "RON",
  "client": {
    "external_id": "customer_123",
    "email": "client@example.com",
    "name": "Client Test SRL",
    "cui": "RO12345678",
    "address": "Str. Exemplu 1",
    "city": "Bucuresti",
    "country": "RO"
  },
  "source": {
    "system": "external_app",
    "connection_id": "ic_123",
    "external_order_id": "100045",
    "external_order_number": "#100045"
  },
  "lines": [
    {
      "external_product_id": "sku_abc",
      "description": "Produs demo",
      "quantity": 1,
      "unit_price": 100,
      "vat_rate": 19
    }
  ]
}

{
  "invoice_id": "inv_123",
  "amount": 119,
  "currency": "RON",
  "payment_date": "2026-04-19",
  "payment_method": "CARD",
  "reference": "order-100045",
  "source": {
    "connection_id": "ic_123",
    "external_order_id": "100045",
    "external_payment_id": "pay_100045"
  }
}

Pentru plati cash poti trimite si receipt_series, apoi folosi endpoint-ul PDF pentru chitanta.