FGO API Ghiduri Referință API

Primii pași

FGO API este un API REST peste JSON. Cu el emiți și administrezi facturi, citești clienți, furnizori și articole — din aplicația ta, pentru firma ta din FGO.

Adresele mediului curent:

Mediu API Aplicația FGO
Test https://api-testuat.fgo.ro testuat.fgo.ro

În test nu ai nevoie de abonament plătit pentru dezvoltarea integrării.

1. Pregătește contul

Pentru generarea cheilor API v2, abonamentul minim este Premium. Cheile sunt disponibile pe abonamentele Premium și Enterprise.

  1. Creează-ți un cont pe testuat.fgo.ro sau autentifică-te dacă ai deja unul.
  2. Configurează un registru de facturi — comun sau al utilizatorului API. Seria pe care o trimiți la emitere trebuie să existe în el.
  3. Selectează firma pe care o conectezi, deschide eCommerce → API → Chei API și apasă „+ Generează”. Alege drepturile necesare integrării.

Cheia aparține firmei selectate în momentul generării și se vede o singură dată. Pune-o într-un secret manager.

Abonamentul Premium permite o cheie activă pe firmă; abonamentul Enterprise, până la 3. Cu abonamentul Premium, revocă-o pe cea veche înainte să generezi alta.

Pentru integrarea unui CRM fără emiterea de documente, vezi Parteneri și CRM.

Disponibilitate pe abonamente

Pentru pachetele standard din producție, operațiile de mai jos necesită Enterprise, peste nivelul minim Premium. Drepturile alese pe cheia API nu activează funcționalități care nu sunt incluse în abonamentul firmei.

Operații Abonament necesar
Listarea și căutarea articolelor — GET /v2/articole Enterprise
Consultarea stocurilor — GET /v2/stocuri/stoc-gestiune, GET /v2/stocuri/stoc-gestiune-articol și GET /v2/stocuri/stoc-articol Enterprise
Facturile generate dintr-o proformă — GET /v2/facturi/{serie}/{numar}/asociate Enterprise

Stocul dintr-un răspuns și accesul la operațiile de stoc sunt condiții distincte. Premium permite informații despre stoc în răspunsul emiterii, când documentul descarcă stoc și firma are dreptul de expunere a cantităților; consultarea prin /v2/stocuri/... necesită Enterprise. Când expunerea cantității nu este permisă, câmpul stoc din citiri este null, iar lista stocuri din răspunsul emiterii este goală. null nu înseamnă stoc zero.

În mediul de test nu ai nevoie de abonament plătit pentru dezvoltarea integrării. Verifică însă abonamentul și drepturile firmei de producție înainte de lansare.

2. Fă primul apel

GET /v2/identitate îți confirmă că cheia este validă și îți arată drepturile acordate acesteia. Pentru a folosi o operație, ai nevoie atât de dreptul corespunzător pe cheie, cât și de accesul permis de abonamentul firmei. Acordarea unui drept pe cheie nu activează funcționalități care nu sunt incluse în abonament.

curl https://api-testuat.fgo.ro/v2/identitate \
  -H "Authorization: Bearer fgo_test_api_v1...." \
  -H "Fgo-Cod-Unic: 12345678"

Pune codul unic al firmei tale în locul lui 12345678 — numai cifrele, fără RO.

{
  "data": {
    "drepturi": ["facturi:citire", "facturi:emitere", "articole:citire"],
    "expira_la": "2026-12-31T23:59:59+02:00",
    "cautare_articol_dupa": "cod_articol"
  },
  "meta": {
    "timestamp": "2026-09-03T12:00:00+03:00"
  }
}

Răspunsul cerut se află în câmpul data.

Vezi formatul erorilor — Erori, limite și reluări.

3. Emite o factură

Înainte de apel:

Folosește seria din registrul configurat în FGO. Pentru valută și tipul facturii, consultă nomenclatoarele corespunzătoare. Descrierea fiecărui câmp precizează valoarea care trebuie transmisă. Cererea include clientul și cel puțin un articol; câmpurile opționale și valorile implicite sunt descrise în referință.

Cerere

curl -X POST https://api-testuat.fgo.ro/v2/facturi \
  -H "Authorization: Bearer fgo_test_api_v1...." \
  -H "Fgo-Cod-Unic: 12345678" \
  -H "Fgo-Url-Platforma: https://magazinul-tau.ro" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": "FGO",
    "valuta": "RON",
    "tip_factura": "F",
    "client": { "tip": "PJ", "denumire": "Client Exemplu SRL", "cod_unic": "12345674", "tara": "Romania" },
    "articole": [
      { "denumire": "Servicii consultanta", "um": "ora", "nr_produse": 1, "pret_unitar": 100, "cota_tva": 0.21 }
    ]
  }'

Răspuns — 200 OK

{
  "data": { "serie": "FGO", "numar": "1201", "stocuri": [] },
  "meta": { "timestamp": "2026-09-03T12:00:00+03:00" }
}

Valorile pentru cota_tva, valuta și tip_factura le iei din nomenclatoare, care se citesc fără cheie.

Cererea completă, cu toate câmpurile și cu ce se întâmplă în spate, e în Emiterea unei facturi.

Ce urmează