Przejdź do treści

PostingInstruction

PostingInstruction to kanoniczny zasób bufora dokumentów przekazywanych do księgowości do dalszego procedowania (dekretacja, ewidencja VAT, przygotowanie pod JPK). Model jest jeden i rozszerzalny przez attribute[] oraz profile walidacji.

Ten dokument zastąpił starszy wariant oparty o sourceDocument oraz postingLine[] jako warstwę zlecenia księgowania.

Kontrakt maszynowy (JSON Schema): PostingInstruction.schema.json, PostingInstructionLine.schema.json, AllocationItem.schema.json. Endpoint: /v1/posting-instructions (§5b).

Rozszerza DomainResource.

1. Zakres i granica odpowiedzialności

Aspekt Opis
PostingInstruction Bufor opisu dokumentu od systemu zewnętrznego (co system wie o dokumencie i jak ma być procedowany).
Księgowość Przetwarza bufor, wykonuje dekretację i ewidencję VAT; wynik księgowania jest dostępny jako JournalEntry.
DocumentReference Nie jest zasobem wejściowym w tym procesie integracyjnym.

2. Pola nagłówka

Poza polami z DomainResource (id, resourceType, meta, owner[] — wymagany, NIP, comment, category[], status — słownik posting-instruction-status, nadawany przez księgowość, type, contained[], attribute[] — §4):

Wszystkie pola kodowane (CodeableConcept) niosą coding.system wskazujący słownik (value set) — pełny rejestr w Systemy kodowania i value sety.

Nazwa Kard. Typ Opis
identifier 0..* Identifier Identyfikatory dokumentu: co najmniej id dokumentu w systemie źródłowym i numer dokumentu — §2a.
participant 0..* Participant Uczestnicy dokumentu: function = CodeableConcept (słownik posting-instruction-participant-function), actor = Reference(Party) przez identifier. Uczestnik bez funkcji to kontrahent dokumentu; funkcja vat-group-member oznacza członka grupy VAT.
attachment 0..* Attachment Załączniki; url = adres dokumentu źródłowego (obraz faktury), title = numer/nazwa. W zapisie przekazywany jest pierwszy załącznik.
issueDate 1..1 date Data wystawienia dokumentu.
realizationDate 0..1 date Data otrzymania / realizacji.
symbol 1..1 CodeableConcept Symbole dokumentu — dwa kodowania w dwu słownikach (§2b).
sourceSystem 1..1 CodeableConcept System źródłowy, który nadał dokument. coding niesie kody systemu nadającego, ustalane na poziomie integracji — API.ERP słownika nie definiuje (value set otwarty, binding example).
paymentMethod 0..1 CodeableConcept Forma płatności. Słownik: posting-instruction-payment-method (cash, transfer, credit-card, other); inny kod → 400.
accountingVariant 0..1 Reference(AccountingVariant) Wariant dekretacji na nagłówku (identifier w przestrzeni AccountingVariant.Id).
grossAmount 0..1 Money Kwota brutto.
netAmount 0..1 Money Kwota netto.
vatAmount 0..1 Money Kwota VAT.
register 0..1 Reference(Register) Rejestr księgowy (identifier w przestrzeni Register.Id).
saleDate 0..1 date Data sprzedaży.
dueDate 0..1 date Termin płatności.
accountingDate 0..1 date Data księgowania.
paymentAccount 0..1 Reference(BankAccount) Rachunek płatności: identifier.value = numer rachunku, display = nazwa banku.
basedOn 0..* Reference Dokumenty powiązane (korekta, oryginał przy poprawie). Pole informacyjne — księgowość wiąże korektę przez atrybut correction-document-number (§3b).
position 0..* PostingInstructionLine Pozycje dokumentu.

2a. Identyfikatory

Rodzaj identyfikatora niesie Identifier.system. Przestrzenie wewnętrzne mają postać urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>; faktyczne przestrzenie publikuje NamingSystem — zob. Identyfikacja i parametry wdrożenia.

Przestrzeń (klucz) Znaczenie Identifier.system W POST W odczycie
PostingInstruction.ExternalId Identyfikator zewnętrzny — id dokumentu nadany przez system wystawiający (klucz add-or-update) …<instalacja>.91.2 opcjonalny tak
numer dokumentu Numer dokumentu https://api-erp.kamsoft.pl/vs/document-number opcjonalny tak
numer KSeF Numer KSeF https://ksef.podatki.gov.pl opcjonalny gdy nadany
PostingInstruction.Id Id bufora dokumentu nadany przez księgowość (klucz referencyjny) …<instalacja>.91 pomijany tak; klucz postingInstruction w JournalEntry

