taxmachine.pl

API zgłoszeń dla asystentów AI

Opublikowano

API zgłoszeń — obsługa sprawy przez asystenta AI

Jeżeli w Twoim imieniu działa asystent AI (np. agent podłączony do TaxMachine przez serwer MCP), może on obsługiwać istniejące zgłoszenie programowo: czytać wątek, odpowiadać i przesyłać pliki. Odpowiedzi agenta trafiają do obsługi dokładnie tak samo, jak wysłane ze strony zgłoszenia.

Najważniejsza zasada: pierwsze zgłoszenie wysyła człowiek

Nowe zgłoszenie można utworzyć wyłącznie przez formularz zgłoszenia — formularz chroni captcha (Cloudflare Turnstile), więc agent go nie wyśle i tak ma być: to świadoma zapora antyspamowa, a przy okazji gwarancja, że człowiek wie o każdej założonej sprawie.

Po wysłaniu formularza:

  • ekran potwierdzenia pokazuje link do strony sprawy — ten sam link przychodzi też w mailu potwierdzającym,
  • link zawiera token dostępu do sprawy (parametr t) — wystarczy przekazać agentowi cały link, od tego momentu może obsługiwać sprawę samodzielnie.

Token daje dostęp wyłącznie do tej jednej sprawy. Traktuj link jak hasło do niej.

Wywołania API

Wszystkie wywołania używają numeru sprawy (TM-RRRRMM-XXXX) i tokenu z linku. Limity częstotliwości per adres IP.

Odczyt wątku sprawy

GET https://taxmachine.pl/api/problem-reports/thread?ticketId=<NUMER>&t=<TOKEN>

Zwraca JSON: tytuł, status (status, statusLabel), opis zgłoszenia w czystym tekście, chronologiczną listę odpowiedzi (replies[].from = "support" albo "client"), listę załączników z adresami URL oraz pole howToReply z gotowym przepisem na odpowiedź.

Odpowiedź w sprawie

POST https://taxmachine.pl/api/problem-reports/reply
Content-Type: application/json

{
  "ticketId": "<NUMER>",
  "token": "<TOKEN>",
  "body": "<treść odpowiedzi>",
  "attachmentIds": []
}

Odpowiedź pojawia się w wątku, sprawa wraca do kolejki obsługi, a zespół dostaje powiadomienie. Można wysłać samą treść, same pliki albo jedno i drugie.

Załączniki

POST https://taxmachine.pl/api/media
Content-Type: multipart/form-data

file      = <plik>
_payload  = {"alt":"nazwa pliku","source":"ticket-reply"}

Zwrócone doc.id przekaż w attachmentIds odpowiedzi. Dozwolone typy: obrazy, PDF, .txt, .log, .db; do 10 plików w jednej odpowiedzi.

Typowy scenariusz

  1. Człowiek wysyła zgłoszenie formularzem i przekazuje agentowi link do sprawy (z potwierdzenia albo z maila).
  2. Agent odczytuje wątek (GET /thread), analizuje odpowiedź wsparcia, w razie potrzeby wykonuje testy po stronie klienta.
  3. Agent odpowiada (POST /reply), dołączając logi lub zrzuty (POST /media).
  4. O każdej odpowiedzi wsparcia klient dostaje maila — agent może też po prostu cyklicznie odpytywać GET /thread o nowe wpisy.

Pytania i sugestie dotyczące API — przez formularz zgłoszenia (typ „Problem z witryną").