Co sprawdzić przy ocenie API do zamówień

Bezpośrednia odpowiedź

Oceniając API do zamówień, skup się na tym, co API faktycznie robi z zamówieniami, jak możesz potwierdzić wyniki oraz gdzie zachowanie może odbiegać od Twoich oczekiwań. Zachowaj obiektywizm listy kontrolnej: oddziel stabilną mechanikę (struktura żądań/odpowiedzi, semantyka cyklu życia) od zmiennych warunków (zmiany rynkowe, koszty, jakość realizacji i lokalne zasady). Ponieważ wyniki zależą od czynników zewnętrznych, traktuj przykłady jako założenia, a nie prognozy.

Jak działa API do zamówień (mechanizm i definicja)

API do zamówień to interfejs programistyczny używany do składania, modyfikowania i anulowania zleceń handlowych oraz do pobierania informacji o ich statusie w cyklu życia. W praktyce zwykle pracujesz z:

• Żądaniem zamówienia: danymi, które wysyłasz (np. typ zlecenia, strona, wolumen, czas obowiązywania i wymagane identyfikatory).
• Realizacją i potwierdzeniem: odpowiedziami, które otrzymujesz (akceptacja, odrzucenie lub błędy).
• Aktualizacjami stanu zamówienia: sposobem, w jaki dostawca raportuje zmiany w czasie (otwarte, częściowo wypełnione, wypełnione, anulowane, wygasłe, odrzucone).
• Identyfikatorami do uzgadniania: polami, które pozwalają dopasować Twoją intencję do wyników raportowanych przez dostawcę (takimi jak identyfikatory zamówień klienta i identyfikatory zamówień dostawcy, jeśli są obsługiwane).

Kluczowym krokiem oceny jest przełożenie dokumentacji na jawny model stanów dla Twojego systemu: jakie statusy istnieją, jak przebiegają przejścia i jakie gwarancje (jeśli jakiekolwiek) API zapewnia w zakresie kolejności, ponawiania i aktualizacji. Stabilna mechanika to ta, którą można wywnioskować ze specyfikacji; zmienne warunki to wszystko, co może się zmienić między żądaniem a potwierdzeniem.

Lista kontrolna due diligence (afvinkpunten)

Skorzystaj z poniższych punktów, aby zbudować powtarzalny proces weryfikacji.

1) Dane wejściowe i semantyka (co wysyłasz)

• Potwierdź wymagane pola i ograniczenia danych (dozwolone typy zleceń, minimalne/maksymalne wielkości, prawidłowe wartości czasu obowiązywania).
• Udokumentuj, jak API interpretuje jednostki i zasady zaokrąglania. Określ własne założenia dotyczące wolumenu, precyzji oraz sposobu obsługi kwot „bazowych” i „kwotowanych”.

2) Idempotentność i ochrona przed duplikatami (zapobiega niezgodnościom stanu)

• Sprawdź, czy API obsługuje żądania idempotentne lub udokumentowaną strategię ponawiania po przekroczeniu czasu.
• Zweryfikuj, jak obsługiwane są duplikaty, gdy to samo żądanie zostanie wysłane ponownie (ten sam identyfikator klienta vs nowe żądanie). Ma to znaczenie, ponieważ logika ponawiania jest powszechna w systemach zautomatyzowanych.

3) Cykl życia zamówienia i uzgadnianie (dowody lub dokumentacja)

• Zweryfikuj pełny cykl życia zamówienia: jakie statusy mogą wystąpić i jak raportowane są przejścia.
• Potwierdź pola potrzebne do uzgadniania (identyfikatory zamówień, znaczniki czasu, wypełnione wolumeny, pozostały wolumen i powody odrzucenia).
• Zdefiniuj kryteria „zakończenia” (np. uznajesz zamówienie za zamknięte, gdy otrzymasz stan końcowy, taki jak wypełnione/anulowane/odrzucone/wygasłe—zgodnie z udokumentowaną semantyką dostawcy).

4) Aktualizacje i model dostarczania (co możesz obserwować)

• Określ, czy informacje o statusie pochodzą z odpytywania, strumieniowania/webhooków, czy obu tych metod.
• Jeśli aktualizacje są asynchroniczne, sprawdź gwarancje dotyczące kolejności zdarzeń i kompletności zdarzeń. Logika uzgadniania powinna uwzględniać brakujące lub opóźnione aktualizacje jako wyraźny scenariusz.

5) Koszty i założenia dotyczące realizacji (co może się zmienić)

• Zidentyfikuj, które koszty i efekty realizacji mogą zmienić wyniki między żądaniem a statusem końcowym: opłaty, spready, poślizg, częściowe wypełnienia i opóźnienia.
• Ilustrując przykład, podaj założenia (np. „załóżmy, że opłaty wynoszą X, a wypełnienia następują w jednej realizacji”), a następnie zaznacz, że rzeczywiste warunki mogą się różnić.

6) Scenariusze awarii (rode vlaggen)

Poszukaj i przetestuj te typowe scenariusze awarii:

• Odrzucone zamówienia (błędy walidacji, niewystarczające uprawnienia lub nieprawidłowe parametry).
• Przekroczenia czasu i błędy przejściowe (Twój klient może ponawiać, podczas gdy dostawca mógł już przetworzyć żądanie).
• Częściowe wypełnienia (zamówienie zostaje częściowo zrealizowane, co wymaga logiki dla wolumenu „pozostałego”).
• Niespójny stan (Twój system widzi jedno źródło statusu, podczas gdy inne źródło jest opóźnione).

Jeśli dokumentacja nie określa jasno, jak te scenariusze działają, potraktuj to jako czerwoną flagę i zaplanuj konserwatywne uzgadnianie i monitorowanie.

Ograniczenia i ryzyka (co może pójść nie tak)

Realizacja zamówień i wyniki stanu zamówień zależą od warunków rynkowych i zachowania dostawcy, które nie są w pełni kontrolowane. Historyczne zależności nie gwarantują przyszłych wyników, a nawet staranne specyfikacje mogą zawieść w warunkach stresu (wysoka zmienność, problemy sieciowe lub prace serwisowe po stronie dostawcy). Istotne ograniczenia, które należy wyraźnie uznać, obejmują:

• Niepewność między intencją a realizacją: potwierdzenie nie musi oznaczać ostatecznej realizacji.
• Wyniki nieatomowe: częściowe wypełnienia i późniejsze anulowania mogą tworzyć wiele stanów dla jednej instrukcji.
• Luki w obserwowalności: opóźnienia lub brakujące aktualizacje mogą spowodować błędną interpretację bieżącego statusu przez Twój system.