Brak identyfikatora zewnętrznego lub numeru dokumentu → 400 (§5a). Każdy identyfikator w zapisie niesie przestrzeń (identifier[].system) — bez niej żądanie kończy się 400, bo nie wiadomo, która instalacja ma zarejestrować dokument; wartość PostingInstruction.Id nadaje księgowość (rejestracja zasobu).

3. PostingInstructionLine (zagnieżdżony)

Nazwa Kard. Typ Opis
positionNo 0..1 integer Numer pozycji (>= 1).
code 0..1 CodeableConcept Typ pozycji: accounting-item (pozycja księgowa; domyślny, gdy brak) lub vat-summary (podsumowanie VAT). Słownik: posting-instruction-line-type.
value 0..* ValueItem Lista wartości pozycji. Każdy element niesie type (słownik: posting-instruction-line-value-item-type) oraz jeden wariant wartości. Elementy bez rozpoznanego kodu type są w zapisie pomijane.
allocation 0..* AllocationItem Lista alokacji pozycji.
purchaseVatDeduction 0..1 CodeableConcept Typ odliczenia VAT zakupu. Słownik: purchase-vat-deduction-type (full-deduction, no-deduction, structured-deduction, deduction-50-percent).
vatRate 0..1 CodeableConcept Stawka VAT (pozycja vat-summary). Słownik: finance/vat-rate (23, 22, 8, 7, 5, 0, ZW, NP, OO).
description 0..1 string Opis pozycji.
accountingVariant 0..1 Reference(AccountingVariant) Wariant dekretacji na pozycji.

Kody value[].type wg typu pozycji:

code pozycji Kod value[].type Wariant Znaczenie
accounting-item amount valueMoney Kwota pozycji
accounting-item vat-amount valueMoney Kwota VAT pozycji
accounting-item vat-amount-without-deductions valueMoney VAT niepodlegający odliczeniu
accounting-item amount-not-earning-expense valueMoney Kwota niestanowiąca kosztu uzyskania przychodu
accounting-item description valueString Opis (alternatywnie pole description)
vat-summary net-amount valueMoney Netto dla stawki
vat-summary vat-amount valueMoney VAT dla stawki

3a. AllocationItem

Nazwa Kard. Typ Opis
formulaComponent 0..1 Reference(FormulaComponent) Składnik formuły; identifier.value musi być liczbą całkowitą (id składnika) — inaczej 400.
costCarrier 0..1 Reference(CostCarrier) Nośnik kosztów (identifier w przestrzeni CostCarrier.Id).
weight 0..1 number Udział procentowy 0–100.
valueString 0..1 string Wariant migracyjny: kody lub @symbol bez referencji.

3b. Korekty i poprawa dokumentu

  • Poprawa wcześniej wysłanego dokumentu — ponowny POST /v1/posting-instructions z tym samym identyfikatorem zewnętrznym (PostingInstruction.ExternalId). Endpoint działa jako add-or-update — nadpisuje istniejący bufor; odpowiedź 200 OK.
  • Korekta (odrębny dokument korygujący) — nowy PostingInstruction z odpowiednim symbol (symbol dokumentu dostawcy oznaczający korektę, np. correction) oraz basedOn wskazującym fakturę/dokument korygowany (referencja przez identifier, np. numer dokumentu oryginału). Dzięki basedOn FKW jednoznacznie wiąże korektę z dokumentem źródłowym, bez polegania wyłącznie na symbolu.

4. Atrybuty

attribute[] (Attribute: code + value[]) w systemie posting-instruction-attribute-type; wartości jako valueString:

Kod Znaczenie
split-payment Mechanizm podzielonej płatności (MPP)
ksef-acquisition-date Data otrzymania w KSeF
pz-document-number Numer dokumentu przyjęcia (PZ)
correction-document-number Numer dokumentu korygowanego (dla korekt)
vat-date Data VAT

5. Systemy kodowania (value sety)

