Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak wygrany deal zamienia się w fakturę FA(3)
Zmiana etapu deala na wygrany uruchamia integrację (webhook aplikacji HubSpot albo akcja w workflow). Integracja pobiera przez CRM API deal, powiązaną firmę i pozycje deala (line items) i buduje z nich dokument w schemie FA(3), czyli w strukturze, której od 2026 roku wymaga KSeF. Pozycje z ilością, ceną netto, rabatem i stawką VAT przechodzą na fakturę jako osobne wiersze. Webhooki aplikacji działają niezależnie od planu HubSpot, więc workflow nie jest wymagany.
Jeśli faktury powstają w narzędziu faktur HubSpot, punktem startu jest faktura (obiekt invoices) w statusie otwartej, z powiązanym kontaktem, firmą i pozycjami. Zmiany faktur odbieram webhookiem, a tam, gdzie konto go nie udostępnia, cyklicznym odpytywaniem API. Dane dla KSeF biorą się wtedy z faktury HubSpot, więc kwoty zgadzają się z dokumentem, który widział klient.
NIP nabywcy pochodzi z właściwości firmy w HubSpot. 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 HubSpot
Po przyjęciu faktury KSeF nadaje jej numer. Integracja zapisuje go we własnych właściwościach deala (i faktury HubSpot, jeśli z niej korzystasz) razem z datą przyjęcia i linkiem do PDF. Obok zapisuje UPO, czyli urzędowe poświadczenie odbioru faktury przez KSeF. Na tych właściwościach da się zbudować widok faktur, które utknęły, albo raport przychodu faktycznie zafakturowanego.
Korekty i duplikaty
Identyfikator deala (lub faktury HubSpot) jest kluczem idempotencji: ponowne zamknięcie tego samego deala nie wystawi drugiej faktury. Korekta powstaje na wyraźny sygnał (zmiana właściwości deala albo akcja w workflow) i wskazuje numer KSeF faktury pierwotnej. Obejmuje tylko zmienione pozycje i kwoty. Moment wystawienia faktury, zaliczki i proformy ustalamy z księgową przed startem, bo to decyzje podatkowe, a nie techniczne.
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.