Parteneri și CRM

Administrezi clienți, furnizori și lead-uri CRM fără să emiți facturi, oferte sau proforme.

Acces și firme

În eCommerce → API → Chei API, generează sau configurează cheia cu drepturile necesare:

Cheile existente nu primesc automat drepturile noi. Se aplică accesul API și restricțiile abonamentului; pentru lead-uri este necesar și accesul CRM. Operațiile nu activează un modul sau un abonament.

Pentru un grup cu patru firme, configurează patru chei, câte una pentru fiecare firmă, și asociază fiecăreia codul unic corect. Headerul Fgo-Cod-Unic confirmă firma cheii; nu schimbă firma. Păstrează în CRM și firma, și identificatorul FGO al fiecărei înregistrări.

Caută înainte de creare

GET /v2/clienti?cod_unic=28639218&fields=id,denumire,cod_unic
Authorization: Bearer fgo_test_api_v1....
Fgo-Cod-Unic: 12345678

Pentru furnizori folosești /v2/furnizori, iar pentru lead-uri /v2/leaduri. Lead-urile pot fi filtrate după q (începutul denumirii), cod_unic, email și telefon (potrivire exactă), cu limit și cursor pentru paginare. Parametrul fields este obligatoriu și selectează câmpurile returnate, de exemplu fields=id,denumire,cod_unic. Nu sunt incluse înregistrările șterse.

Citirea individuală se face prin GET /v2/clienti/{id}, GET /v2/furnizori/{id} sau GET /v2/leaduri/{id}. Folosește exact identificatorul primit: cli_..., frn_..., respectiv lead_....

Creează un partener

curl -X POST https://api-testuat.fgo.ro/v2/clienti \
  -H "Authorization: Bearer fgo_test_api_v1...." \
  -H "Fgo-Cod-Unic: 12345678" \
  -H "Content-Type: application/json" \
  -d '{"denumire":"Firma exemplu","cod_unic":"28639218","tip_persoana":"PJ","cod_tara":"RO","cod_judet":"B","localitate":"București","adresa":"Strada Exemplu 1","email":"contact@example.com","telefon":"0722000000"}'

Pentru un furnizor, trimiți aceleași câmpuri la POST /v2/furnizori. denumire, tip_persoana (PF/PJ) și cod_tara (ISO alpha-2, cu majuscule) sunt obligatorii. Pentru partenerii PJ este obligatoriu și cod_unic. La un client PF trebuie completat CNP-ul sau adresa. Codurile fiscale și telefoanele sunt validate conform regulilor FGO.

Nu trimite prefixul RO în codul unic românesc. cod_judet se preia din nomenclatorul de județe și se folosește numai pentru România.

Un cod unic deja prezent pe un client sau furnizor activ este respins la creare, conform regulilor existente. API-ul nu transformă crearea în actualizare și nu unește înregistrări. Pentru PF fără cod unic, căutarea după contact și păstrarea ID-ului în CRM sunt responsabilitatea integrării.

Răspunsul de succes este 200, cu înregistrarea în data și informațiile apelului în meta. Salvează data.id. Crearea nu emite niciun document.

Creează un lead

POST /v2/leaduri
Content-Type: application/json
Authorization: Bearer fgo_test_api_v1....
Fgo-Cod-Unic: 12345678

{
  "denumire": "Firma de contactat",
  "tip_persoana": "PJ",
  "cod_tara": "RO",
  "cod_unic": "28639218",
  "email": "contact@example.com",
  "sursa": "CRM propriu",
  "observatii": "Solicită o ofertă",
  "data": "2026-10-12"
}

Pe lead, codul unic este opțional. sursa este textul care descrie proveniența lead-ului, iar data este o dată civilă în format yyyy-MM-dd. Poți trimite și telefon și adresa. Județul și localitatea nu sunt câmpuri separate ale lead-ului.

Lead-urile pot avea același cod unic. Fiecare POST creează o înregistrare nouă; nu face deduplicare sau actualizare automată și nu creează un client ori o activitate CRM. Nu relua orbește un POST după un timeout: verifică mai întâi dacă înregistrarea a fost creată. Aceste operații nu oferă idempotenta emiterii facturilor.

Actualizează numai câmpurile necesare

PATCH /v2/clienti/{id}
Content-Type: application/json
Authorization: Bearer fgo_test_api_v1....
Fgo-Cod-Unic: 12345678

{ "telefon": "0733000000", "email": null }

Exemplul schimbă telefonul și golește emailul. Denumirea, adresa și celelalte câmpuri omise rămân nemodificate. Același comportament se aplică la PATCH /v2/furnizori/{id} și PATCH /v2/leaduri/{id}. Trimite cel puțin un câmp.

null este acceptat numai pentru câmpurile opționale; starea finală trebuie să respecte regulile de validare. denumire, tip_persoana și cod_tara nu se pot goli. La clienți și furnizori, codul unic și tipul persoanei nu se schimbă; excepția este completarea CNP-ului lipsă al unui client PF. Schimbarea denumirii prin API reprezintă confirmarea explicită a modificării.

Înregistrările inexistente, șterse sau din altă firmă răspund cu 404. Lipsa drepturilor răspunde cu 403, iar datele invalide cu 400, în formatul comun de eroare.

Aceste metode nu includ ștergerea, conversia lead-ului în client sau administrarea activităților CRM. Callbackul de încasare rămâne configurat separat în eCommerce → API; nu se adaugă un webhook de emitere a facturilor.