Cpf Gratis Laravel Package

Getting Started

• Install with composer require jansenfelipe/cpf-gratis. This is a Laravel 5-era package: on 5.5+ auto-discovery registers the service provider and facade; on older apps add JansenFelipe\CpfGratis\CpfGratisServiceProvider and the CpfGratis facade alias to config/app.php.
• Look first at the README and src/ — the public surface is thin (essentially one lookup method returning an array/object with fields like nome, situacao, nascimento). Confirm the exact method name and response shape against the version you installed before writing code around it.
• Understand the captcha strategy before anything else. The whole point of "gratis" is querying the Receita Federal site directly, which is captcha-protected. Identify whether the package expects a manual token, does OCR itself, or delegates to a captcha service — this dictates your architecture.
• First use case: a single lookup in php artisan tinker against a known-valid test CPF to inspect the real response shape and timing:

$result = \CpfGratis::search('00000000000');
// inspect keys, nulls, and error behavior

• Only after that, wrap it in a service class and move on to caching/queuing.

Implementation Patterns

• Wrap it, don't call it directly. Create a CpfLookupService (or contract) that returns your own DTO. The package scrapes a government site; its return format and failure modes are not a stable contract you want leaking through your app.
• Validate locally first. Run the CPF check-digit algorithm before any network call — rejecting typos locally avoids wasting slow, rate-limited scrapes on malformed input.
• Cache aggressively. CPF registration data changes rarely. Cache by CPF in Redis with a long TTL (days/weeks), and treat the lookup as a cache-miss fallback, not a primary path.
• Queue and throttle bulk lookups. One ShouldQueue job per CPF with backoff(), retryUntil(), and either the RateLimited middleware or a Redis::throttle lock. Never loop synchronously over a list — Receita will throttle or block you.
• Enrich asynchronously. Typical flow: user submits CPF → validate locally → check cache → if miss, dispatch a job → update the user record and fire a CpfQueried/CpfLookupFailed event. Never block an HTTP request on the scrape.
• Bind a fake in tests and local dev. Type-hint an interface, bind the real implementation in the service provider and a FakeCpfLookup in tests. CI should never touch the live service.
• Layer a fallback behind the interface. If the free path fails (captcha, layout change), you can swap in a paid API or manual review without touching callers.

Gotchas and Tips

• Scraping fragility is the headline risk. The package parses the Receita page; a layout change breaks it silently. Pin the version, watch releases, and treat empty/malformed responses as LookupFailed — never as "CPF not found." A silent "not found" is the worst failure mode for a KYC/validation flow.
• Captcha is the real constraint. Free captcha handling (OCR/manual) is brittle. Design the interface so a solver or manual input can be injected, and expect this to be the first thing that breaks.
• Rate limits and IP bans. Add jitter, exponential backoff, and a low concurrency cap. Consider egress through a proxy if volume grows — a single IP hammering the endpoint gets blocked fast.
• LGPD. CPF is personal data under Brazilian law. Have a legal basis, log/audit access, and encrypt at rest. Cache with a defined retention period rather than forever.
• Timeouts and TLS. Set short connect/read timeouts; older PHP/cURL against Brazilian government TLS endpoints can fail on stale CA bundles — keep the system CA store current.
• Config quirks. If the package publishes config, check for proxy/timeout/captcha keys and any env() reads; defaults are often tuned for a single manual query, not production throughput.
• Extension points. The HTTP client and captcha solver are the seams to swap via the container. Prefer rebinding those over forking the package.