API Comarch TNA

Public API

Informacje ogólne o Comarch TNA API

Usługa Comarch TNA umożliwia integrację z zewnętrznymi systemami za pośrednictwem dedykowanego API, udostępniającego szereg pomocnych funkcjonalności. Komunikacja odbywa się przez wymianę obiektów JSON i zabezpieczona jest szyfrowanym protokołem HTTPS.

Możliwości dotyczące zarządzania pracownikami:

  • pobieranie listy pracowników
  • dodanie nowego pracownika
  • edycja danych pracownika
  • usunięcie pracownika
  • pobranie danych o pracowniku

Możliwości dotyczące zarządzania czasem pracy pracownika:

  • sprawdzenie aktualnej obecności pracownika
  • sprawdzenie historii wejść/wyjść

Aktywacja API

W celu aktywacji dostępu do API Comarch TNA wymagane jest wygenerowanie klucza dostępu dedykowanego dla usługi. W celu uzyskania takiego klucza należy wykonać następujące kroki:

  1. Logowanie do usługi na stronie https://tna.comarch.com.
  2. Przejście do sekcji "Narzędzia → API".
  3. Uruchomienie przycisku "Wygeneruj".
  4. Zapisanie identyfikatora klucza oraz samego klucza na potrzeby autoryzacji integrującej się usługi.

OAuth 2.0

Generowanie tokenu

Aplikacja kliencka generuje token wysyłając zapytanie (POST) do serwera autoryzującego z swoim identyfikatorem (client_id) oraz kluczem (secret):
https://tna.comarch.com/api/oauth/token

Zapytanie składa się z następujących nagłówków:

Nazwa Dozwolone wartości Wymagany Opis
Content-Type application/x-www-form-urlencoded Tak
Authorization Basic [client_id:client_secret] Tak Wartość nagłówka Authorization musi być zakodowana w Base64 np. Basic U2ltcGxlQ2xpZW50SWQ6c2VjcmV0

Zapytanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
grant_type text param client_credentials Tak Metoda autoryzacji

Przykładowe żądanie:

POST /oauth/token HTTP/1.1
Host: tna.comarch.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic U2ltcGxlQ2xpZW50SWQ6c2VjcmV0

grant_type=client_credentials

Przykładowa odpowiedź:

 {
  "access_token": "2f1591a7-8202-4f90-b942-9e13a5ad4a14",
  "token_type": "bearer",
  "expires_in": 43090,
  "scope": "EMPLOYEE_HISTORY_MANAGEMENT EMPLOYEE_MANAGEMENT"
 }

Zarządzanie czasem pracy pracownika

API Comarch TNA umożliwia wykonanie następujących operacji związanych z zarządzaniem czasem pracy pracowników:

  • Sprawdzenie aktualnej obecności pracownika
  • Sprawdzenie historii wejść/wyjść

Sprawdzenie aktualnej obecności pracownika

W celu pobrania aktualnej obecności pracownika należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v1/history/{userHash}/presence

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userSubscriptionHash text URL Tak Identyfikator subskrypcji użytkownika do usunięcia. Zwracany na liście pracowników

Przykładowe żądanie:

https://tna.comarch.com/api/v1/history/5279a47d-eb21-448d-8cbc-fe51adbde2ed/presence

Zwracane dane:

Nazwa Typ Dozwolone wartości Wymagany Opis
presence bool Tak true - jeżeli użytkownik jest obecny w pracy, w przeciwnym wypadku false

Przykładowa odpowiedź:

{ "presence":true }

Sprawdzenie historii wejść/wyjść

W celu pobrania historii wejść/wyść pracownika należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v1/history/{userHash}

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userSubscriptionHash text URL Tak Identyfikator subskrypcji użytkownika do usunięcia. Zwracany na liście pracowników
from date URL GET Data ISO-8601 Nie Data minimalna do pobrania wejść/wyjść od początku wskazanego dnia
till date URL GET Data ISO-8601 Nie Data maksymalna do pobrania wejść/wyjść do końca wskazanego dnia

Przykładowe żądanie:

https://tna.comarch.com/api/v1/history/5279a47d-eb21-448d-8cbc-fe51adbde2ed?from=2018-06-15&till=2018-06-20

Zwracane dane:

Nazwa Typ Dozwolone wartości Wymagany Opis
timestamp long Tak Czas aktywności użytkownika w formie EPOCH TIME
direction text IN, OUT Tak Informacja o rodzaju aktywności - wejście/wyjście
entry.description text Tak Nazwa bramki
entry.building.description text Tak Nazwa lokalizacji

