Pozywacz API

Jak zacząć

Integracja sprowadza się do dwóch wywołań: wysyłasz sprawę i odbierasz gotowe pismo. Poniżej masz całą ścieżkę w gotowych do wklejenia przykładach - od sprawdzenia klucza po pobranie PDF-a.

Model działania

API jest asynchroniczne. Twój request nie czeka na gotowy dokument - dostajesz identyfikator zgłoszenia i odbierasz wynik później, webhookiem albo odpytując status.

1. Ty

   POST /api/v1/submissions

   Wysyłasz dane sprawy. Walidujemy je od razu i odpowiadamy 202 z submissionId.

   RECEIVED
2. Pozywacz

   Przygotowanie pisma

   Pracujemy nad dokumentem w tle. Twój request już dawno wrócił.

   GENERATING
3. Pozywacz

   Kontrola po naszej stronie

   Gotowe pismo sprawdza człowiek. Do tego momentu result jest null i nie wysyłamy webhooka.

   IN_REVIEW
4. Ty

   Webhook albo GET /submissions/{id}

   Powiadamiamy Cię sami albo odpytujesz status. Obie drogi zwracają tę samą strukturę.

   COMPLETED
5. Ty

   GET /submissions/{id}/document

   Pobierasz gotowe pismo jako PDF, tym samym kluczem API.

   PDF

Kluczowa różnica wobec typowego API: między przygotowaniem a wydaniem pisma jest kontrola po naszej stronie. Przez ten czas zgłoszenie ma status IN_REVIEW, result pozostaje null i nie wysyłamy webhooka. Zaprojektuj proces tak, żeby to znosił - nie zakładaj odpowiedzi w tej samej sesji użytkownika.

Krok 1. Klucz API

Dostęp nadajemy indywidualnie. Napisz na help@pozywacz.pl. Podanie od razu poniższych informacji skraca ustalenia zwykle do jednej wymiany maili:

Sekret klucza pokazujemy tylko raz, w chwili generowania. Zapisz go od razu w swoim magazynie sekretów - odczytać ponownie się go nie da, można tylko wygenerować nowy.

Krok 2. Sprawdź połączenie

Zanim wyślesz pierwszą sprawę, upewnij się, że klucz działa. GET /case-typesnic nie tworzy i nie liczy się do kwoty, więc jest bezpiecznym testem:

curl https://pozywacz.pl/api/v1/case-types \
  -H "Authorization: Bearer pk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

W odpowiedzi dostajesz typy spraw dostępne dla Twojego konta wraz z pełnym opisem pól. Warto z tego korzystać zamiast przepisywać pola z dokumentacji na sztywno - lista jest generowana z tego samego źródła co walidator, więc nigdy się z nim nie rozjedzie.

Dostajesz 401? Sprawdź, czy nagłówek ma postać Bearer ze spacją i czy nie skopiowałeś klucza ze złamaniem linii. Przy 403 client_suspendednapisz do nas.

Krok 3. Wyślij pierwszą sprawę

Minimalne wywołanie to claimType i obiekt data. Poniższy przykład jest kompletny - możesz go wkleić i podmienić dane:

curl -X POST https://pozywacz.pl/api/v1/submissions \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sprawa-2026-00123" \
  -d '{
  "claimType": "b2b_payment_missing",
  "data": {
    "plaintiff": {
      "name": "Przykład Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "5252525252"
    },
    "defendant": {
      "name": "Dłużnik S.A.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "7010101010"
    },
    "defendantType": "business",
    "defendantPeselUnknown": false,
    "claimAmount": 12000,
    "claimInterest": true,
    "claimBusinessCosts": true,
    "contractSubject": "Wykonanie instalacji elektrycznej",
    "contractDescription": "Kompleksowe wykonanie instalacji elektrycznej w lokalu przy ul. ...",
    "contractDate": "2026-01-15",
    "paymentDue": "2026-05-10",
    "invoices": [
      {
        "fileName": "FV 1/2026",
        "amount": 12000,
        "dueDate": "2026-05-10"
      }
    ],
    "demandSent": true,
    "additionalInfo": "Dłużnik uznał dług mailowo w dniu ...",
    "files": [
      {
        "fileId": "clx9f2k7b0001abcd"
      }
    ]
  }
}'

Odpowiedź:

{
  "submissionId": "clx123abc...",
  "status": "RECEIVED",
  "orderId": "a1b2c3..."
}

