Integrare API intre doua platforme: ce trebuie stabilit inainte de dezvoltare

O integrare API intre doua platforme nu incepe cu endpointurile. Incepe cu o decizie mai importanta: ce sistem este sursa de adevar pentru fiecare tip de date, cine are voie sa le modifice, cand trebuie sincronizate si ce se intampla daca una dintre platforme nu raspunde.

1. Porneste de la procesul de business, nu de la API

Prima intrebare nu este „ce endpointuri are platforma?”, ci „ce problema trebuie sa dispara dupa integrare?”. Diferenta este importanta. Un API poate expune sute de operatii, dar proiectul poate avea nevoie doar de cinci dintre ele.

De exemplu, un magazin online conectat la un ERP poate avea un obiectiv simplu:

• produsele si preturile sunt administrate in ERP;
• stocul din ERP ajunge in magazin;
• comenzile plasate online ajung in ERP;
• statusul procesarii revine in magazin;
• clientul nu este creat de doua ori.

Aceasta descriere este deja mai valoroasa pentru arhitectura decat formularea „vrem integrare API ERP - magazin”. Ea spune ce date pleaca, unde ajung si care este sensul procesului.

Daca proiectul face parte dintr-un proces mai larg de eliminare a operatiunilor manuale, merita analizat mai intai ce procese repetitive din companie merita automatizate. Nu orice pas manual trebuie transformat automat intr-un schimb de date intre sisteme.

2. Stabileste exact ce date se transfera

„Sincronizam produsele” este prea vag pentru dezvoltare. Trebuie stabilite campurile concrete.

Pentru un produs, de exemplu, lista poate include:

• cod intern sau SKU;
• EAN;
• denumire;
• descriere;
• categorie;
• pret de lista;
• pret promotional;
• TVA;
• stoc disponibil;
• unitate de masura;
• status activ/inactiv;
• imagini.

Apoi, pentru fiecare camp trebuie raspuns la cateva intrebari simple: exista in ambele sisteme? Are acelasi format? Este obligatoriu? Poate fi gol? Cine il poate modifica? Ce se intampla daca valoarea primita este invalida?

Aici apar frecvent diferente care par mici, dar schimba implementarea. Un sistem poate stoca pretul cu TVA inclus, iar celalalt fara TVA. Unul poate folosi „activ/inactiv”, iar altul mai multe stari. O platforma poate lucra cu stoc pe depozit, alta doar cu un total general.

Documenteaza contractul de date

Pentru un API HTTP, o descriere formala a endpointurilor, parametrilor, schemelor si raspunsurilor reduce ambiguitatea. OpenAPI defineste un format standard, independent de limbajul de programare, pentru descrierea interfetei si semanticii unui API.

Chiar daca furnizorul nu ofera o specificatie OpenAPI, echipa care implementeaza integrarea ar trebui sa aiba macar un tabel de mapare cu campul sursa, campul destinatie, tipul de date, transformarile si regulile de validare.

3. Decide cine este sursa de adevar pentru fiecare informatie

Aceasta este una dintre cele mai importante decizii ale proiectului. Daca pretul poate fi modificat si in ERP, si in magazin, ce se intampla cand cele doua valori difera?

Pentru fiecare entitate sau chiar pentru fiecare camp trebuie sa existe o regula clara. Un exemplu:

Fara aceasta regula, o sincronizare bidirectionala poate deveni un ping-pong de actualizari: sistemul A modifica sistemul B, B considera modificarea noua si o trimite inapoi catre A.

4. Defineste identificatorii si maparea dintre sisteme

Doua platforme rareori folosesc aceleasi ID-uri interne. Clientul 815 din CRM poate fi clientul 27491 in ERP. Produsul cu ID 450 din magazin poate avea ID 9217 in gestiune.

De aceea, integrarea trebuie sa stabileasca identificatorul comun sau mecanismul de mapare.

Optiunile pot include un cod unic de produs, SKU, identificator fiscal pentru o companie sau o tabela dedicata de corespondenta intre ID-urile celor doua sisteme. Alegerea depinde de datele disponibile si de regulile de business.

Un caz care trebuie tratat explicit este schimbarea identificatorului. Daca un SKU poate fi editat ulterior, el nu mai este neaparat o cheie tehnica sigura pentru asocierea permanenta a produsului.

5. Stabileste directia sincronizarii