Przykładowa odpowiedź:

[
 {
  "timestamp": 1528903571,
  "direction": "IN",
  "entry": {
   "description": "D3.6",
   "building": {
   "description": "SSE 4"
   }
  }
 },
 {
  "timestamp": 1528903590,
  "direction": "OUT",
  "entry": {
   "description": "D3.6",
   "building": {
   "description": "SSE 4"
   }
  }
 }
]

Zarządzanie pracownikami

API Comarch TNA umożliwia wykonanie następujących operacji związanych z zarządzaniem pracownikami:

  • Pobieranie listy pracowników
  • Dodanie nowego pracownika
  • Edycja danych pracownika
  • Usunięcie pracownika
  • Pobranie danych o pracowniku

Pobieranie listy pracowników

W celu pobrania listy pracowników dostępnych w usłudze należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v1/users

Przykładowe żądanie:

https://tna.comarch.com/api/v1/users

Zwracane dane (lista obiektów):

Nazwa Typ Dozwolone wartości Wymagany Opis

userHash

text   Tak Identyfikator subskrypcji użytkownika
nameAndLastname text   Tak Imię i nazwisko
lang text pl, de, fr, en, es Tak Język
state text ACTIVE, INACTIVE Tak Stan subskrypcji
userSubscriptionTimestamp int   Tak Czas włączenia subskrypcji w formie EPOCH TIME
email text   Tak Adres e-mail
userType text user, employee, company Tak Typ użytkownika

Przykładowa odpowiedź:

[
 {
  "userHash": "5b0d6089-cfb2-47ee-892d-d7406ea0cb6f",
  "lang": "pl",
  "state": "INACTIVE",
  "userSubscriptionTimestamp": 1529917237926,
  "email": "jan.kowalski@tna.comarch.pl",
  "userType": "user",
  "nameAndLastname": "Jan Kowalski"
 },
 {
  "userHash": "j65ffi9z9p",
  "lang": "pl",
  "state": "ACTIVE",
  "userSubscriptionTimestamp": 1519992991242,
  "email": "anna.nowak@tna.comarch.pl",
  "userType": "employee",
  "nameAndLastname": "Anna Nowak"
 }
]


Dodanie nowego pracownika

W celu dodania do listy pracowników nowego pracownika należy przesłać żądanie (POST) na adres:

https://tna.comarch.com/api/v1/users

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
email text BODY   Tak Adres e-mail logowania
nameAndLastname text BODY   Nie Imię i nazwisko. Jeśli nie podane użyta zostanie część pola email przed znakiem "@"
language text BODY

pl, de, fr, en, es

Tak Język komunikacji z użytkownikiem

Przykładowe żądanie:

{
 "email":"jan.nowak@tna.comarch.com",
 "nameAndLastname":"Jan Nowak",
 "language":"pl"
}

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 201 Created


Edycja danych pracownika

W celu aktualizacji danych o pracowniku należy przesłać żądanie (PUT) na adres:

https://tna.comarch.com/api/v1/users/{userHash}

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userHash text URL   Tak Identyfikator subskrypcji użytkownika do edycji. Zwracany na liście pracowników
name text BODY   Tak Imię i nazwisko do aktualizacji dla pracownika

Przykładowe żądanie:

{
 "name":"Jan Kowalski"
}

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 200 OK


Usunięcie pracownika

W celu usunięcia pracownika należy przesłać żądanie (DELETE) na adres:

https://tna.comarch.com/api/v1/users/{userHash}

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userHash
text URL   Tak Identyfikator subskrypcji użytkownika do usunięcia. Zwracany na liście pracowników

Przykładowe żądanie:

https://tna.comarch.com/api/v1/users/5279a47d

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 200 OK


Pobranie danych o pracowniku

W celu aktualizacji danych o pracowniku należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v1/users/{userHash}

Przykładowe żądanie:

https://tna.comarch.com/api/v1/users/5279a47d

Zwracane dane:

Nazwa Typ Dozwolone wartości Wymagany Opis

userHash

text   Tak Identyfikator subskrypcji użytkownika
nameAndLastname text   Tak Imię i nazwisko
lang text   Tak Język
state text ACTIVE, INACTIVE Tak Stan subskrypcji
userSubscriptionTimestamp int   Tak Czas włączenia subskrypcji w formie EPOCH TIME
email text   Tak Adres e-mail
userType text user, employee, company Tak Typ

