Download the PHP package tillio-crm/api without Composer

tillio-crm/api

Oficjalne SDK PHP dla Tillio API v2 - pełnego REST-owego API systemu Tillio CRM. Pokrywa 100% tras API (pilnowane testem kontraktowym), każda encja ma typowane DTO z named arguments, a znane pułapki kontraktu (ciche duplikaty, gubione strony, jednorazowe hasła) są zneutralizowane w kodzie, zanim żądanie w ogóle wyjdzie.

Spis treści

• Wymagania
• Instalacja
• Szybki start
  • Tryb bezpośredni (klucz API)
  • Tryb proxy (aplikacje marketplace)
• Zasoby
• Odczyt: strony i pełne przebiegi
• Zapis: DTO, duplikaty, upsert
• Obsługa błędów
• Retry i limity żądań
• Pliki: upload i pobieranie
• Ograniczenia trybu proxy
• Konfiguracja - wszystkie klucze
• Przykłady i integracja przez AI
• Testy
• Wersjonowanie
• Troubleshooting
• Wsparcie
• Licencja

Wymagania

• PHP ^8.3, rozszerzenia ext-curl i ext-json - zero innych zależności
• Composer
• Instancja Tillio z API v2 w wersji co najmniej 2.0.4 - sprawdzisz ją bez uwierzytelnienia: GET /v2/health zwraca pole version (w SDK: $client->health()['version']). Starsze wydania 2.0.x zadziałają z drobnymi różnicami opisanymi w PHPDoc (ServiceCatalogItemInput, flagi zgłoszeń); wydań sprzed 2.0.0 SDK nie obsługuje wcale.
• Część funkcji wymaga nowszej instancji - metody mają to zaznaczone w PHPDoc: kalendarze od 2.2.0, wydarzenia kalendarza od 2.3.0, szablony (maili, notatek, zadań), ich kategorie i pełny cykl typów dokumentów od 2.4.0, pliki pól niestandardowych typu FILE od 2.6.0, komentarze zadań i załączniki szablonów maili od 2.7.0, kontakty przy notatkach, zadaniach i wydarzeniach od 2.8.0, połączenia telefoniczne, SMS i lookup po numerze od 2.10.0, integracja Tillio Calls od 2.11.0, linki "otwórz w CRM" (Note::$url, Contact::$url) i pełne rekordy w lookupie po numerze od 2.12.0, leady bez dubli (WriteOptions w leads()->create(), leads()->upsert()), adresy e-mail leada w zapisie, notatka pod leadem i szansa sprzedaży w odczycie zadania od 2.13.0, zmiana statusu leada (leads()->changeStatus()), etapu i statusu szansy (pipelineItems()->changeStage(), changeStatus()), lookup po adresie e-mail (lookup()->email()), kategorie i tagi leadów, kontakty przy szansie od 2.15.0, służbowe dane kontaktowe użytkownika (jobTitle, contactPhone, contactEmail, gender) i jego aktywność (users()->activity()) od 2.16.0, filtry-listy id (['id' => [12, 15, 18]]), kontrahent przy szansie jednym zapytaniem (include=contractor), lejek i link "otwórz w CRM" szansy (PipelineItem::$pipelineFunnelId, $url) i leada (Lead::$url), notatka pod szansą (pipelineItems()->createNote()), dopisywanie opcji selecta (customFields()->appendOptions()) i przypisanie pola do wszystkich podtypów (assignedTo: 'all') od 2.17.0. Wywołanie funkcji, której CRM instalacji jeszcze nie ma, kończy się FeatureNotSupportedException (501); trasy spoza wersji API - błędem 404, a nieznany na starszej instancji parametr zapytania - błędem 400.

Instalacja

Szybki start

Tryb bezpośredni (klucz API)

Dla skryptów, integracji własnych i narzędzi wewnętrznych - masz klucz API tenanta (ten sam, co w API v1, format nazwa:klucz) i tożsamość instancji:

Tryb proxy (aplikacje marketplace)