• Zapisz submissionId przy swojej sprawie. To po nim rozpoznasz webhooka i odpytasz status.
• Zawsze wysyłaj Idempotency-Key - własny identyfikator sprawy z Twojego systemu. Powtórzenie żądania z tym samym kluczem zwróci istniejące zgłoszenie zamiast utworzyć duplikat, a duplikat to druga sprawa na Twojej fakturze.
• Walidacja jest ścisła. Nieznany klucz w data kończy się błędem 422, a nie cichym pominięciem - literówka w nazwie pola nie przejdzie niezauważona.

Krok 4. Dołącz dokumenty (opcjonalnie)

Faktury, umowy i korespondencję możesz dołączyć do sprawy. Najpierw wgrywasz plik, potem podajesz jego identyfikator przy składaniu sprawy:

# 1. wgraj plik
curl -X POST https://pozywacz.pl/api/v1/files \
  -H "Authorization: Bearer pk_live_..." \
  -F "file=@FV-1-2026.pdf"

# odpowiedź: { "fileId": "clx9f2k7b0001abcd", "extraction": { "status": "ok", ... } }

# 2. podaj fileId w polu data.files przy składaniu sprawy
#    "files": [{ "fileId": "clx9f2k7b0001abcd" }]

Pole extraction.status w odpowiedzi mówi, czy udało się odczytać treść dokumentu. ok to plik czytelny, pending oznacza skan, który spróbujemy rozpoznać przy przygotowaniu pisma. Szczegóły i limity: Załączniki.

Krok 5. Odbierz gotowe pismo

Są dwie drogi i możesz używać obu naraz.

Webhook - powiadamiamy Cię sami, gdy zgłoszenie jest gotowe. Ta sama struktura co odpowiedź GET /submissions/{id}, więc obsłużysz je jednym kodem. Weryfikuj podpis X-Pozywacz-Signature (szczegóły: Webhooki).

Odpytywanie - gdy nie masz publicznego adresu albo chcesz uzgodnić stan:

curl https://pozywacz.pl/api/v1/submissions/clx123abc... \
  -H "Authorization: Bearer pk_live_..."

Dopóki status to RECEIVED, GENERATING albo IN_REVIEW - sprawa jest w toku. Przy COMPLETED wypełnia się result, a w nim documentUrl:

curl -L https://pozywacz.pl/api/v1/submissions/clx123abc.../document \
  -H "Authorization: Bearer pk_live_..." \
  -o pozew.pdf

Dokumenty pobierasz tym samym kluczem API. Nie musisz zakładać konta Google ani niczego sobie udostępniać. W result.files[] znajdziesz też pozostałe pliki sprawy, w tym własne załączniki.

Zanim wejdziesz na produkcję

Najczęstsze pomyłki

• Wysyłanie plików jako JSON. POST /api/v1/files przyjmuje multipart/form-data, inaczej niż pozostałe endpointy.
• Zapominanie o defendantType. Pominięcie oznacza business. Przy dłużniku będącym osobą fizyczną zmienia to podstawę odsetek i wyklucza rekompensatę 40/70/100 EUR - podawaj to pole jawnie.
• Traktowanie załączników jako zamiennika pól. Odczyt dokumentu jest wsparciem, nie gwarancją. Kwoty, daty i dane stron zawsze podawaj też w data.
• Przetrzymywanie fileId. Plik nieprzypięty do sprawy kasujemy po 24 h. Wgrywaj dokumenty tuż przed złożeniem sprawy, nie z wyprzedzeniem.
• Poleganie na orderId. To nasz wewnętrzny identyfikator, przydatny w zgłoszeniach do wsparcia. Do śledzenia sprawy używaj submissionId.

Uwierzytelnianie

Każde żądanie musi zawierać Twój klucz API w nagłówku Authorization:

Authorization: Bearer pk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Sekret klucza pokazujemy tylko raz, w chwili generowania. Przechowuj go bezpiecznie - nie da się go odczytać ponownie.
• Klucz można w każdej chwili unieważnić i wygenerować nowy (rotacja) bez zmiany konta.
• Wszystkie wywołania idą po HTTPS. Nie umieszczaj klucza w kodzie front-endu.

Endpointy

