Szczegóły techniczne dla osoby, która będzie odbierać wdrożenie.
Jak wygrany deal zamienia się w fakturę
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), a potem wysyła do API Fakturowni (POST /invoices.json) gotową fakturę: nabywcę z NIP-em, pozycje z ilością, ceną netto i stawką VAT, termin płatności i walutę. Jeśli firma jest już w Fakturowni, integracja podaje jej client_id, żeby nie mnożyć kontrahentów. Webhooki aplikacji działają niezależnie od planu HubSpot, więc workflow nie jest wymagany. Rozwiązania partnerów HubSpot w wariancie z workflow opierają się na własnym kodzie (custom code actions), dostępnym dopiero w Data Hub Professional.
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 HubSpot
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 dealu zapisuje numer faktury, link do PDF i datę płatności. Na tych właściwościach da się zbudować widok zaległości, przypomnienia dla handlowca albo raport przychodu faktycznie zapłaconego, a nie tylko wygranego.
Duplikaty 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. 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 HubSpot pojawia się zadanie z opisem błędu dla właściciela deala.