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
}