Înregistrarea unei facturi furnizor

POST /v2/facturi-furnizori înregistrează o factură primită, din JSON, cu articole. Documentul apare în aplicația FGO și în GET /v2/facturi-furnizori.

Cheia trebuie să aibă dreptul facturi-furnizori:scriere, acordat explicit; cheile existente nu primesc automat acest drept. Firma trebuie să aibă acces la adăugarea documentelor contabile. Pentru căutarea furnizorilor și verificarea facturilor prin listare este necesar și furnizori:citire.

1. Identifică furnizorul

Caută prin GET /v2/furnizori?cod_unic=12345678&fields=id,denumire,cod_unic. Copiază exact id din rezultat în furnizor_id. Furnizorul trebuie să existe în firma cheii; operația nu îl creează automat.

2. Înregistrează factura

Trimite cererea la https://api-testuat.fgo.ro/v2/facturi-furnizori, cu headerele Authorization: Bearer fgo_test_api_v1...., Fgo-Cod-Unic și Content-Type: application/json.

Înlocuiește referința furnizorului din exemplu cu valoarea reală returnată la pasul anterior.

{
  "furnizor_id": "frn_4f1c9b2e7a3d4c6b8e5f0a1d2c3b4a59",
  "numar": "FF-123",
  "data_emitere": "2026-10-13",
  "data_scadenta": "2026-11-13",
  "valuta": "RON",
  "valoare": 100.00,
  "valoare_tva": 21.00,
  "articole": [
    {
      "denumire": "Serviciu achiziționat",
      "um": "buc",
      "cantitate": 2.000,
      "pret_unitar": 50.0000,
      "cota_tva": 0.2100
    }
  ]
}

Fără coduri, se creează un articol de achiziție cu denumirea trimisă, fără stoc, ca în introducerea manuală. Denumirile articolelor noi trebuie să fie distincte în aceeași cerere. Pentru un articol existent, trimite cod_articol sau cod_bare, nu ambele: potrivirea este exactă, în firma cheii. Lipsa potrivirii răspunde 404; mai multe potriviri răspund 400. Nu se creează automat un articol dacă ai trimis un cod negăsit.

valoare este suma fără TVA a liniilor. Pentru fiecare linie, cantitate × preț unitar se rotunjește comercial la două zecimale; TVA se calculează din această valoare și se rotunjește tot la două zecimale. valoare_tva trebuie să coincidă cu suma TVA a liniilor. cota_tva este coeficient, de exemplu 0.21, nu 21. Cantitatea și prețul sunt obligatorii și diferite de zero. Sunt acceptate maximum 1000 de linii.

Moneda implicită este RON, cu cursul 1. Pentru alte monede, curs_valutar este obligatoriu și pozitiv. Datele sunt date calendaristice; data_emitere este obligatorie. nume_document, data_scadenta, data_inregistrare și detaliile liniilor sunt opționale.

Preluarea în stoc

stoc_preluat este opțional, implicit false. Trimite true pentru preluarea în stoc, cu aceeași logică din aplicația FGO. Cantitățile se actualizează numai dacă firma are dreptul de stoc și bifa „Stoc pe articol” activă, pentru articolele existente care folosesc stoc. Dacă aceste condiții nu sunt îndeplinite, documentul se înregistrează, dar cantitățile nu se modifică. Articolele noi create prin denumire rămân fără stoc.

Pe fiecare linie poți trimite cod_gestiune, folosind un cod din GET /v2/gestiuni. Gestiunea trebuie să fie activă, unică după cod și să aparțină firmei cheii; altfel primești 404 (inexistentă/ștearsă/inaccesibilă) sau 400 (cod ambiguu). Lipsa dreptului de acces la gestiuni răspunde 403. Fără cod_gestiune, se păstrează comportamentul aplicației pentru liniile fără gestiune.

Pentru un articol existent care folosește stoc, înlocuiește linia exemplului cu:

{
  "cod_articol": "PROD-001",
  "cod_gestiune": "MAG",
  "um": "buc",
  "cantitate": 2.000,
  "pret_unitar": 50.0000,
  "cota_tva": 0.2100
}

Adaugă "stoc_preluat": true la nivelul facturii. Preluarea folosește actualizarea stocului, auditul și indexurile existente din aplicație. Operația nu creează NIR, plăți sau fișiere PDF/XML. Nu acceptă centre de cost sau discounturi dedicate.

3. Verifică rezultatul

Succesul este 201, cu data.id în formatul opac ffr_... și metadatele obișnuite v2. Factura poate fi verificată în aplicație sau prin listarea GET /v2/facturi-furnizori, filtrată după furnizor și număr; identificatorul este același.

Retrimiterile nu sunt deduplicate. Nu există actualizare automată după furnizor și număr, iar o nouă cerere poate crea un alt document. După un timeout sau alt rezultat incert, verifică listarea înainte de a retrimite. Operația nu oferă o garanție de idempotency.

Validările cererii răspund 400, lipsa accesului 403, iar referințele la furnizori, articole sau gestiuni inexistente, șterse ori din altă firmă răspund 404. Pentru fiecare firmă folosește cheia și codul unic corespunzătoare.