Correios Api Laravel Package

Technical Evaluation

Architecture fit

• The package follows a layered pattern already visible in prior capabilities: a domain model (Pessoa) carrying serialized attributes, an error taxonomy rooted at ErroApi, and orchestration types (PrePostagemCriada, ProcessamentoAssincrono). v0.5.0 extends each layer consistently rather than inventing a parallel path — ErroContribuinteIcms subclasses ErroApi, contribuinte_icms joins the existing Pessoa array/remetente_padrao shape, and detection helpers are exposed on the two result objects that already surface failure state.
• Two enforcement points are provided deliberately: a pre-flight ErroValidacao on emiteDCe (fail fast, no API call) and a post-hoc detection path for Rejeição 812 arriving through synchronous responses or asynchronous processing. This dual placement matches how the Correios/SEFAZ interaction actually fails and is the right shape for a TPM to plan around.
• Weakest architectural element: ErroContribuinteIcms::reconhece() matches on message text and causa text rather than a stable rejection code. That is a string-contract dependency on an external system whose exact output the maintainer explicitly states has not been observed. Treat this as a knowingly provisional detection layer, not a durable invariant.

Integration feasibility

• Low-friction by default. The new behavior is opt-in: unless a sender is explicitly marked contribuinteIcms: true, existing DC-e flows are unchanged. No forced migration of current callers, no signature breaks indicated.
• Real effort sits outside the package: the application must be able to answer "is this remetente an active ICMS taxpayer (inscrição estadual ativa)?" from its own cadastro/ERP data, and must be able to emit with chaveNFe instead of emiteDCe for those senders. The package now blocks the wrong path but does not implement the correct one — that work is ours.
• Persistence is the concrete integration task: contribuinte_icms is a new attribute on Pessoa, so any locally stored sender records, fixtures, seeders, or API resources with strict validation/serialization need review.

Technical risk

• Detection risk (high): rejection 812 is recognized by message text. If SEFAZ/Correios wording differs from the implemented matcher, the block silently fails and errors surface as generic ErroApi — users retry, postagens are wasted, and the failure looks like an outage rather than a fiscal rule.
• Data-quality risk (high): the control is only as good as the contribuinteIcms flag. Mis-flagging in either direction is costly: false on a taxpayer means hard rejection at volume after the deadline; true on a non-taxpayer means a self-inflicted block on legitimate DC-e emission.
• Deadline risk (medium-high): SEFAZ begins enforcing on 02/11/2026. This is a fixed external date with no ability to negotiate an extension, and it lands late in the year alongside other fiscal calendar pressure.
• Contract risk (medium): package is pre-1.0. Semver minors can carry behavioral nuance; the validation-refusal path is a behavior change for anyone who adopts the flag.
• Coverage risk (medium): the async detection path (ProcessamentoAssincrono::recusadaPorContribuinteIcms()) means failures can appear long after submission, in batch/webhook processing, where they are easiest to miss.

Key questions

1. What is our authoritative source for "inscrição estadual ativa," and how fresh is it? Which system owns it?
2. Does our current integration already support chaveNFe end-to-end, including NF-e key validation and capture from the fiscal pipeline?
3. Are there in-flight or queued pré-postagens that will straddle the 02/11/2026 cutover, and how do we drain or reclassify them?
4. How is Pessoa persisted in our app — is a schema/column change required, and what is the backfill plan?
5. Who owns monitoring of Rejeição 812 occurrences post-cutover, and what is the escalation path if the text matcher misses?
6. What is the rollback story if contribuinteIcms blocks legitimate volume in production?

Integration Approach

Stack fit

• Standard Laravel consumption: composer upgrade, service provider/config publish as usual, no new infrastructure. Pessoa remains a value/DTO-style object, so the integration is data plumbing rather than new architecture.
• Exception handling must be explicit. Register a dedicated catch for ErroContribuinteIcms in job middleware or the queue failure handler and render it as a non-retryable, user-actionable error; a generic ErroApi catch will otherwise burn retry budget on a permanently invalid request.
• For synchronous UI flows, map ErroValidacao on field emiteDCe to the sender-configuration screen so the fix is discoverable at the point of failure rather than buried in a log.

