Jak rozpocząć pracę z Tillio API v2

Co musisz mieć

Każde żądanie do API niesie adres serwera i trzy wymagane nagłówki, po których API rozpoznaje Twoją instancję i klucz. Wszystkie znajdziesz w Tillio w widoku Ustawienia > Moduły > API > Ustawienia. Wartości w lewej kolumnie są przykładowe.

Od zera do pierwszego żądania

Każdy przykład ma dwie wersje: curl i PHP z oficjalnym SDK tillio-crm/api. Przełącznik nad kodem zmienia język we wszystkich przykładach naraz.

1. Otwórz ustawienia modułu API

   W Tillio przejdź do Ustawienia > Moduły > API > Ustawienia. Znajdziesz tam parametry połączenia:

   • adres serwera API (dla SaaS https://s2.public.api.tillio.app),
   • domenę instancji do nagłówka X-Tenant-Domain,
   • identyfikator instancji do nagłówka X-Tenant-Id.

   Jeśli czegoś tam brakuje albo coś jest niejasne, napisz na pomoc@tillio.pl.

2. Załóż klucz API i skopiuj go

   Administrator instancji (osoba z uprawnieniami administratora systemu) otwiera Ustawienia > Moduły > API > Ustawienia > Klucze API i dodaje nowy klucz: nazwę, która jest jednocześnie loginem (np. erp-sync, unikalna w instancji), i opis, do czego klucz służy.

   Po zapisie system pokazuje klucz jeden raz. Skopiuj go od razu. Później można go tylko zresetować, co unieważnia poprzedni.

   Do nagłówka X-Api-Key potrzebujesz obu wartości: nazwy klucza i klucza, połączonych dwukropkiem bez spacji: erp-sync:3f9a1c7e…. W konfiguracji integracji najwygodniej trzymać je jako dwie osobne zmienne i sklejać przy wysyłce, jak w przykładach niżej.

   Każdy klucz dostaje w Tillio własnego użytkownika systemowego o nazwie „API erp-sync”. To on jest autorem rekordów zapisanych przez API i widać go w historii zmian.

   Przechodzisz z API v1? Klucze z API v1 działają w API v2 bez zmian, nie musisz zakładać nowych. API v2 nie jest zgodne z v1, więc przejście wymaga zmian w kodzie skryptu albo integracji. Więcej w sekcji API v1 (wycofywane).

3. Sprawdź, czy serwer odpowiada

   /v2/health nie wymaga nagłówków. Zwraca wersję API wdrożoną na serwerze.

   curlPHP (SDK)

   Kopiuj

   curl https://s2.public.api.tillio.app/v2/health

   odpowiedź 200Kopiuj

   {
     "status": "ok",
     "version": "X.Y.Z",
     "contract": { "openapi": "/v2/openapi.json", "docs": "/v2/docs" },
     "checks": { "crmAutoload": true }
   }

4. Sprawdź swoje dane dostępowe

   /v2/whoami to najtańszy test konfiguracji: nie czyta żadnych danych biznesowych, a potwierdza domenę, identyfikator i klucz.

   curlPHP (SDK)

   Kopiuj

   # dwie wartości z widoku Klucze API, trzymane w zmiennych środowiskowych
   export TILLIO_API_KEY_NAME="erp-sync"
   export TILLIO_API_KEY="TWÓJ_KLUCZ"
   
   curl https://s2.public.api.tillio.app/v2/whoami \
     -H "X-Tenant-Domain: firma.tillio.app" \
     -H "X-Tenant-Id: firma-tillio-app-k3j9x2" \
     -H "X-Api-Key: $TILLIO_API_KEY_NAME:$TILLIO_API_KEY"

   odpowiedź 200Kopiuj

   {
     "authenticated": true,
     "tenantDomain": "firma.tillio.app",
     "tenantId": "firma-tillio-app-k3j9x2",
     "keyName": "erp-sync",
     "userId": 1843
   }

   Zamiast tego 401 auth.invalidCredentials? Przejdź listę w sekcji Gdy coś nie działa.

5. Pobierz pierwsze dane

   Lista kontrahentów, dwa rekordy na stronę, posortowana po id. Odpowiedź poniżej jest skrócona.

   curlPHP (SDK)

   Kopiuj

   curl "https://s2.public.api.tillio.app/v2/contractors?limit=2&sort=id&sortDir=asc" \
     -H "X-Tenant-Domain: firma.tillio.app" \
     -H "X-Tenant-Id: firma-tillio-app-k3j9x2" \
     -H "X-Api-Key: $TILLIO_API_KEY_NAME:$TILLIO_API_KEY"

   odpowiedź 200 (skrócona)Kopiuj

   {
     "data": [
       {
         "id": 121,
         "name": "Acme",
         "taxId": "5252344078",
         "contractorStatusId": 3,
         "ownerUserId": 12,
         "updatedAt": "2026-09-12T14:05:11+02:00",
         "customField": {}
       }
     ],
     "pagination": { "page": 1, "limit": 2, "total": 5598, "pages": 2799 }
   }

6. Zapisz rekord bez ryzyka duplikatu

   Zapis wysyłasz jako JSON. Pole duplicateCheck każe najpierw sprawdzić, czy taki kontrahent już istnieje (tu po NIP-ie). Jeśli tak, API nie zakłada drugiego, tylko zwraca istniejący z 200 i "created": false. Nowy rekord to 201.

   curlPHP (SDK)

   Kopiuj

   curl -X POST https://s2.public.api.tillio.app/v2/contractors \
     -H "X-Tenant-Domain: firma.tillio.app" \
     -H "X-Tenant-Id: firma-tillio-app-k3j9x2" \
     -H "X-Api-Key: $TILLIO_API_KEY_NAME:$TILLIO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "ACME Sp. z o.o.",
       "taxId": "5252344078",
       "contractorTypeId": 2,
       "duplicateCheck": ["taxId"]
     }'

   odpowiedź 201 (skrócona)Kopiuj

   {
     "data": { "id": 950201, "name": "ACME Sp. z o.o.", … },
     "info": {
       "created": true,
       "ids": { "contractorId": 950201, "noteId": 4021 },
       "duplicate": null,
       "warnings": {}
     }
   }

   contractorTypeId to typ kontrahenta, taki sam w każdej instancji: 1 Partner, 2 Klient, 3 Dostawca (GET /v2/contractor/types). Pozostałe słowniki, np. statusy czy źródła, różnią się między instancjami, więc ich id zawsze bierz z odpowiedniego GET.

   Pola niestandardowe dopisujesz w obiekcie customField. Ich klucze są inne w każdej instancji, więc najpierw pobierz je z GET /v2/contractor/custom-fields.

