Ce este API - explicat simplu pentru non-tehnici (cu exemple practice)

Dacă ai o firmă mică și ai discutat vreodată cu un dezvoltator, ai auzit cuvântul API. Probabil ți s-a spus că „are nevoie de API-ul lor", „integrarea se face prin API" sau „API-ul ANAF e nasol". Sună complicat, dar conceptul este simplu - și înțelegerea lui te ajută să iei decizii mai bune când cumperi software, când angajezi un freelancer sau când evaluezi un SaaS.

În termeni simpli: un API este modul în care două programe vorbesc între ele. Nu trebuie să scrii cod ca să înțelegi cum funcționează, așa cum nu trebuie să fii mecanic ca să conduci o mașină. Dar dacă știi că există direcție asistată, ABS și airbag, faci alegeri informate când cumperi.

Acest ghid îți explică API-ul fără jargon, cu analogii din viața reală, exemple pentru o firmă din România și capcanele de securitate. Pentru context, citește și ce este cloud computing pentru IMM și SaaS vs on-premise.

Ce este un API - analogia chelnerului

Imaginează-ți un restaurant. Tu, clientul, stai la masă cu meniul. În spate este bucătăria, unde se gătește. Tu nu intri niciodată acolo. Comunici cu bucătăria prin chelner: el cunoaște meniul (lista de comenzi permise), limbajul (cum scrie comanda pe bon) și aduce înapoi rezultatul (mâncarea) sau o eroare („nu mai avem somon"). Tu nu trebuie să știi cum funcționează bucătăria, bucătăria nu trebuie să știe cine ești tu.

API-ul este exact acel chelner, doar că între două programe. Aplicația ta (de exemplu, magazinul tău WooCommerce) este clientul. Serverul ANAF e-Factura este bucătăria. API-ul ANAF este chelnerul: îți spune ce comenzi poți trimite (upload factură, descarcă răspuns, verifică status), în ce format (XML cu schema strictă) și ce primești înapoi.

Pe scurt: Application Programming Interface = interfața standardizată prin care un program poate cere ceva de la alt program, fără să știe cum funcționează intern celălalt. Mai există o analogie utilă: priza electrică. Nu știi cum funcționează centrala hidroelectrică, dar pui ștecherul în priză și aspiratorul merge. Priza este un API: o interfață standardizată (forma, voltajul, frecvența) care îți dă acces la un serviciu fără să înțelegi infrastructura din spate.

Cum funcționează concret - request și response

Orice API funcționează în cicluri request - response: aplicația ta trimite o cerere, serverul răspunde. Toată complexitatea aparentă vine din câte tipuri de cereri există și câte formate pentru date.

Un request are 4 componente: metodă HTTP (GET, POST, PUT, DELETE, PATCH), endpoint (URL, ex. https://api.smartbill.ro/invoice/), headers (inclusiv autentificarea și Content-Type: application/json), body opțional (datele în JSON).

Un response are 3 componente: status code (numărul HTTP care îți spune în secunda 1 dacă a mers), headers (format, rate limit rămas), body (datele sau mesajul de eroare, în JSON).

Codurile HTTP - cele 7 pe care trebuie să le recunoști

Regula mnemonică: 2xx = bine, 4xx = vina ta, 5xx = vina lor. Dacă vezi 401 sau 403, problema e la setup-ul tău. Dacă vezi 500 sau 503, raportezi la provider.

JSON - formatul universal

Datele se transmit aproape întotdeauna în JSON (JavaScript Object Notation). E format text, citibil de oameni:

{
  "factura": {
    "numar": "F0001",
    "data": "2026-06-01",
    "client": {
      "nume": "SC Exemplu SRL",
      "cui": "RO12345678"
    },
    "total": 1190.00,
    "moneda": "RON"
  }
}

XML mai există în lumea enterprise legacy (ANAF e-Factura folosește UBL XML conform standardului european), dar pentru API-uri moderne, JSON este standard de facto.

Tipurile de API - care contează pentru tine

Există mai multe „dialecte" pentru API-uri. Nu trebuie să le știi pe toate, dar e util să recunoști numele când le auzi.

Pentru 95% dintre IMM-uri, vei lucra exclusiv cu REST API. Dacă cineva îți vinde „integrare GraphQL revoluționară" pentru un magazin online cu 200 produse, e overengineering. REST face treaba.

Verbele HTTP - ce poți cere

REST API folosește metodele HTTP ca verbe pentru acțiuni:

În termeni simpli: GET = citește, POST = creează, PUT/PATCH = modifică, DELETE = șterge. Asta e tot. Dacă înțelegi astea 5 verbe, înțelegi 80% din cum se folosește un REST API.

Autentificare - cum dovedești că ești tu

Niciun API serios nu îți dă acces fără autentificare. Sunt 4 metode uzuale, fiecare cu locul ei:

1. API Key (cea mai simplă)

Un șir lung de caractere generat de provider, ex. sk_live_4eC39HqLyjWDarjtT1zdp7dc. Îl trimiți în header la fiecare request:

Authorization: Bearer sk_live_4eC39HqLyjWDarjtT1zdp7dc

Când: integrări server-to-server (backend-ul tău vorbește cu SmartBill, Stripe, OpenAI). Simplu, dar dacă cineva îți fură cheia, are acces total.

2. OAuth 2.0 (standard pentru aplicații third-party)

Folosit când aplicația ta vrea să acceseze contul unui utilizator pe alt serviciu - ex. „conectează-te cu Google" sau „postează pe Facebook în numele meu". Flow-ul: utilizatorul e redirectat la Google, aprobă permisiunile, Google îți dă un token de acces.

Când: integrări cu Google Workspace, Microsoft 365, Facebook, LinkedIn, GitHub - oriunde un utilizator final trebuie să-și dea acordul.

3. JWT (JSON Web Token)

Un token semnat criptografic care conține informații despre utilizator (cine este, ce permisiuni are, când expiră). Server-ul îl validează matematic fără să consulte o bază de date.

Când: API-uri proprii pentru aplicații mobile sau SPA-uri web, autentificare modernă scalabilă.

4. Basic Auth (învechit, evită)

Username + parolă codate Base64 în header. Trade-off: simplu, dar parola circulă cu fiecare request. Acceptabil doar peste HTTPS și pentru API-uri interne low-stakes. Niciodată pentru integrări production cu date sensibile.

Webhook vs polling - push vs pull

Sunt două modalități prin care aplicația ta poate fi informată despre evenimente la un serviciu extern:

Polling (pull): aplicația ta întreabă serverul la fiecare X minute „s-a întâmplat ceva nou?". Ineficient (cereri inutile când nu e nimic) și lent (afli cu întârziere). E ca și cum ai suna restaurantul la fiecare 5 minute „e gata mâncarea?".

Webhook (push): aplicația ta înregistrează un URL la server, iar serverul îți face POST la URL când apare un eveniment. Eficient, real-time. Restaurantul te sună el când e gata mâncarea.

Exemple practice:

• Stripe webhook: Stripe îți face POST la https://magazinultau.ro/webhook/stripe când o plată reușește, eșuează sau e returnată. Nu trebuie să întrebi tu.
• GitHub webhook: când cineva face push în repo, GitHub anunță serverul tău de deploy.
• WhatsApp Business: când un client trimite mesaj, Meta îți face POST cu conținutul.

Setup minim webhook: expui un endpoint public HTTPS, înregistrezi URL-ul la provider, validezi că request-urile vin chiar de la provider (signature verification). Aici nu se sare peste validare - oricine poate trimite POST la URL-ul tău public, vrei să accepți doar request-urile reale.

Rate limiting - de ce apare 429

Niciun API nu te lasă să trimiți request-uri nelimitate. Toate impun rate limits: maxim X cereri pe minut/oră/zi. Asta protejează serverul de abuz și asigură fair use între clienți.

Exemple tipice:

• Stripe: 100 read + 100 write per secundă în production.
• OpenAI GPT-4: 10.000 tokens/minut pentru tier 1, scale-up cu utilizare.
• WhatsApp Business: tier 1 = 1.000 mesaje/zi, scale automat la engagement bun.
• ANAF e-Factura: limite mai stricte, recomandat batch processing nocturn.

Când depășești, primești HTTP 429 Too Many Requests și de obicei un header Retry-After: 60 care îți spune când să încerci din nou.

Pro tip dev: implementează exponential backoff - dacă primești 429, așteaptă 1 secundă, retry. Dacă iar 429, așteaptă 2 secunde, apoi 4, 8, 16. Nu da retry imediat în loop infinit, vei fi banat și mai tare.

Exemple practice pentru un IMM din România

Suficientă teorie. Iată ce API-uri folosește efectiv o firmă mică din România în 2026:

• ANAF e-Factura (SPV) - obligatoriu B2B/B2G și B2C. Acceptă upload factură UBL XML, returnează număr de înregistrare. Autentificare cu certificat digital. Majoritatea firmelor folosesc intermediar (SmartBill, FGO, Oblio); integrare directă merită peste 500 facturi/lună. Vezi ce este e-Factura.
• SmartBill / FGO / Oblio (facturare) - API REST clasic, API key + username. Creare facturi, listare clienți, sincronizare stocuri, PDF-uri. Caz tipic: WooCommerce → SmartBill → ANAF.
• Stripe / Netopia / Mobilpay (plăți) - REST cu webhook pentru evenimente (plată reușită, refund, dispute). Cardul nu trece prin serverul tău, doar token-ul (PCI-DSS simplificat).
• Google Maps API (curierat, AWB) - rute optime, autocomplete adrese, calcul distanțe. Free tier 200 $/lună acoperă majoritatea IMM-urilor.
• WhatsApp Business API - mesaje tranzacționale (confirmare comandă, AWB, livrare). Cost per mesaj template (~0,02 EUR/mesaj RO categoria utility). ROI imens vs SMS.
• OpenAI / Anthropic API - chatbot suport, sumarizare email-uri, clasificare ticket-uri, descrieri produse. Cost per token. Atenție: un script prost poate genera factură de 500 EUR în câteva ore - setezi spending limit.

Costuri - free tier vs metered

API-urile au modele de pricing tipice: complet free (rar, ex. BNR curs valutar), free tier + paid scale (Google Maps 200 $/lună free, SendGrid 100 emails/zi free), metered pur per call sau token (OpenAI, Stripe), subscription lunar fix.

Trade-off: free tier validează ideea. Production cu trafic real ajunge rapid pe plătit. Calculează costul așteptat înainte să lansezi - simulează 10x volumul actual ca să eviți surprize.

Documentația API și tools de test

Documentația bună are structură standard: Authentication (cum obții API key), Base URL, Endpoints (resurse disponibile), Request parameters (ce trimiți, ce e obligatoriu), Response schema (ce primești), Examples (copy-paste ready), Error codes specifice, Rate limits, Changelog.

RTFM (citește docs oficiale): 80% din problemele cu API-uri se rezolvă la prima citire atentă a documentației, nu pe Stack Overflow.

Pentru testare înainte de implementare, folosești unelte dedicate:

• Postman - desktop și web, cea mai populară. Salvezi colecții de request-uri, le rulezi în batch.
• Insomnia - alternativă open-source (Kong), mai simplă.
• curl - utilitar command line preinstalat pe Mac/Linux. Ex: curl -X GET https://api.exemplu.ro/facturi -H "Authorization: Bearer KEY".
• HTTPie - alternativă curl cu sintaxă mai prietenoasă, output colorat.

Workflow tipic: copiezi exemplul curl din docs, îl lipești în Postman, înlocuiești API key-ul, Send. Iterezi până înțelegi endpoint-ul, apoi implementezi integrarea reală.

Greșeli frecvente și cum le eviți

• API keys în cod commitat pe Git - cel mai distructiv. Folosește .env + .gitignore.
• Lipsa retry logic - implementează exponential backoff pentru 429, 500, 503.
• Logging cu API keys vizibile - filtrezi log-urile înainte să le trimiți la Sentry/Datadog.
• Ignorarea webhook signature validation - oricine poate face POST la URL-ul tău public.
• Hardcoding URL-uri - folosește variabile de mediu pentru a schimba între dev/staging/production.
• Polling agresiv în loc de webhook - dacă provider-ul oferă webhook, folosește-l. Polling la 1 secundă te aduce la 429 sau ban.

Întrebări frecvente

Trebuie să știu să programez ca să folosesc un API?

Pentru a-l înțelege și a discuta informat cu echipa - nu. Pentru a-l implementa - da, sau folosești unelte no-code (Make, n8n, Zapier) care abstractizează cod-ul. Un antreprenor care înțelege API-ul ia decizii mai bune când alege software și când angajează dezvoltatori.

Care e diferența dintre API și SDK?

API este interfața (contractul - ce poți cere). SDK (Software Development Kit) este o bibliotecă în limbajul tău de programare care face request-urile pentru tine, cu funcții prietenoase. Ex. SDK-ul Stripe pentru PHP îți oferă Stripe\Charge::create([...]) în loc să faci tu manual request HTTP.

API-ul ANAF e cu adevărat „nasol"?

Da, din motive structurale: documentație fragmentată, validare strictă XML, autentificare cu certificat digital complicată, ferestre de mentenanță fără preaviz. Soluția pentru majoritatea IMM-urilor: software intermediar (SmartBill, FGO, Oblio) care abstractizează durerea. Integrare directă merită doar peste 500 facturi/lună sau dacă ai ERP custom.

Cât costă să integrez 2-3 API-uri în magazinul meu online?

Pentru un freelancer competent: 800-2.500 EUR pentru integrare simplă (ex. WooCommerce → SmartBill → WhatsApp), 3.000-8.000 EUR pentru ceva mai complex. Plus costuri lunare API (50-300 EUR/lună tipic pentru un magazin matur). Vezi și cum se configurează email pentru firmă în RO.

Cum aleg între REST și GraphQL pentru un proiect nou?

It depends - context matters. REST = ales implicit, ecosistem matur, ușor de cache-uit, toți dezvoltatorii îl știu. GraphQL = ales când ai aplicație mobilă care vrea date specifice cu un singur request, sau când ai multe relații între entități și REST devine chatty. Pentru 90% din magazine online, REST e răspunsul corect.

Cât de des se schimbă un API public?

Provider-ii serioși versionează (/v1/, /v2/) și anunță cu 6-12 luni înainte deprecation-uri. Stripe, Google, AWS dau preaviz lung. Provider-ii mici pot face breaking changes peste noapte - verifici changelog-ul lunar dacă integrarea e critică.

Concluzie

API-ul este interfața standardizată care permite două aplicații să vorbească între ele, fără să se cunoască intern. Conceptul este la fel de simplu ca priza electrică sau chelnerul de restaurant - complexitatea aparentă vine din volumul de detalii tehnice, nu din ideea de bază.

Pentru un antreprenor non-tehnic, înțelegerea API-ului la nivel conceptual aduce 3 beneficii directe: iei decizii mai bune când cumperi software (întrebi „are API public documentat?"), discuți competent cu dezvoltatori (nu te mai poate prosti cineva cu jargon) și recunoști oportunități de automatizare (orice flux manual repetitiv între 2 aplicații e candidat la integrare).

Setup minim pentru IMM: alege software cu API public, implementează 2-3 integrări critice (facturare, plăți, notificări), păstrează API keys în secrets manager, monitorizează costurile lunare. Pentru context complementar, ce este SaaS vs on-premise și ce este cloud computing pentru IMM formează împreună fundamentul vocabularului tehnic modern.

Surse

• developer.mozilla.org/en-US/docs/Web/HTTP - documentația MDN HTTP, autoritativă pentru status codes și metode
• restfulapi.net - principii REST, ghid pentru începători
• stripe.com/docs/api - exemplu de documentație API exemplară
• smartbill.ro/api - documentație SmartBill API pentru integrări RO
• mfinante.gov.ro - portalul ANAF cu informații e-Factura și acces SPV
• swagger.io/specification - OpenAPI Specification, standardul de documentare API
• oauth.net/2 - documentație oficială OAuth 2.0
• jwt.io - introducere JWT cu debugger online