Studiu de caz · Instrumente / Open source
GetCIF
Date publice.Gata de integrat.
Un API gratuit și documentat care face datele publice despre firmele din România mai ușor de interogat, de înțeles și de folosit.
- Acces
- API gratuit, documentat
- Model
- Cache / snapshot / sursă live
- Stadiu
- Live
meta.data_origin → CACHE / SNAPSHOT / ANAF01 / Pe scurt
Nu doar încă un proxy.
GetCIF oferă dezvoltatorilor o cale simplă de a căuta firme din România după CIF. În spatele unui API mic și consecvent se ocupă de validare, cache, snapshoturi și serviciile publice ANAF, astfel încât o integrare primește un răspuns previzibil, nu ciudățeniile sursei.
Este gratuit, documentat în engleză și română și are SDK-uri pentru Node.js și PHP.
02 / Problema
Datele sunt publice. Să te bazezi pe ele e mai greu.
Datele despre firme și TVA de la ANAF sunt disponibile gratuit, dar o integrare directă preia fiecare asperitate a sursei.
O sursă imprevizibilă
Serviciile publice pot fi lente, limitate sau indisponibile pentru scurt timp. Dacă le apelezi direct, fiecare astfel de moment devine problema aplicației tale.
Date de intrare cu reguli proprii
CIF-urile trebuie normalizate, CNP-urile trebuie ținute departe, iar căutările după dată au nevoie de o valoare implicită rezonabilă. Fiecare integrare reînvață aceleași reguli.
Răspunsuri gândite pentru sursă
Răspunsurile brute reflectă felul în care sursa stochează datele, nu cum vrea o aplicație să le folosească, și nu spun dacă datele vin dintr-o interogare live.
03 / Ce face
Suprafață mică. Contract clar.
Câteva endpointuri evidente, un singur format de răspuns și sursa fiecărui rezultat inclusă în răspuns.
Căutare de firme
Caută o firmă după CIF sau mai multe deodată. Cererile bulk păstrează ordinea în care au fost trimise, inclusiv duplicatele.
Date brute, la nevoie
Fiecare endpoint structurat are un echivalent brut care păstrează același format și pune răspunsul original ANAF în data.raw.
Mai mult decât datele firmei
Bilanțurile, registrul agricultorilor, registrul cultelor și registrul RO e-Factura urmează aceleași convenții.
SDK-uri și contract OpenAPI
SDK-uri tipizate pentru Node.js / TypeScript și PHP, plus specificația OpenAPI pentru orice alt limbaj.
| Metodă | Cale | Descriere |
|---|---|---|
| GET | /v1/cifs/{cif} | Căutare structurată |
| GET | /v1/cifs/{cif}/raw | Răspunsul brut ANAF |
| POST | /v1/cifs/bulk | Căutare structurată bulk |
| POST | /v1/cifs/bulk/raw | Căutare brută bulk |
GET /v1/cifs/1590082
{
"data": {
"cif": "1590082",
"name": "ACME SRL",
...
},
"meta": {
"data_origin": "CACHE"
}
}04 / Sub capotă
Întâi munca ieftină.
Fiecare căutare urmează aceeași secvență. Un apel live către ANAF este ultima variantă, nu comportamentul implicit.
- 01
Validare
Normalizează identificatorii, respinge CNP-urile și interpretează datele înainte de orice apel extern.
- 02
Rezolvare
Stabilește cheia căutării. Endpointurile cu dată folosesc implicit ziua curentă în Europe/Bucharest.
- 03
Surse locale
Folosește cache-ul curent și snapshoturile salvate înainte de o cerere live.
- 04
Limitare
Aplică limitele de trafic și regulile de rezervă înainte de a ajunge la sursă.
- 05
Interogare
Apelează ANAF doar când înregistrarea nu există deja local.
- 06
Formatare
Returnează un format stabil: data plus meta, cu rezultate per CIF pentru cererile bulk.
Proaspăt când se poate. Util când nu.
Fiecare răspuns reușit spune de unde provine, astfel încât o integrare poate deosebi un răspuns rapid din cache de un snapshot salvat sau de o interogare live.
- 01 / Prima opțiuneCACHElipsă
O înregistrare aflată deja în fereastra curentă de cache.
- 02 / RezervăSNAPSHOTnesalvat
O înregistrare salvată dintr-o căutare anterioară.
- 03 / Sursa liveANAF
Serviciul public, apelat doar când înregistrarea trebuie obținută live.
meta.data_originX-Data-OriginCACHESNAPSHOTANAF
Căutările live ajută ulterior
Odată obținută și salvată, o înregistrare poate scuti cererile următoare de aceeași muncă.
Erorile sunt gândite, nu transmise
Când ANAF are probleme, API-ul poate returna o înregistrare disponibilă local în loc să transfere problema către aplicația care îl apelează.
05 / Tehnologii
Piese simple și de încredere.
Nimic exotic. Fiecare componentă are un singur rol în drumul unei căutări.
- API
- Go · chi
- Cache + limite de trafic
- Redis
- Snapshoturi
- PostgreSQL · sqlc · pgx · golang-migrate
- Contract
- OpenAPI
- Observabilitate
- OpenTelemetry
- SDK-uri
- TypeScript (@getcif/sdk) · PHP (getcif/sdk)
- Site-ul de documentație
- React · Vite · Tailwind CSS
- Implementare
- Docker · Traefik · Dokploy
06 / Stadiul actual
Live, documentat, intenționat mic.
Scopul este intenționat restrâns: acces de încredere la date utile despre firmele din România, cu suficient cache, proveniență și logică de rezervă pentru integrări mai puțin fragile.
- API
- Live la api.getcif.dev
- Documentație
- Engleză și română
- SDK-uri
- Node.js și PHP · 0.1.0