{
  "caseTypes": [
    {
      "claimType": "b2b_payment_missing",
      "title": "Brak zapłaty za fakturę",
      "fields": [
        {
          "name": "plaintiff",
          "type": "party",
          "required": true
        },
        {
          "name": "defendant",
          "type": "party",
          "required": true
        }
      ]
    },
    {
      "claimType": "other",
      "title": "Inna sprawa",
      "fields": [
        {
          "name": "plaintiff",
          "type": "party",
          "required": true
        },
        {
          "name": "defendant",
          "type": "party",
          "required": true
        }
      ]
    }
  ]
}

{
  "claimType": "b2b_payment_missing",
  "data": {
    "plaintiff": {
      "name": "Przykład Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "5252525252"
    },
    "defendant": {
      "name": "Dłużnik S.A.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "7010101010"
    },
    "defendantType": "business",
    "defendantPeselUnknown": false,
    "claimAmount": 12000,
    "claimInterest": true,
    "claimBusinessCosts": true,
    "contractSubject": "Wykonanie instalacji elektrycznej",
    "contractDescription": "Kompleksowe wykonanie instalacji elektrycznej w lokalu przy ul. ...",
    "contractDate": "2026-01-15",
    "paymentDue": "2026-05-10",
    "invoices": [
      {
        "fileName": "FV 1/2026",
        "amount": 12000,
        "dueDate": "2026-05-10"
      }
    ],
    "demandSent": true,
    "additionalInfo": "Dłużnik uznał dług mailowo w dniu ...",
    "files": [
      {
        "fileId": "clx9f2k7b0001abcd"
      }
    ]
  }
}

{
  "submissionId": "clx123abc...",
  "status": "RECEIVED",
  "orderId": "a1b2c3..."
}

{
  "event": "submission.updated",
  "submissionId": "clx123abc...",
  "claimType": "b2b_payment_missing",
  "status": "COMPLETED",
  "createdAt": "2026-09-04T09:12:31.004Z",
  "completedAt": "2026-09-04T09:13:58.512Z",
  "error": null,
  "result": {
    "documentUrl": "https://pozywacz.pl/api/v1/submissions/clx123abc.../document",
    "files": [
      {
        "fileId": "1AbC…",
        "name": "Pozew_non-payment-work_v1.pdf",
        "mimeType": "application/vnd.google-apps.document",
        "downloadUrl": "https://pozywacz.pl/api/v1/submissions/clx123abc.../files/1AbC…"
      }
    ],
    "lawsuitHtml": "<div>POZEW O ZAPŁATĘ…</div>"
  }
}

{
  "items": [
    {
      "submissionId": "clx…",
      "claimType": "b2b_payment_missing",
      "status": "COMPLETED",
      "orderId": "a1b2c3...",
      "createdAt": "2026-09-04T09:12:31.004Z",
      "completedAt": "2026-09-04T09:13:58.512Z",
      "errorCode": null
    }
  ],
  "nextCursor": null
}

{
  "fileId": "clx9f2k7b0001abcd",
  "name": "FV-1-2026.pdf",
  "mimeType": "application/pdf",
  "size": 184320,
  "expiresAt": "2026-09-09T12:00:00.000Z",
  "extraction": {
    "status": "ok",
    "source": "pdf-text",
    "chars": 2841
  }
}

Cykl życia zgłoszenia

Przygotowanie pozwu jest asynchroniczne - nie blokuj na nim swojego procesu, tylko czekaj na webhooka albo odpytuj status. Każdy pozew przed wydaniem przechodzi kontrolę po naszej stronie: dopóki jej nie zamkniemy, zgłoszenie ma status IN_REVIEW, pole result jest puste i nie wysyłamy żadnego webhooka.

Kody błędów

Każdy błąd ma tę samą strukturę - kod czytelny dla maszyny i komunikat dla człowieka:

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are missing or invalid.",
    "issues": [
      {
        "path": "claimAmount",
        "message": "Required"
      },
      {
        "path": "claimBusinessCosts",
        "message": "Rekompensata za koszty odzyskiwania należności (40/70/100 EUR) przysługuje wyłącznie w transakcjach handlowych między przedsiębiorcami."
      }
    ]
  }
}

Osobno występuje generation_failed - to nie błąd HTTP, tylko kod w polu error.codezgłoszenia ze statusem FAILED. Oznacza, że żądanie było poprawne, ale przygotowanie pozwu się nie powiodło. Podobnie rejected_by_provider przy statusie REJECTED - sprawa nie przeszła naszej kontroli i pozwu nie wydajemy.

