Dokumentacja

Ogólne informacje

Punkt dostępowy

Punkt dostępowy API znajduje się pod adresem:

https://api.infakt.pl/v3

Należy zwrócić uwagę, że dostęp odbywa się szyfrowanym połączeniem https.

Uwierzytelnianie

Klucz dostępu do API można wygenerować po zalogowaniu do aplikacji WWW korzystając z ustawień konta. Klucz powinien być przekazywany za pomocą nagłówka HTTP X-inFakt-ApiKey lub parametru api_key.

Kodowanie znaków

Każdy string przekazy do API musi być kodowany w UTF-8.

Parametry

Dla requestów POST, PATCH, PUT i DELETE parametry nie zawarte w URLu powinny być zakodowane JSONem, a zapytanie powinno posiadać nagłówek Content-Type: application/json.

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: 49206c6f766520496e66616b74203a3e" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"client":{"company_name":"Infakt Biuro Rachunkowe Sp. z o.o."}}' \
  https://api.infakt.pl/v3/clients/1.json

Wyszukiwanie odbywa się poprzez wywołanie akcji listowania odpowiedniego zasobu z parametrem q zawierającym treść zapytania w formacie:

/invoices.json?q[NAZWA_PARAMETRU_eq]=SZUKANA_WARTOŚĆ

Ważne, aby w tym miejscu zwrócić uwagę na modyfikator _eq dołączony do nazwy wyszukiwanego parametru. Nazwa parametru dla każdego pola znajduje się w sekcji Definicja odpowiedniego zasobu (pierwsza kolumna).

Modyfikatory:

Do wartości tekstowych można użyć:

  • _eq - zwraca rekordy w których pole równa się podanej wartości
  • _cont - zwraca rekordy w których pole zawiera podaną wartość

Do dat można użyć:

  • _lt - mniejsze niż
  • _gt - więszke niż
  • _lteq - mniejsze lub równe
  • _gteq - większe lub równe

Ważna informacja: Nie do wszytskich parametrów można zastosować podane modyfikatory.

Przykłady:

Aby wyszukać fakturę o numerze 1/09/2013, do zapytania listującego faktury należy dodać parametr q[number_eq]=1/09/2013.

  • GET /v3/invoices.json?q[number_eq]=1/09/2013

Aby wyszukać klienta po NIP, do zapytania listującego faktury należy dodać parametr q[nip_eq]=SZUKANY_NIP.

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: API_KEY" \
  -H "Content-Type: application/json" \
  -X GET \
  -d '{"q": {"nip_eq": "SZUKANY_NIP"} }' \
  https://api.infakt.pl/v3/clients.json

Aby wyszukać faktury bez daty opłacenia

Przykładowe zapytanie

curl -H "X-inFakt-ApiKey: API_KEY" \
  -H "Content-Type: application/json" \
  -X GET \
  -d '{"q": {"paid_date_null": true} }' \
  https://api.infakt.pl/v3/invoices.json

Stronicowanie

Niektóre zapytania listujące kolekcje zasobów zwracają ograniczoną ilość danych i mogą być stronicowane. W tym celu należy użyć parametrów offset i limit

Przykłady:

  • GET /v3/clients.json?offset=10&limit=50
  • GET /v3/products.json?offset=0&limit=100

Częściowe odpowiedzi

Domyślnie, serwer zwraca pełną reprezentację zasobu. Dla lepszej wydajności, można zwrócić się do serwera, aby wysłał tylko te pola, których naprawdę potrzebujesz i uzyskać częściową odpowiedź.

Aby ubiegać się o częściową odpowiedź, użyj parametru fields celem określenia pól, które mają zostać zwrócone. Możesz użyć tego parametru dla każdej akcji Listowania oraz Podglądu.

Przykłady:

GET /v3/bank_accounts.json?fields=bank_name

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 4,
      "total_count": 4,
      "next": "https://api.infakt.pl/api/v3/bank_accounts.json?fields=bank_name&offset=10",
      "previous": "https://api.infakt.pl/api/v3/bank_accounts.json?fields=bank_name&offset=0"
  },
  "entities": [
    {
      "id": 4,
      "bank_name": "Bank4"
    },
    {
      "id": 3,
      "bank_name": "Bank3"
    },
    {
      "id": 2,
      "bank_name": "Bank2"
    },
    {
      "id": 1,
      "bank_name": "Bank1"
    }
  ]
}
GET /v3/invoices.json?fields=number,services(name,tax_symbol)

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 15,
      "next": "https://api.infakt.pl/api/v3/invoices.json?fields=number,services(name,tax_symbol)&offset=10",
      "previous": "https://api.infakt.pl/api/v3/invoices.json?fields=number,services(name,tax_symbol)&offset=0"
  },
  "entities": [
    {
      "id": 5,
      "number": "4/05/2016",
      "services": [
        {
          "id": 5,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    },
    {
      "id": 3,
      "number": "3/05/2016",
      "services": [
        {
          "id": 3,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    },
    {
      "id": 2,
      "number": "2/05/2016",
      "services": [
        {
          "id": 2,
          "name": "kawa",
          "tax_symbol": "23"
        }
      ]
    }
  ]
}

Sortowanie

Sortowanie odbywa się za pomocą parametru order

Przykłady:

GET /v3/products.json?fields=name&offset=10&limit=5&order=name%20asc

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 467,
      "next": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=15&limit=5&order=name%20asc"
      "previous": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=5&limit=5&order=name%20asc"
  },
  "entities": [
    {
      "id": 391,
      "name": "Air Electric System"
    },
    {
      "id": 327,
      "name": "Air Filter"
    },
    {
      "id": 353,
      "name": "Air GPS Filter"
    }
  ]
}
GET /v3/products.json?fields=name&offset=10&limit=5&order=name%20desc

Przykładowa odpowiedź

{
  "metainfo": {
      "count": 3,
      "total_count": 467,
      "next": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=15&limit=5&order=name%20desc"
      "previous": "https://api.infakt.pl/api/v3/products.json?fields=name&offset=5&limit=5&order=name%20desc"
  },
  "entities": [
    {
      "id": 137,
      "name": "Video Filter"
    },
    {
      "id": 351,
      "name": "Video Controller"
    },
    {
      "id": 369,
      "name": "Video Compressor"
    }
  ]
}

Kody błędów

Rezultat wykonanego zapytania można określić na podstawie kodu błędu HTTP. W InFakt API używane są następujące kody:

Kod odpowiedzi Opis
200 OK Zapytanie zostało wykonane poprawnie
201 Created Zasób został poprawnie utworzony.
202 Accepted Zapytanie zostało zakceptowane do przetworzenia, np. podczas wysyłki dokumentów.
204 No Content Zwracany po poprawnym usunięciu zasobu.
400 Bad Request Któryś z parametrów przyjął nieprawidłową wartość.
401 Unauthorized Brak autoryzacji lub uprawnień do danego zasobu.
403 Forbidden Zwracany w przypadku braku uprawnień do danej akcji (np. posiadanie nieodpowiedniego planu).
404 Not Found Zasób nie został odnaleziony.
406 Not Acceptable Zwracany w przypadku użycia niepoprawnego typu danych w adresie zasobu.
422 Unprocessable Entity Zwracany wraz z informacją o błędach w przypadku problemów z zasobem.

Interaktywna dokumentacja

Dla użytkowników korzystających z API została udostępniona interaktywna dokumentacja, dzięki której można przetestować zapytania do API z poziomu przeglądarki.

Aby korzystać z interaktywnej dokumentacji, należy posiadać klucz dostępu, który można wygenerować tutaj a następnie wprowadzić go do odpowiedniego pola pod adresem:

http://api.infakt.pl/api/v3/doc/index.html

comments powered by Disqus