french-company-check-v1 — operator guide

For Pocket Network suppliers serving french-company-check-v1. What the service does and how to call it: /docs.

Backend software

The source is not yet published; contact the service owner. Until it is, this page describes what running the backend involves, not how to obtain it.

The backend is a stateless FastAPI process (Python 3.12) that calls three public open-data APIs and normalizes their answers. No API key, no database. Known-good implementation: french-company-check >= 1.2.0. Minimum: 1 GB disk, 1 GB RAM.

Checklist

Item	Requirement
Outbound HTTPS	Open to `recherche-entreprises.api.gouv.fr`, `bodacc-datadila.opendatasoft.com` and `ec.europa.eu` (VIES). Behind an egress firewall that blocks them, the backend is useless.
Rate limit	The primary source allows 7 requests per second per IP. Keep the in-process cache and run a single worker per public IP: the built-in 4 req/s outbound limiter is per process. Disable any RelayMiner-side rate limit below that.
Backend timeout	At least 10 s. The service answers within its own 9 s deadline, degraded rather than late.
Transport	REST only. HTTP server on `:8080`, mounted at `/`. Listen on localhost or a private network only.
Gateways	Configure as type `passthrough` with `rpc_types ["rest"]`.
Headers	None needed. Every input is in the JSON body; the service never reads caller headers.

RelayMiner

Sketch of the supplier entry; adapt the rest of the RelayMiner configuration to your setup:

suppliers:
  - service_id: french-company-check-v1
    listen_url: http://0.0.0.0:<relayminer-port>
    rpc_type_service_configs:
      rest:
        backend_url: http://127.0.0.1:8080

Health checks before staking

The same three probes as in the service card:

Request	Expect	Proves
`GET /v1/version`	`$.service` matches `^french-company-check-v1$`	The backend is this service.
`GET /v1/health`	`$.status` matches `^ok$`	The process is alive.
`POST /v1/company` `{"q": "INSEE"}`	`$.sources.recherche_entreprises` matches `^ok$`	The primary registry is reachable from this host.

curl -s http://127.0.0.1:8080/v1/version
curl -s http://127.0.0.1:8080/v1/health
curl -s -X POST http://127.0.0.1:8080/v1/company -H 'content-type: application/json' -d '{"q": "INSEE"}'

Expected behaviour

Never a 5xx. An upstream outage gives a 200 with status: source_unavailable or a source_degraded:* flag; an internal fault gives a 200 with status: error.
VIES is often unavailable (rate_limited, timeout). That is upstream behaviour, not a backend fault.
Results are variable: registries change continuously, so two suppliers answering at different times may differ.

Personal data

Responses may contain personal data: names and roles of company officers, published by the French trade register. They pass through your RelayMiner. Treat them accordingly: do not log response bodies. Callers can suppress them with directors_limit: 0.