Soluții

Șase feluri de a folosi date pe care nu le întreții.

Orice set de date, oricât de diferit ar fi conținutul lui, ajunge să facă în produsul tău unul din câteva lucruri: să confirme, să sugereze, să completeze, să calculeze, să grupeze sau să spună cum era înainte.

Pagina asta e despre acele șase forme. Ce set de date le rezolvă în cazul tău alegi din catalog.

Anatomia oricărui răspunsidentică în tot catalogul
GET /{modul}/v1/{resursă}?pagina=1
Authorization: Bearer …

{
  "data":  // singurul lucru care diferă între seturi
  "meta":  // total, paginare, vechimea datelor
  "links": // pagina următoare, dacă există
}
Ce înveți o singură dată
Autentificareun singur token
Formatul eroriiacelași peste tot
Paginareaceiași parametri
Limiteîn headere
Versionareper modul
Modul nouzero cod nou
01 Ce rezolvi

Șase forme. Restul sunt combinații.

Se aplică oricărui set din catalog și oricăruia dintre cele care vor urma. Dacă recunoști una dintre ele în produsul tău, ai deja cazul de utilizare.

A Validare

Confirmi că o valoare introdusă de utilizator există cu adevărat în setul oficial și e ceea ce pretinde. Verificarea se face la introducere, când corectarea costă un clic — nu mai târziu, când costă altceva.

B Sugestie

Câmpul propune rezultate în timp ce utilizatorul tastează, dintr-un set oficial, nu dintr-o listă statică ținută local. Ce ajunge în baza ta e o valoare aleasă dintr-o mulțime închisă, nu text liber.

C Completare

Un singur identificator introdus aduce restul informațiilor. Utilizatorul tastează mai puțin, datele intră scrise corect de la început, iar tu nu mai cureți în aval ce s-a introdus greșit în amonte.

D Calcul

Uneori nu ai nevoie de înregistrare, ci de rezultat. Răspunsul vine deja calculat, cu regulile aplicate corect, ca să nu reimplementezi o logică pe care ar trebui apoi s-o ții la zi.

E Grupare

Rapoartele se construiesc pe coduri stabile, nu pe denumiri scrise de mână. Trei variante de scriere ale aceluiași lucru ajung în același rând, pentru că nu mai compari șiruri de caractere.

F Interogare în timp

Nu doar cum e acum, ci cum era la o dată anume. Pentru orice decizie care trebuie justificată ulterior, întrebarea corectă e ce era valabil atunci, nu ce e valabil azi.

Modificator

Oricare dintre ele, în masă.

Trimiți multe valori într-un singur apel, în loc de un apel pentru fiecare. Un job programat care trece toată baza ta prin catalog costă zeci de requesturi, nu zeci de mii — de aici vine diferența dintre o verificare lunară și una zilnică.

02 Compunere

Un răspuns util e, de obicei, două apeluri.

Seturile sunt independente, dar se leagă prin coduri. Un rezultat devine parametrul următorului apel, iar întrebarea reală primește răspuns fără să ții nimic local.

1 setul A

Întrebi setul care conține identificatorul

Primești înregistrarea completă, cu toate câmpurile ei — inclusiv codurile prin care e legată de alte seturi.

GET /{modul-a}/v1/{resursă}/{id}
2 din răspuns

Iei codul de legătură din răspuns

E un câmp obișnuit, documentat în schema modulului. Nu trebuie construit, ghicit sau normalizat.

"data": { …, "cod_legatura": … }
3 setul B · din cache

Îl folosești ca parametru în al doilea set

Al doilea apel e aproape întotdeauna servit din cache, deci costul real al compunerii e neglijabil.

GET /{modul-b}/v1/{resursă}?cod=…
De ce contează

Fără compunere ai avea două integrări care nu-și vorbesc și ar trebui să construiești tu puntea dintre ele — exact munca pe care încerci s-o eviți.

Nu e obligatorie

Poți folosi un singur set și ignora restul catalogului; nimic nu te forțează să adopți mai mult decât ai nevoie. Dar când ai nevoie, legătura există deja.

Ai un lanț care nu ți-e clar? Scrie-ne ce încerci să afli și îți trimitem varianta cea mai ieftină în requesturi.

Întreabă-ne
03 Pentru cine

Echipe care depind de date întreținute de altcineva.

Aceleași șase forme, văzute din unghiul câtorva feluri de produse.

Software de business

Câmpurile se completează din identificator, iar ce introduce utilizatorul e confirmat înainte să ajungă într-un document.

Completare Validare
Comerț online și marketplace

Valori alese din sugestii în loc de tastate liber: mai puține comenzi blocate și rapoarte fără curățare manuală.

Sugestie Grupare
Servicii financiare

Verificare la înrolare, calcule pe date oficiale și posibilitatea de a arăta ce era valabil în momentul deciziei.

Validare Interogare în timp
Logistică și operațiuni

Valori normalizate pe coduri stabile înainte de planificare, agregări pe aceeași ierarhie oficială ca rapoartele.

