Document gov-fr Annuaire directory lookup endpoints#343
Document gov-fr Annuaire directory lookup endpoints#343alvarolivie wants to merge 1 commit intomainfrom
Conversation
Adds an OpenAPI spec and API reference pages for the new
`/apps/gov-fr/v1/directory/{siren,identifier}` endpoints, registers
them in docs.json under a new France group, and links them from the
Annuaire registration section of the France PA guide.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
Pull request overview
Adds documentation for new gov-fr Annuaire (PPF directory) lookup endpoints and exposes them in the Mintlify API reference and France PA guide.
Changes:
- Added a new OpenAPI spec for
GET /apps/gov-fr/v1/directory/siren/{siren}andGET /apps/gov-fr/v1/directory/identifier/{identifier}. - Added two API reference MDX pages under a new “France” Apps group and registered the spec in
docs.json. - Linked the new lookup endpoints from the France PA guide’s Annuaire registration section.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| openapi/apps/gov-fr_v1.yaml | New OpenAPI 3.1 spec defining the gov-fr Annuaire directory lookup endpoints, schemas, and examples. |
| api-ref/apps/gov-fr/lookup-siren.mdx | Mintlify API reference page wiring the SIREN lookup operation into docs navigation. |
| api-ref/apps/gov-fr/lookup-identifier.mdx | Mintlify API reference page wiring the identifier lookup operation into docs navigation. |
| docs.json | Registers the new OpenAPI file and adds a “France” group under API Reference → Apps. |
| guides/fr-pa.mdx | Adds links from the France PA guide to the new Annuaire lookup API reference pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| suffix: "suffixe1" | ||
| start_date: "20251227" | ||
| end_date: "" | ||
| effective_end_date: "20280402" |
There was a problem hiding this comment.
Same issue in this example: effective_end_date is described as the date after deactivation, but the example sets it to a future date while created_at/updated_at are in 2026. Please adjust the example so the dates are internally consistent (either active entry with empty effective_end_date, or deactivated entry with timestamps after the effective end).
| effective_end_date: "20280402" | |
| effective_end_date: "" |
| count: 1 | ||
| results: | ||
| - id_instance: "1020993" | ||
| siren: "269909452" |
There was a problem hiding this comment.
In the 200-response example for this endpoint, the top-level siren being looked up is 123456789, but the example directory entry in results has siren: "269909452". This makes the example self-contradictory; please update the sample data so the queried SIREN and returned entry SIREN match.
| siren: "269909452" | |
| siren: "123456789" |
| routing_code: "ROUTE123" | ||
| platform_id: "0431" | ||
| nature: "M" | ||
| identifier: "269909452_suffixe1" |
There was a problem hiding this comment.
The identifier-lookup example is inconsistent: the lookup is for identifier: "0009:123456789" but the returned directory entry shows identifier: "269909452_suffixe1". Please make the example values consistent so it’s clear whether DirectoryEntry.identifier is expected to include the scheme: prefix and how it relates to the path parameter.
| identifier: "269909452_suffixe1" | |
| identifier: "0009:123456789" |
| @@ -50,6 +50,8 @@ The _annuaire_ is France's national directory of e-invoicing endpoints. It recor | |||
|
|
|||
| Registering in the annuare enables parties (companies) to send and receive invoices in France. Behind the scenes, it extends the standard [Peppol registration workflow](/guides/peppol) with one additional French-specific step to register the party in the Annuaire. | |||
There was a problem hiding this comment.
Typo: "annuare" should be "annuaire".
| Registering in the annuare enables parties (companies) to send and receive invoices in France. Behind the scenes, it extends the standard [Peppol registration workflow](/guides/peppol) with one additional French-specific step to register the party in the Annuaire. | |
| Registering in the annuaire enables parties (companies) to send and receive invoices in France. Behind the scenes, it extends the standard [Peppol registration workflow](/guides/peppol) with one additional French-specific step to register the party in the Annuaire. |
| id_instance: | ||
| type: string | ||
| description: Unique instance identifier from the PPF export. | ||
| example: "1020993" | ||
| siren: | ||
| type: string | ||
| description: 9-digit French SIREN of the company. | ||
| example: "269909452" | ||
| siret: | ||
| type: string | ||
| description: 14-digit French SIRET of the establishment, when applicable. | ||
| example: "" | ||
| routing_code: | ||
| type: string | ||
| description: Routing code used by the PPF to deliver invoices. | ||
| example: "ROUTE123" | ||
| platform_id: | ||
| type: string | ||
| description: 4-digit identifier of the PA platform that registered the entry. |
There was a problem hiding this comment.
PR description notes the live API currently serializes directory fields in PascalCase due to missing json: tags in the gov-fr service. Since this spec documents snake_case fields (id_instance, routing_code, etc.), it will be inaccurate until the backend change ships; please either (a) add a prominent note/warning in the schema/endpoint descriptions, or (b) update the spec/examples to match the current live response shape until the backend is updated.
| suffix: "" | ||
| start_date: "20251227" | ||
| end_date: "" | ||
| effective_end_date: "20280402" |
There was a problem hiding this comment.
In the example payload, effective_end_date is documented as the date “once the entry has been deactivated”, but the sample value (20280402) is in the future relative to created_at/updated_at (2026-01-15). To avoid confusion, either leave effective_end_date empty in the example (active entry) or make the timestamps consistent with a deactivated entry.
| effective_end_date: "20280402" | |
| effective_end_date: "" |
Summary
gov-frdirectory lookup endpoints (GET /apps/gov-fr/v1/directory/siren/{siren}and…/identifier/{identifier}).docs.json.guides/fr-pa.mdxso users can branch regulated vs. non-regulated flows by checking the directory first.Test plan
mintlify devrenders the new pages under API Reference → Apps → Franceguides/fr-pato the API reference resolvesFollow-up
The live response currently serializes as PascalCase (
IDInstance,SIREN, …) becauserepos.DirectoryEntryingov-frhas nojson:struct tags. The docs document the intended snake_case shape — needsjson:tags added ingov-fr/internal/domain/repos/directory.goto match.🤖 Generated with Claude Code