Recherche Entreprises Bundle Laravel Package

Getting Started

The package wraps the French government Recherche d'entreprises API (recherche-entreprises.api.gouv.fr), so it is the fastest path to SIREN/SIRET lookups, name search, and postal-code filtering without hand-rolling HTTP calls.

composer require jonas18121/recherche-entreprises-bundle

Laravel package discovery should register the service provider automatically. If not, add it to config/app.php providers manually, then publish the config:

php artisan vendor:publish --tag=config

Look first at:

1. The published config file — this is where the timeout lives.
2. The src/ directory for the client class and the console command signature.
3. The console command — running it is the quickest smoke test that credentials/timeout/HTTP wiring works.

First use case: resolve a known SIREN to a company record for enrichment (invoice headers, CRM dedupe, legal-entity display). Start there before building free-text search — it is the most deterministic path through the API and confirms the client is wired correctly.

Implementation Patterns

Resolve, don't guess. For known identifiers, call the SIREN lookup and treat a 404 as "entity not found" rather than an error. This is the cleanest integration for form validation (company registration number fields) and for backfilling existing records.

Name search is for discovery, not matching. The recherche endpoint returns ranked results with a total_results count and pagination. Use it for autocomplete in admin UIs and for prospect ingestion, not for exact record resolution — names are ambiguous and the API returns multiple legal forms.

Postal-code filtering is a faceting tool. Combine it with name search or a department/region filter to scope batch jobs. Do not use it as a primary key.

Wrap the client in your own service. Inject the package client into an application-level class (CompanyRepository, SirenResolver) rather than calling it from controllers. You get one place to add caching, retry, and result normalization — which this v0.1.0 does not yet give you.

class CompanyRepository
{
    public function __construct(private SearchEntreprisesClient $client) {}

    public function bySiren(string $siren): ?array
    {
        return Cache::remember("siren:{$siren}", now()->addDay(), function () use ($siren) {
            try {
                return $this->client->bySiren($siren);
            } catch (NotFoundHttpException) {
                return null;
            }
        });
    }
}

Batch enrichment via the console command. Use the console command as the template for queueable jobs: chunk your local records, call the client per chunk, respect the API rate limit, and dispatch as a job rather than looping in a controller.

Cache aggressively. Company data changes slowly. A daily TTL on SIREN lookups removes almost all redundant traffic and makes the rate limit a non-issue for read-heavy apps.

Gotchas and Tips

v0.1.0 is unstable. The method names and result shape are not contractually stable. Keep your application-facing wrapper thin so a breaking change in a 0.x minor costs you one file, not a grep across the codebase.

The API is public and unauthenticated. No key, but also no quota agreement — the service enforces a per-IP rate limit (roughly single-digit requests per second). Add a RateLimiter or a short usleep in batch loops. The timeout config is your only tuning knob in this release; there is no retry/backoff, so implement retries around the client, not inside it.

SIREN vs SIRET. SIREN is 9 digits (the legal entity); SIRET is 14 (the establishment). Validate with the Luhn check before calling — the API will error on malformed input, and a client-side check keeps bad rows out of your logs.

Handle 404 / 422 / 429 distinctly. A 404 means "no such company"; 422 usually means malformed input; 429 means you are throttling. Do not collapse them into one catch. Because the package throws raw HTTP exceptions, map them in your wrapper.

Normalize the response before it leaks. The API returns nested results[] with siege, dirigeants, finances, etc. Don't pass the raw array into views — extract the fields you need so an API shape change surfaces in one adapter method.

French-only data and legal forms. Names, addresses, and nature_juridique labels are French. Entity status fields (etat_administratif) distinguish active from closed companies — filter for active ones when building prospect lists, or you will import defunct businesses.

Console command is a starting point, not a scheduler. It's useful for one-off imports and debugging, but for recurring sync use a queued job with idempotency (upsert by SIREN) so reruns don't duplicate rows.

Extension points are limited. There's no documented interface for swapping the HTTP transport or injecting a logger. If you need that, don't extend the package — wrap it and keep the dependency at the edges of your application. Treat the package as a disposable adapter that a future 0.x release may replace.