Value sety pól kodowanych PostingInstruction (przestrzeń https://api-erp.kamsoft.pl/vs/finance/...; rejestr: Systemy kodowania i value sety).

Pole Value set Kody
status posting-instruction-status ready-for-retrieval, retrieved, in-registration, deleted
sourceSystem source-system (value set otwarty — kody systemu nadającego, ustalane na integracji)
symbol posting-instruction-symbol (słownik dostawcy — value set otwarty, API.ERP nie definiuje)
paymentMethod posting-instruction-payment-method cash, transfer, credit-card, other
participant.function posting-instruction-participant-function seller, buyer, recipient, vat-group-member, subordinate-lgu
attribute[].code posting-instruction-attribute-type §4
position.code posting-instruction-line-type accounting-item, vat-summary
position.value[].type posting-instruction-line-value-item-type amount, net-amount, vat-amount, vat-amount-without-deductions, amount-not-earning-expense, description
position.purchaseVatDeduction purchase-vat-deduction-type full-deduction, no-deduction, structured-deduction, deduction-50-percent
position.vatRate finance/vat-rate 23, 22, 8, 7, 5, 0, ZW, NP, OO

Przykłady użycia z konkretnymi kodami: PostingInstruction — przykłady.

5a. Reguły walidacyjne

Reguły sprawdzane przez API przy POST. Naruszenie skutkuje odpowiedzią 400 Problem Details (§5b).

ID Reguła
pi-1 owner[] niesie identyfikator NIP (https://gov.pl/nip).
pi-2 sourceSystem (1..1) i symbol (1..1) są wymagane. Wartości pochodzą ze słowników ustalanych na integracji (systemu nadającego / dostawcy) — API nie waliduje ich względem słownika (value set otwarty; przenosi system/code bez interpretacji).
pi-3 issueDate jest podane.
pi-4 identifier jest opcjonalny (0..*); zalecane internal-id (klucz add-or-update) i document-number — slicing wg §2a. Bez twardego wymogu obecności.
pi-5 position[].allocation[].formulaComponent (gdy type = FormulaComponent) ma identifier.value będące liczbą całkowitą.
pi-6 Kody status i paymentMethod, jeśli podane, pochodzą z odpowiednich słowników (§5).

Pozostałe pola nie są walidowane przez API poza zgodnością ze schematem JSON.

5b. Operacje i parametry wyszukiwania

Instalację księgowości wyznacza profil zasobu, a gdy podano przestrzeń identyfikatora (identifier[].system) — ta przestrzeń (zakres żądania).

Metoda Ścieżka Opis Odpowiedź
POST /v1/posting-instructions Przekazanie dokumentu do bufora księgowości; add-or-update po identyfikatorze zewnętrznym (§3b) 200 OK z zapisanym zasobem (także dla nowego bufora); 400 przy naruszeniu §5a; 404, gdy księgowość nie zwróciła zapisanego dokumentu
GET /v1/posting-instructions Wyszukiwanie buforów dokumentów 200 OK: { "items": [...], "nextToken": null }

Parametry GET (paginacja count, domyślnie 20, i offset, domyślnie 0):

Parametr Wymagany Format Opis
identifier nie system\|value Id w przestrzeni PostingInstruction.ExternalId lub PostingInstruction.Id
symbol nie system\|value Symbol bufora: https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol\|<symbol>
owner nie system\|value Firma po NIP: https://gov.pl/nip\|<NIP>

Błędy: naruszenie reguły z §5a lub błędny format parametru zwraca RFC 9457 Problem Details (technical-conventions, §9) ze statusem 400. Przykład — żądanie POST bez kodowania symbolu bufora:

{
  "type": "http://hl7.org/fhir/issue-type#invalid",
  "title": "Invalid Content",
  "status": 400,
  "detail": "Missing required value: symbol (https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol|value in body).",
  "instance": "/v1/posting-instructions",
  "traceId": "00-6f1c…-04",
  "issues": [
    { "severity": "error", "code": "invalid", "details": { "text": "Missing required value: symbol (https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol|value in body)." } }
  ]
}

5c. Wsparcie wdrożeniowe

Zakres faktycznie wspieranych interakcji, aktywnych value setów oraz systemy identyfikatorów z §2a wynikają z zakresu uzgodnionego w umowie oraz z parametrów wdrożenia przekazanych przez KAMSOFT — zob. Identyfikacja i parametry wdrożenia. Niniejsza strona opisuje model kanoniczny, nie możliwości konkretnej instalacji.

6. Odniesienia