Dokumentacja

Dokumentacja jest na serwerze API, pod tym samym adresem co samo API, i nie wymaga klucza. Generuje się z kodu wdrożonego na tym serwerze, więc zawsze opisuje dokładnie tę wersję, z którą rozmawiasz.

Na górze Swaggera jest rozszerzony opis zasad: strefy czasowe, zakresy dat, synchronizacja przyrostowa, limity. Warto go przeczytać przed pisaniem synchronizacji.

SDK PHP

Oficjalne SDK obejmuje wszystkie trasy API. Ma typowane obiekty dla każdej encji, samo ponawia żądania po chwilowych błędach, pilnuje limitu żądań i przechodzi po stronach list tak, żeby nie gubić rekordów. Dokumentacja i przykłady są po polsku.

composer require tillio-crm/api

use TillioCrm\Api\TillioClient;

$client = new TillioClient([
    // adres serwera pomijasz: SDK domyślnie łączy się z https://s2.public.api.tillio.app
    'tenantDomain' => 'firma.tillio.app',
    'tenantId'     => 'firma-tillio-app-k3j9x2',
    // nazwa-klucza:klucz, np. "erp-sync:3f9a1c7e..."
    'apiKey'       => getenv('TILLIO_API_KEY_NAME') . ':' . getenv('TILLIO_API_KEY'),
]);

