Vodič za API integracije
API integracija poslovnih sustava: što dogovoriti prije izrade
API integracija povezuje dogovorene radnje i podatke između programa. Za njezinu pripremu navedite koji događaj pokreće prijenos, koji sustav određuje ispravan podatak i što se događa kad prijenos nije potvrđen. Tek tada ima smisla procjenjivati izradu konektora, testiranje i održavanje.
Krenite od jednog toka podataka
Primjerice, želite da narudžba iz web trgovine stigne u ERP. Radni zadatak uključuje i odgovore na manje vidljiva pitanja: je li kupac već evidentiran, smije li se promijeniti adresa te hoće li ponovni pokušaj napraviti još jednu narudžbu. Upravo ta pravila trebaju ući u ponudu.
Umjesto zahtjeva „povežite sve”, opišite jedan događaj od početka do završne provjere. To može biti potvrđena narudžba, promjena kontakta ili završetak radnog naloga.
Za početni opseg odgovorite:
- Gdje zapis nastaje i u kojem je trenutku spreman za prijenos?
- Koji se podaci prenose i u kojem smjeru?
- Treba li drugi sustav samo primiti zapis ili i vratiti potvrdu i identifikator?
- Koliko je kašnjenje prihvatljivo za poslovanje?
- Tko postupa ako se prijenos ne može dovršiti?
Narudžbe i zalihe ne moraju imati isti ritam ažuriranja. Ako definirate prihvatljivo kašnjenje za svaki tok, izvođač može provjeriti zadovoljava li ga postojeće sučelje. Izraz „u stvarnom vremenu” bez tog dogovora ostavlja previše prostora za različita očekivanja.
Koji je sustav izvor istine za pojedini podatak?
Odredite gdje se podatak smije promijeniti i koja verzija vrijedi kada se programi razlikuju. Jedan sustav ne mora biti glavni za sve: CRM može voditi prodajni kontakt, ERP šifru artikla, a web trgovina sadržaj prikaza proizvoda.
Microsoftov obrazac za povezivanje različitih modela podataka objašnjava zašto se među sustavima prevode značenja i strukture. Za poslovni dogovor dovoljno je krenuti od tablice polja; zasebna složena infrastruktura nije automatski potrebna.
Sljedeća tablica je ilustrativan dogovor za zamišljenu web trgovinu i ERP, a ne opis već izvedene Novero integracije.
| Podatak | Dogovoreni izvor | Pravilo prijenosa ili sukoba |
|---|---|---|
| Broj narudžbe u trgovini | Web trgovina | Sprema se i u ERP radi povezivanja zapisa. |
| Šifra artikla | ERP | Nepoznata šifra zaustavlja stavku za provjeru. |
| Adresa za konkretnu isporuku | Potvrđena narudžba | Ne prepisuje automatski sve postojeće adrese kupca. |
| Status otpreme | ERP | Vraća se u trgovinu prema dogovorenim statusima. |
| Identifikator narudžbe u ERP-u | ERP | Veže se uz izvornu narudžbu radi provjere i kasnijih promjena. |
Za svako polje provjerite format, obveznost, jedinicu i dopuštene vrijednosti. „Komad” i „paket”, prazno polje i nula ili datum i trenutak događaja mogu imati različito poslovno značenje. Pravilo za nepoznatu vrijednost treba biti zapisano prije prvog uvoza.
Postoji li pristup baš onim radnjama koje trebate?
Prije procjene zatražite aktualnu dokumentaciju, testno okruženje i potvrdu dostupnih operacija. Mogućnost čitanja kupaca ne znači da ih API dopušta stvarati ili mijenjati. Provjerite i ovisi li pristup o paketu, dozvoli dobavljača ili dodatnoj konfiguraciji.
Popis provjera treba obuhvatiti verziju sučelja, ograničenja poziva, način prijave, obvezna polja i dostupne statuse. Ako gotov konektor pokriva tražene radnje, usporedite ga s izradom po mjeri prije narudžbe novog razvoja.
Ovlasti su zasebna provjera. OWASP upozorava na potrebu provjere pristupa konkretnom zapisu i radnji. U testiranju zato provjerite i da korisnik ili integracijski račun ne može dohvatiti tuđe podatke promjenom identifikatora.
Dogovorite tko izdaje i obnavlja pristupne podatke. U primjere zahtjeva i zapise za podršku nemojte stavljati aktivne tajne ili nepotrebne osobne podatke.
Što nakon prekida veze ili ponovljene poruke?
Zamišljeni scenarij: ERP spremi narudžbu, ali odgovor ne stigne do trgovine. Trgovina tada ne zna je li predaja uspjela. Slijepo ponovno stvaranje narudžbe može napraviti duplikat.
Microsoftove upute o ponavljanju zahtjeva razlikuju privremene poteškoće od drugih pogrešaka te upozoravaju na ponovljeno izvršavanje radnje. Zato automatsko ponavljanje ugovorite prema ponašanju konkretnog API-ja.
Idempotentnost ovisi o ugovoru sučelja
Idempotentna radnja pri ponavljanju ne bi trebala proizvesti još jedan isti poslovni učinak. Jedan način podrške je ključ kojim poslužitelj prepoznaje ponovljeni zahtjev.
Stripe dokumentira korištenje idempotency ključeva, ali i razlike među svojim verzijama API-ja. To je konkretan primjer, a ne svojstvo koje možete pretpostaviti za svaki ERP. Provjerite podržava li dobavljač ključ, koliko dugo ga pamti i što se događa nakon promjene podataka ili djelomičnog uspjeha.
Ako takva podrška ne postoji, dogovorite drugi provjerljiv način utvrđivanja prethodnog ishoda prije ponovne radnje. Kad ishod nije moguće sigurno potvrditi, označite slučaj za provjeru. Neizvjesnost nemojte prikazati kao uspješan prijenos.
Obavijest o događaju također treba obradu
Webhook je obavijest koju jedan sustav šalje drugome nakon događaja. Njegovo primanje ne uklanja potrebu za provjerom pošiljatelja, ponovljenih poruka i redoslijeda obrade.
Primjerice, Stripeove upute za webhooks opisuju provjeru potpisa, duplikate i mogućnost dostave izvan redoslijeda nastanka događaja. Za vlastitu integraciju provjerite što doista obećava vaš dobavljač. Njegove uvjete pretvorite u konkretne testove i pravila oporavka.
Kako ćete otkriti da neki zapis nedostaje?
Pregled pogrešaka treba biti dio radnog procesa. Za svaki nedovršen prijenos dogovorite status, odgovornu osobu i sljedeću radnju. Ponavljanje, ručni ispravak i odustajanje uz razlog trebaju ostaviti razumljiv trag.
Usklađivanje podataka znači usporedbu očekivanih i stvarno prihvaćenih zapisa. Sam broj narudžbi nije dovoljan: isti ukupni broj može skrivati nedostajući zapis i duplikat. Usklađujte identifikatore, dogovorena polja i konačne statuse.
U kriterije prihvata uključite barem ove scenarije:
- Ista poruka stiže ponovno.
- Odredište izvrši radnju, ali potvrda izostane.
- Jedna stavka sadrži nepoznatu šifru ili nedopuštenu vrijednost.
- Pristup istekne ili dobavljač privremeno odbija pozive.
- Dio prijenosa uspije, a ostatak treba intervenciju.
Za svaki scenarij pokažite gdje zaposlenik vidi problem i kako nastavlja posao. Neuspjeli ili neizvjesni zapisi trebaju ostati vidljivi do razrješenja. Automatsko brisanje takvih stavki iz reda prikriva posao koji još nije završen.
Što treba pisati u ponudi za API integraciju?
Ponuda treba imenovati sustave, tokove i operacije, pravila mapiranja, testove, način uvođenja te odgovornost za iznimke. Dodajte granice održavanja: promjene postojeće verzije API-ja, nove funkcije i rad trećeg dobavljača nisu ista stavka.
Za povezivanje postojećih programa pogledajte opseg integracija poslovnih sustava. Ako između programa nedostaje cijeli postupak s korisničkim ulogama i odobrenjima, procijenite i poslovni softver po mjeri. Potrebu za novom aplikacijom odvojite od samog prijenosa podataka.
Za prvi razgovor pripremite nazive i verzije programa, primjer zapisa bez osjetljivih podataka te opis željenog ishoda. Pošaljite Noveru što želite povezati kako bi procjena mogla obuhvatiti dostupni pristup, provjeru prijenosa i postupanje kad nešto zapne.