O integrare poate fi:

• unidirectionala - A trimite catre B;
• bidirectionala - A si B pot genera modificari;
• mixta - anumite date merg intr-o directie, altele in sens invers.

In practica, varianta mixta este frecventa. ERP-ul poate controla produsele si stocurile, in timp ce magazinul genereaza comenzile.

Sincronizarea bidirectionala trebuie justificata. Ea creste numarul de conflicte care trebuie rezolvate: cine castiga daca ambele sisteme modifica acelasi camp, cum sunt comparate datele modificarilor si ce se intampla daca unul dintre sisteme a lucrat offline?

6. Cum va fi autentificata integrarea?

Inainte de implementare trebuie cunoscuta metoda exacta acceptata de API: cheie API, credentiale dedicate, OAuth 2.0, certificate sau alta metoda definita de furnizor.

Autentificarea spune cine face cererea. Autorizarea stabileste ce are voie sa faca acel client. Sunt doua probleme diferite.

Pentru OAuth 2.0, recomandarile IETF actualizate in RFC 9700 includ masuri moderne de securitate precum PKCE pentru fluxurile relevante, protejarea tokenurilor si evitarea unor moduri de operare considerate nesigure. Alegerea mecanismului trebuie facuta conform capabilitatilor sistemelor conectate, nu prin copierea unei retete universale.

Indiferent de mecanism, este sanatos ca integrarea sa primeasca doar permisiunile necesare. Un serviciu care trebuie sa citeasca stocul nu are motiv sa poata sterge produse sau administra utilizatori.

Pentru o evaluare mai larga a suprafetei de atac, vezi si ce trebuie verificat la securitatea unei aplicatii web dincolo de certificatul SSL.

7. Webhooks, polling sau sincronizare programata?

Nu toate integrarile trebuie sa functioneze „in timp real”. Mai intai trebuie stabilit cat de repede trebuie sa ajunga informatia in sistemul destinatie.

Webhooks

Daca platforma sursa suporta webhooks, ea poate notifica sistemul destinatie atunci cand apare un eveniment: comanda noua, plata confirmata, stoc modificat sau document emis.

Avantajul este ca sistemul destinatie nu trebuie sa intrebe continuu daca s-a schimbat ceva. Dar webhookurile au nevoie de reguli clare pentru autentificarea sau verificarea mesajului, duplicate, livrari intarziate, ordinea evenimentelor si reluarea procesarii dupa erori.

Polling

Daca nu exista webhooks, integrarea poate interoga periodic API-ul. Aici trebuie stabilite frecventa si filtrarea. Este mult mai eficient sa soliciti „elementele modificate dupa ultima sincronizare” decat sa descarci intregul catalog la fiecare cateva minute, daca API-ul ofera aceasta posibilitate.

Sincronizare programata

Pentru date care nu necesita reactie imediata, un job programat poate fi suficient. De exemplu, anumite nomenclatoare pot fi actualizate o data pe zi, in timp ce comenzile necesita procesare mult mai rapida.

8. Verifica rate limits inainte sa alegi frecventa

Un API poate limita numarul de cereri acceptate intr-o perioada. HTTP defineste codul 429 Too Many Requests pentru situatiile in care un client a trimis prea multe solicitari intr-un interval.

De aceea, inainte de dezvoltare trebuie cunoscute:

• limita de cereri;
• daca limita este per cont, token, IP sau endpoint;
• dimensiunea maxima a unui raspuns;
• daca exista paginare;
• daca exista operatii batch;
• daca API-ul comunica momentul in care o cerere poate fi reluata.

HTTP permite folosirea antetului Retry-After pentru a indica perioada dupa care clientul ar trebui sa incerce din nou in anumite situatii. Integrarea trebuie sa respecte mecanismul furnizat de API, nu sa reia agresiv aceeasi cerere intr-o bucla.

9. Stabileste dinainte ce se intampla cand o cerere esueaza

Intr-o integrare reala vor exista erori: timeout, mentenanta, credentiale expirate, payload invalid, rate limit, date lipsa sau raspunsuri neasteptate.

Intrebarea corecta nu este daca vor aparea, ci cum revine integrarea la o stare corecta dupa eroare.

Retry nu inseamna repetare infinita

Pentru erorile temporare poate exista o politica de retry cu un numar limitat de incercari si pauze progresive. Pentru erori de validare, repetarea aceluiasi payload fara nicio modificare nu rezolva problema.

