Przejdź do treści

PostingInstruction — przykłady (zasób bufora dokumentu)

Przykłady dla zasobu PostingInstruction. Konwencje wspólne dla wszystkich przykładów (placeholdery, referencje przez identifier, URL-e słowników): Konwencje przykładów.

Legenda placeholderów

Wartości urn:oid:2.999.<n> to placeholdery wdrożeniowe — łuk OID 2.999 jest zarezerwowany do celów przykładowych. Realne przestrzenie mają postać urn:oid:1.2.616.1.113769.4.<instalacja>.<klucz>; gotową przestrzeń przekazuje KAMSOFT w parametrach wdrożenia. W przykładach na tej stronie:

Placeholder Przestrzeń identyfikatorów (klucz)
urn:oid:2.999.1 Id dokumentu nadany przez system źródłowy (PostingInstruction.ExternalId)
urn:oid:2.999.2 Party — kontrahenci (Party.Id)
urn:oid:2.999.3 AccountingVariant — warianty dekretacji (AccountingVariant.Id)
urn:oid:2.999.4 Register — rejestry księgowe (Register.Id)
urn:oid:2.999.5 BankAccount — rachunki bankowe (BankAccount.Id)
urn:oid:2.999.6 FormulaComponent — składniki formuł (FormulaComponent.Id)
urn:oid:2.999.7 Id bufora nadany przez księgowość (PostingInstruction.Id)

URL systemów kodów: https://api-erp.kamsoft.pl/vs/finance/<slug> (np. posting-instruction-line-type) — pełny rejestr w Systemy kodowania i value sety. Kody symboli (posting-instruction-symbol, posting-instruction-document-symbol-type) nadaje wdrożenie — w przykładach zapisano je jako <symbol-bufora> i <rodzaj-dokumentu>. Rodzaj identyfikatora niesie Identifier.system.

Wymagania POST

  • identifier — id dokumentu w systemie źródłowym (przestrzeń PostingInstruction.ExternalId; pierwszy identyfikator o systemie innym niż KSeF i document-number),
  • identifier — numer dokumentu (system = https://api-erp.kamsoft.pl/vs/document-number),
  • owner — NIP (https://gov.pl/nip),
  • issueDate — data wystawienia dokumentu,
  • symbol — dwa kodowania: posting-instruction-symbol (symbol bufora) i posting-instruction-document-symbol-type (rodzaj dokumentu),
  • przestrzeń identyfikatora (identifier[].system) — wskazuje instalację księgowości, która dokument zarejestruje; pominięta, instalację rozstrzyga profil (rejestracja zasobu).

Wartość id bufora (PostingInstruction.Id) nadaje księgowość — integrator jej nie wymyśla.

Brak którejkolwiek z pozostałych wartości → 400 Problem Details (sekcja 5).

1. Utworzenie dokumentu (POST)

Przekazanie faktury zakupu do bufora księgowości.

Request:

POST /v1/posting-instructions HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
    "resourceType": "PostingInstruction",
    "identifier": [
        {
            "system": "urn:oid:2.999.1",
            "value": "EKS17"
        },
        {
            "system": "https://api-erp.kamsoft.pl/vs/document-number",
            "value": "123456789"
        },
        {
            "system": "https://ksef.podatki.gov.pl",
            "value": "9999999999-RRRRMMDD-FFFFFFFFFFFF-FF"
        }
    ],
    "owner": [
        {
            "type": "Party",
            "identifier": {
                "system": "https://gov.pl/nip",
                "value": "0123456789"
            }
        }
    ],
    "participant": [
        {
            "function": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-participant-function", "code": "seller" }]
            },
            "actor": {
                "type": "Party",
                "identifier": { "system": "urn:oid:2.999.2", "value": "7" }
            }
        }
    ],
    "attachment": [
        { "url": "https://dms.example.pl/documents/EKS17.pdf", "title": "123456789" }
    ],
    "issueDate": "2026-02-09",
    "realizationDate": "2026-02-09",
    "symbol": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol", "code": "<symbol-bufora>" }] },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-document-symbol-type", "code": "<rodzaj-dokumentu>" }] }
    ],
    "paymentMethod": {
        "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-payment-method", "code": "transfer" }]
    },
    "accountingVariant": {
        "type": "AccountingVariant",
        "identifier": { "system": "urn:oid:2.999.3", "value": "1" }
    },
    "grossAmount": { "value": 246.0, "currency": "PLN" },
    "netAmount": { "value": 200.0, "currency": "PLN" },
    "vatAmount": { "value": 46.0, "currency": "PLN" },
    "register": {
        "type": "Register",
        "identifier": { "system": "urn:oid:2.999.4", "value": "1" }
    },
    "saleDate": "2026-02-10",
    "dueDate": "2026-02-11",
    "accountingDate": "2026-02-09",
    "paymentAccount": {
        "type": "BankAccount",
        "identifier": { "system": "urn:oid:2.999.5", "value": "65432112345678876589989999" },
        "display": "Bank Przykładowy"
    },
    "attribute": [
        {
            "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-attribute-type", "code": "vat-date" }] },
            "value": [{ "valueString": "2026-02-09" }]
        }
    ],
    "position": [
        {
            "positionNo": 1,
            "code": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-type", "code": "accounting-item" }]
            },
            "value": [
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "amount" }] },
                    "valueMoney": { "value": 200.0, "currency": "PLN" }
                },
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "vat-amount" }] },
                    "valueMoney": { "value": 46.0, "currency": "PLN" }
                }
            ],
            "allocation": {
                "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-allocation-item-type", "code": "cost-type" }] },
                "formulaComponent": {
                    "type": "FormulaComponent",
                    "identifier": { "system": "urn:oid:2.999.6", "value": "4" }
                }
            },
            "purchaseVatDeduction": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/purchase-vat-deduction-type", "code": "full-deduction" }]
            },
            "description": "Usługa serwisowa — luty 2026",
            "accountingVariant": {
                "type": "AccountingVariant",
                "identifier": { "system": "urn:oid:2.999.3", "value": "1" }
            }
        },
        {
            "positionNo": 2,
            "code": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-type", "code": "vat-summary" }]
            },
            "value": [
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "net-amount" }] },
                    "valueMoney": { "value": 200.0, "currency": "PLN" }
                },
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "vat-amount" }] },
                    "valueMoney": { "value": 46.0, "currency": "PLN" }
                }
            ],
            "vatRate": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/vat-rate", "code": "23" }]
            }
        }
    ],
    "comment": "Faktura zakupu — serwis"
}