Aplikacja marketplace nie ma i nie może mieć klucza do CRM - woła platformę własnym tokenem, a platforma dokłada sekret tenanta. Token podajesz jako string albo callable wywoływane przy każdym żądaniu (odświeżanie tokenu działa wtedy samo):

Tryb wybiera konfiguracja: dokładnie jeden z apiKey/accessToken - brak lub oba naraz to ConfigurationException już w konstruktorze. Klasy zasobów są identyczne w obu trybach i nie wiedzą, którym działają.

whoami() zwraca 401 mimo poprawnego klucza? Jeśli łączysz się z adresem hostującym wiele instancji CRM (typowo środowiska deweloperskie), podaj instanceName - nazwę instancji (nagłówek X-Instance-Name). Bez niego żądanie trafia na instancję DOMYŚLNĄ serwera, a klucz innej instancji nie pasuje. Produkcyjny adres z jedną instancją per domena tego nie wymaga.

Zasoby

Każdy zasób to jawna metoda fasady (IDE i analiza statyczna widzą typy):

Systemowe na fasadzie: health(), whoami(), selfcheck(), openapi(), modules() - docs/examples/systemowe.md.

Fasada udostępnia też warstwę surową - przydatną w nietypowych scenariuszach i wtedy, gdy Twoja instancja API ma trasę nowszą niż to wydanie SDK: get()/post()/put()/delete() (dowolna ścieżka v2/..., z retry i limiterem), postMultipart() (upload plików, domyślnie bez retry), listPage() i iterateAll() (surowe strony i pełne przebiegi) oraz download() (pobranie pliku spod podpisanego downloadUrl).

Odczyt: strony i pełne przebiegi

Listy zwracają Page<T> z typowanymi DTO i metadanymi stronicowania:

Do pełnych przebiegów służy generator iterate() - przechodzi wszystkie strony, oddając rekordy po jednym:

Filtry dokładne po liczbie całkowitej (id, contractorId, leadId, ownerUserId i pozostałe *Id na każdej liście) przyjmują od API 2.17.0 listę do 100 wartości - podajesz tablicę, SDK skleja ją do ?id=12,15,18. Tak sprawdzisz paczkę znanych rekordów jednym zapytaniem, a id nieobecne w odpowiedzi oznacza rekord usunięty w CRM (leady i szanse CRM kasuje bez śladu - innego sposobu na wykrycie usunięcia nie ma):

Pustą listę, więcej niż 100 wartości i element, który nie jest liczbą całkowitą (albo tekstem bez przecinka), SDK odrzuca InvalidFilterException, zanim żądanie wyjdzie - pusta lista bez filtra zwróciłaby wszystkie rekordy.

iterate() domyślnie wymusza sort=id - i to nie jest kosmetyka. API stronicuje przez LIMIT/OFFSET z domyślnym sortowaniem po dacie modyfikacji, czyli kolumnie, która ZMIENIA SIĘ w trakcie przebiegu: rekord zmodyfikowany między stronami wypada z niepobranego zakresu (cicha utrata) albo wraca drugi raz. id jest unikalne i niezmienne, więc tylko ono daje porządek, którego nic nie przestawi. Jawne sort w filtrach wygrywa z wymuszeniem; stany magazynowe (bez sortowalnego id) nie wymuszają niczego same z siebie.

Każde DTO odczytu ma pełny, surowy rekord w $raw / toArray() - pola dodane w nowszych wydaniach API nie giną i nie wywracają SDK. Kwoty są stringami dziesiętnymi ("1999.90") - rzutowanie na float gubi grosze, więc SDK tego nie robi za Ciebie.

Zapis: DTO, duplikaty, upsert

Input-DTO z named arguments; null znaczy "nie wysyłaj pola":

Kluczowe zachowania:

