inFakt Styleguide

Informujemy, że ze względu na udostępnienie nowej wersji API (wersja 3), dokumentacja oraz funkcjonalności APIv2 nie będą dłużej rozwijane przez zespół inFakt i zostaną wyłączone do końca maja 2015. Zapraszamy do zapoznania się z nową wersją API oraz dokumentacją na stronie: https://www.infakt.pl/developers

Uwierzytelnianie

Opis

Uwierzytelnianie odbywa się z wykorzystaniem protokołu oAuth (http://oauth.net/). Dlatego przed rozpoczęciem pracy z API konieczne jest zarejestrowanie aplikacji w systemie inFakt. W tym celu należy skorzystać z formularza dostępnego w menu Ustawienia -> API v2 – lista aplikacji. Wygenerowany zostanie consumer_key oraz consumer_secret – dane te należy umieścić w aplikacji.

Na potrzeby urządzeń mobilnych i aplikacji desktopowych zaimplementowane zostało rozszerzenie xAuth (podobne rozwiązanie znane z API Twitter – http://dev.twitter.com/pages/xauth ).

Aby zalogować się za pomocą xAuth należy również skorzystać z consumer_key oraz @consumer_secret@, jednak żądanie wykonywane jest bezpośrednio do @https://www.infakt.pl/oauth/access_token@ dodatkowo przekazując za pomocą metody POST dodatkowe dane:

  • x_auth_username – nazwa użytkownika dla którego chcemy uzyskać token
  • x_auth_password – hasło użytkownika dla którego chcemy uzyskać token
  • x_auth_mode – zmienna ta musi przyjąć wartość client_auth

Po prawidłowej autoryzacji, w odpowiedzi zostanie zwrócony oauth_token oraz oauth_token_secret. W tym momencie z aplikacja powinna usunąć dane użytkownika (x_auth_username i x_auth_password) a do uwierzytelniania na serwerze powinna korzystać ze standardowych procedur oAuth.


Przykład

Zakładając, że:

  • Consumer Key: JXqGL77C6Gs1JkK0DYsK
  • Consumer Secret: StbgxM7BK1hBDeCzbLBGeW8nwvnCQuvbKr9cTptu

Dane użytkownika:

  • login: testuser
  • hasło: aeVaa9eRena

Skrypt w Ruby:

Przykładowy skrypt

     1 #!/usr/bin/env ruby
         2 
         3 require "rubygems"
         4 require "oauth"
         5 require "json"
         6 
         7 module XAuth
         8         module_function
         9         def retrieve_access_token(
        10           username,
        11           password,
        12           consumer_key,
        13           consumer_secret,
        14           site = "https://www.infakt.pl")
        15 
        16         consumer = OAuth::Consumer.new(
        17           consumer_key,
        18           consumer_secret,
        19           :site => site
        20         )
        21 
        22         access_token = consumer.get_access_token(nil, {}, {
        23             :x_auth_mode => "client_auth",
        24             :x_auth_username => username,
        25             :x_auth_password => password,
        26           })
        27 
        28                 [consumer, access_token]
        29         end
        30 end
        31 
        32 if $0 == __FILE__
        33         puts "---------- Retrieving an access token... ----------"
        34 
        35         consumer, access_token = XAuth.retrieve_access_token(*ARGV)
        36         puts "Consumer key: #{consumer.key}"
        37         puts "Consumer token secret: #{consumer.secret}"
        38         puts "Access token: #{access_token.token}"
        39         puts "Access token secret: #{access_token.secret}"
        40 
        41         puts "---------- Retrieving user data... ----------"
        42 
        43         response = access_token.get("/api/v2/settings/user_data.json")
        44         user_data = JSON.load(response.body)
        45                 user_data["user_data"].each do |key, value|
        46                 puts "#{sprintf "%-15s", key}: #{value}"
        47         end
        48 end

użycie:

Przykładowy wynik

    1 ./xauth.rb user password consumer_key consumer_secret https://adres
        2 ./xauth.rb "testuser" \
        3         "aeVaa9eRena" \
        4         "JXqGL77C6Gs1JkK0DYsK" \
        5         "StbgxM7BK1hBDeCzbLBGeW8nwvnCQuvbKr9cTptu" \
        6          https://www.infakt.pl

wynik:

Przykładowe użycie

     1 ---------- Retrieving an access token... ----------
         2 Consumer key: JXqGL77C6Gs1JkK0DYsK
         3 Consumer token secret: StbgxM7BK1hBDeCzbLBGeW8nwvnCQuvbKr9cTptu
         4 Access token: K1FzSdad3zBAjSJZ8XVF
         5 Access token secret: ZbCZ7M9b57ErKPeRzqvB3CW3AKmHnxjaqhtXLNR4
         6 ---------- Retrieving user data... ----------
         7 
         8 imie                : Test
         9 nazwisko            : User
        10 nazwa_firmy         : Firma Testowa
        11 ulica               : Kolorowa
        12 kod_pocztowy        : 11-111
        13 miejscowosc         : Kraków
        14 nip                 : 6794370641
        15 numer_telefonu      : 12 123 123 123
        16 email               : test@test.pl
        17 rodzaj_dzialalnosci : 90099 (oznaczenie działalności gospodarczej GUS)

Po stronie aplikacji klienckiej należy zachować Access token i Access token secret – w połączeniu z Consumer Key i Consumer Secret umożliwią poprawne uwierzytelnienie na serwerze.

Prosta implementacja logowania z wykorzystaniem Access token i Access token secret języku Ruby za pomocą Gemu oAuth może wyglądać następująco:

Prosta implementacja logowania

     1 @consumer = OAuth::Consumer.new(
         2         consumer_key,
         3         consumer_secret,
         4         {:site => 'https://www.infakt.pl'})
         5 @access_token = OAuth::AccessToken.new(
         6                               @consumer,
         7                               access_token,
         8                               access_token_secret)
         9 @access_token.get('/api/v2/settings/user_data.json')

Implementacje protokołu oAuth w różnych językach mozna znaleźć pod adresem http://oauth.net/code/