Dokumentacja Contrata

Contrata wspiera zespoły HR, finansów i operacji w prowadzeniu rozliczeń z kontrahentami: przechowuje dane osób współpracujących, planuje harmonogramy wypłat, generuje dokumenty księgowe (faktury, rachunki) oraz ewidencję czasu pracy w PDF, a także umożliwia eksport przelewów do banku.

1. 1

   Załóż konto i zaloguj się

   Zarejestruj się e-mailem lub przez Google. Rejestrując się, akceptujesz Politykę prywatności i Regulamin Contrata. Po pierwszym logowaniu system utworzy organizację (jeśli nie dołączasz przez zaproszenie) i rozpocznie okres próbny subskrypcji.

2. 2

   Przejdź onboarding (3 kroki)

   • Krok 1 — dane firmy: nazwa, adres, NIP
   • Krok 2 — opcjonalne zaproszenia zespołu (administrator / manager)
   • Krok 3 — pierwsi kontrahenci i stanowiska
3. 3

   Skonfiguruj organizację

   W Ustawienia → Firma ustaw liczbę terminów wypłat w każdym okresie rozliczeniowym (2–4), waluty wypłat i konta bankowe organizacji. W Stanowiska dodaj role przypisywane kontrahentom.

4. 4

   Dodaj kontrahentów

   W module Kontrahenci wprowadź dane umowy (B2B lub UoD), kwotę miesięczną, datę startu rozliczeń (do 30 dni od dziś), walutę, dane rozliczeniowe i numer konta. Dla B2B podaj też e-mail — kontrahent może otrzymać zaproszenie do portalu. Możesz zaimportować listę z CSV (Ustawienia → Import).

5. 5

   Obserwuj kalendarz i dokumenty

   System zaplanuje wypłaty na 3 okresy rozliczeniowe od daty startu. W dniu każdego terminu automatycznie powstaną faktura/rachunek oraz ewidencja pracy — sprawdzisz je w odpowiednich modułach panelu.

Moduł Kontrahenci (/dashboard/pracownicy) to punkt startowy w większości pracy. Tu dodajesz, edytujesz i dezaktywujesz osoby objęte rozliczeniami.

Dane kontrahenta obejmują:

• Imię i nazwisko, e-mail, adres
• Typ umowy: B2B (faktura) lub UoD (rachunek)
• Stanowisko, kwota miesięczna (brutto/netto), waluta
• Start rozliczeń — data, od której liczą się okresy rozliczeniowe i planowane wypłaty (wybór z listy: dziś do 30 dni do przodu)
• NIP, numer konta bankowego (IBAN)
• Prefiks numeracji dokumentów
• Status aktywny / nieaktywny
• Portal B2B — ikona przy imieniu: brak konta / zaproszenie wysłane / konto aktywne (tylko umowa B2B z adresem e-mail)
• Źródło ewidencji — ikona integracji w tabeli (Jira, Asana, Toggl itd.) po mapowaniu w modalu kontrahenta
• Mapowanie użytkownika integracji w sekcji Ewidencja pracy modalu

Kontrahenci nieaktywni nie wchodzą w nowe harmonogramy wypłat. Liczba aktywnych kontrahentów może wpływać na rozmiar subskrypcji zgodnie z cennikiem. Zmiana typu umowy UoD → B2B (z e-mailem) uruchamia zaproszenie do portalu; B2B → UoD odłącza konto portalu.

Kalendarz pokazuje zaplanowane terminy i kwoty wypłat dla aktywnych kontrahentów. Planowanie opiera się na okresach rozliczeniowych od daty startu kontrahenta (pole Start rozliczeń w modalu), a nie na kalendarzowych miesiącach.

• System utrzymuje harmonogram na 3 pełne okresy do przodu (np. start 3 VI → wypłaty w okresach do ok. 2 IX)
• W każdym okresie suma wypłat = kwota miesięczna kontrahenta; liczba terminów w okresie wynika z ustawień firmy (2–4)
• Widok miesiąca — kliknij dzień, aby zobaczyć listę wypłat tego dnia (w tym okresy rozliczeniowe nachodzące na dany miesiąc kalendarzowy)
• Widok listy — chronologiczny przegląd wszystkich terminów w wybranym miesiącu kalendarzowym
• Status Zaplanowana — termin w przyszłości, dokumenty jeszcze nie wygenerowane
• Po wygenerowaniu dokumentów status przechodzi w zrealizowaną / wysłaną wypłatę

W dniu terminu wypłaty system automatycznie tworzy fakturę lub rachunek oraz ewidencję pracy. Przed datą startu rozliczeń w kalendarzu nie ma zaplanowanych wypłat. Szczegóły dokumentów — w modułach Faktury i Ewidencja pracy.

Ewidencja to dokument PDF powstający automatycznie razem z fakturą lub rachunkiem dla danego terminu wypłaty kontrahenta.