Typy spraw i pola formularza

Pole data w POST /api/v1/submissions zależy od claimType. Poniżej pełny zestaw pól każdego typu. Obiekt data jest walidowany ściśle - klucz spoza tabeli kończy się błędem 422, więc niczego nie trzeba zgadywać.

curl -X POST https://pozywacz.pl/api/v1/submissions \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "claimType": "b2b_payment_missing",
  "data": {
    "plaintiff": {
      "name": "Przykład Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "5252525252"
    },
    "defendant": {
      "name": "Dłużnik S.A.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "7010101010"
    },
    "defendantType": "business",
    "defendantPeselUnknown": false,
    "claimAmount": 12000,
    "claimInterest": true,
    "claimBusinessCosts": true,
    "contractSubject": "Wykonanie instalacji elektrycznej",
    "contractDescription": "Kompleksowe wykonanie instalacji elektrycznej w lokalu przy ul. ...",
    "contractDate": "2026-01-15",
    "paymentDue": "2026-05-10",
    "invoices": [
      {
        "fileName": "FV 1/2026",
        "amount": 12000,
        "dueDate": "2026-05-10"
      }
    ],
    "demandSent": true,
    "additionalInfo": "Dłużnik uznał dług mailowo w dniu ...",
    "files": [
      {
        "fileId": "clx9f2k7b0001abcd"
      }
    ]
  }
}'

{
  "claimType": "b2b_payment_missing",
  "data": {
    "plaintiff": {
      "name": "Przykład Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "5252525252"
    },
    "defendant": {
      "name": "Jan Przykładowy",
      "street": "ul. Kwiatowa",
      "houseNumber": "5",
      "apartmentNumber": "2",
      "city": "Kraków",
      "postalCode": "30-001",
      "pesel": "90010112345"
    },
    "defendantType": "individual",
    "defendantPeselUnknown": false,
    "claimAmount": 12000,
    "claimInterest": true,
    "claimBusinessCosts": false,
    "contractSubject": "Wykonanie instalacji elektrycznej",
    "contractDescription": "Kompleksowe wykonanie instalacji elektrycznej w lokalu przy ul. ...",
    "contractDate": "2026-01-15",
    "paymentDue": "2026-05-10",
    "invoices": [
      {
        "fileName": "FV 1/2026",
        "amount": 12000,
        "dueDate": "2026-05-10"
      }
    ],
    "demandSent": true,
    "additionalInfo": "Dłużnik uznał dług mailowo w dniu ...",
    "files": [
      {
        "fileId": "clx9f2k7b0001abcd"
      }
    ]
  }
}

curl -X POST https://pozywacz.pl/api/v1/submissions \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "claimType": "other",
  "data": {
    "plaintiff": {
      "name": "Przykład Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "5252525252"
    },
    "defendant": {
      "name": "Dłużnik S.A.",
      "street": "ul. Przykładowa",
      "houseNumber": "12",
      "city": "Warszawa",
      "postalCode": "00-001",
      "nip": "7010101010"
    },
    "claimAmount": 8000,
    "contractSubject": "Zwrot zaliczki za niewykonaną usługę",
    "whatWentWrong": "Wykonawca pobrał zaliczkę i nie przystąpił do prac mimo upływu terminu...",
    "additionalInfo": "Strony wymieniły korespondencję mailową w okresie ...",
    "files": [
      {
        "fileId": "clx9f2k7b0001abcd"
      }
    ]
  }
}'

Obiekt strony (plaintiff, defendant)

Pola typu „obiekt: strona” przyjmują wyłącznie poniższe klucze. Podawaj identyfikator właściwy dla rodzaju strony: firma - nip lub krs, osoba fizyczna - pesel.

Obiekt faktury (invoices[])

Lista przyjmuje maksymalnie 100 pozycji. Suma kwot nie musi równać się polu claimAmount.

Obiekt załącznika (files[])

Lista przyjmuje maksymalnie 10 plików, łącznie do 40 MB. Każdy element ma jeden z dwóch kształtów - albo referencja do pliku wgranego wcześniej, albo mały plik przesłany od razu:

[
  {
    "fileId": "clx9f2k7b0001abcd"
  },
  {
    "name": "umowa.pdf",
    "mimeType": "application/pdf",
    "contentBase64": "JVBERi0xLjQK..."
  }
]