RFC 9110 face o distinctie importanta privind idempotenta. Metode precum PUT si DELETE sunt definite ca idempotente la nivelul efectului intentionat, in timp ce o cerere non-idempotenta nu ar trebui reluata automat fara o garantie ca repetarea este sigura sau fara un mecanism care poate determina daca operatia initiala a fost aplicata.

Idempotenta trebuie proiectata pentru operatiunile sensibile

Sa presupunem ca magazinul trimite o comanda catre ERP, dar conexiunea se intrerupe inainte de primirea raspunsului. Integrarea nu stie daca ERP-ul a creat sau nu comanda.

Daca retrimite pur si simplu aceeasi operatie, poate crea doua documente. O solutie este folosirea unui identificator extern unic sau a unui mecanism de idempotency oferit de API, astfel incat aceeasi operatie sa poata fi recunoscuta.

10. Logarea trebuie proiectata, nu adaugata dupa aparitia primei probleme

O integrare fara loguri bune poate functiona luni de zile, pana cand cineva intreaba de ce lipseste o comanda. Atunci devine dificil de stabilit daca sursa nu a trimis-o, API-ul a refuzat-o sau sistemul destinatie a procesat-o gresit.

Un jurnal operational util poate retine, dupa caz:

• identificatorul operatiei;
• sistemul sursa si destinatia;
• tipul evenimentului;
• data si ora;
• endpointul sau operatia executata;
• codul de raspuns;
• numarul incercarii;
• rezultatul procesarii;
• mesajul de eroare relevant;
• identificatorii obiectelor implicate.

Nu inseamna ca trebuie salvate integral toate payloadurile. Logarea trebuie proiectata si din perspectiva securitatii si a datelor personale: parolele, tokenurile, cheile API sau alte secrete nu ar trebui expuse in loguri.

11. Stabileste ce date personale trec dintr-un sistem in altul

Daca integrarea transfera date cu caracter personal, proiectarea tehnica trebuie corelata cu regulile aplicabile prelucrarii. GDPR stabileste, printre altele, principii de limitare la scop, minimizare a datelor, exactitate, limitare a stocarii si integritate si confidentialitate.

Practic, echipa trebuie sa poata raspunde la intrebari precum:

• ce date personale sunt realmente necesare destinatiei;
• de ce sunt transferate;
• cine poate avea acces la ele;
• cat timp sunt pastrate;
• ce se intampla cu actualizarile si stergerile;
• ce date apar in logurile tehnice;
• cine raspunde operational pentru fiecare sistem.

Nu este eficient sa trimiti automat toate campurile disponibile doar pentru ca API-ul le expune. Pe langa complexitate, creste inutil cantitatea de date pe care integrarea trebuie sa o protejeze si sa o mentina corecta.

12. Cine raspunde cand integrarea se opreste?

Un proiect de integrare are de obicei cel putin trei componente: sistemul A, sistemul B si codul care le conecteaza. Uneori sunt implicati trei furnizori diferiti.

Inainte de lansare trebuie stabilit:

• cine furnizeaza documentatia API;
• cine emite si roteste credentialele;
• cine anunta modificarile API;
• cine verifica incidentele;
• cine poate relansa o sincronizare;
• cine corecteaza datele invalide;
• cine raspunde pentru modificarile din fiecare platforma;
• cum este tratata schimbarea unei versiuni de API.

OWASP include gestionarea deficitara a inventarului API si consumul nesigur al API-urilor terte intre riscurile importante pentru API-uri. Asta face relevante documentarea versiunilor, a endpointurilor active si a dependintelor externe, nu doar codul propriu-zis.

13. Testeaza scenariile neplacute, nu doar cazul ideal

Un test in care o comanda valida trece din A in B demonstreaza prea putin. Integrarea trebuie verificata si cand apar conditii neasteptate.

Un plan realist de testare poate include:

• produs inexistent in destinatie;
• SKU duplicat;
• camp obligatoriu lipsa;
• valoare intr-un format neacceptat;
• token expirat;
• raspuns 401 sau 403;
• raspuns 429;
• timeout;
• raspuns 500/503;
• retrimis acelasi eveniment de doua ori;
• evenimente primite in alta ordine;
• sistem destinatie indisponibil timp de cateva ore;
• reluarea sincronizarii dupa revenire.

