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:
Zakres danych dostępnych dla klucza wynika z uprawnień włączonych na kluczu. Uprawnienia klucza pojawiają się na liście uprawnień (scope) w odpowiedzi z punktu końcowego tokena.
Ustawienia serwisu (SERVICE_SETTINGS) — uprawnienie do odczytu konfiguracji usługi: urządzeń, bramek i lokalizacji, oraz do zarządzania identyfikatorami. Dostępne poziomy: Wyłączone, Odczyt, Modyfikacja.
Po aktualizacji systemu uprawnienie Ustawienia serwisu jest domyślnie wyłączone na wszystkich istniejących kluczach API. Aby korzystać z metod pobierania urządzeń, bramek i lokalizacji, administrator usługi musi włączyć je w konfiguracji klucza (Narzędzia → API).
Możliwości dotyczące zarządzania czasem pracy pracownika:
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:
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"
}
API Comarch TNA umożliwia wykonanie następujących operacji związanych z zarządzaniem czasem pracy pracowników:
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"
}
}
}
]
API Comarch TNA umożliwia wykonanie następujących operacji związanych z zarządzaniem pracownikami:
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 | |
| 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 |
|---|---|---|---|---|---|
| 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"
}
Przykładowa odpowiedź:
{
"userHash": "2w091r86vw",
"nameAndLastname": "Public Api",
"lang": "pl",
"state": "INACTIVE",
"createTimestamp": 1649055678456,
"email": null,
"userType": null
}
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 | |
| 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"
}
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 | |
| 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 |
|---|---|---|---|---|---|
| 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"
}
}
Przykładowa odpowiedź:
{
"userHash": "2w091r86vw",
"nameAndLastname": "Public Api",
"lang": "pl",
"state": "INACTIVE",
"createTimestamp": 1649055678456,
"email": null,
"userType": null
}
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 | |
| 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
}
}
Pobieranie szczegółowego raportu obecności pracownika
W celu pobrania raportu z podziałem na dni pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/users/w49ww977e9?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane:
Przykładowa odpowiedź:
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS_NET",
"subscription":{
"userHash":"vd0hb1jbvx",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2019-03-19",
}
},
"days": [
{
"time": {
"timeType": "GROSS_NET",
"grossTime": 29717,
"netTime": 29717
},
"date": "2020-01-01",
"status": "PRESENCE",
"workPlan": {
"workingDay": true,
"fixedTime": 30600
},
"in": "08:45:08",
"out": "17:00:25",
"balance": -883,
"lateness": false
},
{…}
],
"summary": {
"workTime": 29717,
"notEqualizedWorkTime": 0,
"month": 12,
"workedDays": 1,
"differentDays": 0,
"workPlanTime": 30600,
"balance": -883,
"notEqualizedBalance": -883,
"workTimeGross": 29717,
"workTimeNet": 29717,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
}
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podsumowaniem czasu pracy pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/users/{userHash}/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/users/w49ww977e9/summary?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane:
Przykładowa odpowiedź:
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS_NET",
"subscription":{
"userHash":"vd0hb1jbvx",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2019-03-19",
}
},
"months": [
{
"workTime": 612000,
"notEqualizedWorkTime": 0,
"month": 12,
"workedDays": 20,
"differentDays": 0,
"workPlanTime": 612000,
"balance": 0,
"notEqualizedBalance": 0,
"workTimeGross": 612000,
"workTimeNet": 612000,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
},
{…}
],
"summary": {
"workTime": 612000,
"notEqualizedWorkTime": 0,
"workedDays": 20,
"differentDays": 0,
"workPlanTime": 612000,
"balance": 0,
"notEqualizedBalance": 0,
"workTimeGross": 612000,
"workTimeNet": 612000,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
}
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podziałem na dni pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| date | date | Path | 2020-01-01 | Tak | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie | ||
| search | text | URL | ||||
| includeArchival | bool | URL | true, false | false | nie | Dołącza do raportu użytkowników archiwalnych |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports?date=2020-01-01
Zwracane dane:
Przykładowa odpowiedź:
{
"content":[
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS",
"subscription":{
"userHash":"y518uam23d",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"archival": false,
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"validFrom": "2019-03-18",
}
},
"days": [
{
"time":{
"timeType": "GROSS_NET",
"grossTime": 29717,
"netTime": 29717
},
"date": "2020-01-01",
"status": "PRESENCE",
"workPlan": {
"workingDay": true,
"fixedTime": 30600
},
"in": "08:45:08",
"out": "17:00:25",
"balance": -883,
"lateness": false
}
]
}
},
"last": false,
"totalElements": 89,
"totalPages": 89,
"sort": [
{
"direction": "ASC",
"property": "name"
}
],
"numberOfElements": 1,
"first": true,
"size": 1,
"number": 0
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podsumowaniem czasu pracy pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| date | date | Path | 2020-01-01 | Tak | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie | ||
| search | text | URL | ||||
| includeArchival | bool | URL | true, false | false | nie | Dołącza do raportu użytkowników archiwalnych |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/summary ?fromDate=2020-01-01&tillDate=2020-09-30
Zwracane dane:
Przykładowa odpowiedź:
{
"content":[
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS",
"subscription":{
"userHash":"rxw7q52krm",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"archival": false,
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2018-08-10",
}
},
"summary": {
"time":{
"workTime": 185126,
"month": 1,
"workedDays": 5,
"differentDays": 1,
"workPlanTime": 5844600,
"balance": -5659474,
"workTimeGross": 185126,
"workTimeNet": 185126
}
},
{...}
},
"totalElements": 89,
"last": false,
"totalPages": 9,
"sort": [
{
"direction": "ASC",
"property": "name"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"first": true,
"numberOfElements": 10,
"size": 10,
"number": 0
},
Typy wyliczeniowe
api/v2/presences
type:
| LEAVE_ON_DEMAND, | Urlop na żądania |
| VACATION, | Urlop wypoczynkowy |
| SICK_LEAVE, | Zwolnienie chorobowe |
| SPECIAL_LEAVE, | |
| OFFICIAL_TRIP, | Delegacja |
| MANUALLY_ADDED, | Obecność zgłoszona ręcznie |
| OTHER_CIRCUMSTANCES, | |
| TRAINING, | Szkolenie |
| OTHER, | Inne |
| HOME_OFFICE, | Praca zdalna |
| OPTIMA_E_NIEOBECNOSC, OPTIMA_INNA_NIEOBECNOSC, OPTIMA_NIEOBECNOSC_USPRAWIEDLIWIONA, OPTIMA_NIEOBECNOSC_NIEUSPRAWIEDLIWIONA, OPTIMA_SLUZBA_WOJSKOWA, OPTIMA_URLOP_BEZPLATNY_111, OPTIMA_URLOP_BEZPLATNY_112, OPTIMA_URLOP_MACIERZYNSKI, OPTIMA_URLOP_MACIERZYNSKI_DODATKOWY, OPTIMA_URLOP_OJCOWSKI, OPTIMA_URLOP_OKOLICZNOSCIOWY, OPTIMA_URLOP_OPIEKUNCZY_ZASILEK, OPTIMA_URLOP_OPIEKUNCZY_188_2DNI, OPTIMA_URLOP_OPIEKUNCZY_188_2DNIGODZ, OPTIMA_URLOP_REHABILITACYJNY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_PRZY_PRACY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_W_DRODZE, OPTIMA_URLOP_RODZICIELSKI, OPTIMA_URLOP_SZKOLENIOWY, OPTIMA_URLOP_WYCHOWAWCZY_121, OPTIMA_URLOP_WYCHOWAWCZY_122, OPTIMA_URLOP_WYPOCZYNKOWY, OPTIMA_URLOP_WYPOCZYNKOWY_PLAN, OPTIMA_URLOP_WYPOCZYNKOWY_TYMCZASOWY, OPTIMA_ZWOLNIENIE_CHOROBOWE, |
presenceStatus:
| ACCEPTED | Zaakceptowany |
| WAITING | Nowy/oczekujący |
| ACCEPTED_AUTOMATICALLY | Zaakceptowany automatycznie |
| ACCEPTED_CORRECTED | Zaakceptowany poprawiony |
| REJECTED | Odrzucony |
| CANCELED | Anulowany |
| REMOVED | Usunięty |
api/v2/delegations
type:
| DOMESTIC | Krajowa |
| FOREIGN | Zagraniczna |
Status:
| NEW | Nowa |
| REJECTED | Odrzucona |
| ACCEPTED | Zaakceptowana |
| FOR_SETTLEMENT | Do rozliczenia |
| SETTLED | Rozliczona |
| CANCELED | Anulowana |
modeOfTransportation:
| PRIVATE_CAR | Samochód prywatny |
| COMPANY_CAR | Samochód służbowy |
| PLANE | Samolot |
| TRAIN | Pociąg |
| BUS | Autobus |
| TAXI | Taksówka |
| PUBLIC_TRANSPORT | Transport publiczny |
| OTHER | Inne |
api/v2/reports
status:
| WORKING_DAY, | Dzień pracujący |
| HOLIDAY, | Święto |
| EMPTY, | Brak planu pracy |
| DAY_OFF, | Dzień wolny |
| PRESENCE, | Obecność |
| UNEXCUSED_ABSENCE, | Nieobecność |
| LEAVE_ON_DEMAND, | Urlop na żądania |
| VACATION, | Urlop wypoczynkowy |
| SICK_LEAVE, | Zwolnienie chorobowe |
| SPECIAL_LEAVE, | |
| OFFICIAL_TRIP, | Delegacja |
| MANUALLY_ADDED, | Obecność zgłoszona ręcznie |
| OTHER_CIRCUMSTANCES, | |
| TRAINING, | Szkolenie |
| OTHER, | Inne |
| HOME_OFFICE, | Praca zdalna |
| OPTIMA_E_NIEOBECNOSC, OPTIMA_INNA_NIEOBECNOSC, OPTIMA_NIEOBECNOSC_USPRAWIEDLIWIONA, OPTIMA_NIEOBECNOSC_NIEUSPRAWIEDLIWIONA, OPTIMA_SLUZBA_WOJSKOWA, OPTIMA_URLOP_BEZPLATNY_111, OPTIMA_URLOP_BEZPLATNY_112, OPTIMA_URLOP_MACIERZYNSKI, OPTIMA_URLOP_MACIERZYNSKI_DODATKOWY, OPTIMA_URLOP_OJCOWSKI, OPTIMA_URLOP_OKOLICZNOSCIOWY, OPTIMA_URLOP_OPIEKUNCZY_ZASILEK, OPTIMA_URLOP_OPIEKUNCZY_188_2DNI, OPTIMA_URLOP_OPIEKUNCZY_188_2DNIGODZ, OPTIMA_URLOP_REHABILITACYJNY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_PRZY_PRACY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_W_DRODZE, OPTIMA_URLOP_RODZICIELSKI, OPTIMA_URLOP_SZKOLENIOWY, OPTIMA_URLOP_WYCHOWAWCZY_121, OPTIMA_URLOP_WYCHOWAWCZY_122, OPTIMA_URLOP_WYPOCZYNKOWY, OPTIMA_URLOP_WYPOCZYNKOWY_PLAN, OPTIMA_URLOP_WYPOCZYNKOWY_TYMCZASOWY, OPTIMA_ZWOLNIENIE_CHOROBOWE, |
Pobieranie listy zgłoszeń pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/presences
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|
| fromDate | date | 2020-07-01 | Tak | ||
| tillDate | date | 2020-07-01 | Tak | ||
| type | text | PresenceType | Nie | ||
| excludeType | text | PresenceType | Nie | ||
| status | text | PresenceStatus | Nie | ||
| excludeStatus | text | PresenceStatus | Nie | ||
| size | int | 20 | Nie | ||
| page | int | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/presences?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"subscription": {
"userHash": "o29hhutr9c",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-06-25"
}
},
"dates": [
"2020-10-01"
],
"type": "VACATION",
"presenceStatus": "WAITING",
"hash": "62mvsid33fgpr8ntr4ga1n87s9",
"from": "2020-10-01",
"to": "2020-10-01",
"createDateTime": "2020-10-01T12:35:02.887"
},
{…}
],
"totalElements": 9,
"totalPages": 5,
"last": false,
"size": 2,
"number": 0,
"sort": [
{
"direction": "DESC",
"property": "date"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}
{
"direction": "ASC",
"property": "nameAndLastName",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"numberOfElements": 2,
"first": true
}
Pobieranie listy zgłoszeń pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/presences/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| type | text | URL | PresenceType | Nie | ||
| excludeType | text | URL | PresenceType | Nie | ||
| status | text | URL | PresenceStatus | Nie | ||
| excludeStatus | text | URL | PresenceStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/presences/users/o29hhutr9c?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"subscription": {
"userHash": "o29hhutr9c",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-06-25"
}
},
"dates": [
"2020-10-01"
],
"type": "VACATION",
"presenceStatus": "WAITING",
"hash": "62mvsid33fgpr8ntr4ga1n87s9",
"from": "2020-10-01",
"to": "2020-10-01",
"createDateTime": "2020-10-01T12:35:02.887"
},
{…}
],
"totalElements": 9,
"totalPages": 5,
"last": false,
"size": 2,
"number": 0,
"sort": [
{
"direction": "DESC",
"property": "date"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}
{
"direction": "ASC",
"property": "nameAndLastName",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"numberOfElements": 2,
"first": true
}
Pobieranie listy delegacji pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/delegations
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| status | text | URL | DelegationStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/delegations?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"hash": "trgi7g3gc2sbddkcj5fm56lorh",
"subscription": {
"userHash": "w49ww977e9",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-08-01"
}
},
"reportingPerson": {
"userHash": "w49ww977e9",
"name": " Jan Kowalski"
},
"from": "2018-08-01",
"to": "2018-08-01",
"type": "DOMESTIC",
"remark": "komentarz",
"modeOfTransportation": "PRIVATE_CAR",
"address": "Kraków",
"createDateTime": "2017-08-07T10:16:00.514Z",
"status": "NEW"
},
{…}
],
"totalElements": 90,
"last": false,
"totalPages": 90,
"size": 10,
"number": 0,
"sort": null,
"numberOfElements": 1,
"first": true
}
Pobieranie listy delegacji pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/delegations/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| status | text | URL | DelegationStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/delegations/users/w49ww977e9?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"hash": "trgi7g3gc2sbddkcj5fm56lorh",
"subscription": {
"userHash": "w49ww977e9",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-08-01"
}
},
"reportingPerson": {
"userHash": "w49ww977e9",
"name": " Jan Kowalski"
},
"from": "2018-08-01",
"to": "2018-08-01",
"type": "DOMESTIC",
"remark": "komentarz",
"modeOfTransportation": "PRIVATE_CAR",
"address": "Kraków",
"createDateTime": "2017-08-07T10:16:00.514Z",
"status": "WAITING"
},
{…}
],
"totalElements": 90,
"last": false,
"totalPages": 90,
"size": 10,
"number": 0,
"sort": null,
"numberOfElements": 1,
"first": true
}
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 | |
| text | Tak | Adres e-mail | ||
| userType | text | user, employee, company | Tak | Typ użytkownika |
| identifiers | lista | - | Nie | Lista identyfikatorów przypisanych do pracownika. Pole jest zawsze zwracane jako tablica; gdy pracownik nie ma przypisanych identyfikatorów, zwracana jest pusta tablica []. Lista nie zawiera identyfikatorów typu MOBILE_CARD. |
| etats | lista | - | Nie | Etaty pracownika wraz z firmą i centrum, do których należą. Pole jest zawsze zwracane jako tablica; gdy pracownik nie ma etatów, zwracana jest pusta tablica []. |
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| identifiers[].identifierType | text | CARD, TAG, STICKER, OTHER | Nie | Typ identyfikatora. |
| identifiers[].description | text | - | Nie | Opis identyfikatora. |
| identifiers[].status | text | DISABLED, ACTIVE_AVAILABLE, ACTIVE_IN_USE, SUSPENDED, IN_SHIPPING, ASSIGNED, LOSS | Nie | Status identyfikatora. |
| identifiers[].tagId | text | - | Nie | Identyfikator znacznika (tag) zapisany w identyfikatorze. |
| identifiers[].hash | text | - | Nie | Unikalny skrót (hash) identyfikatora. |
| identifiers[].stickerId | text | - | Nie | Numer naklejki (sticker) identyfikatora. |
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| etats[].etatHash | text | — | Nie | Identyfikator etatu. |
| etats[].state | text | ACTIVE, INACTIVE, ARCHIVAL | Nie | Stan etatu. |
| etats[].type | text | PRIMARY, ADDITIONAL, DEFAULT | Nie | Typ etatu: PRIMARY — podstawowy, ADDITIONAL — dodatkowy. |
| etats[].position | text | — | Nie | Stanowisko. |
| etats[].etatNumerator | int | — | Nie | Licznik wymiaru etatu — np. 1 dla wymiaru 1/2. |
| etats[].etatDenominator | int | — | Nie | Mianownik wymiaru etatu — np. 2 dla wymiaru 1/2. |
| etats[].validDateRanges | lista | — | Nie | Okresy obowiązywania etatu. Każdy element ma pola from i to w formacie yyyy-MM-dd. |
| etats[].company | obiekt | — | Nie | Firma, do której należy etat: hash, name, location. |
| etats[].center | obiekt | — | Nie | Centrum, do którego należy etat: hash, code, name. |
Przykładowa odpowiedź:
Pracownik z przypisanymi identyfikatorami i etatami (element listy z GET /api/v2/users):
{
"userHash": "a1b2c3d4e5f6a7b8c9d0",
"nameAndLastname": "Jan Kowalski",
"lang": "pl",
"state": "ACTIVE",
"createTimestamp": 1700000000000,
"email": "jan.kowalski@example.com",
"userType": "EMPLOYEE",
"identifiers": [
{
"identifierType": "CARD",
"description": "Karta wejściowa",
"status": "ACTIVE_IN_USE",
"tagId": "04A1B2C3D4E5F6",
"hash": "id1a2b3c4d5e6f7a8b9c0",
"stickerId": "ST-000123"
}
],
"etats": [
{
"etatHash": "e1a2b3c4d5e6f7a8b9c0",
"state": "ACTIVE",
"type": "PRIMARY",
"position": "Specjalista",
"etatNumerator": 1,
"etatDenominator": 1,
"validDateRanges": [
{
"from": "2026-01-01",
"to": "2026-12-31"
}
],
"company": {
"hash": "c1a2b3c4d5e6f7a8b9c0",
"name": "Comarch S.A.",
"location": "Kraków"
},
"center": {
"hash": "ce1a2b3c4d5e6f7a8b9",
"code": "DZ-IT",
"name": "Dział IT"
}
}
]
}
Pracownik bez przypisanych identyfikatorów i etatów — pola identifiers i etats zwracane jako puste tablice:
{
"userHash": "b2c3d4e5f6a7b8c9d0e1",
"nameAndLastname": "Anna Nowak",
"lang": "pl",
"state": "ACTIVE",
"createTimestamp": 1700000500000,
"email": "anna.nowak@example.com",
"userType": "EMPLOYEE",
"identifiers": [],
"etats": []
}
Pole etats jest zwracane wyłącznie na liście pracowników. Zasób „Pobranie danych o pracowniku" (GET https://tna.comarch.com/api/v2/users/{userHash}) tego pola nie zwraca — integrator, który potrzebuje etatów konkretnego pracownika, korzysta z listy.
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 |
|---|---|---|---|---|---|
| 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"
}
}
Przykładowa odpowiedź:
{
"userHash": "2w091r86vw",
"nameAndLastname": "Public Api",
"lang": "pl",
"state": "INACTIVE",
"createTimestamp": 1649055678456,
"email": null,
"userType": null
}
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 | |
| text | Tak | Adres e-mail | ||
| userType | text | user, employee, company | Tak | Typ |
| identifiers | lista | - | Nie | Lista identyfikatorów przypisanych do pracownika. Pole jest zawsze zwracane jako tablica; gdy pracownik nie ma przypisanych identyfikatorów, zwracana jest pusta tablica []. Lista nie zawiera identyfikatorów typu MOBILE_CARD. |
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| identifiers[].identifierType | text | CARD, TAG, STICKER, OTHER | Nie | Typ identyfikatora. |
| identifiers[].description | text | - | Nie | Opis identyfikatora. |
| identifiers[].status | text | DISABLED, ACTIVE_AVAILABLE, ACTIVE_IN_USE, SUSPENDED, IN_SHIPPING, ASSIGNED, LOSS | Nie | Status identyfikatora. |
| identifiers[].tagId | text | - | Nie | Identyfikator znacznika (tag) zapisany w identyfikatorze. |
| identifiers[].hash | text | - | Nie | Unikalny skrót (hash) identyfikatora. |
| identifiers[].stickerId | text | - | Nie | Numer naklejki (sticker) identyfikatora. |
Przykładowa odpowiedź:
Pracownik z przypisanymi identyfikatorami (GET /api/v2/users/{userHash}):
Pracownik bez przypisanych identyfikatorów — pole identifiers zwracane jako pusta tablica:
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
}
}
Pobieranie szczegółowego raportu obecności pracownika
W celu pobrania raportu z podziałem na dni pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/users/w49ww977e9?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane:
Przykładowa odpowiedź:
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS_NET",
"subscription":{
"userHash":"vd0hb1jbvx",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2019-03-19",
}
},
"days": [
{
"time": {
"timeType": "GROSS_NET",
"grossTime": 29717,
"netTime": 29717
},
"date": "2020-01-01",
"status": "PRESENCE",
"workPlan": {
"workingDay": true,
"fixedTime": 30600
},
"in": "08:45:08",
"out": "17:00:25",
"balance": -883,
"lateness": false
},
{…}
],
"summary": {
"workTime": 29717,
"notEqualizedWorkTime": 0,
"month": 12,
"workedDays": 1,
"differentDays": 0,
"workPlanTime": 30600,
"balance": -883,
"notEqualizedBalance": -883,
"workTimeGross": 29717,
"workTimeNet": 29717,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
}
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podsumowaniem czasu pracy pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/users/{userHash}/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/users/w49ww977e9/summary?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane:
Przykładowa odpowiedź:
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS_NET",
"subscription":{
"userHash":"vd0hb1jbvx",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2019-03-19",
}
},
"months": [
{
"workTime": 612000,
"notEqualizedWorkTime": 0,
"month": 12,
"workedDays": 20,
"differentDays": 0,
"workPlanTime": 612000,
"balance": 0,
"notEqualizedBalance": 0,
"workTimeGross": 612000,
"workTimeNet": 612000,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
},
{…}
],
"summary": {
"workTime": 612000,
"notEqualizedWorkTime": 0,
"workedDays": 20,
"differentDays": 0,
"workPlanTime": 612000,
"balance": 0,
"notEqualizedBalance": 0,
"workTimeGross": 612000,
"workTimeNet": 612000,
"notEqualizedWorkTimeGross": 0,
"notEqualizedWorkTimeNet": 0
}
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podziałem na dni pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| date | date | Path | 2020-01-01 | Tak | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie | ||
| search | text | URL | ||||
| includeArchival | bool | URL | true, false | false | nie | Dołącza do raportu użytkowników archiwalnych |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports?date=2020-01-01
Zwracane dane:
Przykładowa odpowiedź:
{
"content":[
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS",
"subscription":{
"userHash":"y518uam23d",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"archival": false,
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"validFrom": "2019-03-18",
}
},
"days": [
{
"time":{
"timeType": "GROSS_NET",
"grossTime": 29717,
"netTime": 29717
},
"date": "2020-01-01",
"status": "PRESENCE",
"workPlan": {
"workingDay": true,
"fixedTime": 30600
},
"in": "08:45:08",
"out": "17:00:25",
"balance": -883,
"lateness": false
}
]
}
},
"last": false,
"totalElements": 89,
"totalPages": 89,
"sort": [
{
"direction": "ASC",
"property": "name"
}
],
"numberOfElements": 1,
"first": true,
"size": 1,
"number": 0
},
Pobieranie ogólnego raportu obecności pracownika
W celu pobrania raportu z podsumowaniem czasu pracy pracowników należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/reports/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| date | date | Path | 2020-01-01 | Tak | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie | ||
| search | text | URL | ||||
| includeArchival | bool | URL | true, false | false | nie | Dołącza do raportu użytkowników archiwalnych |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/summary ?fromDate=2020-01-01&tillDate=2020-09-30
Zwracane dane:
Przykładowa odpowiedź:
{
"content":[
{
"timeType":"GROSS_NET",
"userTimeType":"GROSS",
"subscription":{
"userHash":"rxw7q52krm",
"name":"Jan Kowalski",
"email":"test@comarch.pl",
"archival": false,
"etat":{
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2018-08-10",
}
},
"summary": {
"time":{
"workTime": 185126,
"month": 1,
"workedDays": 5,
"differentDays": 1,
"workPlanTime": 5844600,
"balance": -5659474,
"workTimeGross": 185126,
"workTimeNet": 185126
}
},
{...}
},
"totalElements": 89,
"last": false,
"totalPages": 9,
"sort": [
{
"direction": "ASC",
"property": "name"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"first": true,
"numberOfElements": 10,
"size": 10,
"number": 0
},
Typy wyliczeniowe
api/v2/presences
type:
| LEAVE_ON_DEMAND, | Urlop na żądania |
| VACATION, | Urlop wypoczynkowy |
| SICK_LEAVE, | Zwolnienie chorobowe |
| SPECIAL_LEAVE, | |
| OFFICIAL_TRIP, | Delegacja |
| MANUALLY_ADDED, | Obecność zgłoszona ręcznie |
| OTHER_CIRCUMSTANCES, | |
| TRAINING, | Szkolenie |
| OTHER, | Inne |
| HOME_OFFICE, | Praca zdalna |
| OPTIMA_E_NIEOBECNOSC, OPTIMA_INNA_NIEOBECNOSC, OPTIMA_NIEOBECNOSC_USPRAWIEDLIWIONA, OPTIMA_NIEOBECNOSC_NIEUSPRAWIEDLIWIONA, OPTIMA_SLUZBA_WOJSKOWA, OPTIMA_URLOP_BEZPLATNY_111, OPTIMA_URLOP_BEZPLATNY_112, OPTIMA_URLOP_MACIERZYNSKI, OPTIMA_URLOP_MACIERZYNSKI_DODATKOWY, OPTIMA_URLOP_OJCOWSKI, OPTIMA_URLOP_OKOLICZNOSCIOWY, OPTIMA_URLOP_OPIEKUNCZY_ZASILEK, OPTIMA_URLOP_OPIEKUNCZY_188_2DNI, OPTIMA_URLOP_OPIEKUNCZY_188_2DNIGODZ, OPTIMA_URLOP_REHABILITACYJNY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_PRZY_PRACY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_W_DRODZE, OPTIMA_URLOP_RODZICIELSKI, OPTIMA_URLOP_SZKOLENIOWY, OPTIMA_URLOP_WYCHOWAWCZY_121, OPTIMA_URLOP_WYCHOWAWCZY_122, OPTIMA_URLOP_WYPOCZYNKOWY, OPTIMA_URLOP_WYPOCZYNKOWY_PLAN, OPTIMA_URLOP_WYPOCZYNKOWY_TYMCZASOWY, OPTIMA_ZWOLNIENIE_CHOROBOWE, |
presenceStatus:
| ACCEPTED | Zaakceptowany |
| WAITING | Nowy/oczekujący |
| ACCEPTED_AUTOMATICALLY | Zaakceptowany automatycznie |
| ACCEPTED_CORRECTED | Zaakceptowany poprawiony |
| REJECTED | Odrzucony |
| CANCELED | Anulowany |
| REMOVED | Usunięty |
api/v2/delegations
type:
| DOMESTIC | Krajowa |
| FOREIGN | Zagraniczna |
Status:
| NEW | Nowa |
| REJECTED | Odrzucona |
| ACCEPTED | Zaakceptowana |
| FOR_SETTLEMENT | Do rozliczenia |
| SETTLED | Rozliczona |
| CANCELED | Anulowana |
modeOfTransportation:
| PRIVATE_CAR | Samochód prywatny |
| COMPANY_CAR | Samochód służbowy |
| PLANE | Samolot |
| TRAIN | Pociąg |
| BUS | Autobus |
| TAXI | Taksówka |
| PUBLIC_TRANSPORT | Transport publiczny |
| OTHER | Inne |
api/v2/reports
status:
| WORKING_DAY, | Dzień pracujący |
| HOLIDAY, | Święto |
| EMPTY, | Brak planu pracy |
| DAY_OFF, | Dzień wolny |
| PRESENCE, | Obecność |
| UNEXCUSED_ABSENCE, | Nieobecność |
| LEAVE_ON_DEMAND, | Urlop na żądania |
| VACATION, | Urlop wypoczynkowy |
| SICK_LEAVE, | Zwolnienie chorobowe |
| SPECIAL_LEAVE, | |
| OFFICIAL_TRIP, | Delegacja |
| MANUALLY_ADDED, | Obecność zgłoszona ręcznie |
| OTHER_CIRCUMSTANCES, | |
| TRAINING, | Szkolenie |
| OTHER, | Inne |
| HOME_OFFICE, | Praca zdalna |
| OPTIMA_E_NIEOBECNOSC, OPTIMA_INNA_NIEOBECNOSC, OPTIMA_NIEOBECNOSC_USPRAWIEDLIWIONA, OPTIMA_NIEOBECNOSC_NIEUSPRAWIEDLIWIONA, OPTIMA_SLUZBA_WOJSKOWA, OPTIMA_URLOP_BEZPLATNY_111, OPTIMA_URLOP_BEZPLATNY_112, OPTIMA_URLOP_MACIERZYNSKI, OPTIMA_URLOP_MACIERZYNSKI_DODATKOWY, OPTIMA_URLOP_OJCOWSKI, OPTIMA_URLOP_OKOLICZNOSCIOWY, OPTIMA_URLOP_OPIEKUNCZY_ZASILEK, OPTIMA_URLOP_OPIEKUNCZY_188_2DNI, OPTIMA_URLOP_OPIEKUNCZY_188_2DNIGODZ, OPTIMA_URLOP_REHABILITACYJNY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_PRZY_PRACY, OPTIMA_URLOP_REHABILITACYJNY_WYPADEK_W_DRODZE, OPTIMA_URLOP_RODZICIELSKI, OPTIMA_URLOP_SZKOLENIOWY, OPTIMA_URLOP_WYCHOWAWCZY_121, OPTIMA_URLOP_WYCHOWAWCZY_122, OPTIMA_URLOP_WYPOCZYNKOWY, OPTIMA_URLOP_WYPOCZYNKOWY_PLAN, OPTIMA_URLOP_WYPOCZYNKOWY_TYMCZASOWY, OPTIMA_ZWOLNIENIE_CHOROBOWE, |
Zasoby w tej sekcji umożliwiają pobieranie danych o identyfikatorach przypisanych w ramach serwisu. Dostęp do zasobów wymaga uprawnienia SERVICE_SETTINGS (Ustawienia serwisu) — uprawnienie to pojawia się na liście uprawnień (scope) w odpowiedzi z punktu końcowego tokena. Wymagane wcześniej uprawnienie IDENTIFIERS_MANAGEMENT nie jest już używane. Identyfikatory typu MOBILE_CARD nie są zwracane przez żaden z poniższych zasobów.
Pobranie danych o identyfikatorze
Aby pobrać dane pojedynczego identyfikatora, należy przesłać żądanie (GET) na adres https://tna.comarch.com/api/v2/identifiers/{hash}.
Parametry ścieżki:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
| hash | text | — | Tak | Unikalny skrót (hash) identyfikatora. |
Odpowiedź:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
| identifierType | text | CARD, TAG, STICKER, OTHER | Nie | Typ identyfikatora. |
| description | text | — | Nie | Opis identyfikatora. |
| status | text | DISABLED, ACTIVE_AVAILABLE, ACTIVE_IN_USE, SUSPENDED, IN_SHIPPING, ASSIGNED, LOSS | Nie | Status identyfikatora. |
| tagId | text | — | Nie | Identyfikator znacznika (tag) zapisany w identyfikatorze. |
| hash | text | — | Nie | Unikalny skrót (hash) identyfikatora. |
| stickerId | text | — | Nie | Numer naklejki (sticker) identyfikatora. |
| user | obiekt | — | Nie | Dane pracownika, do którego identyfikator jest przypisany. Pole jest pomijane, gdy identyfikator nie jest przypisany do żadnego pracownika. |
| user.userHash | text | — | Nie | Unikalny skrót (hash) pracownika. |
| user.nameAndLastName | text | — | Nie | Imię i nazwisko pracownika. |
| user.firstName | text | — | Nie | Imię pracownika. |
| user.lastName | text | — | Nie | Nazwisko pracownika. |
| user.email | text | — | Nie | Adres e-mail pracownika. |
Jeżeli identyfikator o podanym hash nie istnieje, nie należy do serwisu wywołującego lub jest identyfikatorem typu MOBILE_CARD, zwracany jest kod odpowiedzi 404 (Not Found). Zasób ten może zwrócić identyfikator w dowolnym statusie poza identyfikatorami typu MOBILE_CARD.
Przykład — identyfikator przypisany do pracownika:
Pobieranie listy identyfikatorów
Aby pobrać listę identyfikatorów serwisu, należy przesłać żądanie (GET) na adres https://tna.comarch.com/api/v2/identifiers.
Parametry zapytania:
| Nazwa | Typ | Forma | Domyślna wartość | Wymagany | Opis |
| page | int | query | 0 | Nie | Numer pobieranej strony (numeracja od 0). |
| size | int | query | 20 | Nie | Liczba elementów na stronie. |
Lista jest domyślnie sortowana rosnąco po polu stickerId. Lista nie zawiera identyfikatorów typu MOBILE_CARD ani identyfikatorów w statusie IN_SHIPPING.
Struktura pojedynczego elementu listy (content[]) jest taka sama jak w odpowiedzi zasobu „Pobranie danych o identyfikatorze” (pola identifierType, description, status, tagId, hash, stickerId oraz opcjonalny obiekt user).
Przykład odpowiedzi:
Pobieranie listy zgłoszeń pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/presences
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|
| fromDate | date | 2020-07-01 | Tak | ||
| tillDate | date | 2020-07-01 | Tak | ||
| type | text | PresenceType | Nie | ||
| excludeType | text | PresenceType | Nie | ||
| status | text | PresenceStatus | Nie | ||
| excludeStatus | text | PresenceStatus | Nie | ||
| size | int | 20 | Nie | ||
| page | int | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/presences?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"subscription": {
"userHash": "o29hhutr9c",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-06-25"
}
},
"dates": [
"2020-10-01"
],
"type": "VACATION",
"presenceStatus": "WAITING",
"hash": "62mvsid33fgpr8ntr4ga1n87s9",
"from": "2020-10-01",
"to": "2020-10-01",
"createDateTime": "2020-10-01T12:35:02.887"
},
{…}
],
"totalElements": 9,
"totalPages": 5,
"last": false,
"size": 2,
"number": 0,
"sort": [
{
"direction": "DESC",
"property": "date"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}
{
"direction": "ASC",
"property": "nameAndLastName",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"numberOfElements": 2,
"first": true
}
Pobieranie listy zgłoszeń pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/presences/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| type | text | URL | PresenceType | Nie | ||
| excludeType | text | URL | PresenceType | Nie | ||
| status | text | URL | PresenceStatus | Nie | ||
| excludeStatus | text | URL | PresenceStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/presences/users/o29hhutr9c?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"subscription": {
"userHash": "o29hhutr9c",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-06-25"
}
},
"dates": [
"2020-10-01"
],
"type": "VACATION",
"presenceStatus": "WAITING",
"hash": "62mvsid33fgpr8ntr4ga1n87s9",
"from": "2020-10-01",
"to": "2020-10-01",
"createDateTime": "2020-10-01T12:35:02.887"
},
{…}
],
"totalElements": 9,
"totalPages": 5,
"last": false,
"size": 2,
"number": 0,
"sort": [
{
"direction": "DESC",
"property": "date"
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}
{
"direction": "ASC",
"property": "nameAndLastName",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": true
}
],
"numberOfElements": 2,
"first": true
}
Pobieranie listy delegacji pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/delegations
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| status | text | URL | DelegationStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/delegations?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"hash": "trgi7g3gc2sbddkcj5fm56lorh",
"subscription": {
"userHash": "w49ww977e9",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-08-01"
}
},
"reportingPerson": {
"userHash": "w49ww977e9",
"name": " Jan Kowalski"
},
"from": "2018-08-01",
"to": "2018-08-01",
"type": "DOMESTIC",
"remark": "komentarz",
"modeOfTransportation": "PRIVATE_CAR",
"address": "Kraków",
"createDateTime": "2017-08-07T10:16:00.514Z",
"status": "NEW"
},
{…}
],
"totalElements": 90,
"last": false,
"totalPages": 90,
"size": 10,
"number": 0,
"sort": null,
"numberOfElements": 1,
"first": true
}
Pobieranie listy delegacji pracowników
W celu pobrania listy delegacji pracownika należy przesłać żądanie (GET) na adres:https://tna.comarch.com/api/v2/delegations/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| userHash | text | Path | Tak | |||
| fromDate | date | URL | 2020-07-01 | Tak | ||
| tillDate | date | URL | 2020-07-01 | Tak | ||
| status | text | URL | DelegationStatus | Nie | ||
| size | int | URL | 20 | Nie | ||
| page | int | URL | 0 | Nie |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/delegations/users/w49ww977e9?fromDate=2020-01-01&tillDate=2020-12-31&size=10&page=1
Zwracane dane (strona obiektów):
Przykładowa odpowiedź:
{
"content":[
{
"hash": "trgi7g3gc2sbddkcj5fm56lorh",
"subscription": {
"userHash": "w49ww977e9",
"name": "Jan Kowalski",
"email": "test@comarch.pl",
"etat": {
"position": "Kierownik",
"etatNumerator": 1,
"etatDenominator": 1,
"fullTimeDailyNorm": 480,
"type": "DEFAULT",
"validFrom": "2020-08-01"
}
},
"reportingPerson": {
"userHash": "w49ww977e9",
"name": " Jan Kowalski"
},
"from": "2018-08-01",
"to": "2018-08-01",
"type": "DOMESTIC",
"remark": "komentarz",
"modeOfTransportation": "PRIVATE_CAR",
"address": "Kraków",
"createDateTime": "2017-08-07T10:16:00.514Z",
"status": "WAITING"
},
{…}
],
"totalElements": 90,
"last": false,
"totalPages": 90,
"size": 10,
"number": 0,
"sort": null,
"numberOfElements": 1,
"first": true
}
Zasoby w tej sekcji umożliwiają pobieranie konfiguracji usługi: urządzeń, bramek i lokalizacji. Dostęp do zasobów wymaga uprawnienia SERVICE_SETTINGS (Ustawienia serwisu) — uprawnienie to pojawia się na liście uprawnień (scope) w odpowiedzi z punktu końcowego tokena.
Zwracane są wyłącznie rekordy aktywne. Pola o wartości pustej są pomijane w odpowiedzi. Listy nie są stronicowane — cała lista zwracana jest w polu content.
Pobieranie listy urządzeń
W celu pobrania listy urządzeń usługi należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/devices
Żądanie nie przyjmuje parametrów. Lista jest sortowana rosnąco po polu deviceId.
Przykładowe żądanie:
https://tna.comarch.com/api/v2/devices
Zwracane dane:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| content | lista | — | Tak | Tablica urządzeń usługi. |
| content[].deviceId | text | — | Tak | Identyfikator urządzenia (numer naklejki). Ten sam identyfikator występuje w polu deviceIds na liście bramek. |
| content[].deviceName | text | — | Tak | Nazwa urządzenia w TNA. |
| content[].deviceType | text | BEACON_COMBO, DUAL_USE, GW_MOBILE, BASE, POS, OTHER | Tak | Typ urządzenia. |
| content[].direction | text | IN, OUT, INOUT | Nie | Kierunek urządzenia. |
| content[].status | text | ONLINE, OFFLINE, IN_SHIPPING | Nie | Status urządzenia. Ustawiany wyłącznie dla urządzeń typu DUAL_USE — dla pozostałych typów, w tym dla urządzeń zarejestrowanych przez publiczne API, pole jest pomijane i nie należy go traktować jako informacji o dostępności urządzenia. |
| content[].clientDevice | bool | true, false | Tak | true dla urządzeń zarejestrowanych zasobem POST /api/v2/devices/register. |
| content[].entryDescription | text | — | Nie | Opis bramki, do której urządzenie jest przypisane. Pole jest pomijane, gdy urządzenie nie ma przypisanej bramki. |
Przykładowa odpowiedź:
Pobieranie listy bramek
W celu pobrania listy bramek usługi należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/entries
Żądanie nie przyjmuje parametrów. Lista jest sortowana rosnąco po polu description.
Przykładowe żądanie:
https://tna.comarch.com/api/v2/entries
Zwracane dane:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| content | lista | — | Tak | Tablica bramek usługi. |
| content[].description | text | — | Tak | Opis bramki. Identyfikuje bramkę w polu entryDescription na liście urządzeń oraz w danych o wejściach/wyjściach. |
| content[].building | obiekt | — | Nie | Lokalizacja, w której znajduje się bramka. Pole jest pomijane, gdy bramka nie ma przypisanej lokalizacji. |
| content[].building.description | text | — | Nie | Opis lokalizacji. |
| content[].building.timeZoneId | text | — | Nie | Strefa czasowa lokalizacji w notacji IANA, np. Europe/Warsaw. |
| content[].deviceIds | lista | — | Tak | Identyfikatory urządzeń przypisanych do bramki, posortowane rosnąco. Zwracane są wyłącznie urządzenia aktywne. Pole jest zawsze zwracane jako tablica; gdy bramka nie ma urządzeń, zwracana jest pusta tablica []. |
Przykładowa odpowiedź:
Pobieranie listy lokalizacji
W celu pobrania listy lokalizacji usługi należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/buildings
Żądanie nie przyjmuje parametrów. Lista jest sortowana rosnąco po polu description.
Przykładowe żądanie:
https://tna.comarch.com/api/v2/buildings
Zwracane dane:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| content | lista | — | Tak | Tablica lokalizacji usługi. |
| content[].description | text | — | Tak | Opis lokalizacji. Identyfikuje lokalizację na liście bramek oraz w danych o wejściach/wyjściach. |
| content[].timeZoneId | text | — | Nie | Strefa czasowa lokalizacji w notacji IANA, np. Europe/Warsaw. Pole jest pomijane, gdy lokalizacja nie ma ustawionej strefy czasowej. |
Przykładowa odpowiedź:
Zasób w tej sekcji umożliwia pobranie listy projektów usługi. Dostęp do zasobów wymaga uprawnienia EMPLOYEE_WORK_TIME_MANAGEMENT (Zarządzanie czasem pracy pracownika) — tego samego, którego wymagają raporty obecności pracowników.
Pobieranie listy projektów
W celu pobrania listy projektów usługi należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/projects
Żądanie nie przyjmuje parametrów. Lista nie jest stronicowana i jest sortowana rosnąco po polu name.
Zwracane są projekty aktywne i archiwalne — dzięki temu integrator rozliczający historyczny czas pracy może rozwiązać identyfikator projektu zapisany wcześniej, także dla projektu już zamkniętego.
Przykładowe żądanie:
https://tna.comarch.com/api/v2/projects
Zwracane dane:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| content | lista | — | Tak | Tablica projektów usługi. |
| content[].name | text | — | Tak | Nazwa projektu. |
| content[].dateFrom | date | Data w formacie yyyy-MM-dd | Nie | Początek obowiązywania projektu. Pole jest pomijane, gdy nie jest określony. |
| content[].dateTo | date | Data w formacie yyyy-MM-dd | Nie | Koniec obowiązywania projektu. Pole jest pomijane, gdy nie jest określony. |
| content[].status | text | ACTIVE, INACTIVE | Tak | Status projektu. |
| content[].hash | text | — | Tak | Identyfikator projektu. Identyfikuje projekt w polu projectHash w raportach projektowych. |
Przykładowa odpowiedź:
Zasoby w tej sekcji zwracają czas pracy w rozbiciu na projekty. Odpowiadają czterem raportom obecności z sekcji „Zarządzanie pracownikami" — mają te same adresy uzupełnione o segment /projects, te same parametry i to samo stronicowanie. Dostęp do zasobów wymaga uprawnienia EMPLOYEE_WORK_TIME_MANAGEMENT (Zarządzanie czasem pracy pracownika) — tego samego, którego wymagają raporty obecności pracowników.
Identyfikatory projektów zwracane w polu projectHash rozwiązuje zasób „Pobieranie listy projektów".
Klucz API nie ma tożsamości kierownika, dlatego raporty dla całej usługi obejmują wszystkich pracowników usługi, zawężonych parametrami companies i centers. Nie ma odpowiednika ograniczenia „tylko podwładni" znanego z aplikacji.
Pobieranie szczegółowego raportu projektowego pracownika
W celu pobrania raportu projektowego pracownika z podziałem na dni należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/reports/projects/users/{userHash}
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|---|
| userHash | text | Path | — | Tak | Identyfikator pracownika. Zwracany na liście pracowników. |
| fromDate | date | URL | 2026-07-01 | Tak | Początek zakresu raportu. |
| tillDate | date | URL | 2026-07-31 | Tak | Koniec zakresu raportu. |
| etat | text | URL | — | Nie | Identyfikator etatu. Zawęża raport do jednego etatu pracownika. Bez tego parametru raport obejmuje wszystkie etaty. |
https://tna.comarch.com/api/v2/reports/projects/users/w49ww977e9?fromDate=2026-07-01&tillDate=2026-07-31
Zwracane dane:
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| timeType | text | GROSS, NET, GROSS_NET, CUSTOM, NONE | Tak | Tryb prezentacji czasu pracy w raporcie. |
| userTimeType | text | GROSS, NET, GROSS_NET, CUSTOM, NONE | Tak | Tryb prezentacji czasu pracy ustawiony dla pracownika. |
| subscription | obiekt | — | Tak | Dane pracownika: userHash, nameAndLastName, email oraz etat. |
| days | lista | — | Tak | Kolejne dni zakresu raportu. |
| days[].date | date | Data w formacie yyyy-MM-dd | Tak | Dzień raportu. |
| days[].status | text | m.in. PRESENCE, WORKING_DAY, HOLIDAY, DAY_OFF, VACATION, SICK_LEAVE | Tak | Status dnia — wartości jak w raporcie obecności pracownika. |
| days[].workPlan | obiekt | — | Nie | Plan pracy na ten dzień: workingDay i fixedTime. |
| days[].in | text | — | Nie | Godzina pierwszego wejścia. |
| days[].out | text | — | Nie | Godzina ostatniego wyjścia. |
| days[].balance | long | — | Nie | Bilans dnia w sekundach. |
| days[].lateness | bool | true, false | Tak | Informacja o spóźnieniu. |
| days[].projectsTimes | lista | — | Tak | Czas pracy w rozbiciu na projekty. Pole jest zawsze zwracane jako tablica; gdy w danym dniu nie ma czasu projektowego, zwracana jest pusta tablica []. |
| days[].projectsTimes[].projectHash | text | — | Tak | Identyfikator projektu. |
| days[].projectsTimes[].dateTimeFrom | date | Data ISO-8601 | Tak | Początek pracy nad projektem. |
| days[].projectsTimes[].dateTimeTo | date | Data ISO-8601 | Tak | Koniec pracy nad projektem. |
| days[].projectsTimes[].time | obiekt | — | Tak | Czas pracy nad projektem: timeType oraz grossTime i netTime w sekundach. |
| days[].projectsTimes[].notEqualizedTime | obiekt | — | Nie | Czas pracy nad projektem przed wygładzeniem. |
| days[].projectsTimes[].equalizedTime | obiekt | — | Nie | Czas pracy nad projektem po wygładzeniu. |
| days[].totalProjectsTimes | obiekt | — | Tak | Suma czasu projektowego w dniu. |
| days[].totalProjectsNotEqualizedTimes | obiekt | — | Nie | Suma czasu projektowego w dniu przed wygładzeniem. |
| days[].totalProjectsEqualizedTimes | obiekt | — | Nie | Suma czasu projektowego w dniu po wygładzeniu. |
| summary | obiekt | — | Tak | Podsumowanie całego zakresu raportu: projectsTimes z sumami dla każdego projektu, totalProjectsTimes, totalProjectsNotEqualizedTimes, totalProjectsEqualizedTimes, projectsCount, workPlanTime i balance. |
Przykładowa odpowiedź:
Pobieranie ogólnego raportu projektowego pracownika
W celu pobrania raportu projektowego pracownika z podsumowaniem miesięcznym należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/reports/projects/users/{userHash}/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|---|
| userHash | text | Path | — | Tak | Identyfikator pracownika. Zwracany na liście pracowników. |
| fromDate | date | URL | 2026-01-01 | Tak | Początek zakresu raportu. |
| tillDate | date | URL | 2026-12-31 | Tak | Koniec zakresu raportu. |
| etat | text | URL | — | Nie | Identyfikator etatu. Zawęża raport do jednego etatu pracownika. |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/projects/users/w49ww977e9/summary?fromDate=2026-01-01&tillDate=2026-12-31
Zwracane dane:
Struktura jak w zasobie „Pobieranie szczegółowego raportu projektowego pracownika", z tą różnicą, że zamiast pola days zwracane jest pole months. Każdy element months ma tę samą strukturę co pole summary, uzupełnioną o pola month i year — sumy dla poszczególnych projektów czyta się więc w obu zasobach identycznie.
Przykładowa odpowiedź:
Pobieranie raportu projektowego pracowników za dzień
W celu pobrania raportu projektowego wszystkich pracowników usługi za jeden dzień należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/reports/projects
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| date | date | URL | 2026-07-15 | — | Tak | Dzień raportu. |
| search | text | URL | — | — | Nie | Filtr po imieniu lub nazwisku pracownika. |
| includeArchival | bool | URL | true, false | false | Nie | Dołącza do raportu pracowników archiwalnych. |
| companies | lista | URL | — | — | Nie | Identyfikatory firm — zawężenie raportu do wskazanych firm. |
| centers | lista | URL | — | — | Nie | Identyfikatory centrów — zawężenie raportu do wskazanych centrów. |
| page | int | URL | — | 0 | Nie | Numer pobieranej strony (numeracja od 0). |
| size | int | URL | — | 20 | Nie | Liczba elementów na stronie. |
| sort | text | URL | — | name | Nie | Pole sortowania. |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/projects?date=2026-07-15&size=20&page=0
Zwracane dane:
Strona obiektów o strukturze jak w zasobie „Pobieranie szczegółowego raportu projektowego pracownika", zwracana w standardowej kopercie stronicowania.
| Nazwa | Typ | Dozwolone wartości | Wymagany | Opis |
|---|---|---|---|---|
| content | lista | — | Tak | Tablica raportów — po jednym na pracownika. |
| totalElements | long | — | Tak | Liczba wszystkich elementów. |
| totalPages | long | — | Tak | Liczba stron. |
| size | long | — | Tak | Rozmiar strony. |
| number | long | — | Tak | Numer strony. |
| first | bool | true, false | Tak | Czy pierwsza strona. |
| last | bool | true, false | Tak | Czy ostatnia strona. |
| numberOfElements | long | — | Tak | Liczba elementów na stronie. |
| sort | lista | — | Tak | Zastosowane sortowanie: direction i property. |
Przykładowa odpowiedź:
Pobieranie raportu projektowego pracowników za okres
W celu pobrania raportu projektowego wszystkich pracowników usługi za zakres dat należy przesłać żądanie (GET) na adres:
https://tna.comarch.com/api/v2/reports/projects/summary
Żądanie składa się z następujących parametrów:
| Nazwa | Typ | Forma | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
|---|---|---|---|---|---|---|
| fromDate | date | URL | 2026-07-01 | — | Tak | Początek zakresu raportu. |
| tillDate | date | URL | 2026-07-31 | — | Tak | Koniec zakresu raportu. |
| search | text | URL | — | — | Nie | Filtr po imieniu lub nazwisku pracownika. |
| includeArchival | bool | URL | true, false | false | Nie | Dołącza do raportu pracowników archiwalnych. |
| companies | lista | URL | — | — | Nie | Identyfikatory firm — zawężenie raportu do wskazanych firm. |
| centers | lista | URL | — | — | Nie | Identyfikatory centrów — zawężenie raportu do wskazanych centrów. |
| page | int | URL | — | 0 | Nie | Numer pobieranej strony (numeracja od 0). |
| size | int | URL | — | 20 | Nie | Liczba elementów na stronie. |
| sort | text | URL | — | name | Nie | Pole sortowania. |
Przykładowe żądanie:
https://tna.comarch.com/api/v2/reports/projects/summary?fromDate=2026-07-01&tillDate=2026-07-31
Zwracane dane:
Koperta stronicowania jak w zasobie „Pobieranie raportu projektowego pracowników za dzień". Każdy element pola content ma strukturę raportu szczegółowego, obejmującą wszystkie dni wskazanego zakresu.
Publiczne API do rejestracji odbić składa się z 2 elementów:
POST https://tna.comarch.com/api/v2/devices/register
Body:
| Nazwa | Typ | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
| deviceId | String | Tak | Identyfikator urządzenia | ||
| deviceName | String | Tak | Nazwa urządzenia w TNA | ||
| direction | Direction | IN,OUT, INOUT | INOUT | Nie | Kierunek urządzenia INOUT – naprzemiennie dla tego samego użytkownika |
Przykład:
{ "deviceId": "mydevice1", "deviceName": "name", "direction": "INOUT" |
Odpowiedź:
200 – OK
kody błędów:
2001 – Urządzenie od podanym deviceId już istnieje
2002 – Urządzenie o podanej nazwie już istnieje
Listę urządzeń zarejestrowanych w usłudze można pobrać zasobem GET https://tna.comarch.com/api/v2/devices (sekcja „Ustawienia serwisu" w Public API - 2.1.0). Urządzenia dodane tym zasobem mają w odpowiedzi clientDevice: true.
POST https://tna.comarch.com/api/v2/scans/report
Body:
| Nazwa | Typ | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
| tagId | String | Tak | Rev hex karty użytkownika | ||
| deviceId | String | Tak | Identyfikator urządzenia na którym zostanie zarejestrowana aktywność | ||
| direction | Direction | IN,OUT | Nie | Kierunek odbicia -> nadrzedy do kierunku urzadzenia | |
| zonedDateTime | yyyy-MM-dd'T'HH:mm:ss. SSSZ | 2000-10-31 01:30:00.000+01:00 | Nie | Data + czas z jakim ma być zarejestrowane odbicie (Nie może występować jeśli istnieje wartość dla „timestamp” | |
| timestamp | Number | 1731675479 | Nie | UNIX timestamp (seconds) z jakim ma być zarejestrowane odbicie (Nie może występować jeśli istnieje wartość dla „zonedDateTime” | |
| date | Date | 2000-10-31 | Nie | Data do której zaliczone zostanie odbicie. W przypadku podania tego pola, pola zonedDateTime lub timestamp muszą mieścić się w przedziale wskazanej w tym polu daty i kolejnego dnia. Przykład: W przypadku braku podania tego pola system sam wybierze odpowiedni dzień na podstawie planu pracy i ustawień usługi. |
W przypadku kiedy nie podano wartości dla zonedDateTime oraz timestamp odbicie zostanie zarejestrowane z czasem serwerowym.
Niedozwolone jest podanie razem wartości dla „zonedDateTime” i „timestamp”
Przykład:
{ "deviceId": "mydevice1", "tagId": "AABBCCDD", "direction": "IN", |
{ "deviceId": "mydevice1", "tagId": "AABBCCDD", "direction": "IN", |
Odpowiedź:
{ "tagId": " AABBCCDD ", "deviceId": " mydevice1", "dateTime": "2024-11-15T14:46:17.162", "direction": { "present": true }, "scanFlags": [], "errorCode": 0, "scanType": "CARD", "subscriptionHash": "cc132da4-ac48-4373-8d1b-856f5e5703a9", "date": "2024-11-15", "buildingDescription": "Lokalizacja 1", "timestamp": 1731678377, "zonedDateTime": "2024-11-15T14:46:17.162+01:00", "entryDescription": "Bramka 1", "scanDirection": "IN", "zonedTimestamp": "2024-11-15T14:46:17.162+01:00[Europe/Warsaw]" } |
POST https://tna.comarch.com/api/v2/scans/report/batch
Body:
| Nazwa | Typ | Dozwolone wartości | Domyślna wartość | Wymagany | Opis |
| scans | Array[] | Tak | Lista obiektów z metody do dodawnia pojedynczego odbicia |
Przykład:
{ "scans": [ { "deviceId": "mydevice1", "tagId": "AABBCCDD", "direction": "IN", }, { "deviceId": "mydevice1", "tagId": "AABBCCDD", "direction": "IN", } ] }
|
Odpowiedź:
{ "addedScans": [ { "tagId": " AABBCCDD", "deviceId": " mydevice1", "dateTime": "2024-11-15T14:55:18.682", "direction": { "present": true }, "scanFlags": [], "errorCode": 0, "scanType": "CARD", "subscriptionHash": "cc132da4-ac48-4373-8d1b-856f5e5703a9", "date": "2024-11-15", "buildingDescription": "Lokalizacja 1", "timestamp": 1731678918, "zonedDateTime": "2024-11-15T14:55:18.682+01:00", "entryDescription": "Bramka 1", "scanDirection": "OUT", "zonedTimestamp": "2024-11-15T14:55:18.682+01:00[Europe/Warsaw]" } ], "errorScans": [ { "tagId": " AABBCCDD", "deviceId": " mydevice1", "dateTime": "2024-11-15T14:55:18.682", "direction": { "present": true }, "scanFlags": [], "errorCode": 1004, "errorMessage": "Scan with date time [2024-11-15T14:55:18.682] already exists", "scanType": "CARD", "subscriptionHash": "cc132da4-ac48-4373-8d1b-856f5e5703a9", "scanDirection": "IN" } ] }
|
addedScans – lista z odbiciami które zostały poprawnie dodane
errorScans – lista z odbiciami które nie zostały zarejestrowane z powodu błędu
Kody błedów:
1001 – Nie znaleziono urządzenia o podanym deviceId
1002 – Urządzenie nie zostało przypisane do bramki
1003 – Nie znaleziono przypisanej do użytkownika karty o podanym tagId
1004 – Odbicie z taką datą i godziną już istnieje
1005 – Próba dodania odbicia na przyszłość
1006 – Data + czas odbicia (zonedDateTime lub timestamp) nie mieszczą się w dozwolonym zakresie opartym o pole date (występuje wyłącznie w przypadku podania pola date)
Comarch SA
al. Jana Pawła II 39a
31-864 Kraków
Telefon: 12 681 43 00 wew. 3*
*w dni robocze 9:00 – 17:00
Comarch SA
al. Jana Pawła II 39a
31-864 Kraków
kontakt@tna.comarch.com
Telefon: 12 681 43 00 wew. 3*
*w dni robocze 9:00 – 17:00