Migration path

• Phase 1 — upgrade in staging only; verify no regression for un-flagged senders and confirm the array shape change is tolerated by our serializers/validators.
• Phase 2 — data backfill: derive contribuinte_icms from the cadastro's IE status, store it alongside sender records, and reconcile a sample manually with the fiscal team before trusting the flag.
• Phase 3 — enable the flag first in a shadow/observe posture (log what would have been blocked) to quantify blast radius before enforcing.
• Phase 4 — enforce in production, with the NF-e/chaveNFe path already available so blocked senders have an immediate correct alternative.

Compatibility

• No breaking changes indicated for existing consumers; the flag is additive and default-off. Confirm PHP and Laravel version constraints from composer.json before scheduling.
• Audit anything that consumes the Pessoa array by fixed key list or strict schema — the added contribuinte_icms key and its appearance in remetente_padrao can trip strict validators, snapshot tests, or API resource whitelists.
• Pin the exact version (0.5.x) rather than floating, given pre-1.0 and an unverified detection contract.

Sequencing

1. Composer upgrade + staging regression pass.
2. Cadastro audit and contribuinteIcms backfill (data work is the long pole — start first).
3. NF-e chaveNFe emission path for taxpayer senders.
4. Exception handling, user-facing messaging, and 812 alerting.
5. Observe-only rollout → enforce, targeting production enforcement well before 02/11/2026 with a buffer for unknowns in the unverified rejection format.

Operational Impact

Maintenance

• Expect continued churn at 0.x. Budget a recurring dependency-review slot rather than a one-off upgrade.
• Create a follow-up ticket to replace text-based 812 detection with a code/structured-field check once real payloads are captured; log raw rejection bodies from day one so this is possible. Without that instrumentation the matcher stays permanently unverifiable.
• Track the upstream communicado/changelog for the eventual "exact format observed" note and re-test at that point.

Support

• New first-line scenario: "my DC-e was blocked." Support needs a runbook distinguishing (a) our pre-flight block on emiteDCe, (b) SEFAZ Rejeição 812 detected synchronously, (c) 812 discovered asynchronously on an already-submitted pré-postagem, and (d) an unrecognized rejection that should have been 812.
• Documentation in this release is Portuguese-only and assumes Brazilian fiscal literacy (DC-e vs NF-e, ICMS taxpayer status). Non-Brazilian or generalist on-call staff will not self-serve; produce an internal English/plain-language summary and name a fiscal SME as escalation.
• Prepare canned customer-facing guidance: "sender with active IE must ship goods with the NF-e key, not DC-e."

Scaling

• Runtime cost is negligible — a boolean check before the API call actually reduces load by eliminating doomed requests.
• The scaling concern is volume of rejections, not throughput: if the flag is under-populated, the deadline produces a step-change in failed calls and support tickets at once. Pre-deadline enforcement converts that spike into a controlled trickle.
• Async workers need a terminal-failure classification for 812 so failed pré-postagens do not accumulate in retry loops or dead-letter queues without ownership.

Failure modes

• Silent miss: matcher fails on real wording → generic API error → retries → wasted postagens and eroded trust in the block.
• False positive block: non-taxpayer flagged true → legitimate DC-e emission refused locally with no external error to explain it. Highest-severity self-inflicted mode.
• False negative at scale: taxpayer un-flagged → bulk 812s immediately after 02/11/2026, discovered via customer complaints.
• Cutover straddle: pré-postagens created before enforcement and processed after it, producing mixed states and partial cancellations.
• Async invisibility: 812 only appearing in motivoCancelamento or async failure messages, never surfaced to an operator.

Ramp-up

• Engineering: roughly a day to upgrade and wire exception handling; several days for cadastro backfill and reconciliation with fiscal.
• Fiscal/product: meaningful time to validate the IE-status rule against real customer records and to confirm the NF-e key flow covers all affected senders.
• Recommend a short written decision record capturing why the flag is set the way it is per sender segment, so the logic survives staff turnover before the enforcement date.