Wstęp

ORKANmulti API dostępne jest jako zbiór metod wywoływanych za pomocą protokołu HTTP.

• Funkcje udostępnione są w ramach modułów co obrazuje struktura URL: https:/.../api/moduł.metoda.

• Całość komunikacji chroniona jest poprzez HTTPS, moduł API nie jest dostępny przez HTTP.

• Wszystkie wywołania używają metody HTTP/POST.

• Zarówno parametry funkcji jak i jej wynik ma typ Content-type: application/json.

• Łańcuchy znaków kodowane są jako UTF-8.

Argumenty funkcji (metod)

• Parametry funkcji przekazywane są jako obiekt JSON. Obiekt powinien być umieszczony jako zawartość (body) żądania HTTP/POST.

• Dla nielicznych metod, wymagających przekazania zawartości plików, może być wymagana kodowanie multipart/form-data. Przypadki takie są oznaczone w opisie metody.

• Typ żądania powinien być prawidłowo określony w nagłówku HTTP. Brak nagłówka oznacza domyślnie Content-type: application/json.

• Żądanie HTTP powinno zawierać również nagłówek X-Requested-With.

Autoryzacja

• Autoryzacja wywołania metod odbywa się w oparciu o token (klucz dostępowy).

• Token musi być umieszczony w nagłówku HTTP jako zmienna: X-Auth-Pasz.

Token można wygenerować w rejestrze użytkowników systemu pole Klucz API.

Limity wywołań

• Funkcje mogą posiadać zabezpieczenie w postaci ograniczenia liczby wywołań z jednego źródła w jednostce czasu (np. nie więcej niż 1 na sekundę oraz 40 na dobę).

• W celu identyfikacji źródła wywołania klient musi umieścić w nagłówku HTTP następujące zmienne:

  • X-Org-User-Agent - identyfikator klienta

  • X-Org-Remote-Addr - adres IP klienta.

Wynik zwracany przez funkcje

• Rezultat wywołania funkcji przekazywany jest jest również jako obiekt JSON.

• Wszystkie odpowiedzi API opatrzone są statusem HTTP/200 OK, natomiast rezultat wykonania metody zwracany jest w jedynym obowiązkowym polu obiektu o nazwie rez.

• Pozostałe pola zależne są od konkretnej metody lub wystąpienia błędu.

Wartości rez są następujące

rez	Znaczenie kodu	Dodatkowe informacje
OK	Oznacza prawidłowe wykonanie funkcji. Każda inna wartość tj. rez !== “OK” oznacza wystąpienie błędu.	Pozostałe pola zależne są od wywoływanej metody. Patrz opis dostępnych metod.
KLC	Błąd autoryzacji klucza. Nieprawidłowy lub nieaktualny klucz.	blad_komunikat - komunikat błędu
LIM	Osiągnięto limit wywołań API. Metody zabezpieczone w ten sposób są oznaczone w opisie.	blad_komunikat - komunikat błędu powtorz_za_sek - czas w sekundach po którym klient może powtórzyć żądanie lub 0.
STOP	Błąd uniemożliwiający wykonanie operacji. Np. nieprawidłowa wartość parametrów lub nieznaleziony rekord w bazie danych.	blad_komunikat - komunikat wyświetlany w UI wynik_walidacji_pol - tablica wartości postaci { “nazwa_argumentu” : “komunikat_błędu” } odnosząca się do parametrów wywołania metody.
BW	Podobnie jak STOP ale operacja została częściowo wykonana. BW = “błąd walidacji” parametrów niekrytycznych. Może być konieczne poprawienie błędnych parametrów (wynik_walidacji_pol) i powtórne wykonanie funkcji.	jak dla STOP
ASY	Funkcja wykonywana asynchronicznie. Operacja została wstawiona do kolejki a jej zakończenie sygnalizowane będzie jako meldunek wysyłany poprzez serwer WebSocket. Możliwe jest odpytanie o status zadania podając jego ID. Metody asynchroniczne są oznaczone w opisie.	id_zadania - identyfikator zadania
inne	Pozostałe wartości oznaczają błędy krytyczne. Np. niedostępny serwer bazy danych.	blad_komunikat - komunikat błędu blad_info_tech - informacje systemowe (techniczne) ułatwiające diagnozowanie błędu