Ideal, furnizorul API ofera un mediu sandbox sau de test. Daca nu exista, trebuie stabilita o strategie prin care testele sa nu genereze documente, clienti sau tranzactii reale nedorite.

Exemplu: ERP + magazin online + sistem de facturare

Sa luam o companie in care produsele sunt administrate intr-un ERP, comenzile sunt plasate intr-un magazin online, iar facturile sunt emise printr-o alta platforma.

Un flux coerent ar putea fi proiectat astfel:

1. ERP-ul ramane sursa de adevar pentru produse, preturi si stoc.
2. Magazinul primeste periodic modificarile sau este notificat cand acestea apar.
3. Comanda este creata in magazin cu un identificator unic.
4. Integrarea trimite comanda in ERP si pastreaza asocierea dintre ID-uri.
5. ERP-ul valideaza stocul si comanda.
6. La momentul definit de procesul firmei, datele necesare documentului sunt trimise sistemului de facturare.
7. Numarul si statusul documentului sunt salvate inapoi unde sunt necesare.
8. Orice eroare ramane vizibila intr-un jurnal si poate fi reluata controlat.

Observatia importanta este ca „integrarea” nu este o singura cerere API. Este un flux cu stare, reguli de business, dependinte si mecanisme de recuperare.

14. Greseli frecvente in proiectele de integrare

• Se incepe dezvoltarea fara o matrice de date. Echipa descopera in timpul implementarii ca aceleasi campuri au semnificatii diferite.
• Nu este definita sursa de adevar. Doua sisteme ajung sa se suprascrie reciproc.
• Se presupune ca orice eroare trebuie retrimisa. Un payload invalid va ramane invalid si dupa zece incercari.
• Se trateaza webhooks ca livrare garantata o singura data. Integrarea nu este pregatita pentru duplicate sau ordine diferita a evenimentelor.
• Se folosesc credentiale cu acces prea larg. Integrarea primeste drepturi pe care nu le necesita.
• Nu exista loguri operationale. Problemele sunt descoperite de utilizatori, dar cauza nu poate fi reconstruita.
• Se ignora limitele API. Un proces aparent corect functioneaza la 100 de produse, dar cade la 100.000.
• Nu este stabilit cine mentine integrarea dupa lansare. Prima schimbare de API transforma o problema previzibila intr-o urgenta.

15. Checklist: ce trebuie stabilit inainte sa inceapa dezvoltarea

Ce informatii sunt necesare pentru o estimare corecta?

Costul si durata unei integrari nu pot fi evaluate serios doar din propozitia „avem doua API-uri”. Diferenta dintre un import zilnic de produse si o sincronizare bidirectionala pentru produse, stocuri, clienti, comenzi, facturi si statusuri poate fi substantiala.

Pentru o analiza tehnica sunt utile:

• documentatia ambelor API-uri;
• lista fluxurilor dorite;
• exemple de request si response;
• metoda de autentificare;
• restrictiile API si limitele de utilizare;
• volumele aproximative de date;
• frecventa necesara a sincronizarii;
• regulile de business care nu apar in documentatia API;
• acces la un mediu de test, daca exista.

Daca ai un ERP, CRM, magazin online, sistem de facturare sau alta platforma pe care vrei sa o conectezi, serviciul de integrari API intre platforme de business poate porni de la analiza fluxurilor si a documentatiei existente, inainte de estimarea implementarii.

Integrarea nu se termina in ziua lansarii

API-urile evolueaza. Pot aparea versiuni noi, endpointuri depreciate, permisiuni schimbate, certificate sau secrete care expira si modificari ale structurii datelor.

De aceea, proiectul ar trebui sa prevada cine urmareste functionarea integrarii si cum sunt aplicate actualizarile. Pentru sisteme importante operational, acest aspect poate fi inclus intr-un plan de mentenanta a aplicatiei si integrarilor.

Concluzie

O integrare API buna nu este definita de numarul de endpointuri folosite, ci de predictibilitatea fluxului. Trebuie sa fie clar cine creeaza datele, cine le modifica, cum sunt identificate, cand circula, cum sunt protejate si cum revine sistemul dupa o eroare.

Cele mai scumpe probleme se previn inainte de prima linie de cod: printr-un contract de date clar, o sursa de adevar bine stabilita si scenarii explicite pentru erori, duplicate si indisponibilitate.