Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak wygrany deal zamienia się w fakturę FA(3)
Integracja subskrybuje webhook v2 change.deal i reaguje, gdy status deala zmienia się na won. Payload zawiera blok previous ze zmienionymi polami, więc łatwo odróżnić wygranie deala od zwykłej edycji. Integracja pobiera przez API deal, powiązaną organizację i produkty deala (GET /api/v2/deals/{id}/products), a potem buduje dokument w schemie FA(3), czyli w strukturze, której od 2026 roku wymaga KSeF. Każdy produkt przechodzi na fakturę jako osobny wiersz z ilością, ceną, rabatem i stawką VAT.
NIP nabywcy pochodzi z własnego pola organizacji. Integracja sprawdza go w wykazie podatników VAT (Biała lista) dla firm z Polski i w VIES dla firm z UE, a nazwę i adres uzupełnia z rejestru. Do KSeF integracja loguje się tokenem lub certyfikatem wygenerowanym w Twoim KSeF, z uprawnieniem tylko do wystawiania faktur.
Co wraca do Pipedrive
Po przyjęciu faktury KSeF nadaje jej numer. Integracja zapisuje go we własnych polach deala razem z datą przyjęcia, a PDF faktury dodaje jako plik w dealu. Obok zapisuje UPO, czyli urzędowe poświadczenie odbioru faktury przez KSeF. Na tych polach da się zbudować filtr deali wygranych, ale jeszcze niezafakturowanych.
Webhooki, limity i duplikaty
Pipedrive ponawia nieudany webhook trzy razy w ciągu kilku minut, a po kilku dniach bez udanej dostawy usuwa go. Dlatego obok webhooka działa okresowe uzgadnianie: integracja odpytuje API o deale wygrane od ostatniego sprawdzenia i dopisuje te, które mogły się zgubić. Pipedrive liczy limit API w tokenach na dzień (zależnie od planu i liczby licencji), a jedna faktura to kilka odczytów i jeden zapis, więc przy typowym wolumenie limit nie jest problemem.
Identyfikator deala jest kluczem idempotencji: ponowne oznaczenie tego samego deala jako wygranego nie wystawi drugiej faktury. Korekta powstaje na wyraźny sygnał (pole w dealu albo automatyzacja) i wskazuje numer KSeF faktury pierwotnej.
Gdy KSeF nie działa
Każda faktura przechodzi przez kolejkę z ponowieniami. Chwilowy błąd API oznacza kolejną próbę, a nie zgubioną fakturę. Gdy fakturę trzeba wydać bez KSeF, integracja wystawia ją w trybie offline. Tryby offline24, niedostępności i awarii to technicznie ta sama ścieżka z innym terminem dosłania. Faktura dostaje dwa kody QR, z których drugi jest podpisany certyfikatem KSeF, a integracja pilnuje terminu i dosyła ją sama. Błąd danych, którego nie naprawi ponowienie, trafia jako zadanie do właściciela deala.