Finvalda Sdk Laravel Package

Getting Started

• Install with Composer (arturas88/finvalda-sdk) and configure Finvalda credentials per package docs. As of v3.4.0 the SDK is PHPStan level 5 clean with 297 tests, so the test suite is a reliable first reference.
• Look first at the builders: PurchaseBuilder, PurchaseOrderBuilder, ProductLine, Stock, and the new purchaseUpdate() path. The v3.4.0 tests around additional costs, corrections, and stock lookup are the fastest way to learn intended usage.
• Start with the most common day-to-day flow: create a purchase with header-level cost buckets and per-line allocations.

$finvalda->purchase()
    ->client('SUP001')
    ->additionalCostCodes(['KITOS', 'TRANSP', 'ILGALSAV', 'DRAUDIM'])
    ->product(
        ProductLine::make('WSM000001TB061527', 1)
            ->warehouse('WH01')
            ->amount(38_500.00)
            ->additionalCost(2, 950.00) // TRANSP -> dPapIsldSumaV2/L2
    )
    ->save('PIRKNAU');

• Before any correction, use Stock::purchaseOpFor($productCode) as a pre-flight check. It answers whether the product is still held by a purchase operation and whether it has been sold since.

Implementation Patterns

• Model additional costs as a paired header/line workflow. Set header buckets with additionalCostCodes() and line amounts with ProductLine::additionalCost() or additionalCosts(). The slot number is the binding key between the two.
• Prefer slot-keyed maps when only some buckets are used: additionalCostCodes([2 => 'TRANSP']). Use ordered lists only when the slot order is obvious and stable.
• Use ProductLine::additionalCosts([1 => 10.00, 2 => 950.00]) for multi-bucket lines. The helper writes both dPapIsldSumaV{slot} and dPapIsldSumaL{slot} as a pair, avoiding the half-pair mistake that set() made easy.
• For purchase corrections, treat purchaseUpdate() as a delete-and-re-add operation, not an edit. Build the KoregPirkDok envelope through the SDK rather than hand-assembling it.
• Guard corrections explicitly:

$op = $finvalda->stock()->purchaseOpFor('WSM000001TB061527');

if ($op === null || ($op['sold'] ?? false)) {
    // do not correct; inspect history or choose another action
}

$finvalda->purchaseUpdate()
    ->assertNotSold(['WSM000001TB061527'])
    ->header(/* ... */)
    ->product(/* replacement detail lines */)
    ->save(/* ... */);

• Do not rely on save() to call assertNotSold(). The SDK deliberately leaves that decision to the caller because it costs one round trip per product code and is a business decision, not a serialization concern.
• For the other six UpdateOperationClass cases, use operations()->update() with a hand-built payload. v3.4.0 only adds a first-class purchase correction builder.
• Handle error 4027 explicitly. An update call can return a deletion-class code because the correction path deletes detail lines internally.
• Avoid automatic retries around corrections. A correction is not idempotent, and retrying after a partial failure can delete or re-add lines unexpectedly. Log the operation identifiers and require a fresh pre-flight lookup before retrying.
• Use Stock::purchaseOpFor() as a read-only pre-flight, not as a transactional lock. It returns a plain array and never throws, so callers must branch on null and on the reported sold state.
• Write integration tests for the exact spec constraints: max four cost codes, slot range 1–4, code length up to 10, and short-document rejection at build() time.

Gotchas and Tips

• Additional-cost validation is intentionally strict: max 4 buckets, slots 1–4, code length up to 10. Violations fail early.
• additionalCostCodes() is rejected on ->short() at build() time because TrumpasPirkDok/TrumpasPirkUzsDok have no such fields. It is also absent from purchaseReturn() per the spec.
• ProductLine::additionalCost() and additionalCosts() write both the currency and local amount fields. Do not use raw set() calls for these fields; a half-populated pair books the line incorrectly.
• The slot number on a line amount must match the header bucket slot. A mismatch is a data-model error, not something the SDK can infer for you.
• Additional costs are not added to ServiceLine. The spec marks all eight fields as Tik PirkDokPrekeDetEil, so service lines cannot carry them.
• A purchase correction is destructive. It deletes the named detail lines and re-adds the lines you supply, rebuilding the product’s FIFO stock layer. It fails late: unsold stock may correct fine, then the same code path starts failing once the goods are sold or consumed by another operation.
• Error 4027 (Operacijos detalios eilutės yra panaudotos kitose operacijose!) comes from the internal delete, not from the 5000–5005 correction family. Do not assume an update call can only return correction-class errors.
• UpdPrekeDetEil is not an escape hatch for restating amounts. It carries only nPozymis and sPapInfo.
• purchaseUpdate()->header() refuses fields the PirkDokHeadEil node does not accept for a purchase: sKlientas (supplier cannot change), operation-date fields, sObjektas5/6, and waybill fields.
• assertNotSold() fails closed on unresolvable history. That is safer than correcting blindly, but it means a lookup failure blocks the correction until you investigate.
• Stock::purchaseOpFor() returns null for no purchase history or a failed call, and never throws. It is a pre-flight check, not a source of truth for accounting decisions.
• The lookup picks the latest purchase when a product has been re-acquired. A sale counts as sold only when dated at or after that purchase.
• The op_rusis_pav values Pirkimai and Pardavimai are observed against a live Finvalda, not documented in the API spec. Unknown kinds are ignored rather than guessed, so do not assume every history row will be classified.
• Only purchases are covered by the new correction builder. Other update operation classes share the envelope shape but have their own Tik ... annotations; use the generic operations()->update() path with a hand-built payload.
• For debugging, inspect the generated payload in tests and compare it against the node-specific spec. The v3.4.0 constraints are mostly enforced at build() time, so validation errors usually point to the exact field or arity problem.