Finvalda Sdk Laravel Package

Product Decisions This Supports

• Landed-cost and additional purchase costs: additionalCostCodes() and per-line additionalCost() let product teams support procurement cost allocation directly on purchase documents instead of hand-rolling raw Finvalda fields. This enables supplier invoice cost capture, freight/duty allocation, margin analysis, and inventory valuation workflows.
• Purchase correction workflows: purchaseUpdate() gives a spec-aligned correction path for purchase documents, but the product decision must treat corrections as destructive rebuilds, not ordinary edits. Any “edit purchase” UI should communicate that detail lines are deleted and re-added, affecting FIFO stock layers.
• Inventory integrity guardrails: Stock::purchaseOpFor() and assertNotSold() support pre-flight checks before corrections. PMs can design safer admin flows that warn or block when goods have been sold, rather than discovering failure late via error 4027.
• Build vs. buy: the SDK now covers features previously requiring raw Lithuanian field names and hand-assembled envelopes. This reduces custom mapping and maintenance for purchase cost allocation and purchase corrections.
• Roadmap scoping: v3.4.0 supports purchase-order/purchase-document cost allocation and purchase corrections only. It does not cover service-line additional costs, purchase-return cost buckets, or the other six UpdateOperationClass correction cases. Those remain custom work or future roadmap items.
• Quality signal: 65 new tests, 297 total, and PHPStan level 5 clean indicate the package is investing in correctness for these workflows, which lowers integration risk but does not remove the need for product-level safety design around destructive corrections.

When to Consider This Package

• Consider it when building a Laravel/PHP application that integrates with Finvalda and needs purchase-order or purchase-document workflows, especially additional cost allocation, per-line cost distribution, purchase corrections, or stock-history prechecks.
• Consider it when the team wants typed builders and validation over raw field names, and values test coverage and static analysis for accounting/ERP integrations.
• Consider it when purchase corrections can be gated by a pre-flight check and the business accepts that corrections are destructive, non-idempotent, and may fail once stock has been sold.
• Look elsewhere or plan custom work if you need additional-cost allocation on service lines, purchase returns, or non-purchase update operations. The release explicitly limits scope to PirkDok/PirkUzsDok purchase paths.
• Look elsewhere or avoid the correction path if the product requires idempotent edits, non-destructive corrections, amount restatement through UpdPrekeDetEil, or guaranteed success without a sold-stock check.
• Treat as a risk area the fact that 4027 is a deletion-class error returned from an update call, and that op_rusis_pav values used by Stock::purchaseOpFor() are observed against a live system rather than specified in the API document.

How to Pitch It (Stakeholders)

Executive summary: v3.4.0 expands the Finvalda SDK into purchase cost allocation and purchase correction workflows, reducing the need for brittle custom field mapping in procurement and inventory features. It enables landed-cost capture, per-line cost allocation, and safer correction prechecks. The main caveat is that purchase corrections are destructive and can fail late if stock has already been sold, so adoption should include explicit UX and workflow guardrails.

Engineering summary: the release adds validated additional-cost buckets, paired per-line allocation, a dedicated KoregPirkDok correction envelope, and a stock-operation lookup. It also adds 65 tests and keeps PHPStan level 5 clean. Teams should use assertNotSold() deliberately before corrections, treat 4027 as a possible update-time failure, and avoid assuming coverage for service lines or non-purchase correction operations.

Recommendation: adopt for purchase cost allocation and purchase correction use cases where the business can accept destructive correction semantics and a pre-flight sold-stock check. Defer service-line allocation and non-purchase correction workflows until the SDK exposes them or fund custom integration work.