• Treść (zadania, godziny, kod projektu) wynika z ustawień kontrahenta, stanowiska oraz okresu rozliczeniowego przypisanego do danego terminu wypłaty (od daty startu kontrahenta, nie od 1. dnia miesiąca kalendarzowego)
• Przy mapowaniu integracji (Jira, Asana, Toggl, Teamwork, Trello, ClickUp) dane pochodzą z wybranego narzędzia; bez mapowania — ewidencja syntetyczna
• Filtruj po miesiącu i kontrahencie, podglądaj PDF, pobieraj pojedynczo lub paczką ZIP
• Możesz oznaczać dokumenty jako pobrane

Moduł gromadzi wygenerowane faktury (B2B) i rachunki (UoD). Typ dokumentu wynika z umowy kontrahenta.

• Numeracja, kwota i waluta pochodzą z danych kontrahenta oraz reguł organizacji (liczba terminów wypłat w okresie rozliczeniowym 2–4, podział kwoty miesięcznej między terminy)
• Dokument powstaje w dniu terminu wypłaty z harmonogramu — nie tworzysz go ręcznie
• Filtruj po miesiącu i kontrahencie, wyszukuj po nazwie lub numerze
• Podgląd PDF, pobieranie pojedyncze lub ZIP zaznaczonych dokumentów

Moduł Umowy służy do archiwizacji podpisanych umów współpracy z kontrahentami w formacie PDF.

• Prześlij plik PDF powiązany z konkretnym kontrahentem
• Podgląd i pobieranie umów z poziomu listy
• Umowy są dostępne także przez API (read:signed-contracts)

Archiwum zbiera historyczne dokumenty rozliczeniowe oraz umowy, ułatwiając wyszukiwanie starszych plików bez przechodzenia przez bieżące widoki operacyjne.

Moduł Kontrola PIP pomaga przygotować zestaw materiałów wymaganych podczas kontroli PIP: manifesty dokumentów, ewidencje, umowy i powiązane pliki dla wybranych kontrahentów i okresów.

Zakładka Ustawienia ma układ pionowych kart:

Subskrypcja Contrata jest rozliczana przez Stripe. Administrator wybiera plan (Team, Business, Enterprise) i interwał (miesięczny / roczny). Liczba aktywnych kontrahentów wpływa na liczbę płatnych miejsc (seats).

• Status subskrypcji i szacowany abonament — w Ustawienia → Płatności
• Portal klienta Stripe — faktury abonamentu, metoda płatności, historia
• Okres próbny — dostęp do modułów do momentu aktywacji planu
• Po anulowaniu subskrypcji lub zakończeniu trialu bez płatnego planu dane organizacji są automatycznie usuwane po 30 dniach (szczegóły w sekcji RODO)
• Przy problemach z płatnością skontaktuj się z administratorem organizacji

W Profilu każdy użytkownik może włączyć 2FA przez SMS(Firebase). Wymagany jest potwierdzony e-mail oraz skonfigurowane SMS MFA w projekcie Firebase.

Administrator w Ustawienia → Bezpieczeństwo ustawia politykę organizacji:

• Opcjonalne — każdy decyduje sam
• Wymagane dla wszystkich — brak 2FA blokuje dostęp do panelu (Profil pozostaje dostępny)

Przy logowaniu hasłem lub Google, jeśli konto ma 2FA, po pierwszym składniku pojawia się krok z kodem SMS. Status 2FA członków widoczny jest na liście zespołu (administrator).

Integracje konfigurujesz w Ustawienia → Integracje (administrator lub manager). Mapowanie kontrahenta → użytkownik narzędzia w modalu kontrahenta, sekcja Ewidencja pracy. Każdy kontrahent ma jedno źródło danych. Odłączenie integracji czyści mapowania.

Portal działa pod adresem kontrahenci.contrata.pl (osobne konto użytkownika — nie loguj się tam kontem organizacji). Dotyczy wyłącznie kontrahentów z umową B2B i adresem e-mail.

1. 1

   Zaproszenie (perspektywa organizacji)

   • Dodaj kontrahenta B2B z poprawnym e-mailem — po zapisie system wysyła zaproszenie (link ważny 30 dni)
   • W liście kontrahentów ikona przy imieniu: brak konta / oczekujące / aktywne
   • Możesz ponownie wysłać zaproszenie lub odłączyć konto z modułu kontrahentów
2. 2

   Aktywacja konta (perspektywa kontrahenta)

   • Kliknij link z e-maila → ustaw hasło na stronie akceptacji zaproszenia
   • Zaloguj się na portalu (e-mail + hasło lub Google, jeśli dostępne)
   • Jeśli masz już konto kontrahenta u innego pracodawcy, ten sam login może obsłużyć wiele organizacji