• POST z duplicateCheck nie duplikuje: trafienie w istniejący rekord to 200 z tym rekordem, bez zmiany danych - rozróżniaj po created.
• Strażnik lokalny: każde pole wskazane w duplicateCheck musi mieć wartość w payloadzie. Bez tego API pominęłoby warunek z samym ostrzeżeniem i założyło duplikat - SDK rzuca IncompleteDuplicateCheckException, zanim żądanie wyjdzie.
• Upsert (contractors()->upsert(), contacts()->upsert()): HTTP jest ZAWSZE 200, wynik per item w UpsertResult - sprawdzaj hasFailures(), kod HTTP nie powie Ci nic.
• Fallback tablicowy: metody zapisu przyjmują Input|array. Tablica to jedyna droga wysłania JAWNEGO nulla (czyszczenie pola, np. externalId) i pól, których DTO jeszcze nie zna.
• users()->create() zwraca CreatedUser z jednorazowym temporaryPassword i celowo NIE ponawia żądania - szczegóły w docs/examples/users.md.

Obsługa błędów

API zawsze zwraca prawdziwy status HTTP i typowany kontrakt błędu {field, code, message} - SDK zamienia go na hierarchię wyjątków (wspólny przodek TillioApiException):

Kolejność catchów ma znaczenie: FieldUnavailableException i ExternalIdAlreadyUsedException dziedziczą po ValidationException - łap je PRZED nią, jeżeli chcesz je obsłużyć osobno.

Retry i limity żądań

Wbudowane, bez konfiguracji:

• Limiter okienkowy trzyma żądania PONIŻEJ limitów API (429 kosztuje pełny round-trip - taniej przytrzymać wątek u siebie). Okna domyślne są celowo ciaśniejsze niż limit API (1000/min per klucz - tym samym kluczem potrafi jechać kilka integracji naraz).
• Retry z backoffem wykładniczym: ponawiane 429 (z respektowaniem Retry-After, z sufitem) i 5xx oraz błędy transportu. NIE ponawiane: przerwa serwisowa, 4xx poza 429, odmowa binariów przez proxy oraz operacje nieidempotentne (POST /v2/users, uploady plików, mail z załącznikami).

Wszystko jest konfigurowalne - konsument pracujący w krótkich porcjach ustawia krótkie sufity (lepiej oddać porcję i wrócić), skrypt wsadowy może czekać dłużej:

Pliki: upload i pobieranie

Upload (DMS, załączniki notatek/zadań, załączniki maili) idzie WYŁĄCZNIE przez multipart/form-data - w API nie ma wariantu JSON. SDK ogarnia to typem FileUpload:

Pobieranie: API nigdy nie zwraca binariów. Metadane pliku niosą downloadUrl - podpisany link do storage'u ważny około 1 minuty, pobierany bez nagłówków Tillio:

Nie buforuj linku; po wygaśnięciu odczytaj metadane ponownie. downloadUrl null znaczy "środowisko bez podpisywania", nie "brak pliku". Dokumenty DMS adresuje się WYŁĄCZNIE stringowym publicId - pole id to referencja CRM, która w ścieżce nie działa.

Ograniczenia trybu proxy