Przykładowa odpowiedź:

{
 "userHash": "5b0d6089-cfb2-47ee-892d-d7406ea0cb6f",
 "lang": "pl",
 "state": "INACTIVE",
 "userSubscriptionTimestamp": 1529917237926,
 "email": "jan.kowalski@tna.comarch.pl",
 "userType": "user",
 "nameAndLastname": "Jan Kowalski"
}

Powiadomienia

W celu wysłania powiadomienia push dla użytkownika należy przesłać żądanie (POST) wraz z nagłówkiem Authorization zawierającym token dla TNA-PUBLIC-API na adres:
https://tna.comarch.com/api/v2/users/{userHash}/notifications/push

Przykładowe żądanie:

 {
  "title":"Title of the message",
  "message":"This is a message",
  "rawBody":"This is a rawBody"
 }

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 201 Created.

Token dla powiadomień

Generowanie tokenu do autoryzacji w serwerze TNA-EVENTS jest możliwe poprzez wysłanie żądania (POST) wraz z nagłówkiem Authorization zawierającym token dla TNA-PUBLIC-API na adres:
https://tna.comarch.com/api/v2/events/tokens

Przykładowa odpowiedź:

 {
  "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "eventsService": {
   "host": "https://tna.comarch.com",
   "path": "/api/v2/events/scans/socket.io"
   }
 }

Pobieranie listy pracowników

W celu pobrania listy pracowników dostępnych w usłudze należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v2/users

Przykładowe żądanie:

https://tna.comarch.com/api/v2/users

Zwracane dane (lista obiektów):

Nazwa Typ Dozwolone wartości Wymagany Opis

userHash

text   Tak Identyfikator subskrypcji użytkownika
nameAndLastname text   Tak Imię i nazwisko
lang text pl, de, fr, en, es Tak Język
state text ACTIVE, INACTIVE Tak Stan subskrypcji
userSubscriptionTimestamp int   Tak Czas włączenia subskrypcji w formie EPOCH TIME
email text   Tak Adres e-mail
userType text user, employee, company Tak Typ użytkownika

Przykładowa odpowiedź:

[
 {
  "userHash": "5b0d6089-cfb2-47ee-892d-d7406ea0cb6f",
  "lang": "pl",
  "state": "INACTIVE",
  "userSubscriptionTimestamp": 1529917237926,
  "email": "jan.kowalski@tna.comarch.pl",
  "userType": "user",
  "nameAndLastname": "Jan Kowalski"
 },
 {
  "userHash": "j65ffi9z9p",
  "lang": "pl",
  "state": "ACTIVE",
  "userSubscriptionTimestamp": 1519992991242,
  "email": "anna.nowak@tna.comarch.pl",
  "userType": "employee",
  "nameAndLastname": "Anna Nowak"
 }
]


Dodanie nowego pracownika

W celu dodania do listy pracowników nowego pracownika należy przesłać żądanie (POST) na adres:

https://tna.comarch.com/api/v2/users

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
email text BODY   Tak Adres e-mail logowania
nameAndLastname text BODY   Nie Imię i nazwisko. Jeśli nie podane użyta zostanie część pola email przed znakiem "@"
language text BODY

pl, de, fr, en, es

Tak Język komunikacji z użytkownikiem
settings.timeType TimeType BODY

GROSS, NET, GROSS_NET, NONE

Tak Ustawienia wyświetlania czasu pracy użytkownika

Przykładowe żądanie:

{
  "email":"jan.nowak@tna.comarch.com",
  "nameAndLastname":"Jan Nowak",
  "language":"pl",
 "settings": {
  "timeType":"GROSS"
 }
}

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 201 Created


Edycja danych pracownika

W celu aktualizacji danych o pracowniku należy przesłać żądanie (PUT) na adres:

https://tna.comarch.com/api/v2/users/{userHash}

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userHash text URL   Tak Identyfikator subskrypcji użytkownika do edycji. Zwracany na liście pracowników
name text BODY   Tak Imię i nazwisko do aktualizacji dla pracownika

Przykładowe żądanie:

{
 "name":"Jan Kowalski"
}

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 200 OK


Usunięcie pracownika

W celu usunięcia pracownika należy przesłać żądanie (DELETE) na adres:

https://tna.comarch.com/api/v2/users/{userHash}

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
userHash text URL   Tak Identyfikator subskrypcji użytkownika do usunięcia. Zwracany na liście pracowników