Response (200 OK):

{
    "resourceType": "PostingInstruction",
    "identifier": [
        {
            "system": "urn:oid:2.999.1",
            "value": "EKS17"
        },
        {
            "system": "urn:oid:2.999.7",
            "value": "40817"
        },
        {
            "system": "https://ksef.podatki.gov.pl",
            "value": "9999999999-RRRRMMDD-FFFFFFFFFFFF-FF"
        },
        {
            "system": "https://api-erp.kamsoft.pl/vs/document-number",
            "value": "123456789"
        }
    ],
    "status": {
        "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-status", "code": "ready-for-retrieval" }]
    },
    "meta": {
        "added": "2026-02-09T10:15:00"
    }
}

Odpowiedź zawiera zapisany zasób: identyfikatory uzupełnione o id bufora nadane przez księgowość (przestrzeń PostingInstruction.Id), status przetwarzania (słownik posting-instruction-status) i meta.added; pozostałe pola — jak w żądaniu (skrócono).

2. Poprawa dokumentu (add-or-update)

Zgodnie z §3b strony zasobu: poprawa wcześniej wysłanego dokumentu to ponowny POST /v1/posting-instructions z tym samym identyfikatorem eod-id. Endpoint działa jako add-or-update — nadpisuje istniejący bufor w całości.

Przykład: w dokumencie z sekcji 1 poprawiono termin płatności (dueDate) i formę płatności. Żądanie zawiera pełną, poprawioną treść dokumentu (poniżej skrócono ją do pól wymaganych i zmienionych):

Request:

POST /v1/posting-instructions HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
    "resourceType": "PostingInstruction",
    "identifier": [
        {
            "system": "urn:oid:2.999.1",
            "value": "EKS17"
        },
        {
            "system": "https://api-erp.kamsoft.pl/vs/document-number",
            "value": "123456789"
        }
    ],
    "owner": [
        { "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "0123456789" } }
    ],
    "issueDate": "2026-02-09",
    "symbol": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol", "code": "<symbol-bufora>" }] },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-document-symbol-type", "code": "<rodzaj-dokumentu>" }] }
    ],
    "paymentMethod": {
        "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-payment-method", "code": "cash" }]
    },
    "dueDate": "2026-02-20"
}

Response (200 OK): zapisany zasób jak w sekcji 1 — ten sam identyfikator zewnętrzny i id bufora (urn:oid:2.999.7 / 40817), meta.lastModified z datą zmiany.

Serwer rozpoznał istniejący bufor po identyfikatorze zewnętrznym (urn:oid:2.999.1 / EKS17) i nadpisał go. Kod odpowiedzi jest zawsze 200 OK — także przy utworzeniu nowego bufora.

3. Korekta