$client->whoami(); // test konfiguracji

// pełny przebieg po wszystkich stronach, bez gubienia rekordów
foreach ($client->contractors()->iterate(['updatedAfter' => '2026-09-01T00:00:00']) as $contractor) {
    echo $contractor->name, ' ', $contractor->taxId, PHP_EOL;
}

Budujemy integrację z Tillio API v2 przy użyciu oficjalnego SDK tillio-crm/api (composer require tillio-crm/api).

Zanim napiszesz kod:
1. Przeczytaj vendor/tillio-crm/api/README.md.
2. Przeczytaj vendor/tillio-crm/api/docs/.ai/ai_integration.md.
3. Dla każdego obszaru, którego dotyczy zadanie (np. kontrahenci, zadania, notatki), przeczytaj odpowiednią instrukcję z vendor/tillio-crm/api/docs/.ai/ oraz przykłady z vendor/tillio-crm/api/docs/examples/ i vendor/tillio-crm/api/examples/.

Zasady:
- Nie zgaduj identyfikatorów. Użytkowników, wartości słowników i klucze pól niestandardowych pobieraj przez SDK.
- Klucz API (nazwa-klucza:klucz), domenę instancji i identyfikator instancji czytaj ze zmiennych środowiskowych. Nigdy nie wpisuj ich do kodu.
- Zanim wyślesz do instancji pierwsze żądanie zapisu, pokaż mi, co zostanie zapisane.

Budujemy integrację z Tillio API v2 w języku [wpisz język, np. Python]. Dla tego języka nie ma oficjalnego SDK, więc pracujemy na specyfikacji OpenAPI.

Zanim napiszesz kod:
1. Pobierz i przeczytaj specyfikację https://s2.public.api.tillio.app/v2/openapi.json. Opis na jej początku wyjaśnia autoryzację, strefę czasową, zakresy dat, stronicowanie i limity.
2. Wygeneruj klienta ze specyfikacji (np. OpenAPI Generator) albo napisz cienką warstwę HTTP tylko dla endpointów potrzebnych w zadaniu.
3. Sprawdzaj pola, filtry i kody błędów w specyfikacji, zamiast ich zgadywać.

Zasady:
- Każde żądanie poza /v2/health wysyła nagłówki X-Tenant-Domain, X-Tenant-Id i X-Api-Key (nazwa-klucza:klucz).
- Klucz API, domenę instancji i identyfikator instancji czytaj ze zmiennych środowiskowych. Nigdy nie wpisuj ich do kodu.
- Nie zgaduj identyfikatorów. Użytkowników, wartości słowników i klucze pól niestandardowych pobieraj z API.
- Obsłuż błędy według kontraktu _error.errors[] (field, code, message) oraz limit żądań: po 429 odczekaj tyle sekund, ile podaje nagłówek Retry-After.
- Pełne listy pobieraj stronami, sortując po id.
- Zanim wyślesz do instancji pierwsze żądanie zapisu, pokaż mi, co zostanie zapisane.

Co obejmuje API

Ponad 220 operacji. Poniżej obszary w skrócie, pełna lista w Swaggerze. Większość encji ma listę z filtrami, odczyt po id, tworzenie (POST) i edycję (PUT).

Zasady kontraktu

Limity

Stan limitu żądań zwracamy w każdej odpowiedzi w nagłówkach X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (sekundy do nowego okna). Wartości poniżej są domyślne dla planu PRO.

Czego API nie robi

• Nie usuwa głównych rekordów Tak jest z założenia: kontrahentów, kontakty, leady, zadania, notatki, zgłoszenia i zamówienia usuwa się w interfejsie Tillio. Przez API (DELETE) usuniesz wybrane rekordy, wskazane w dokumentacji.

