invopop · mrdanwa · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026 · Jul 13, 2026
diff --git a/api-ref/apps/gov-fr/agreement-fetch.mdx b/api-ref/apps/gov-fr/agreement-fetch.mdx
@@ -1,6 +1,7 @@
 ---
-title: "Generate agreement PDF"
+title: "Download agreement PDF"
+description: "Download the current agreement PDF for a silo entry. Returns the signed mandate if already signed, otherwise the unsigned template."
 openapi: "GET /apps/gov-fr/v1/entry/{silo_entry_id}/agreement"
 ---
 
-Returns the unsigned mandate PDF that the signer must review and sign. The document is generated on the fly from the silo entry's draft party — the call fails with `422` when any required party or signer field is missing.
+Returns the current agreement PDF. If the signer has already completed the signing step (`POST /sign` or `POST /agreement`), the signed mandate is returned. Otherwise the unsigned template is returned, pre-filled with the party's details.
diff --git a/api-ref/apps/gov-fr/agreement-upload.mdx b/api-ref/apps/gov-fr/agreement-upload.mdx
@@ -1,8 +1,11 @@
 ---
-title: "Upload signed agreement"
+title: "Upload pre-signed agreement"
+description: "Store a mandate signed outside Invopop on the silo entry."
 openapi: "POST /apps/gov-fr/v1/entry/{silo_entry_id}/agreement"
 ---
 
-Stores the customer's signed PDF on the silo entry together with the chosen signature method. Two methods are accepted: `esignature` (PAdES — validated cryptographically against the EU Trusted List) and `identity` (hand-signed — verification deferred to Invopop's approval service, requires identity images uploaded via `POST /identity` first).
+Stores a mandate the customer has signed outside Invopop. Satisfies the `agreement` step on the approval flow.
 
-This call only persists the document. Call `POST /confirm` afterwards to mark the submission complete and let the onboarding workflow proceed.
+Identity verification is still required. Call `POST /identity` before or after this endpoint, then call `POST /confirm` to finalise.
+
+For in-app signing, use `POST /sign` instead.
diff --git a/api-ref/apps/gov-fr/confirm.mdx b/api-ref/apps/gov-fr/confirm.mdx
@@ -1,6 +1,14 @@
 ---
 title: "Confirm submission"
+description: "Finalise the onboarding approval and advance the registration workflow."
 openapi: "POST /apps/gov-fr/v1/entry/{silo_entry_id}/confirm"
 ---
 
-Marks the customer's submission as complete once the signed agreement (and any required identity images) have been uploaded. Records the decision in silo meta and pokes the queued `agreement.wait.approval` task so the onboarding workflow can continue.
+Finalises the approval and pokes the queued `agreement.wait.approval` task so the onboarding workflow continues. Returns the approval flow status.
+
+Identity verification (`POST /identity`) is required on both paths. In addition:
+
+- **In-app signing**: `POST /sign` must have been called.
+- **Pre-signed PDF**: `POST /agreement` must have been called.
+
+A `submitted` status in the response means the submission is under review; the workflow advances once a decision is made.
diff --git a/api-ref/apps/gov-fr/identity-upload.mdx b/api-ref/apps/gov-fr/identity-upload.mdx
@@ -1,6 +1,9 @@
 ---
 title: "Upload identity image"
+description: "Upload one face of the signer's identity document for verification."
 openapi: "POST /apps/gov-fr/v1/entry/{silo_entry_id}/identity"
 ---
 
-Stores one face of the signer's identity document as an attachment on the silo entry. Required before confirming when the agreement was uploaded with `signature=identity`. Call once per view — `front` + `back` for an ID card (CNI, titre de séjour), or `page` for a passport. Re-uploading the same view overwrites the previous image; the MIME type is detected from the bytes.
+Stores one face of the signer's identity document. Required on both signing paths. Call before `POST /confirm`.
+
+Call once per side: `front` + `back` for an ID card (CNI, titre de séjour), or a single `page` for a passport. Re-uploading the same view overwrites the previous image.
diff --git a/api-ref/apps/gov-fr/sign.mdx b/api-ref/apps/gov-fr/sign.mdx
@@ -0,0 +1,14 @@
+---
+title: "Sign agreement mandate"
+description: "Stamp the signer's signature onto the mandate and store the result as the signed agreement."
+openapi: "POST /apps/gov-fr/v1/entry/{silo_entry_id}/sign"
+---
+
+Stamps the signer's signature onto the generated mandate PDF and stores the result as the entry's signed agreement. Satisfies the `sign` step on the approval flow.
+
+Two modes:
+
+- **Drawn**: pass a PNG or JPEG image in `signature` (≤ 4 MB). The image is inked onto the signature box.
+- **Typed**: omit `signature`. The signer's name is rendered as a typed signature.
+
+The silo entry must have signer fields set (given name, surname, and identity number) before calling. Use together with `POST /identity`, then call `POST /confirm` to finalise.
diff --git a/docs.json b/docs.json
@@ -616,6 +616,7 @@
 									"api-ref/apps/gov-fr/agreement-fetch",
 									"api-ref/apps/gov-fr/agreement-upload",
 									"api-ref/apps/gov-fr/identity-upload",