• Pobieranie plików DZIAŁA (przez proxy jedzie tylko JSON z downloadUrl, plik idzie prosto ze storage'u). Gdyby jednak jakaś odpowiedź binarna trafiła w proxy, dostaniesz jasny ProxyBinaryResponseException, nie ogólne 502.
• Platforma ma allowlistę ścieżek per aplikacja - 403 z proxy to ProxyAccessDeniedException ("popraw manifest apki"), odróżnione od 403 z API (uprawnienia klucza w CRM).
• Uploady multipart przechodzą przez proxy w górę normalnie.
• Wybór połączenia przy >1 connectorze: klucz konfiguracji connector - parametr platformy, dokleja go transport, zasoby go nie widzą.

Konfiguracja - wszystkie klucze

Nieznany klucz konfiguracji = ConfigurationException (literówka nie może po cichu zamienić się w żądania bez nagłówka).

Przykłady i integracja przez AI

• Uruchamialny przykład: katalog examples/ - skopiuj config.example.php do config.php, wpisz klucz i odpal php examples/quickstart.php (odczyt listy + jeden zapis). Po instalacji Composerem katalog leży w vendor/tillio-crm/api/examples/ - config trzymaj we własnym projekcie i wskaż go w TILLIO_EXAMPLES_CONFIG (szczegóły w examples/README.md).
• Przykład na każdy zasób: docs/examples/ - 24 pliki, wszystkie bloki składniowo sprawdzone.

Integrujesz przez asystenta AI (Claude, Cursor, Copilot)? Wskaż mu katalog docs/.ai/. Zaczyna się od ai_integration.md (wspólne wzorce: jak rozwiązywać osoby i słowniki na id, obsługa błędów, dwa tryby auth), a playbooki domenowe (tasks/, contractors/, notes/) pokazują krok po kroku, jak zamienić polecenie w języku naturalnym na wywołania SDK - tak, żeby "dodaj zadanie dla czterech osób z zespołu" zadziałało bez zgadywania id.

Testy

Zestaw zawiera test kontraktowy (RouteCoverageTest - każda z 243 tras mapy wskazuje istniejącą metodę SDK; pełne porównanie 1:1 ze specyfikacją instancji włączysz, pobierając GET /v2/openapi.json i ustawiając TILLIO_OPENAPI_FILE) oraz test przenośności (zero zależności spoza TillioCrm\Api w src/).

Wersjonowanie

Semver, start 0.1.0; przed 1.0.0 zmiany łamiące = minor. Historia: CHANGELOG.md. Wersję instancji API sprawdzisz przez $client->health()['version'], a jej pełny kontrakt przez $client->openapi().

Troubleshooting

Każde żądanie HTTPS pada: SSL certificate problem

PHP CLI (typowo na Windows) nie ma skonfigurowanego curl.cainfo. Wskaż plik CA bundle w konfiguracji: 'caFile' => 'C:/Program Files/Git/mingw64/etc/ssl/certs/ca-bundle.crt'. Weryfikacji TLS nie da się wyłączyć przez SDK - można tylko podać właściwy zestaw zaufanych CA.

ValidationException (400) na liście, choć filtr wygląda dobrze

API v2 odrzuca NIEZNANY parametr zapytania błędem 400 (literówka w filtrze nie zwróci po cichu całej bazy). Sprawdź nazwę filtra w PHPDoc metody list() danego zasobu - dokumentuje komplet filtrów wg kontraktu.

IncompleteDuplicateCheckException przed wysłaniem żądania

To strażnik SDK, nie błąd API: duplicateCheck wskazuje pole, które nie ma wartości w payloadzie. API pominęłoby taki warunek z samym ostrzeżeniem i mogłoby założyć duplikat - uzupełnij wartość pola albo zdejmij je z duplicateCheck.

403 w trybie proxy: ProxyAccessDeniedException czy AccessDeniedException?

ProxyAccessDeniedException = platforma nie zezwala aplikacji na tę operację (popraw manifest apki). AccessDeniedException = klucz API nie ma uprawnień w CRM (nadaj je w panelu). To dwa różne miejsca naprawy.

ServiceUnavailableException (503) na kalendarzach albo szablonach

Moduł jest wyłączony w planie tej instancji - to nie chwilowa awaria i SDK tego nie ponawia. Sprawdź $client->modules(), zanim zaczniesz pisać w dany moduł.

Pełny przebieg (iterate()) gubi albo dubluje rekordy

Nie nadpisuj wymuszonego sort=id własnym sort w filtrach przy pełnym przejściu - sortowanie po zmiennej kolumnie (np. dacie modyfikacji) przestawia rekordy między stronami. Zostaw domyślne sort=id.

Wsparcie

• Błędy i propozycje: GitHub Issues
• Podatności bezpieczeństwa: zgłaszaj prywatnie wg SECURITY.md, nie przez publiczne issue

Licencja

MIT © Tillio CRM