Correios Api Laravel Package

Product Decisions This Supports

• Regulatory deadline planning (hard date: 02/11/2026). SEFAZ begins rejecting DC-e (Rejeição 812) for senders who are ICMS taxpayers. This release gives you a concrete, dated roadmap item and the technical primitives to ship before the cutoff rather than after customers start failing at label time.
• Build vs. buy / vendor dependency evaluation. The package now encodes a domain rule you would otherwise hand-roll: a sender who is an active ICMS taxpayer must ship goods with the NF-e key (chaveNFe), not with emiteDCe. Adopting v0.5.0 is cheaper than building and maintaining that branch plus rejection parsing yourself.
• Data model decision: capture taxpayer status on the sender record. Pessoa::$contribuinteIcms (also honored in remetente_padrao) is a product-visible field. PM decision needed: how is it populated — self-declared at onboarding, derived from state registration data, or inferred from the presence of an active IE? Whatever you choose, it becomes part of your customer/address schema and your onboarding funnel.
• Fail-fast UX vs. fail-at-the-counter. Because creation of a pre-postagem with emiteDCe is now refused locally with ErroValidacao (field emiteDCe) before the API call, you can decide where the guardrail lives: block at shipment creation with a corrective message ("use the NF-e key"), or fall back silently. Recommendation: block with an actionable message and a link to the new README section.
• Customer segmentation and migration campaign. Two distinct cohorts emerge: (a) ICMS-taxpayer senders who must migrate to chaveNFe and need a data-migration/backfill plan and comms; (b) non-taxpayers unaffected. This drives support-macro design, docs, and targeted outreach ahead of November.
• Async reconciliation and support tooling. PrePostagemCriada::recusadaPorContribuinteIcms() and ProcessamentoAssincrono::recusadaPorContribuinteIcms() make rejection 812 detectable in both synchronous results and asynchronous failure messages — enabling dashboards ("812 rate per day"), alerting, and a self-serve remediation path instead of ticket escalation.
• Risk tracking / scope honesty. ErroContribuinteIcms::reconhece() matches on the message text or causa, and the release explicitly notes the exact API rejection format has not yet been observed. Treat text-matching as a provisional contract; log raw payloads from day one so you can tighten the matcher when real 812 responses appear.

When to Consider This Package

• Adopt when: you emit DC-e through Correios and have any sender base containing ICMS taxpayers (i.e., most B2B shippers with active state registration). The November 2026 deadline makes this effectively mandatory for such flows.
• Adopt when: you want rejection 812 handled as a typed error (ErroContribuinteIcms extending ErroApi) rather than string-sniffing in your own controllers, and you want the pre-flight block on emiteDCe.
• Adopt when: you already depend on this package — v0.5.0 is additive (new class, new optional attribute, new helper methods), so upgrade risk is low; the real work is your data model and customer comms, not the code.
• Look elsewhere / defer when: you only ship non-taxpayer (individual/CPF) senders, or you never use emiteDCe (already sending chaveNFe exclusively) — the feature is inert for you and only the upgrade hygiene matters.
• Look elsewhere when: you need a guaranteed-stable rejection contract. The message/causa matching is best-effort pending observed API behavior; if you require deterministic classification today, plan your own validation layer on top of contribuinteIcms and treat recusadaPorContribuinteIcms() as a secondary signal.
• Watch for: future releases revisiting reconhece() once the real rejection payload is captured — expect a possible tightening of the matcher (potential behavior change in edge cases).

How to Pitch It (Stakeholders)

To executives: Correios/SEFAZ will start rejecting DC-e declarations for ICMS-taxpayer senders on 2 November 2026. This release is our compliance lever: it lets us mark a sender as an ICMS taxpayer, block the wrong document type before we ever call the API, and detect the rejection if it slips through. Shipping this ahead of the deadline avoids a hard cutover failure in peak season and protects label throughput. Cost is a small, backward-compatible upgrade; the effort is mostly data capture and customer communication.

To engineering: v0.5.0 is additive — new ErroContribuinteIcms (subclass of ErroApi, with a static reconhece() helper), new Pessoa::$contribuinteIcms flag honored in the raw array and remetente_padrao, and two detection helpers: PrePostagemCriada::recusadaPorContribuinteIcms() and ProcessamentoAssincrono::recusadaPorContribuinteIcms(). The flag causes pre-postagem creation with emiteDCe to throw ErroValidacao on field emiteDCe before the HTTP call. Ask: add the attribute to sender persistence and API serialization, add a guardrail in the shipment-creation path, log raw rejection payloads (the exact 812 wire format is unobserved), and cover both sync and async paths in tests.

To support/ops: expect a new error surface. Senders with an active state registration must send goods with the NF-e key, not emiteDCe. Point them at the README section "DC-e e remetente contribuinte do ICMS." Build a saved reply and a dashboard on 812 occurrences as soon as payloads are captured.