Zgodnie z §3b strony zasobu: korekta to nowy PostingInstruction (odrębny dokument korygujący) z:

  • własnym identyfikatorem zewnętrznym,
  • symbolem rodzaju dokumentu oznaczającym korektę (kodowanie w posting-instruction-document-symbol-type — kod nadaje wdrożenie),
  • atrybutem correction-document-number z numerem dokumentu korygowanego.

Request:

POST /v1/posting-instructions HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
    "resourceType": "PostingInstruction",
    "identifier": [
        {
            "system": "urn:oid:2.999.1",
            "value": "EKS18"
        },
        {
            "system": "https://api-erp.kamsoft.pl/vs/document-number",
            "value": "123456789/K1"
        }
    ],
    "owner": [
        { "type": "Party", "identifier": { "system": "https://gov.pl/nip", "value": "0123456789" } }
    ],
    "issueDate": "2026-03-02",
    "symbol": [
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol", "code": "<symbol-bufora>" }] },
        { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-document-symbol-type", "code": "<rodzaj-dokumentu-korekta>" }] }
    ],
    "attribute": [
        {
            "code": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-attribute-type", "code": "correction-document-number" }] },
            "value": [{ "valueString": "123456789" }]
        }
    ],
    "grossAmount": { "value": -123.0, "currency": "PLN" },
    "netAmount": { "value": -100.0, "currency": "PLN" },
    "vatAmount": { "value": -23.0, "currency": "PLN" },
    "position": [
        {
            "positionNo": 1,
            "code": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-type", "code": "accounting-item" }]
            },
            "value": [
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "amount" }] },
                    "valueMoney": { "value": -100.0, "currency": "PLN" }
                },
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "vat-amount" }] },
                    "valueMoney": { "value": -23.0, "currency": "PLN" }
                }
            ],
            "allocation": {
                "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-allocation-item-type", "code": "cost-type" }] },
                "formulaComponent": {
                    "type": "FormulaComponent",
                    "identifier": { "system": "urn:oid:2.999.6", "value": "4" }
                }
            },
            "description": "Korekta pozycji 1 — zwrot towaru"
        },
        {
            "positionNo": 2,
            "code": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-type", "code": "vat-summary" }]
            },
            "value": [
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "net-amount" }] },
                    "valueMoney": { "value": -100.0, "currency": "PLN" }
                },
                {
                    "type": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-line-value-item-type", "code": "vat-amount" }] },
                    "valueMoney": { "value": -23.0, "currency": "PLN" }
                }
            ],
            "vatRate": {
                "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/vat-rate", "code": "23" }]
            }
        }
    ],
    "comment": "Korekta do faktury 123456789"
}

Response (200 OK): nowy bufor z własnym id (urn:oid:2.999.7 / 40818) i statusem ready-for-retrieval.

Korekta jest nowym buforem (własny identyfikator zewnętrzny = EKS18); powiązanie z dokumentem korygowanym niesie atrybut correction-document-number. Pole basedOn może dodatkowo wskazywać oryginał (referencja logiczna przez identifier), ale nie jest interpretowane w zapisie.

4. Odczyt bufora (GET)

Request:

GET /v1/posting-instructions?identifier=urn:oid:2.999.1|EKS17&owner=https://gov.pl/nip|0123456789 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json

Response (200 OK):

{
    "items": [
        {
            "resourceType": "PostingInstruction",
            "identifier": [
                { "system": "urn:oid:2.999.1", "value": "EKS17" },
                { "system": "urn:oid:2.999.7", "value": "40817" },
                { "system": "https://api-erp.kamsoft.pl/vs/document-number", "value": "123456789" }
            ],
            "status": { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-status", "code": "retrieved" }] },
            "issueDate": "2026-02-09",
            "symbol": [
                { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-document-symbol-type", "code": "<rodzaj-dokumentu>" }] },
                { "coding": [{ "system": "https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol", "code": "<symbol-bufora>" }] }
            ]
        }
    ],
    "nextToken": null
}

Pozostałe pola zasobu skrócono. Zamiast identifier można filtrować po symbol=https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol|<symbol-bufora>; paginacja count / offset.

5. Błąd walidacji (400)

Żądanie POST bez kodowania symbolu bufora:

{
    "type": "https://httpstatuses.com/400",
    "title": "Invalid request",
    "status": 400,
    "detail": "Missing required value: symbol (https://api-erp.kamsoft.pl/vs/finance/posting-instruction-symbol|value in body)."
}

Analogiczne odpowiedzi zwracają: brak NIP w owner, brak issueDate, brak numeru dokumentu lub id dokumentu w identifier, nieliczbowy identifier.value w allocation.formulaComponent, nieznany kod status lub paymentMethod.