• Kody odpowiedzi inne niż HTTP/200 oznaczają powstanie błędu w warstwie “powyżej” modułu API. Np. HTTP/500 może oznaczać niedostępność serwera a HTTP/401 nieprawidłową konfigurację. Błędy te należy traktować jako krytyczne.

• Nagłówek HTTP odpowiedzi zawiera zmienną Access-Control-Allow-Origin.

---

Metoda strona.kontakty

Metoda zwraca listę kontaktów udostępnionych w module Współpracownicy. Zwracane są dane z sekcji Strona internetowa oraz informacja o właścicielu systemu, zakładka Ustawienia.

Parametry

Brak.

Wynik

Lista kontaktów zwracana w tablicy kontakty.

pole	opis
id (int)	identyfikator kontaktu
typ	BP - biuro partnerskie, BG - biuro główne, WSP - współpracownik
nazwa	nazwa biura lub imię i nazwisko agenta
ulica	ulica numer domu / numer mieszkania
kod_pocztowy, miejscowosc
telefon
email
lat	Szerokość i długość geograficzna dla celów prezentacji kontaktu na mapie. Jeżeli nie udało się ustalić prawidłowej lokalizacji pozycja przyjmuje wartość (0.0, 0.0).
lng

Przykład

{
    "rez": "OK",
    "kontakty": [
        {
            "id": 485,
            "typ": "BP",
            "nazwa": "Finance sp. z o.o.",
            "ulica": "ul. 3 Maja 42/4",
            "kod_pocztowy": "81-743",
            "miejscowosc": "Gdynia",
            "telefon": "600-511-001",
            "email": "finance@msm.pl",
            "lat": 54.435829,
            "lng": 18.566261
        },
        {
            "id": 640,
            "typ": "WSP",
            "nazwa": "Jan Kowalski",
            "ulica": "M. Buczka 5",
            "kod_pocztowy": "00-230",
            "miejscowosc": "Warszawa",
            "telefon": "600-511-000",
            "email": "j.kowalski@msm.pl",
            "lat": 0,
            "lng": 0
        },
        {
            "id": 1,
            "typ": "BG",
            "nazwa": "MultiSaveMoney sp. z o.o.",
            "ulica": "Lelewela 47/13",
            "kod_pocztowy": "85-368",
            "miejscowosc": "Bydgoszcz",
            "telefon": "52 346 03 37",
            "email": "sekretariat@msm.pl",
            "lat": 53.136546,
            "lng": 18.031181
        }
    ]
}

---

Metoda strona.rejestrujAgenta

Metoda rejestruje nowego współpracownika na podstawie formularza umieszczonego na stronie multiagencji. Prawidłowe wykonanie funkcji powoduje założenie nowego użytkownika w systemie.

Metoda kontroluje limit wywołań.

Parametry

nazwa	walidacja
imie	wymagane
nazwisko	nie jest wymagane - może ulec zmianie
kod_pocztowy	kontrola prawidłowego kodu pocztowego, w celu walidacji usuwane są wszelkie znaki niebędące cyframi
email	kontrola prawidłowego formatu email, kontrola czy rejestr współpracowników nie zawiera już email (aktywnego lub nie)
telefon	kontrola formatu
zgoda_na_regulamin	czy użytkownik wyraził zgodę na zapisy regulaminu, wartość true / false, zgoda jest wymagana

Wynik

Prawidłowy wykonanie metody zwraca komunikat do prezentacji w UI portalu multiagencji.

Przykład

{
    "rez": "OK",
    "komunikat": "Dziękujemy za Twoje zgłoszenie. Sprawdź maila  (janusz@poczta.com) a znajdzesz tam wskazówki jak zalogować się do systemu ORKANmulti"
}

 

