WWindykatorAI ›Dokumentacja

Dokumentacja integracji: REST API i MCP

Dwie równorzędne drogi do tych samych możliwości. MCP — gdy podłączasz agenta AI (Claude, ChatGPT, Gemini, Grok, Copilot). REST API — gdy integrujesz księgowość, ERP albo własny system. Ta sama logika, ten sam mechanizm zatwierdzania.

Zasada nadrzędna: żadne działanie skierowane do dłużnika nie jest wykonywane od razu. send zawsze trafia do kolejki zatwierdzeń i czeka na kliknięcie człowieka w panelu. Dotyczy to tak samo REST, MCP i agenta.

Uwierzytelnianie

MetodaDla kogoJak
Klucz APIREST API oraz MCP Nagłówek X-Api-Key: rd_live_… albo Authorization: Bearer rd_live_…. Klucz generujesz po rejestracji (ekran „Połącz agenta") lub w Ustawieniach → API dla deweloperów.
OAuth 2.1MCP (Claude, ChatGPT itd.) Klient wykrywa konfigurację automatycznie (dynamic client registration + PKCE) z https://windykatorai.app/.well-known/oauth-authorization-server. Użytkownik loguje się w przeglądarce i klika „Zezwól" — bez wklejania klucza.

Serwer MCP

Adres: https://windykatorai.app/mcp · transport: streamable-http.

Konfiguracja dla klienta przyjmującego plik (Claude Desktop, VS Code, własny agent):

{
  "mcpServers": {
    "windykatorai": {
      "url": "https://windykatorai.app/mcp",
      "headers": { "Authorization": "Bearer TWOJ_KLUCZ_API" }
    }
  }
}

W klientach z obsługą OAuth (Claude.ai, ChatGPT w trybie deweloperskim, Copilot Studio — „Dynamic discovery") wystarczy sam adres serwera; sekcja headers jest wtedy zbędna.

Narzędzia MCP

NarzędzieDziałanie
create_caseZakłada sprawę windykacyjną (dłużnik, kwota w groszach, termin, NIP, adres…).
get_casePełne dane sprawy: status, dni po terminie, oś zdarzeń, szansa odzyskania.
calculate_balanceSaldo: kwota, wpłaty, pozostało, dni po terminie.
draft_contactPodgląd dokładnej treści wezwania dla wybranego szablonu — nic nie wysyła.
send_contactKolejkuje wysyłkę do zatwierdzenia przez człowieka. Zwraca approval_url.
get_delivery_statusHistoria doręczeń i stan kolejki zatwierdzeń.
record_debtor_responseOdnotowuje odpowiedź dłużnika, która przyszła poza platformą.
close_caseZamyka sprawę: paid, disputed albo unrecoverable.

Szablony treści (template): friendly_reminder, payment_overdue, second_reminder, final_pre_court_notice, installment_offer. Kanały (channel): email, sms, whatsapp, letter (alias physical_letter), call (alias voice_call).

REST API v1

Baza: https://windykatorai.app/api/v1 · format: JSON · uwierzytelnianie: klucz API (patrz wyżej). Możliwości są identyczne z narzędziami MCP.

Metoda i ścieżkaDziałanie
GET /casesLista spraw (filtry jak w panelu).
POST /casesNowa sprawa. Body: debtor_name, amount_cents (int, grosze) albo amount (PLN), opcjonalnie currency, due_date, invoice_ref, email, phone, nip, address.
POST /debtsImport wielu długów naraz: {"debts": [...]}.
GET /cases/{id}Pełne dane sprawy.
GET /cases/{id}/balanceSaldo sprawy.
GET /cases/{id}/draft?template=…Podgląd treści wezwania — nic nie wysyła.
POST /cases/{id}/sendKolejkuje wysyłkę do zatwierdzenia. Body: channel, template. Zwraca approval_url.
GET /cases/{id}/deliveryHistoria doręczeń i kolejka zatwierdzeń.
POST /cases/{id}/responseOdnotowuje odpowiedź dłużnika. Body: channel, note.
POST /cases/{id}/closeZamyka sprawę. Body: status (paid / disputed / unrecoverable), opcjonalnie note.

Przykład: pełny przebieg

# 1. Załóż sprawę
curl -X POST https://windykatorai.app/api/v1/cases \
  -H "X-Api-Key: rd_live_..." -H "Content-Type: application/json" \
  -d '{"debtor_name":"Nord Studio Sp. z o.o.","amount_cents":842000,
       "due_date":"2026-08-09","email":"biuro@nordstudio.example",
       "invoice_ref":"FV/08/2026"}'

# 2. Sprawdź saldo (odsetki, dni po terminie)
curl -H "X-Api-Key: rd_live_..." \
  https://windykatorai.app/api/v1/cases/123/balance

# 3. Zobacz treść wezwania przed wysyłką
curl -H "X-Api-Key: rd_live_..." \
  "https://windykatorai.app/api/v1/cases/123/draft?template=payment_overdue"

# 4. Zakolejkuj wysyłkę — wróci approval_url, wysyłka czeka na Twoje kliknięcie
curl -X POST https://windykatorai.app/api/v1/cases/123/send \
  -H "X-Api-Key: rd_live_..." -H "Content-Type: application/json" \
  -d '{"channel":"email","template":"payment_overdue"}'

Błędy

KodZnaczenie
401Brak lub nieprawidłowy klucz API.
400Błędne dane wejściowe — treść błędu w polu error po polsku.
404Sprawa nie istnieje albo należy do innej organizacji.

Jak zacząć

  1. Załóż konto — klucz API dostajesz od razu na ekranie „Połącz agenta".
  2. Podłącz agenta (MCP) albo wywołaj API — jak wyżej.
  3. Wysyłki zatwierdzasz w panelu — każde send zwraca link prosto do właściwej rozmowy.