Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak wygrany deal zamienia się w fakturę
Zmiana statusu deala na wygrany (status: won) przychodzi do integracji jako webhook (Webhooks v2, obiekt deal, akcja change). Integracja porównuje poprzedni i obecny status, żeby reagować tylko na faktyczne wygranie, a potem pobiera przez API Pipedrive deal, powiązaną organizację i produkty deala (GET /api/v2/deals/{id}/products) z ilością, ceną, rabatem i stawką podatku. Do API Fakturowni (POST /invoices.json) wysyła gotową fakturę: nabywcę z NIP-em, pozycje z ceną netto i stawką VAT, termin płatności i walutę deala. Jeśli firma jest już w Fakturowni, integracja podaje jej client_id, żeby nie mnożyć kontrahentów.
NIP trzymam w polu niestandardowym organizacji. Zamiast faktury może powstać proforma, a faktura dopiero po zaksięgowaniu wpłaty. Przy dealach w walucie obcej kurs i przeliczenie liczy Fakturownia według ustawień konta.
KSeF zostaje w Fakturowni
Nie buduję własnej wysyłki do KSeF. Fakturownia ma ją wbudowaną: faktura z oznaczeniem, że nabywca jest firmą, idzie do KSeF automatycznie albo na zlecenie z API (gov_save_and_send). Numer KSeF i status wysyłki przychodzą w webhooku i zapisują się w dealu. Na koncie z produkcyjnym KSeF Fakturownia wysyła klientowi e-mail z fakturą dopiero po nadaniu numeru KSeF (lub w trybie offline), więc klient nie dostaje dokumentu, którego nie ma w systemie.
Co wraca do Pipedrive
Fakturownia wysyła webhook invoice:update przy każdej zmianie faktury. Integracja czyta z niego status (wystawiona, wysłana, opłacona, częściowo opłacona) i numer KSeF, a w polach niestandardowych deala zapisuje numer faktury, link do PDF i datę płatności. Na tych polach da się zbudować filtr zaległości, aktywność z przypomnieniem dla handlowca albo raport przychodu faktycznie zapłaconego, a nie tylko wygranego.
Duplikaty, limity i błędy
Identyfikator deala trafia do pola numeru zamówienia (oid) z włączoną unikalnością, więc ponowne zamknięcie tego samego deala nie wystawi drugiej faktury. Zapis pól przez API sam wywołuje webhook change, więc integracja rozpoznaje własne zmiany i nie zapętla się. Webhooki Pipedrive nie zużywają dziennego budżetu API, a jedna faktura to kilka wywołań, więc limit konta nie jest problemem. Każde wywołanie przechodzi przez kolejkę z ponowieniami. Gdy Fakturownia odrzuci dane (np. brak NIP-u albo niepoprawna stawka VAT), faktura czeka, a w Pipedrive pojawia się aktywność z opisem błędu dla właściciela deala.