Laravel Fina Sdk Laravel Package

Product Decisions This Supports

• Inventory visibility across stores: getProductsRest() returns { rest: [{ id, store, rest, reserve }] } — the current rest (available stock) and reserve per product, per store. This directly unblocks storefront "available in store", pick-up-in-store eligibility, low-stock badges, and store-level allocation rules without a bespoke data pipeline.
• Fulfilment and order routing: With per-store rest and reserve in one call, we can decide which store ships an order, when to split a shipment, and when to fall back to backorder — a product decision that previously required either manual checks or a one-off raw integration.
• Sales reconciliation and after-sales: getProductOutSingle($id) returns the full retail sale document (product_out_single with products[]), enabling order-detail screens, returns/exchange flows, invoice re-download, and finance reconciliation against our own order records.
• Build vs buy: These two endpoints were only reachable via raw HTTP calls. Every call we hand-roll is code we own, test, and maintain against a changing ERP contract. Adopting the package version converts that into a dependency with 84 tests behind it.
• Roadmap sequencing: The pairing is a signal — stock data plus sale documents is the minimum viable slice for a "store availability + order lookup" feature. This release makes that slice shippable now rather than next quarter.
• Reliability as a product property: Both endpoints now go through the regular response guard, so a FINA ex raises FinaRemoteException instead of being silently returned as data. Fewer silent-wrong-numbers incidents in stock displays is a user-facing quality decision, not just a technical one.

When to Consider This Package

Consider adoption when:

• FINA is already the system of record for products, stock, or retail sales in the business — this package speaks FINA Web API v8.0 and gives you typed-ish, guarded access rather than raw JSON.
• You are on v8.0 of the API. The endpoints here are version-specific (getProductsRest, getDocProductOutSingle); confirm your FINA instance is on 8.0 before committing.
• You need read access for display or decisioning — stock per store or a sale document by id. Both new endpoints are GETs; they fit read-model, dashboard, and order-lookup use cases cleanly.
• You want consistent failure semantics. The response guard plus FinaRemoteException and the 401 token-refresh path mean our code handles one exception type and one auth story instead of per-call special cases.
• You would otherwise write raw HTTP glue. If a team member is about to Http::withToken(...)->get('getProductsRest'), take the package instead.

Look elsewhere or hold when:

• You need write operations (adjusting stock, creating documents). This release adds reads only; confirm coverage for mutations before designing a workflow around it.
• You need near-real-time stock. There is no webhook or push here — this is pull-based. High-velocity inventory needs a polling strategy, cache TTL, and staleness UX, which is product work this package does not do for you.
• You are not on FINA, or are on a materially different API version. The wrapper's value is entirely in matching the provider contract.
• You need guaranteed semantic versioning for a long-lived platform integration. At v0.1.x this is pre-1.0; treat the surface as movable and pin versions deliberately.
• Your scale makes per-store fan-out expensive. getProductsRest returns all products for all stores in one payload — fine for catalogues in the thousands, worth measuring before you build a live per-page inventory check on it.

How to Pitch It (Stakeholders)

For executives (one paragraph): The FINA integration package shipped a release that adds the two API endpoints we previously could only reach with hand-written calls: per-store stock levels for every product, and full retail sale documents by id. That means two roadmap items — showing customers what is actually available in their store, and letting support look up a real sale — move from "needs custom integration work" to "build on an existing, tested dependency." Both endpoints now fail loudly with a proper exception instead of quietly returning bad data, so inventory numbers on screen are more trustworthy. Cost is a version bump; the alternative is bespoke integration code we would own indefinitely.

For engineering (summary): v0.1.3 adds rest() (GET getProductsRest, returns { rest: [{ id, store, rest, reserve }] }) and getProductOutSingle($id) (GET getDocProductOutSingle/{id}, returns product_out_single with products[]). Both are routed through the standard response guard, so a FINA ex surfaces as FinaRemoteException rather than as payload. Coverage includes URL/method, bearer token, payload passthrough, ex handling, HTTP 400/500, and the 401 token-refresh path — 9 new tests, 84 total. No breaking changes noted; still pre-1.0, so pin the version and expect surface movement. Recommended next step: wrap rest() behind a cached repository with an explicit TTL, and validate the shape of products[] against our order model before we commit to a reconciliation design.