Przykładowe żądanie:

https://tna.comarch.com/api/v2/users/5279a47d

Odpowiedź nie zawiera dodatkowych informacji. Zwracany jest status HTTP 200 OK


Pobranie danych o pracowniku

W celu aktualizacji danych o pracowniku należy przesłać żądanie (GET) na adres:

https://tna.comarch.com/api/v2/users/{userHash}

Przykładowe żądanie:

https://tna.comarch.com/api/v2/users/5279a47d

Zwracane dane:

Nazwa Typ Dozwolone wartości Wymagany Opis

userHash

text   Tak Identyfikator subskrypcji użytkownika
nameAndLastname text   Tak Imię i nazwisko
lang text   Tak Język
state text ACTIVE, INACTIVE Tak Stan subskrypcji
userSubscriptionTimestamp int   Tak Czas włączenia subskrypcji w formie EPOCH TIME
email text   Tak Adres e-mail
userType text user, employee, company Tak Typ

Przykładowa odpowiedź:

{
 "userHash": "5b0d6089-cfb2-47ee-892d-d7406ea0cb6f",
 "lang": "pl",
 "state": "INACTIVE",
 "userSubscriptionTimestamp": 1529917237926,
 "email": "jan.kowalski@tna.comarch.pl",
 "userType": "user",
 "nameAndLastname": "Jan Kowalski"
}

 


Pobieranie historii wejść/wyjść pracowników

W celu pobrania historii wejść/wyść pracowników należy przesłać żądanie (GET) wraz z nagłówkiem Authorization zawierającym token dla TNA-PUBLIC-API na adres:
https://tna.comarch.com/api/v2/history

Żądanie składa się z następujących parametrów:

Nazwa Typ Forma Dozwolone wartości Wymagany Opis
from date URL GET Data ISO-8601 Nie Data minimalna do pobrania wejść/wyjść od początku wskazanego dnia
till date URL GET Data ISO-8601 Nie Data maksymalna do pobrania wejść/wyjść do końca wskazanego dnia
page long param Nie Numer strony
page long param Nie Numer strony
size long param Nie Rozmiar strony

Przykładowe żądanie:

https://tna.comarch.com/api/v2/history?from=2018-06-15&till=2018-06-20&page=3&size=2

Zwracane dane:

Nazwa Typ Dozwolone wartości Opis
value array Tak Tablica obiektów z wejściami/wyjściami pracowników
userHash text Tak Identyfikator pracownika
scans array Tak Tablica wejść/wyjść pracownika
timestamp long Tak Czas aktywności użytkownika w formie EPOCH TIME
direction text IN, OUT Tak Informacja o rodzaju aktywności - wejście/wyjście
entry.description text Tak Nazwa bramki
entry.building.description text Tak Nazwa lokalizacji
page.totalElements long Tak Liczba wszystkich elementów
page.totalPages long Tak Liczba stron
page.size long Tak Rozmiar strony
page.number long Tak Numer strony
page.first boolean Tak Czy pierwsza strona
page.last boolean Tak Czy ostatnia strona
page.numberOfElements long Tak Liczba elementów na stronie

Przykładowa odpowiedź:

 {
  "value":[
    {
     "userHash":"0h70az3t2s",
     "scans":[
     {
      "timestamp": 1528903571,
      "direction": "IN",
     "entry": {
       "description": "D3.6",
       "building": {
       "description": "SSE 4"
    }
   }
   },
   {
   "timestamp": 1528903590,
   "direction": "OUT",
   "entry": {
    "description": "D3.6",
    "building": {
     "description": "SSE 4"
    }
   }
  }
  ]
 },
  {
   "userHash":"nm64xc6483",
    "scans":[
     {
     "timestamp": 1528903590,
     "direction": "IN",
     "entry": {
      "description": "D3.6",
     "building": {
      "description": "SSE 4"
     }
    }
   }
  ]
 },
  "page":{
   "totalElements": 16,
   "totalPages": 8,
   "size": 2,
   "number": 3,
   "first": false,
   "last": false,
   "numberOfElements": 2
  }
 }
Public API
  • Informacje ogólne o Comarch TNA API
  • Aktywacja API
  • Nagłówek autoryzacji
Public API - 1.2.0
  • Zarządzanie czasem pracy pracownika
  • Zarządzanie pracownikami
Public API - 2.0.0
  • Powiadomienia
  • Zarządzanie pracownikami