Vodič za API integracije
API integracija poslovnih sistema: šta dogovoriti pre izrade
API integracija povezuje dogovorene radnje i podatke između programa. Za njenu pripremu navedite koji događaj pokreće prenos, koji sistem određuje ispravan podatak i šta se događa kada prenos nije potvrđen. Tek tada ima smisla procenjivati izradu konektora, testiranje i održavanje.
Krenite od jednog toka podataka
Na primer, želite da porudžbina iz web prodavnice stigne u ERP. Radni zadatak uključuje i odgovore na manje vidljiva pitanja: da li je kupac već evidentiran, sme li adresa da se promeni i da li će ponovni pokušaj napraviti još jednu porudžbinu. Upravo ta pravila treba da uđu u ponudu.
Umesto zahteva „povežite sve”, opišite jedan događaj od početka do završne provere. To može biti potvrđena porudžbina, promena kontakta ili završetak radnog naloga.
Za početni opseg odgovorite:
- Gde zapis nastaje i u kom trenutku je spreman za prenos?
- Koji se podaci prenose i u kom smeru?
- Treba li drugi sistem samo da primi zapis ili i da vrati potvrdu i identifikator?
- Koliko je kašnjenje prihvatljivo za poslovanje?
- Ko postupa ako prenos ne može da se dovrši?
Porudžbine i zalihe ne moraju da imaju isti ritam ažuriranja. Ako definišete prihvatljivo kašnjenje za svaki tok, izvođač može da proveri da li ga postojeći interfejs zadovoljava. Izraz „u realnom vremenu” bez tog dogovora ostavlja previše prostora za različita očekivanja.
Koji je sistem izvor istine za pojedini podatak?
Odredite gde podatak sme da se promeni i koja verzija važi kada se programi razlikuju. Jedan sistem ne mora biti glavni za sve: CRM može da vodi prodajni kontakt, ERP šifru artikla, a web prodavnica sadržaj prikaza proizvoda.
Microsoftov obrazac za povezivanje različitih modela podataka objašnjava zašto se između sistema prevode značenja i strukture. Za poslovni dogovor dovoljno je da krenete od tabele polja; zasebna složena infrastruktura nije automatski potrebna.
Sledeća tabela je ilustrativan dogovor za zamišljenu web prodavnicu i ERP, a ne opis već izvedene Novero integracije.
| Podatak | Dogovoreni izvor | Pravilo prenosa ili sukoba |
|---|---|---|
| Broj porudžbine u prodavnici | Web prodavnica | Čuva se i u ERP-u radi povezivanja zapisa. |
| Šifra artikla | ERP | Nepoznata šifra zaustavlja stavku radi provere. |
| Adresa za konkretnu isporuku | Potvrđena porudžbina | Ne prepisuje automatski sve postojeće adrese kupca. |
| Status otpreme | ERP | Vraća se u prodavnicu prema dogovorenim statusima. |
| Identifikator porudžbine u ERP-u | ERP | Vezuje se za izvornu porudžbinu radi provere i kasnijih promena. |
Za svako polje proverite format, obaveznost, jedinicu i dozvoljene vrednosti. „Komad” i „paket”, prazno polje i nula ili datum i trenutak događaja mogu da imaju različito poslovno značenje. Pravilo za nepoznatu vrednost treba da bude zapisano pre prvog uvoza.
Postoji li pristup baš onim radnjama koje su vam potrebne?
Pre procene zatražite aktuelnu dokumentaciju, testno okruženje i potvrdu dostupnih operacija. Mogućnost čitanja kupaca ne znači da API dozvoljava njihovo kreiranje ili menjanje. Proverite i da li pristup zavisi od paketa, dozvole dobavljača ili dodatne konfiguracije.
Spisak provera treba da obuhvati verziju interfejsa, ograničenja poziva, način prijave, obavezna polja i dostupne statuse. Ako gotov konektor pokriva tražene radnje, uporedite ga s izradom po meri pre naručivanja novog razvoja.
Ovlašćenja su zasebna provera. OWASP upozorava na potrebu provere pristupa konkretnom zapisu i radnji. U testiranju zato proverite i da korisnik ili integracioni nalog ne može da dohvati tuđe podatke promenom identifikatora.
Dogovorite ko izdaje i obnavlja pristupne podatke. U primere zahteva i zapise za podršku ne stavljajte aktivne tajne ili nepotrebne lične podatke.
Šta nakon prekida veze ili ponovljene poruke?
Zamišljeni scenario: ERP sačuva porudžbinu, ali odgovor ne stigne do prodavnice. Prodavnica tada ne zna da li je predaja uspela. Slepo ponovno kreiranje porudžbine može da napravi duplikat.
Microsoftova uputstva o ponavljanju zahteva razlikuju privremene poteškoće od drugih grešaka i upozoravaju na ponovljeno izvršavanje radnje. Zato automatsko ponavljanje dogovorite prema ponašanju konkretnog API-ja.
Idempotentnost zavisi od ugovora interfejsa
Idempotentna radnja pri ponavljanju ne bi trebalo da proizvede još jedan isti poslovni efekat. Jedan način podrške je ključ kojim server prepoznaje ponovljeni zahtev.
Stripe dokumentuje korišćenje idempotency ključeva, ali i razlike među svojim verzijama API-ja. To je konkretan primer, a ne svojstvo koje možete da pretpostavite za svaki ERP. Proverite da li dobavljač podržava ključ, koliko dugo ga pamti i šta se događa nakon promene podataka ili delimičnog uspeha.
Ako takva podrška ne postoji, dogovorite drugi proverljiv način da se utvrdi prethodni ishod pre ponovne radnje. Kada ishod nije moguće sigurno potvrditi, označite slučaj za proveru. Neizvesnost nemojte prikazati kao uspešan prenos.
Obaveštenje o događaju takođe treba obradu
Webhook je obaveštenje koje jedan sistem šalje drugom nakon događaja. Njegovo primanje ne uklanja potrebu za proverom pošiljaoca, ponovljenih poruka i redosleda obrade.
Na primer, Stripeova uputstva za webhooks opisuju proveru potpisa, duplikate i mogućnost dostave izvan redosleda nastanka događaja. Za sopstvenu integraciju proverite šta zaista obećava vaš dobavljač. Njegove uslove pretvorite u konkretne testove i pravila oporavka.
Kako ćete otkriti da neki zapis nedostaje?
Pregled grešaka treba da bude deo radnog procesa. Za svaki nedovršen prenos dogovorite status, odgovornu osobu i sledeću radnju. Ponavljanje, ručni ispravak i odustajanje uz razlog treba da ostave razumljiv trag.
Usklađivanje podataka znači poređenje očekivanih i stvarno prihvaćenih zapisa. Sam broj porudžbina nije dovoljan: isti ukupan broj može da sakrije zapis koji nedostaje i duplikat. Usklađujte identifikatore, dogovorena polja i konačne statuse.
U kriterijume prihvatanja uključite barem ove scenarije:
- Ista poruka stiže ponovo.
- Odredište izvrši radnju, ali potvrda izostane.
- Jedna stavka sadrži nepoznatu šifru ili nedozvoljenu vrednost.
- Pristup istekne ili dobavljač privremeno odbija pozive.
- Deo prenosa uspe, a ostatak zahteva intervenciju.
Za svaki scenario pokažite gde zaposleni vidi problem i kako nastavlja posao. Neuspeli ili neizvesni zapisi treba da ostanu vidljivi do rešenja. Automatsko brisanje takvih stavki iz reda prikriva posao koji još nije završen.
Šta treba pisati u ponudi za API integraciju?
Ponuda treba da imenuje sisteme, tokove i operacije, pravila mapiranja, testove, način uvođenja i odgovornost za izuzetke. Dodajte granice održavanja: promene postojeće verzije API-ja, nove funkcije i rad trećeg dobavljača nisu ista stavka.
Za povezivanje postojećih programa pogledajte obim integracija poslovnih sistema. Ako između programa nedostaje ceo postupak s korisničkim ulogama i odobrenjima, procenite i poslovni softver po meri. Potrebu za novom aplikacijom odvojite od samog prenosa podataka.
Za prvi razgovor pripremite nazive i verzije programa, primer zapisa bez osetljivih podataka i opis željenog ishoda. Pošaljite Noveru šta želite da povežete kako bi procena mogla da obuhvati dostupni pristup, proveru prenosa i postupanje kada nešto zapne.