Grupare Validare
Aplicații pentru consumatori

O căutare, o sugestie, un total calculat — funcții simple care se sprijină pe un set pe care nimeni nu vrea să-l întrețină.

Sugestie Calcul
Echipe de date și analiză

Dimensiuni gata normalizate pentru warehouse, cu coduri care nu se schimbă între rulări. Join-uri reproductibile.

Grupare Interogare în timp
Integratori și agenții

Un singur strat de integrare, refolosit la toți clienții. Versionarea per modul face ca un upgrade să nu atingă restul.

Toate șase
Care set de date rezolvă cazul tău?

Fiecare modul are pagina lui, cu endpointurile, schema și cazurile specifice.

Vezi catalogul →
04 Costul real

Costul nu e integrarea. E întreținerea.

Un import se scrie într-o după-amiază. Problema începe în luna a patra, când sursa își schimbă formatul într-o vineri seara.

Cu import propriucost recurent
Un cron care descarcă un fișier și speră că formatul n-a fost schimbat.
Cod de normalizare scris de două ori, în două locuri, ușor diferit.
Limitele sursei, gestionate cu pauze fixe și degete încrucișate.
Un tabel local care rămâne în urmă după fiecare modificare din amonte.
Nicio urmă a ce valoare avea un câmp acum șase luni.
Un coleg care „știe cum merge importul” și e în concediu.
Cu oneapio integrare
Un client HTTP și un token. Fără SDK obligatoriu.
Datele ajung normalizate înainte să le atingi.
Limita, restul și momentul resetării, în headere, la fiecare răspuns.
Modificările din amonte apar în changelog, nu într-un incident de producție.
Istoricul e o interogare, nu ceva ce trebuia să fi salvat tu.
Contractul e documentat public. Oricine din echipă îl poate citi.
Milisecunde

Majoritatea răspunsurilor vin din cache, nu din baza de date.

304

Cu validare condiționată nu consumi din cotă dacă datele n-au variat.

12 luni

Cât rămâne activă o versiune veche de modul, minimum, după anunț.

05 Integrare

Un token și clientul HTTP pe care îl ai deja.

Nu instalezi nimic. Dacă vrei un client tipat, îl generezi din specificația OpenAPI a modulului, în limbajul tău.

# orice modul, aceeași formă
curl "https://oneapi.ro/api/{modul}/v1/{resursă}" \
  -H "Authorization: Bearer $ONEAPI_TOKEN" \
  -H "Accept: application/json"

# a doua oară, fără consum din cotă
curl "https://oneapi.ro/api/{modul}/v1/{resursă}" \
  -H "Authorization: Bearer $ONEAPI_TOKEN" \
  -H 'If-None-Match: "a3f9c1e0"'
# → 304 Not Modified
use Illuminate\Support\Facades\Http;

// un singur client, refolosit pentru toate modulele
$oneapi = Http::baseUrl('https://oneapi.ro/api')
    ->withToken(config('services.oneapi.token'))
    ->acceptJson()
    ->retry(2, 200);

$rezultat = $oneapi
    ->get("/{$modul}/v1/{$resursa}", ['pagina' => 1])
    ->throw()
    ->json('data');
const oneapi = async (path, init = {}) => {
  const res = await fetch(`https://oneapi.ro/api${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.ONEAPI_TOKEN}`,
      Accept: 'application/json',
      ...init.headers,
    },
  });
  // aceeași tratare a limitei, oricare ar fi modulul
  if (res.status === 429) {
    const asteapta = Number(res.headers.get('Retry-After')) * 1000;
    await new Promise((r) => setTimeout(r, asteapta));
    return oneapi(path, init);
  }
  return res.json();
};
import os
import httpx

client = httpx.Client(
    base_url="https://oneapi.ro/api",
    headers={"Authorization": f"Bearer {os.environ['ONEAPI_TOKEN']}"},
    timeout=5.0,
)

# aceeași funcție, orice modul
def ia(modul: str, resursa: str, **params) -> list:
    r = client.get(f"/{modul}/v1/{resursa}", params=params)
    r.raise_for_status()
    return r.json()["data"]
Când ceva nu merge

O singură formă de eroare, în tot catalogul.

Codul e stabil și documentat, mesajul e pentru om, câmpul îți spune ce parametru să corectezi, iar identificatorul cererii e ce ne trimiți nouă dacă ai nevoie de ajutor.

HTTP/1.1 422 Unprocessable Content
{ "error": {
    "cod": "parametru_invalid",
    "mesaj": "Valoarea nu e acceptată.",
    "camp": "…",
    "request_id": "req_01JZQ8M2"
} }
06 Întrebări

Înainte să scrii primul request.

Restul, în întrebări frecvente și în documentație.

Da. Consolele din paginile de modul rulează cereri reale, fără autentificare, cu o limită mică pe minut. Pentru volum real ai nevoie de un token, iar planul gratuit nu cere card.

De la cont nou la primul răspuns, în câteva minute. 3.000 de requesturi pe lună, tot catalogul, fără card.
Generează un token Vezi documentația