Finkok Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for the PAC transport layer. This package settles the "how do we talk to a PAC" decision for Finkok: SOAP envelopes, WSDL-derived document/literal messages, response parsing, DTOs, error catalogs. It does not decide the PAC itself — Finkok remains a separate commercial dependency. A PM should treat this as buying the plumbing while still sourcing the stamping service.
• Mexican market entry / roadmap sequencing. If CFDI stamping and cancellation are on the roadmap, this removes the lowest-differentiation, highest-annoyance workstream and lets the team spend the quarter on product surface instead of SOAP.
• Multi-tenant and multi-issuer architecture. CredentialsProviderInterface keeps RFCs, environments (DEMO/PROD) and CSD material in the application — env vars, secret manager, database, active tenant. This directly supports white-label invoicing, per-tenant credentials, and a single deployment serving many issuers. That is a product-architecture decision, not just a config detail.
• Infrastructure and packaging decisions. No ext-soap means the extension can be dropped from base images and build pipelines. Smaller attack surface, simpler container builds, and viability on hosts where the extension is unavailable. dom + libxml (+ openssl only when cancelling with your own CSD) is a low bar.
• Reliability and support-cost decisions. Typed error catalogs (24 stamping incidences, 28 cancellation codes, 1000–1006 for accept_reject) plus typed DTOs mean support tooling and on-call runbooks can branch on known codes instead of string-matching SOAP faults. Retries are deliberately scoped to transport errors and transient codes (205, 302, 708, 798) and are safe because Finkok deduplicates by UUID — that is a defensible default rather than an ad-hoc retry loop.
• Compliance and auditability. Business errors do not throw — isSuccess(), getIncidences(), hasErrorCode(), assertSuccess() let a PM decide per surface whether a stamping incident is a user-visible failure or a background retry. previewStampRequest() allows envelope inspection without opening a connection, which supports audit trails and pre-production sign-off.
• Testing strategy decisions. 219 offline tests / 880 assertions on MockHttpClient, plus 4 contract tests against Finkok, means CI does not need network access or live credentials. This is a real cost saver and a prerequisite for anything resembling TDD in a fiscal integration.
• Concrete use cases: facturación SaaS, ERP and e-commerce add-ons, marketplace seller billing, expense/receipt platforms, fiscal middleware, and multi-issuer portals — anywhere CFDI stamping or cancellation is one capability inside a larger product.

When to Consider This Package

Adopt when:

• You are on PHP 8.2+ with Symfony components ^7.4 — or you are willing to wire the bundle manually (see the Laravel caveat below).
• You need CFDI stamping and/or cancellation in production, at volume, and Finkok is your PAC of choice (new or existing contract).
• You operate or plan to operate multiple RFCs, environments, or tenants, and want credentials owned by the application rather than a YAML file.
• Your infrastructure does not ship ext-soap, or you have a policy against it.
• You want testability and byte-level auditability of the SOAP traffic, and a team comfortable with immutable DTOs rather than array/stdClass wrangling.
• You need to pre-validate invoices locally (empty, malformed, unsealed, non-CFDI, over 1 MB) rather than burning stamping attempts on defects detectable offline.

Look elsewhere or plan extra work when:

• You need PAC-agnosticism or failover. This is a Finkok client, not an abstraction over PACs. SW Sapien, Facturama, or direct SAT integrations are out of scope; multi-PAC strategy means an adapter layer you own.
• You expect a Laravel-native experience. The package is Symfony-native: config/bundles.php registration, Symfony DI autowiring, Symfony HttpClient. In Laravel you would write a service provider and adapter yourself. That is feasible — Laravel already consumes Symfony components — but it is real work and should be priced in. If Laravel DX is the requirement, a Laravel-specific wrapper is cheaper.
• You need a billing engine, not a transport. It validates and transports XML; it does not generate CFDI, manage catalogs (SAT product/service keys, tax regimes), produce PDFs, or handle retention. Budget for those separately.
• Your documents routinely exceed 1 MB. That is a hard Finkok limit and can affect subsequent stamping; the package will refuse them, and you need an authoring-side fix.
• You need cancellation beyond the fifth attempt. At attempt six Finkok returns 799 and the SAT portal is the only remaining route. No package can change that.
• Documentation language is a blocker. README and docs/errores.md are in Spanish. Your team must be able to work with Spanish-language compliance material.
• You are pre-upgrade. Symfony 7.4 components and PHP 8.2 are hard floors.

Maturity note for the decision record: v1.0.0 is the first stable release. The dev-main era carried two breaking changes (namespace Finkok\CfdiBundle → Estratos\FinkokBundle; credentials removed from bundle YAML in favor of CredentialsProviderInterface). No published consumers were affected, but this signals the public API is young. Contract coverage is 4 live tests — meaningful but thin — so pin the version and re-run the live group on upgrade.

How to Pitch It (Stakeholders)

For executives. This is a compliance-critical integration for Mexican electronic invoicing, released as a stable 1.0. It removes the need to build and maintain a custom SOAP client, is verified against Finkok's real DEMO and PRODUCTION servers across all 11 operations, and adds no new runtime dependency (notably no ext-soap). It is multi-tenant ready — one deployment can serve many issuers with credentials held in our secret manager rather than in config. Risks to acknowledge: single PAC dependency (Finkok), Spanish-only documentation, and a young public API. Recommendation: adopt behind a version pin, with the live contract test group in the release checklist.

For engineering. The differentiating design is the transport: envelopes are generated from the real WSDL and responses are parsed by local name, so server-side namespace prefixes cannot break deserialization. That buys testability — 219 offline tests on MockHttpClient, no network in CI — and auditability, including previewStampRequest() to inspect the envelope without connecting. Responses are immutable DTOs with typed error catalogs and no exceptions on business errors, so callers choose their own policy. Reuses the app's http_client and logger when present and exposes everything through interfaces for autowiring. Non-negotiable integration rules to design around: a 201 is not a cancellation — confirm with get_sat_status() and use isCancelled() / isInProcess() rather than treating request acceptance as success; 1 MB per XML hard limit; 72-hour stamping window; five cancellation attempts per UUID before 799; CSD is optional for cancellation; DEMO has its own timings. In a Laravel codebase, plan an adapter and service provider — the bundle's Symfony registration convention does not apply there.