3. 3

   Co kontrahent widzi w portalu

   • Faktury — lista i pobieranie PDF faktur B2B
   • Ewidencja pracy — PDF ewidencji za okresy wypłat
   • Kalendarz wypłat — zaplanowane terminy i kwoty
   • KSeF — podłączenie tokenu i wysyłka faktur (osobna sekcja poniżej)
   • Profil — zmiana hasła i danych konta
4. 4

   E-maile automatyczne

   • Zaproszenie do portalu (nowe konto)
   • Powiadomienie o dołączeniu do organizacji (istniejące konto)
   • Po wygenerowaniu wypłaty: linki do PDF faktury/rachunku i ewidencji + link do portalu

Integracja KSeF jest dostępna wyłącznie w portalu kontrahenta (kontrahenci.contrata.pl). Organizacja nie konfiguruje KSeF w swoim panelu — kontrahent B2B podłącza własny token MCU i wysyła faktury wygenerowane przez Contrata.

1. 1

   Wygeneruj token w MCU

   Zaloguj się na podatki.gov.pl → Moduł Certyfikatów i Uprawnień (MCU) → sekcja KSeF → wygeneruj token autoryzacyjny dla NIP, którym wystawiasz faktury B2B.

2. 2

   Podłącz w portalu Contrata

   • Portal → KSeF
   • Podaj NIP (10 cyfr), wklej token, wybierz środowisko demo lub prod
   • Token jest przechowywany zaszyfrowany — po zapisie nie jest ponownie wyświetlany
3. 3

   Wyślij fakturę

   • Portal → Faktury → przy fakturze bez numeru KSeF użyj akcji wysyłki
   • Po sukcesie faktura otrzymuje numer KSeF; w PDF może pojawić się kod QR
   • Token testowy działa tylko w środowisku demo i odwrotnie

Administrator zarządza danymi organizacji w Ustawienia → Konto. Sekcja Usuwanie danych (RODO) dotyczy wszystkich danych: kontrahentów, PDF, integracji, kluczy API i ustawień.

Contrata udostępnia API v1 pod adresem /api/v1/…. Endpointy wymagają klucza API z odpowiednim zakresem uprawnień. Klucze tworzy administrator w Ustawienia → API (maksymalnie 10 kluczy na organizację).

Dostępne zakresy (scopes):

• read:organization
• read:employees
• read:schedules
• read:documents
• read:signed-contracts
• write:payouts
• manage:webhooks

Każde żądanie do API v1 musi zawierać nagłówek Authorization z tokenem Bearer:

Authorization: Bearer ctr_live_xxxxxxxxxxxxxxxx

Odpowiedzi błędów:

• 401 — brak lub nieprawidłowy klucz
• 403 — klucz nie ma wymaganego scope
• 404 — zasób nie istnieje
• 400 — nieprawidłowe parametry żądania

Typy dokumentów (type): faktura, rachunek, ewidencja. Daty w formacie YYYY-MM-DD.

Webhooki pozwalają otrzymywać powiadomienia HTTP o zdarzeniach w organizacji. Subskrypcja wymaga scope manage:webhooks. Maksymalnie 20 aktywnych webhooków na organizację.

Obsługiwane zdarzenia:

• document.created — utworzono nowy dokument PDF
• payout.generated — wygenerowano dokumenty wypłaty

Subskrypcja:

POST /api/v1/webhooks/subscribeAuthorization: Bearer ctr_live_…Content-Type: application/json{  "targetUrl": "https://hooks.example.com/contrata",  "events": ["payout.generated", "document.created"]}→ { "id": "hookId", "secret": "hex-secret" }

Payload wysyłany jest metodą POST na targetUrl. Podpis HMAC-SHA256 (nagłówek z sekretem webhooka) pozwala zweryfikować autentyczność żądania.

1. Pobierz listę aktywnych kontrahentów

curl -s -H "Authorization: Bearer $CONTRATA_API_KEY" \  "https://twoja-domena.pl/api/v1/employees"

2. Harmonogram wypłat za maj 2026

curl -s -H "Authorization: Bearer $CONTRATA_API_KEY" \  "https://twoja-domena.pl/api/v1/schedules?year=2026&month=5"

3. Wygeneruj dokumenty wypłaty w danym terminie

curl -s -X POST \  -H "Authorization: Bearer $CONTRATA_API_KEY" \  -H "Content-Type: application/json" \  -d '{"employeeId":"abc123","date":"2026-05-15"}' \  "https://twoja-domena.pl/api/v1/payouts/materialize"→ { "scheduleId": "…", "documentIds": ["…"], "skipped": false }

4. Pobierz faktury kontrahenta

curl -s -H "Authorization: Bearer $CONTRATA_API_KEY" \  "https://twoja-domena.pl/api/v1/documents?employeeId=abc123&type=faktura&limit=50"

Formularz jest dostępny wyłącznie dla zalogowanych użytkowników Contrata. Po wysłaniu zgłoszenia otrzymasz potwierdzenie na swój adres e-mail, a zespół wsparcia odpowie w tej samej wątku korespondencji.