• Nie powiadamia o zmianach API v2 nie wysyła webhooków. Zmiany pobierasz cyklicznie przez updatedAfter.

• Nie działa w imieniu konkretnego użytkownika Tillio Wszystkie zapisy idą jako użytkownik klucza API. Opiekuna rekordu wskazujesz polem ownerUserId, ale autorem zmiany pozostaje użytkownik klucza.

• Nie cofa częściowej paczki Upsert zapisuje pozycje po kolei, bez wspólnej transakcji. Błąd jednej pozycji nie zatrzymuje pozostałych. Wynik każdej pozycji (created, updated, failed) jest w odpowiedzi i trzeba go przeczytać.

• Nie jest zgodne z API v1 Klucze z v1 działają w v2, ale przejście na v2 wymaga zmian w kodzie skryptu albo integracji.

• Nie zapisuje do wyłączonych modułów Zapis do obszaru, którego instancja nie ma w planie albo ma wyłączony, kończy się 403 module.notActive z nazwą modułu.

• Nie obsłuży funkcji, której nie ma Twoja wersja Tillio Jeśli instancja działa na starszej wersji systemu, nowsza funkcja zwróci 501 feature.notSupportedByCrmVersion. Reszta API działa normalnie.

• Nie wysyła maili bez podłączonej skrzynki Wysyłka idzie z kont pocztowych podłączonych w Tillio. Listę dostępnych kont zwraca GET /v2/mail/accounts.

Bezpieczeństwo klucza

Użytkownik klucza API dostaje przy zakładaniu pełne uprawnienia do danych instancji. Traktuj klucz jak hasło administratora.

• Trzymaj klucz po stronie serwera. Nie wołaj API z przeglądarki, aplikacji mobilnej ani wtyczki: klucz byłby widoczny dla każdego użytkownika.
• Przechowuj go w sejfie sekretów albo zmiennej środowiskowej. Nie w repozytorium, nie w logach, nie w treści zgłoszeń.
• Jedna integracja, jeden klucz. Każdy klucz ma własny limit żądań, własnego autora w historii zmian i można go wyłączyć bez zatrzymywania pozostałych.
• Po wycieku zresetuj klucz od razu. Reset unieważnia stary klucz. Nieużywany klucz wyłącz albo usuń w Ustawienia > Moduły > API > Ustawienia > Klucze API.
• Łącz się wyłącznie przez HTTPS.

Gdy coś nie działa

Każdy błąd ma ten sam kształt: _error z kodem i listą errors, w której każdy wpis wskazuje pole, kod i opis. Komunikaty są celowo neutralne: szczegóły techniczne (zapytania, ścieżki na serwerze) nie wychodzą poza API.

use TillioCrm\Api\Exception\ApiException;
use TillioCrm\Api\Exception\ValidationException;

try {
    $client->contractors()->list(['updatedAfter' => 'jutro']);
} catch (ValidationException $e) {
    // 400 albo 422: wszystkie powody naraz
    foreach ($e->errors as $error) {
        echo $error->field, ': ', $error->message, PHP_EOL;
    }
} catch (ApiException $e) {
    // pozostałe błędy API: kod HTTP i pełna treść odpowiedzi
    echo $e->status, ' ', $e->rawBody, PHP_EOL;
}

{
  "_error": {
    "code": 400,
    "message": "validation.error",
    "errors": [
      { "field": "updatedAfter", "code": "query.invalidDate", "message": "Parametr updatedAfter musi być datą ISO 8601." }
    ],
    "requestId": "9c1e4b2a7f03d615"
  }
}

Zgłoszenie do Tillio

API v1 (wycofywane)

API v1 nie będzie już rozwijane. Tillio utrzymuje je co najmniej do września 2027 roku i wspiera wyłącznie w zakresie ewentualnych błędów bezpieczeństwa.

Jeśli utrzymujesz jeszcze integrację opartą na API v1, jej dokumentacja jest pod adresem doc-api.tillio.pl.