+									"api-ref/apps/gov-fr/sign",
 									"api-ref/apps/gov-fr/confirm",
 									"api-ref/apps/gov-fr/reports-summary",
 									"api-ref/apps/gov-fr/reports-periods",

diff --git a/guides/fr-pa-registration.mdx b/guides/fr-pa-registration.mdx
@@ -59,6 +59,90 @@ The Annuaire requires every entry to be receive-capable, so there is no send-onl
   </Tab>
 </Tabs>
 
+## Agreement signing
+
+The `gov-fr.agreement.sign` step generates the mandate and publishes a `link_url` under the `approval-link` key in the silo entry meta. The party representative can complete signing through the registration wizard, or platforms that want full control can use the [entry API](#entry-api) directly.
+
+### Registration wizard
+
+Once the workflow step runs, find the `link_url` in the `approval-link` meta entry of the silo entry. In console, it appears in the Meta tab of the entry's right sidebar.
+
+<Accordion title="Example approval-link meta entry">
+```json
+{
+  "src": "gov-fr",
+  "key": "approval-link",
+  "ref": "EgDeG3pDBDe",
+  "link_url": "https://gouv-fr.invopop.com/reg/EgDeG3pDBDe/start",
+  "link_scope": "public",
+  "indexed": true,
+  "shared": true
+}
+```
+</Accordion>
+
+Forward the `link_url` to the party representative, or embed it as an `iframe` to keep them within your platform.
+
+The wizard walks the representative through each step:
+
+<Steps>
+  <Step title="Party details">
+    Review and confirm the pre-filled company and signer information.
+  </Step>
+  <Step title="Identity document">
+    Upload a photo of the signer's ID card (front and back) or passport page.
+  </Step>
+  <Step title="Sign mandate">
+    Sign the pre-filled mandate directly in the browser, or upload a pre-signed PDF.
+  </Step>
+  <Step title="Confirm">
+    Submit for Invopop review. The party status moves to `submitted` until a decision is made.
+  </Step>
+</Steps>
+
+### Entry API
+
+For platforms that want to drive the signing process programmatically, use the entry API (all endpoints under `/apps/gov-fr/v1/entry/{silo_entry_id}/`). Identity verification is required on both paths.
+
+<Tabs>
+  <Tab title="In-app signing">
+    The customer signs the mandate directly. Invopop stamps the signature and verifies identity.
+
+    <Steps>
+      <Step title="Download mandate">
+        `GET /agreement` returns the mandate PDF pre-filled with the party's details. Fails with `422` if any required signer field is missing.
+      </Step>
+      <Step title="Upload identity document">
+        `POST /identity` uploads one face at a time: `front` + `back` for an ID card, or `page` for a passport.
+      </Step>
+      <Step title="Sign the mandate">
+        `POST /sign` stamps the signature. Pass a drawn PNG or JPEG image in `signature` (≤ 4 MB), or omit it to render the signer's name as a typed signature.
+      </Step>
+      <Step title="Confirm">
+        `POST /confirm` finalises the submission and returns a `status` field. `submitted` means the party is under approval review before registration continues.
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Pre-signed PDF">
+    The customer signs the mandate externally and uploads the result.
+
+    <Steps>
+      <Step title="Download mandate">
+        `GET /agreement` returns the pre-filled mandate PDF for the customer to sign externally.
+      </Step>
+      <Step title="Upload identity document">
+        `POST /identity` uploads one face at a time: `front` + `back` for an ID card, or `page` for a passport.
+      </Step>
+      <Step title="Upload signed PDF">
+        `POST /agreement` stores the signed PDF (≤ 4 MB).
+      </Step>
+      <Step title="Confirm">
+        `POST /confirm` finalises the submission and returns a `status` field. `submitted` means the party is under approval review before registration continues.
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
 ### Taking over a line from another Plateforme Agréée
 
 If a SIREN's Annuaire line is already held by another Plateforme Agréée (PA), registration takes that line over instead of creating a duplicate. To do so, the party must specify the former PA line under `fr-former-matricule` meta key. This will add an additional section in the signed agreement that asks for consent to take over the line.