Przykład błędu walidacji rez=”STOP”

{
    "rez": "STOP",
    "blad_komunikat": "Prosimy poprawić dane",
    "wynik_walidacji_pol": [
        {
            "kod_pocztowy": "Proszę podać prawidłowy kod pocztowy"
        },
        {
            "email": "Proszę podać prawidłowy e-mail"
        }
    ]
}

 

Przykład przekroczenia limitu wywołań rez=”LIM”

{
    "rez": "LIM",
    "blad_komunikat": "Przekroczono dostępny limit liczby żądań",
    "powtorz_za_sek": 1
}

---

Metoda strona.rejestrujTelefon

Metoda rejestruje kontakt telefoniczny pochodzący ze strony multiagencji. Np. formularz Zostaw telefon.

Metoda kontroluje limit wywołań.

Parametry

nazwa	walidacja
zrodlo	źródło pochodzenia kontaktu, dopuszczalne są wartości AGENT - podstrona zostań Agentem, MDSR - podstrona zostań Managerem ds Rozwoju | BP - załóż Biuro Partnerskie;
imie	wymagane
nazwisko	nie jest wymagane
telefon	kontrola formatu
zgoda_na_regulamin	czy użytkownik wyraził zgodę na zapisy regulaminu, wartość true / false, zgoda jest wymagana dla źródeł MDSR oraz BP

Wynik

Prawidłowy wykonanie metody zwraca komunikat do prezentacji w UI.

Przykład

{
    "rez": "OK",
    "komunikat": "Dziękujemy za kontakt. Oddzwonimy w ciągu 15 minut na numer 505300100"
}

 

Przykład błędu walidacji rez=”STOP”

{
    "rez": "STOP",
    "blad_komunikat": "Prosimy poprawić dane",
    "wynik_walidacji_pol": [
        {
            "zrodlo": "Dopuszczalne wartości to: AGENT, MDSR lub BP"
        }
    ]
}

 

Przykład przekroczenia limitu wywołań rez=”LIM”

{
    "rez": "LIM",
    "blad_komunikat": "Przekroczono dostępny limit liczby żądań",
    "powtorz_za_sek": 1
}

---

Metoda strona.rejestrujBiznes

Metoda rejestruje kontakt biznesowy pochodzący ze strony multiagencji. Prawidłowe wykonanie metody powoduje założenie nowego (lub aktualizację obecnego) wpisu w module Kontakty.

Metoda kontroluje limit wywołań.

Parametry

nazwa	walidacja
imie	opcjonalne
nazwisko	opcjonalne
telefon	wymagane, kontrola formatu
email	wymagane, kontrola prawidłowego formatu email
NIP	wymagane, sprawdzana jest cyfra kontrolna a następnie obecność podmiotu z bazie GUS, przed rozpoczęciem walidacji z pola usuwane są wszystkie znaki nie będące cyframi
koszty_ub_pow_100tys	czy koszty ubezpieczeń w firmie powyżej 100 tyś PLN, wartość true / false
zgoda_na_regulamin	czy użytkownik wyraził zgodę na zapisy regulaminu, wartość true / false

Wynik

Prawidłowy wykonanie metody zwraca komunikat do prezentacji w UI.

Przykład

{
    "rez": "OK",
    "komunikat": "Dziękujemy za kontakt. Oddzwonimy w ciągu 15 minut na numer 505300100"
}

  Przykład błędu walidacji rez=”STOP”

{
    "rez": "STOP",
    "blad_komunikat": "Prosimy poprawić dane",
    "wynik_walidacji_pol": [
        {
            "NIP": "Nieprawidłowy format NIP"
        }
    ]
}

Przykład przekroczenia limitu wywołań rez=”LIM”

{
    "rez": "LIM",
    "blad_komunikat": "Przekroczono dostępny limit liczby żądań",
    "powtorz_za_sek": 1
}

---