Wariant inline jest ograniczony do 2 MB, bo tyle mieści się w ciele pojedynczego żądania. Większe pliki wysyłaj przez POST /api/v1/files.

Załączniki

Do każdej sprawy możesz dołączyć dokumenty - faktury, umowy, korespondencję. Trafiają do akt zlecenia razem z przygotowanym pismem i odczytujemy z nich treść, gdy redagujemy dokument.

Jak dołączyć

1. Wyślij plik do POST /api/v1/files i zapisz fileId.
2. Podaj go w polu data.files przy składaniu sprawy.

Pliki do 2 MB możesz też przesłać od razu w zgłoszeniu, w postaci contentBase64, bez osobnego żądania.

Limity

Załączniki nie są dodatkowo płatne - mieszczą się w miesięcznym rozliczeniu Twojego konta.

Jak czytamy pliki

PDF-y z warstwą tekstową i pliki DOCX odczytujemy wprost, bez rozpoznawania obrazu. Skany i zdjęcia przepuszczamy przez rozpoznawanie tekstu, co daje wynik zauważalnie mniej pewny.

Praktyczna wskazówka: wysyłaj PDF generowany z systemu księgowego, a nie skan wydruku. Odczyta się pewniej, a dane w piśmie będą dokładniejsze.

Odczyt treści jest wsparciem, nie gwarancją - słaby skan może się nie odczytać. Kwoty, daty i dane stron podawaj zawsze także w polach data. To one są źródłem prawdy: nie nadpisujemy pól tym, co znaleźliśmy w załączniku.

Odbiór dokumentów

Po zwolnieniu zgłoszenia result.files[] zawiera wszystkie pliki sprawy - przygotowane pismo, instrukcję i Twoje załączniki - każdy z gotowym downloadUrl. Pobierasz je tym samym kluczem API.

Webhooki

Jeśli skonfigurujemy dla Ciebie adres webhooka, wyślemy na niego POST z wynikiem - ale dopiero po zamknięciu naszej kontroli. Wcześniej (status IN_REVIEW) nie wysyłamy żadnego webhooka. Treść jest podpisana Twoim sekretem:

X-Pozywacz-Signature: sha256=<hmac_sha256(webhookSecret, body)>

Treść jest identyczna z odpowiedzią GET /api/v1/submissions/{id}, więc obie ścieżki obsłużysz jednym kodem. Opis wszystkich pól znajdziesz przy tym endpoincie.

Zweryfikuj podpis na surowym ciele żądania, zanim je sparsujesz - ponowne serializowanie JSON-a zmienia bajty i psuje porównanie:

const crypto = require('crypto');

// rawBody: Buffer/string dokładnie tak, jak przyszedł
function isFromPozywacz(rawBody, signatureHeader, webhookSecret) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', webhookSecret)
        .update(rawBody)
        .digest('hex');
    const a = Buffer.from(expected);
    const b = Buffer.from(signatureHeader || '');
    return a.length === b.length && crypto.timingSafeEqual(a, b);
}

• Wysyłamy POST dopiero po zwolnieniu zgłoszenia z kontroli - przy COMPLETED, FAILED i REJECTED. W trakcie kontroli webhook nie leci nigdy.
• Odpowiedz kodem 2xx, aby potwierdzić odbiór. Każda inna odpowiedź liczy się jako nieudana.
• Czekamy na odpowiedź maksymalnie 10 sekund. Nie wykonuj ciężkiej pracy synchronicznie - przyjmij i przetwórz asynchronicznie.
• Ponawiamy do 5 prób łącznie.
• Ta sama sprawa może dotrzeć więcej niż raz - obsłuż odbiór idempotentnie po submissionId.
• Webhook jest opcjonalny i najlepiej traktować go jako przyspieszenie, nie jedyne źródło prawdy. Jeśli nie dotarł, stan zawsze uzgodnisz przez GET /api/v1/submissions.

Limity i rozliczenia

• Rate limit - liczba zapytań na minutę, ustalana per konto (domyślnie 60/min).
• Kwota miesięczna - opcjonalny limit liczby zgłoszeń w miesiącu kalendarzowym. Po przekroczeniu zwracamy 429 quota_exceeded.
• Rozliczenie - na podstawie liczby zgłoszeń, jedną fakturą zbiorczą miesięcznie na dane Twojej firmy (zgodnie z umową).