KSeF ma pobierać zakupy (faktury kosztowe) do Trawersa - jakie zmiany/rozbudowy są potrzebne w SOA(API)
Cel: pobieranie faktur kosztowych z KSeF i automatyczne rejestrowanie w Trawers (ZO).
PS: Ważne: Trawers już ma mechanizm dopisywania faktur zakupu z XML ECOD EDI INVOICE przez SOA
'<Document-Invoice>' i ta ścieżka jest technicznie oparta o wspólną procedurę 'InvoiceZO_EDI()',
która wyszukuje asortyment po EAN wg KIM/KID .
To można wykorzystać w na końcowym etapie procesu KSeF->Trawers.
1.1 Nowe usługi SOA dla KSeF-Inbound (co dodać)
(Propozycja AI)
1. KsefInboxSync (pobierz metadane / listę)
* Wejście: zakres dat, tryb (nowe/zmienione), filtr (oddział/podmiot)
* Wyjście: lista dokumentów (identyfikatory KSeF, NIP dostawcy, daty, suma, waluta, typ: FA/FK)
Cel: budowa 'inboxa' po stronie Trawers (gdy pobiera się pojedyńczo).
2. KsefInvoiceDownload (pobierz treść)
* Wejście: identyfikator KSeF
* Wyjście: treść e-faktury (XML) + metadane
3. KsefInvoiceImportToZO (import do Trawers)
* Wejście: identyfikator KSeF (lub już pobrany XML), tryb dopasowania dostawcy/asortymentu
* Wyjście: `erpKey` (numer dokumentu ZO: FA/FK), status importu, lista błędów/ostrzeżeń
4. KsefInboxStatus / Retry / Reject (operacyjne)
* status pozycji w inboxie: NEW / DOWNLOADED / IMPORTED / ERROR / DUPLICATE
* retry importu po poprawie kartotek
* oznaczenie nie importować (gdy dokument dotyczy innej spółki/nie ten NIP itp.)
1.2 Wewnętrzna kolejka 'INBOX'
KSeF inbound jest z natury asynchroniczny, więc potrzebny jest zbiór/tabela np. `KSEF_INBOX`:
* `ksefId` (unikalny), `supplierNip`, `invoiceNumber`, `invoiceDate`, `receivedAt`
* `net/gross/vat`, `currency`
* `state` + `attempts`, `lastError`
* mapowanie do dokumentu w ERP: `zoDocumentNr` / `erpKey`
* ślad audytowy: kto/import kiedy
Idempotencja: klucz = `ksefId`.
Import drugi raz ma zwracać: już zaimportowane + numer dokumentu w ZO.
1.3 Mapowanie KSeF -> Trawers
(Propozycja AI)
Tu są największe koszty wdrożenia.
1. Dopasowanie dostawcy (Vendor matching)
KSeF daje NIP i dane wystawcy. W Trawersie trzeba:
* znaleźć dostawcę po NIP (albo ILN / inne identyfikatory),
* jeśli brak - polityka: *auto-dodaj dostawcę* (SOA ma VendorNewRequest) lub *wrzuć do kolejki błędu*.
Jeśli planujesz 'auto-dodaj', to warto dodać w imporcie reguły wypełniania pól z KSeF.
2. Dopasowanie pozycji/asortymentu
Największy problem: faktury kosztowe często mają:
* opis usługi bez kodów,
* brak EAN,
* własne kody dostawcy.
Obecny mechanizm `InvoiceZO_EDI()` (wykorzystywany przez `<Document-Invoice>`)
szuka po EAN wg KIM/KID . To działa dobrze tylko, gdy masz EAN-y i KID-y.
Dlatego zwykle potrzebujesz rozszerzeń:
* fallback 1: szukaj po kodzie dostawcy / MPN / indeksie (jeśli jest),
* fallback 2: mapa dostawca+kod indeks KIM (słownik translacji),
* fallback 3: jeśli brak dopasowania: import jako usługa obca /
pozycja niemagazynowa z grupą zakupową (zależnie od zasad firmy).
3. VAT, RC, terminy, daty
Import musi prawidłowo ustalić:
* stawki VAT i numer PTU na dzień transakcji (analogicznie do EDI INVOICE;
Trawers ma logikę ustalania stawki/NRPTU) ,
* VAT reverse charge / RC (w Trawersie jest opisana logika RC w zakupach) ,
* datę dokumentu vs datę otrzymania (w VAT/JPK to bywa istotne).
4. LOT/SER
Jeśli KSeF/źródło zawiera numer seryjny/partię - trzeba zmapować na LOT/SER w ZO
(w EDI jest jedno pole `SerialNumber`, a Trawers zapisuje do LOT albo SER
zależnie od wskaźnika w KIM) .
(Propozycja AI)
Najbardziej praktyczna architektura jest taka:
KSeF -> (parser/maper) -> generujesz ECOD XML INVOICE -> wywołujesz SOA `<Document-Invoice>`
-> powstaje dokument ZO [FA/FK]
Dlaczego:
* `<Document-Invoice>` jest oficjalnym wejściem do automatycznego dopisywania faktur zakupu i korekt w ZO ,
* już zawiera sporo logiki zakupowej i dopasowań (np. EAN->KIM/KID) ,
* ograniczasz zmiany w samym Trawersie do: kef-inbox + mapping + proces.
W praktyce zmiany w SOA mogą być wtedy mniejsze: zamiast pisać pełny importer ZO od zera, piszesz:
* usługi KSeF download/sync,
* translator KSeF->INVOICE(ECOD),
* kontrolę błędów i kolejkę.
1.5 Obsługa dostaw [DA] i powiązań
Jeżeli firma pracuje z dostawami:
* awizo DESADV i dokument [DA] można rejestrować przez SOA `Document-DespatchAdvice` ,
* dokumenty EDI [DA] i [FA] mogą być automatycznie kojarzone (w programie jest proces kojarzenia) .
KSeF sam w sobie nie daje 'awiza dostawy', ale klienci często chcą:
* jeśli faktura dotyczy towaru magazynowego, a mają politykę 'FA zawsze z DA' (parametr ZO),
to import faktury bez DA może blokować proces .
Wtedy trzeba ustalić strategię:
* albo import faktury tworzy towary w drodze,
* albo wymagane jest wcześniejsze/ równoległe wczytanie DA (z WMS/EDI), nie z KSeF.
1.6 Minimalny zestaw zmian
(Propozycja AI)
1. `KsefInboxSync` + `KsefInvoiceDownload`
2. `KsefInvoiceImportToZO` zbudowane jako: KSeFECOD INVOICE->`<Document-Invoice>`
3. `KSEF_INBOX` + idempotencja po `ksefId`
4. reguły dopasowania dostawcy po NIP + procedura obsługi braków
5. rozszerzenie dopasowania pozycji (mapa kodów dostawcy -> KIM / usługi)
W kolejnym kroku mogą rozpisać warianty dopasowania pozycji (najczęstsze problemy)
i zaproponuję konkretną politykę:
* co robić, gdy brak EAN,
* kiedy auto-dodawać dostawcę,
* jak rozróżniać zakup towarów vs usług w imporcie,
* jak wykrywać duplikaty (KSeF vs numer obcy faktury).