Zanim zaczniesz

Dokumentacja API

TessAPI umożliwia dostęp do Twojej Symfonii ERP przez chmurowe REST API. Twoja aplikacja komunikuje się z jednym adresem w chmurze, a lokalny konektor bezpiecznie wykonuje operacje w odpowiedniej instalacji Symfonii.

Ta strona opisuje endpointy publiczne dostępne obecnie w aplikacji.

Adres bazowy https://tessapi.pl/api

Uwierzytelnianie

Dostęp przebiega dwuetapowo. Najpierw token dostępowy tenanta przekazany w nagłówku X-Access-Token jest wymieniany na krótkotrwały JWT. Następnie JWT należy przesyłać w nagłówku Authorization przy każdym żądaniu.

POST /api/Auth/Token
X-Access-Token: twój-token-dostępowy

Authorization: Bearer otrzymany-token-jwt
Content-Type: application/json

Tokeny przechowuj wyłącznie po stronie serwera i nie umieszczaj ich w publicznym kodzie aplikacji.
JWT jest ważny przez 60 minut. Do uzyskania kolejnego służy token odświeżający.
Wywołania endpointów wymagają aktywnego konektora i włączonej odpowiedniej licencji.

Konwencje

Format: JSON kodowany w UTF-8. Nazwy właściwości odpowiedzi są zapisywane w notacji camelCase.
Daty: Daty i czas są serializowane zgodnie z ISO 8601, np. 2026-09-10T12:30:00Z.
Paginacja: Część endpointów używa paginacji za pomocą parametrów page i pageSize.

Zasoby

Tokeny

Endpointy autoryzacji wydają JWT dla konkretnego tenanta i pozwalają odnowić sesję bez ponownego użycia głównego tokenu dostępowego.

POST /api/Auth/Token Wydanie JWT i tokenu odświeżającego

POST /api/Auth/Refresh Odnowienie JWT

Odświeżenie tokenu

POST /api/Auth/Refresh
Content-Type: application/json

{
  "token": "eyJhbGciOi...",
  "refreshToken": "odświeżający-token"
}

Odpowiedź 200

{
  "token": "eyJhbGciOi...",
  "refreshToken": "odświeżający-token",
  "refreshTokenExpireDateUtc": "2026-09-11T12:30:00Z"
}

Kontrahenci

Kartoteka kontrahentów z lokalnej Symfonii. Wszystkie wywołania wymagają JWT, dostępnego konektora oraz odpowiedniej licencji.

GET /api/Contractors Lista kontrahentów

GET /api/Contractors?code={code} Kontrahent wyszukany po kodzie

GET /api/Contractors/{id} Kontrahent wyszukany po ID

POST /api/Contractors Utworzenie kontrahenta

PUT /api/Contractors Aktualizacja kontrahenta

Utworzenie kontrahenta

POST /api/Contractors
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "KLIENT-001",
  "name": "Przykładowa sp. z o.o.",
  "nip": "5250001009",
  "country": "Polska",
  "city": "Warszawa",
  "street": "Prosta",
  "houseNo": "1",
  "postCode": "00-001"
}

Odpowiedź 201

HTTP/1.1 201 Created
Location: /api/Contractors/123

(pusta treść odpowiedzi)

PoleTypOpis

idintegerIdentyfikator kontrahenta w Symfonii; wymagany przy aktualizacji.

codestringKod kontrahenta; wymagany przy tworzeniu.

namestringNazwa kontrahenta.

nipstring?Numer NIP; walidowany, jeśli został podany.

peselstring?Numer PESEL; walidowany, jeśli został podany.

regonstring?Numer REGON.

country, province, citystring?Podstawowe elementy adresu.

street, houseNo, apartmentNostring?Szczegóły adresu.

postCode, postOfficestring?Kod i urząd pocztowy.

eParagony

Fiskalizacja dokumentów Symfonii w serwisie eparagony.pl. Endpointy klienckie wymagają JWT i odpowiedniej licencji.

Dostęp do modułu eparagony

Endpointy związane z fiskalizacją eparagonów są częścią modułu eparagony. W sprawie licencji skontaktuj się z nami.

POST /api/eparagony/fiscalize/{documentId} Rozpoczęcie fiskalizacji

GET /api/eparagony/jobs/{jobId} Status fiskalizacji

GET /api/eparagony/jobs?page=1&pageSize=20&status=Pending Lista zadań fiskalizacji

GET /api/eparagony/fiscalizable-documents?limit=100 Dokumenty gotowe do fiskalizacji

Rozpoczęcie fiskalizacji

POST /api/eparagony/fiscalize/12345
Authorization: Bearer <token>

Odpowiedź 200

{
  "jobId": "d3f5e764-c3ae-4b16-a067-164522b845ac",
  "status": 0
}

1SentDokument został przyjęty przez eparagony.pl. TessAPI czeka na fiskalizację dokumentu. Ten status jest również używany, gdy eParagon został potwierdzony, ale nie udało się jeszcze oznaczyć dokumentu jako fiskalnego w Symfonii.

2ReadySerwis eparagony.pl przygotował dokument, zwykle wraz z publicznym adresem, ale proces nie został jeszcze fizycznie zafiskalizowany, potwierdzony i zsynchronizowany z Symfonią.

3ConfirmedFiskalizacja zakończyła się pomyślnie, a dokument został także oznaczony jako fiskalny w Symfonii. Jest to końcowy status sukcesu.

4ErrorWystąpił błąd przejściowy. Zadanie zostanie ponowione zgodnie z harmonogramem odnowień.

5Failedbłąd trwały albo wyczerpanie limitu ponowień. Zadanie nie będzie już samoczynnie ponawiane. Ponowne wywołanie fiskalizacji może je zresetować do Pending.

Praktyka

Błędy

Błąd API zawiera liczbowy errorCode oraz tablicę komunikatów messages. Kod HTTP opisuje klasę błędu.

{
  "errorCode": 400,
  "messages": [
    "Opis błędu lub naruszonej reguły"
  ]
}

400VALIDATION_FAILNiepoprawne parametry lub treść żądania.

401UNAUTHORIZEDBrak lub nieprawidłowy token.

402FEATURE_DISABLEDWymagana funkcja nie jest aktywna dla tenanta.

404NOT_FOUNDNie znaleziono wskazanego zasobu.

500INTERNAL_ERRORNieoczekiwany błąd po stronie usługi.

503CONNECTOR_UNAVAILABLELokalny konektor jest niedostępny; odpowiedź zawiera Retry-After.

Konektor a API

Operacje na kontrahentach i dokumentach fiskalnych są przekazywane przez chmurę do konektora działającego przy lokalnej bazie Symfonii. Jeżeli konektor jest niedostępny, API zwraca 503 Service Unavailable wraz z nagłówkiem Retry-After: 30.

Twoja aplikacja→TessAPI→Konektor→Symfonia ERP

Specyfikacja techniczna

Wszystkie schematy w OpenAPI

Interaktywna specyfikacja jest generowana bezpośrednio z kontrolerów aplikacji, dlatego pozostaje źródłem szczegółowych typów żądań i odpowiedzi.

Otwórz OpenAPI