Identificatori

Un identificator FGO e un text opac cu prefix:

{ "id": "cli_4f1c9b2e7a3d4c6b8e5f0a1d2c3b4a59" }

Îl păstrezi ca text și îl compari ca text. Nu îl parsezi, nu îl construiești tu și nu deduci nimic din el — nu e un număr, nu e ordonat și nu spune câte resurse există.

Un id are cel mult 64 de caractere, litere mici, cifre și _. Acceptăm exact forma pe care o emitem — cu majuscule sau cu un caracter schimbat nu mai e același id, e un id invalid.

Unde îl trimiți

În cale, id-ul e parte din adresă: GET /v2/clienti/cli_4f1c9b2e7a3d4c6b8e5f0a1d2c3b4a59/sold. Un id malformat sau cu alt prefix nu potrivește ruta, deci primești 404 url-not-found, ca pentru orice adresă inexistentă.

În query sau în corp, id-ul e o valoare: GET /v2/facturi?client_id=cli_4f1c9b2e7a3d4c6b8e5f0a1d2c3b4a59, sau "id_client": "cli_4f1c…" în cererea fișei de partener. Un id malformat răspunde 400 validation, cu valoarea primită în mesaj, ca să vezi care e greșit.

Un id valid ca formă, dar al altei firme, se poartă ca unul inexistent. La citirea unei resurse, de exemplu GET /v2/clienti/{id_client}/sold, primești 404. La căutarea în colecție, GET /v2/clienti?id={id_client}&fields=denumire, primești 200 cu data: [] dacă nu există un client accesibil care corespunde filtrului. Nu poți afla din răspuns dacă id-ul există la altcineva.

Clienții folosesc prefixul cli_, furnizorii frn_, iar lead-urile CRM lead_. Păstrează ID-ul returnat la creare pentru actualizările ulterioare. ID-urile sunt verificate întotdeauna în firma cheii API.

Facturile n-au id

O factură se identifică prin serie și număr — cheia ei naturală, cea de pe document:

GET /v2/facturi/FGO/1201
POST /v2/facturi/FGO/1201/incasari

La fel încasările: serie_incasare și numar_incasare.

Coduri

Un cod nu e un id. E o valoare de business, stabilă, pe care o poți ști dinainte:

• cod pe resursa care îl definește — un județ are cod: "B", un articol are cod: "SERV-CONSULT", o bancă are bic;
• cod_<entitate> când altă resursă se referă la el — articolul de pe factură are cod_articol, clientul are cod_judet.

Codul unui articol nu e unic: mai multe articole pot avea același cod. Filtrarea după el face potrivire exactă și poate întoarce mai multe rezultate.

Articolele se caută printr-un singur câmp, ales de firmă în FGO, la Configurare API, setarea „Căutare articole după”: cod articol (implicit), cod de bare sau denumire. GET /v2/articole acceptă atunci doar filtrul corespunzător — cod, cod_bare sau nume — iar operațiile de stoc doar cod_articol, cod_bare sau nume_articol. Un filtru care nu e cel al firmei răspunde 400 validation, cu mesajul care spune ce câmp e acceptat.

id_extern e al tău

Pe factură, id_extern este referința documentului din sistemul tău. Cu verificare_duplicat=true, FGO îl folosește pentru a căuta o factură existentă înainte de emitere. Dacă o găsește, oprește emiterea cu 400 invalid-state. Fără această opțiune, aceeași valoare poate fi folosită pe mai multe facturi. Vezi verificarea duplicatelor.

Pe client, client.id_extern poate identifica un client PF existent dacă nu există un CNP/cod unic utilizabil și firma are activată căutarea după ID extern în setările API. Căutarea se face în firma cheii API. Valoarea trebuie să conțină numai cifre și să încapă într-un întreg pozitiv de 32 de biți (maximum 2147483647); 0 nu activează căutarea. Nu este o garanție de unicitate.