Jak działa API Optifora
Ta strona opisuje kształt API: jak dowodzi się tożsamości, jak posuwają się naprzód wersje, w jakich limitach mieści się żądanie, jak wygląda błąd i w jaki sposób wymienia się dane ze światem zewnętrznym.
Produkt jest w budowie, a powierzchnia API wciąż jest uzupełniana. Dokument referencyjny punktów końcowych zostanie opublikowany osobno; ta strona nie zawiera żadnego adresu ani przykładowego wywołania, tylko mechanikę działania.
Uwierzytelnianie
Każde żądanie należy albo do osoby, albo do zarejestrowanej aplikacji. Żądanie bez tożsamości, które trafi do chronionego punktu końcowego, wraca jako nieuwierzytelnione.
- Token bearerToken dostępu podróżuje w nagłówku autoryzacyjnym żądania. Jest podpisany i mówi wyłącznie o tym, do kogo żądanie należy.
- Krótkie życieToken dostępu wygasa po czasie liczonym w minutach; długość jest ustawieniem wdrożenia i domyślnie wynosi trzydzieści minut.
- Odświeżanie i rotacjaSesję przedłuża się tokenem odświeżającym, a każde przedłużenie wydaje nową parę. Jeśli zużyty token odświeżający zostanie okazany po raz drugi, wszystkie sesje tej osoby zostają unieważnione.
- Uprawnienia nie są zapiekane w tokenieToken niesie wyłącznie tożsamość; o to, co dana osoba może zobaczyć, pytana jest baza danych przy każdym żądaniu. Cofnięte uprawnienie przestaje więc działać, zanim wygaśnie posiadany token.
- Klucz integratoraZarejestrowana aplikacja łączy się własnym kluczem. Wartość jawna pokazywana jest jeden raz, przy tworzeniu; przechowywany jest jej skrót oraz niebędący tajemnicą przedrostek, który pozwala rozpoznać klucz.
- Dostęp nadaje organizacjaNiezależnie od tego, jak szeroko używana jest aplikacja, bez zgody zapisanej przez organizację nie zobaczy ona ani jednego wiersza. Zgoda ma datę, zakres i może zostać cofnięta.
Wersjonowanie
- Wersja jest w ścieżcePunkty końcowe publikowane są za przedrostkiem wersji; dzisiejsza powierzchnia to wersja pierwsza.
- Zmiana łamiąca zgodność otwiera nową ścieżkęKontrakt istniejącego punktu końcowego nie jest łamany w miejscu. Niezgodna zmiana publikowana jest na nowej ścieżce wersji, a stara nadal działa.
- Dokument sam podaje swoją wersjęDokumentacja niesie numer wersji, z której została wygenerowana; na pytanie, którą wersję się czyta, odpowiada sam dokument.
Środowiska i limity
Dokumentacja deklaruje dwa środowiska: produkcyjne i lokalne deweloperskie. Adres główny przekazywany jest integratorowi razem z jego kluczem; nie jest publikowany na tej stronie.
- Żywotność i gotowość mierzone są osobnoJeden punkt końcowy mówi, że proces działa; drugi wysyła prawdziwe zapytanie do bazy danych i potwierdza, że jest osiągalna. Dopiero ten drugi rozstrzyga, czy należy kierować ruch.
- Źródła przeglądarkowe ograniczone są do listyŻądania z innych domen przyjmowane są wyłącznie ze źródeł zadeklarowanych wcześniej; dopóki lista jest pusta, żądanie przeglądarki z innej domeny zostaje odrzucone.
- Limit treści żądaniaTreść żądania nie może przekroczyć pięciu megabajtów. Duże zbiory przekazywane są jako zadanie transferu zbiorczego z własnym rekordem statusu, a nie jako pojedyncze żądanie.
- Tajemnice nie trafiają do dziennikaDziennik serwera nie przechowuje nagłówka autoryzacji, pliku cookie, hasła ani krajowego numeru identyfikacyjnego.
Limit szybkości
Limit liczony jest na adres i na minutę. Domyślnie to 120 żądań na minutę i ustawia się go przy wdrożeniu. Pozostały przydział raportowany jest w nagłówkach każdej odpowiedzi.
| Nagłówek odpowiedzi | Co mówi |
|---|---|
| x-ratelimit-limit | Cały przydział wewnątrz okna. |
| x-ratelimit-remaining | Ile pozostało w tym oknie. |
| x-ratelimit-reset | Sekundy do odnowienia przydziału. |
| retry-after | Ile sekund do ponowienia. Występuje tylko w odpowiedzi, która odrzuciła żądanie. |
Po przekroczeniu limitu żądanie zostaje odrzucone, a odpowiedź podaje w sekundach, jak długo czekać. Ponowienie następuje po tym czasie, a nie natychmiast.
Format błędu
Każdy błąd wraca w tej samej kopercie: krótkie pole kodu, po którym rozgałęzia się maszyna, oraz pole wyjaśnienia do przeczytania przez człowieka.
- errorKrótki kod, na podstawie którego decyduje klient.
- messageWyjaśnienie tego, co się wydarzyło.
| Status | Pole kodu | Co oznacza |
|---|---|---|
| 400 | Bad Request | Żądanie nie pasuje do schematu. Wyjaśnienie wskazuje pole, którego brakuje lub które jest nieprawidłowe. |
| 401 | unauthenticated | Brak ważnej tożsamości: token nie został wysłany, wygasł albo nie przeszedł weryfikacji. |
| 404 | Not Found | Nie ma takiego punktu końcowego albo nie ma takiego rekordu. |
| 429 | Too Many Requests | Przekroczono limit szybkości; odpowiedź podaje, jak długo należy czekać. |
| 5xx | internal_error | Nieoczekiwana awaria. Szczegół nie trafia do klienta; zapisywany jest w dzienniku serwera. |
Stronicowanie
Punkty końcowe zwracające listy przyjmują te same dwa parametry i zwracają te same liczniki, więc klienta obsługującego stronicowanie nie pisze się od nowa dla każdego punktu końcowego.
- limitIle rekordów ma mieścić strona. Co najmniej jeden, najwyżej dwieście; pięćdziesiąt, gdy nie podano.
- offsetIle rekordów pominąć. Liczone od zera.
- totalIle rekordów w sumie odpowiada filtrom.
- countIle rekordów faktycznie niesie ta odpowiedź.
Odpowiedź zwraca również użyte wartości limit i offset; klient odczytuje swoje położenie z odpowiedzi, zamiast je zgadywać.
Wymiana danych i webhooki
Tryb wymiany jest ustawieniem, a nie osobnym produktem: każda zarejestrowana aplikacja niesie na własnym rekordzie tryb, w którym pracuje.
| Tryb | Co oznacza |
|---|---|
| Jednokierunkowo — na zewnątrz | Optifora publikuje dane; druga strona je odczytuje albo subskrybuje zdarzenia. |
| Jednokierunkowo — do środka | Druga strona przesyła dane; Optifora sprawdza je i zapisuje. |
| Dwukierunkowo | Zapisują obie strony; reguła rozstrzygania konfliktu jest ustalona z góry. |
| Uzgodnienie | Każde przekazanie otwiera sesję: oferta, weryfikacja, zatwierdzenie, przekazanie i potwierdzenie. Potwierdzenie zostaje u obu stron. |
- Zdarzenia są wypychane na zewnątrzWebhook wysyła zdarzenie pod adres zwrotny zadeklarowany przez zarejestrowaną aplikację. Zdarzenie, którego nie da się dostarczyć, zostaje w kolejce i jest ponawiane; nigdy nie znika po cichu.
- To samo żądanie nie zapisuje dwa razyŻądanie zapisu niesie klucz idempotencji. Drugie żądanie z tym samym kluczem nie tworzy drugiego rekordu.
- Każde wywołanie jest mierzoneKto wywołał, kiedy, w jakim zakresie i z jakim wynikiem — wszystko to jest rejestrowane. Ten sam zapis odpowiada zarówno na potrzeby diagnostyki, jak i na pytanie, kto pobrał te dane.
- Nasze aplikacje korzystają z tych samych drzwiNie istnieje żadna uprzywilejowana druga droga. Nasza własna integracja jest dowodem na to, jaką powierzchnię napotyka zewnętrzny programista.
Model danych warstwy wymiany jest gotowy; jej punkty końcowe nie zostały jeszcze opublikowane. Gdy to nastąpi, ta sekcja będzie odsyłać do ich opisów w dokumentacji.
Dokumenty referencyjne
Dokumentacja nie jest pisana ręcznie; generuje się ją ze schematów punktów końcowych. Gdy kolejny punkt końcowy przekazuje swój schemat, dokument uzupełnia się sam, więc dokument i zachowanie nie mogą się rozjechać.
- Dziś: w przygotowaniuSchematy przenoszone są moduł po module. Zanim dokument zostanie opublikowany, będzie w nim widoczne żądanie i odpowiedź każdego punktu końcowego.
- Opublikowane zostaną dwa formatyOdczytywalny maszynowo dokument OpenAPI oraz strona referencyjna wygenerowana z tego samego dokumentu i przeglądana w przeglądarce.
- Dostęp jest stopniowanyPrzegląd ogólny jest otwarty dla każdego. Pełna dokumentacja może stać za tokenem dokumentacyjnym wydanym zarejestrowanemu integratorowi; klucze produkcyjne i adresy zwrotne nie są w ogóle sprawą dokumentacji — należą do rekordu aplikacji.
- Standard adresowaniaPublikowane są dwie dokumentacje, a ich adresy są stałe: client-api.optifora.com/docs jest otwarta, admin-api.optifora.com/docs wymaga autoryzacji i pozostaje zamknięta na zewnątrz. Dziś żadna z nich nie działa; odnośniki pojawią się w tej sekcji, gdy zostaną uruchomione.
Jeśli plan integracji jest już jasny, prosimy o wiadomość ze strony kontaktowej: informacja o otwarciu powierzchni API dotrze do Państwa w pierwszej kolejności.
Mają Państwo konkretną prośbę?
Te strony wyjaśniają, jak działa proces wsparcia. W razie prośby albo pytania prosimy napisać do nas ze strony kontaktowej.
Przejdź do strony kontaktowej