**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Justificatifs

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Reçus ordinaires et fiscaux enregistrés, avec autorisation indépendante des sources documentaires et accès aux PDF existants.

## Opérations

## GET /receipts

Lister les reçus ordinaires et fiscaux enregistrés

`list_receipts`

Exige receipts:read explicitement attribué ; cette autorisation n’est jamais proposée par défaut. Liste les reçus ordinaires et fiscaux existants de l’organisation authentifiée. Les filtres se combinent avec ET : kind, paymentId source, contactId actuel du paiement source, associationId, période documentaire enregistrée [from,before), et status. from/before sont des instants RFC 3339 avec fuseau, comparés en UTC. RECORDED décrit une entrée enregistrée sans marqueur deleted vrai ; WITHHELD inclut les annulations et les publications SEPA/KESHER en attente ; UNKNOWN conserve un marqueur deleted invalide. La présence ne prouve ni disponibilité du PDF, ni livraison d’email, ni validité juridique, ni capture, ni règlement bancaire. Une file sans document enregistré est absente ; cette lecture ne prédit aucune éligibilité et ne déclenche aucune émission. Réadmet l’association actuelle, chaque paiement, cible et contact reliés, ainsi que l’abonnement annuel, dans l’organisation et le périmètre des collectes autorisées. Une référence historique ou un snapshot ne donne aucun droit. Les documents annuels exposent subscriptionId depuis paiement et les vrais paymentIds depuis paiements[] ; un document groupé ou annuel est entièrement omis dès qu’une source complète ne peut être prouvée autorisée. Les paiements SERVICE historiques et les types de cible inconnus sont écartés faute de propriétaire de cible admis par cette API. amountMinor provient uniquement du document, en unités mineures (5000 pour EUR 50), et currency uniquement de sa devise ; toute valeur historique absente ou invalide reste null, sans repli sur un paiement, l’organisation ou un snapshot. Aucune identité de facturation, moyen réutilisable, configuration privée, réponse prestataire, URL ou erreur brute n’est exposée. Tri croissant stable par kind puis UUID du document, limit par défaut 50, maximum 200. Chaque appel parcourt au plus 1000 documents candidats ; une page vide peut avoir hasMore:true. Conservez les filtres et continuez avec nextCursor jusqu’à hasMore:false ; count concerne seulement la page, jamais le total autorisé complet. Un document dépassant 200 paiements sources ou entrées d’affectation produit 409 RECEIPT_CATALOG_TOO_LARGE, sans autorisation partielle ; faites vérifier les sources par leur propriétaire. Paramètres inconnus, répétés ou structurés, UUID/dates/statut/limite/curseur invalides et corps non vides sont refusés avec 400. Aucun débit, remboursement, appel prestataire, synchronisation, rapprochement, traitement de file, génération, régénération ni changement métier n’a lieu ; l’authentification commune peut mettre à jour la télémétrie d’utilisation de la clé API.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Type documentaire facultatif ; les deux types sont inclus par défaut."
}
```

```json
{
  "name": "paymentId",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Filtre sur l’UUID d’un vrai paiement source, y compris membre d’un reçu groupé ou annuel ; ne fournissez jamais ici l’UUID de l’abonnement annuel."
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Filtre sur l’UUID du contact actuel d’un paiement source de la même organisation ; ne désigne pas un nom de facturation historique."
}
```

```json
{
  "name": "associationId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filtre sur MAIN ou l’UUID d’une association émettrice actuelle. Une association inconnue ou hors périmètre ne renvoie aucune entrée."
}
```

```json
{
  "name": "from",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Borne inclusive du datetime documentaire enregistré, instant RFC 3339 avec fuseau. Les documents dont la date est inconnue ne correspondent pas à une période."
}
```

```json
{
  "name": "before",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Borne exclusive du datetime documentaire enregistré ; doit suivre from lorsque les deux sont fournis."
}
```

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "RECORDED",
      "WITHHELD",
      "UNKNOWN"
    ]
  },
  "description": "Filtre du statut de visibilité enregistré RECORDED, WITHHELD ou UNKNOWN. Il ne désigne aucun état financier ou de livraison."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre maximal d’entrées renvoyées, de 1 à 200 ; seuls les entiers décimaux sont acceptés."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 300
  },
  "description": "nextCursor opaque de la réponse précédente. Conservez les mêmes filtres ; continuez même après une page vide avec hasMore:true."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Métadonnées documentaires autorisées et continuation de lecture bornée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptCatalogResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Paramètre invalide ou inattendu, corps non vide, UUID, période, statut, limite ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Autorisation receipts:read explicitement attribuée absente, ou organisation désactivée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_CATALOG_TOO_LARGE : un document dépasse 200 sources ou entrées d’affectation ; une vérification par le propriétaire est requise. Aucune réponse partielle n’est renvoyée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les documents n’ont pas pu être lus. Aucune opération financière ou documentaire n’a été tentée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/access

Lire l’accès autorisé au PDF d’un reçu existant

`get_receipt_access`

Autorisation requise : `receipts:read`, explicitement attribuée. Fournir kind et id depuis le catalogue de reçus. Aucun paramètre de requête ni corps non vide n’est accepté. Réadmet le document et tous les paiements sources actuels, l’abonnement annuel, les membres groupés et les cibles liées dans l’organisation authentifiée et les restrictions de collecte ; un snapshot ou une référence historique n’élargit jamais l’accès. Les enregistrements absents, supprimés, incohérents ou hors périmètre renvoient 404. Un reçu fiscal est distinct d’un reçu ordinaire. Le champ de métadonnées amountMinor contient uniquement le montant documentaire enregistré en unités mineures ; un montant ou une devise null demeure inconnu, notamment sur les anciens reçus annuels. La présence du document et son accès ne prouvent ni capture, ni règlement bancaire, ni validité juridique, ni livraison par email. Lit uniquement un original existant : aucune génération, émission, régénération, synchronisation, mise en file, requête au prestataire ou écriture métier. Les documents externes restent UNAVAILABLE avec EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER tant qu’un propriétaire de lecture du prestataire ne valide pas organisation, configuration et destination ; aucune URL fournisseur arbitraire ni URL historique de reçu sans authentification n’est renvoyée. L’authentification commune peut actualiser les données d’utilisation de la clé API. Renvoie du JSON avec les métadonnées du reçu et access.status, reason, method, path, requiredScope, contentType et filename. AVAILABLE indique qu’un fichier local ordinaire avec une signature PDF existe actuellement et ne dépasse pas 25 MiB (26214400 octets). Effectuer un GET sur access.path depuis la même origine API de confiance avec les mêmes identifiants autorisés dans les en-têtes, et X-Org-Id pour root. Le téléchargement recontrôle les droits et le stockage : la disponibilité peut changer. Cet outil renvoie les métadonnées et la disponibilité de l’accès. Utiliser download_receipt_pdf via le MCP pour récupérer le fichier privé lui-même, ou utiliser le chemin REST authentifié. UNAVAILABLE fournit un path et une method null ainsi qu’un motif exploitable ; ne jamais émettre ou régénérer de reçu pour réessayer cette lecture.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Type de document renvoyé par le catalogue. RECEIPT désigne un reçu de paiement ordinaire ; FISCAL_RECEIPT désigne un reçu fiscal, y compris annuel."
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du document renvoyé par le catalogue ; il ne s’agit pas d’un identifiant de paiement ou d’abonnement."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Métadonnées du reçu et disponibilité actuelle de l’accès ; UNAVAILABLE constitue une observation réussie sans chemin de téléchargement.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptAccessResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_RECEIPT_KIND, INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS ou UNEXPECTED_REQUEST_BODY. Fournir uniquement le type du catalogue et l’UUID du document.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Autorisation receipts:read non explicitement attribuée ou accès à l’organisation refusé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : document ou source actuelle absent, retenu, de statut invalide, incohérent ou non autorisé. Les reçus annuels et groupés exigent l’autorisation de chaque source.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_CATALOG_TOO_LARGE : l’admission dépasse la limite de 200 paiements sources ou entrées d’affectation ; demander une revue au propriétaire sans tronquer les contrôles d’autorisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : l’accès au document n’a pas pu être lu ; aucune opération documentaire n’a été tentée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/pdf

Télécharger le PDF existant d’un reçu avec authentification

`download_receipt_pdf`

Autorisation requise : `receipts:read`, explicitement attribuée. Fournir kind et id depuis le catalogue de reçus. Aucun paramètre de requête ni corps non vide n’est accepté. Réadmet le document et tous les paiements sources actuels, l’abonnement annuel, les membres groupés et les cibles liées dans l’organisation authentifiée et les restrictions de collecte ; un snapshot ou une référence historique n’élargit jamais l’accès. Les enregistrements absents, supprimés, incohérents ou hors périmètre renvoient 404. Un reçu fiscal est distinct d’un reçu ordinaire. Le champ de métadonnées amountMinor contient uniquement le montant documentaire enregistré en unités mineures ; un montant ou une devise null demeure inconnu, notamment sur les anciens reçus annuels. La présence du document et son accès ne prouvent ni capture, ni règlement bancaire, ni validité juridique, ni livraison par email. Lit uniquement un original existant : aucune génération, émission, régénération, synchronisation, mise en file, requête au prestataire ou écriture métier. Les documents externes restent UNAVAILABLE avec EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER tant qu’un propriétaire de lecture du prestataire ne valide pas organisation, configuration et destination ; aucune URL fournisseur arbitraire ni URL historique de reçu sans authentification n’est renvoyée. L’authentification commune peut actualiser les données d’utilisation de la clé API. Recontrôle les droits et lit un original local déjà stocké, fichier ordinaire avec une signature PDF, limité à 25 MiB (26214400 octets) ; les liens symboliques, dossiers et autres fichiers spéciaux sont refusés. Renvoie application/pdf avec un nom de pièce jointe et un cache no-store. Lorsqu’un document admis ne possède pas d’original utilisable, renvoie 409 RECEIPT_PDF_UNAVAILABLE et un motif ; consulter le JSON d’accès ou faire réparer l’original par son propriétaire, sans émission automatique. Aucune redirection ni récupération auprès du prestataire.

Le MCP renvoie le fichier privé réel dans une ressource embarquée avec son type MIME et son blob base64, ainsi que filename, byteLength et le SHA-256 des octets décodés. Utiliser la capacité fichiers de l’hôte pour enregistrer ou joindre ces octets sous le nom renvoyé et vérifier leur taille et leur SHA-256. L’URI unisoft identifie uniquement cette réponse. Elle ne constitue ni une URL publique ni une référence de téléchargement réutilisable. Fournir le fichier au destinataire autorisé, sans recopier le blob dans le texte du chat, publier un document financier ou inventer une URL de partage. Le propriétaire REST authentifié recontrôle l’organisation, les permissions et toutes les sources ou preuves d’export requises à chaque appel. REST conserve sa réponse binaire. Le fichier prouve uniquement la récupération de ces octets. Il ne prouve ni règlement bancaire, ni validité juridique du document, ni remise à un destinataire.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  },
  "description": "Type de document renvoyé par le catalogue. RECEIPT désigne un reçu de paiement ordinaire ; FISCAL_RECEIPT désigne un reçu fiscal, y compris annuel."
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du document renvoyé par le catalogue ; il ne s’agit pas d’un identifiant de paiement ou d’abonnement."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Octets du PDF original existant ; téléchargement authentifié, sans réponse JSON.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_RECEIPT_KIND, INVALID_UUID, UNEXPECTED_QUERY_PARAMETERS ou UNEXPECTED_REQUEST_BODY. Fournir uniquement le type du catalogue et l’UUID du document.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Autorisation receipts:read non explicitement attribuée ou accès à l’organisation refusé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : document ou source actuelle absent, retenu, de statut invalide, incohérent ou non autorisé. Les reçus annuels et groupés exigent l’autorisation de chaque source.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "RECEIPT_PDF_UNAVAILABLE avec un motif fixe, ou RECEIPT_CATALOG_TOO_LARGE si l’admission dépasse 200 paiements sources ou entrées d’affectation. Aucun document n’a été généré ou modifié.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reason": {
            "type": "string",
            "enum": [
              "EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER",
              "STORAGE_NOT_CONFIGURED",
              "PDF_UNAVAILABLE",
              "PDF_INVALID",
              "PDF_TOO_LARGE"
            ]
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : l’accès au document n’a pas pu être lu ; aucune opération documentaire n’a été tentée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "param": {
            "type": "string"
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 26214400
  }
}
```

## GET /abonnements/{id}/fiscal-grouping-preview

Prévisualiser les candidats du regroupement fiscal annuel natif

`preview_annual_receipt_grouping`

Requiert receipts:read ET paiements:read ET abonnements:read explicitement attribués. Ces lectures annuelles concernent l’UUID d’un abonnement existant, pas un UUID de paiement/document ni un groupe libre. Fournir l’année documentaire obligatoire (1000–9999) ; les règles natives de date/année de reçu s’appliquent, pas la date d’enregistrement. preview_annual_receipt_grouping suit hooks/cerfa-year : abonnement annuel existant, association FR/défaut sans noCerfa:true, paiements COMPLETED non déjà liés à un reçu fiscal et fiscalContribution(payment,{annual:true}) positive sur cette année. Les instantanés fiscaux figés priment. Contrairement à la file unitaire, ce sélecteur annuel n’exclut pas imported, finalized:false ni ignoreCerfa ; l’aperçu décrit ce sélecteur sans certification indépendante ni droit d’émettre. Tous les paiements, l’abonnement parent, contacts et cibles conservées exigent les droits actuels d’organisation/association/collecte. Seuls les historiques EUR prouvés sont admis, le propriétaire PDF annuel n’ayant pas de paramètre explicite de devise. Le scan complet est borné à 200 paiements COMPLETED ; dépassement refusé sans troncature des droits/totaux. Dates/devises/instantanés inconnus ne deviennent ni zéro ni EUR. Aucun candidat admis donne un refus de revue propriétaire, pas une preuve d’absence de document. amountMinor est la somme fiscale candidate en unités mineures EUR (5000 = 50 EUR), distincte du montant nominal et du total documentaire émis. emissionSupported:false/TARGETED_ANNUAL_OWNER_REQUIRED signifie qu’aucune commande annuelle ciblée n’est offerte actuellement ; le daemon annuel exporté est global et ne doit jamais être invoqué pour un appelant. Ne pas contourner par émission unitaire, marqueurs, import ou routes internes. list_annual_receipt_groupings lit les documents annuels du catalogue pour cet abonnement et cette année en réadmettant toutes les sources ; les inaccessibles sont omis. scanComplete désigne seulement ce scan borné des documents autorisés, jamais un historique prestataire complet ni l’absence d’opération en cours. Montants/devises historiques restent enregistrés, y compris null. Aucune génération, écriture de groupe, modification fiscale, requête prestataire ou email. L’accès PDF est séparé ; présence ne prouve ni capture, règlement bancaire, validité juridique ni livraison. Seul year est accepté, sans corps GET.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read",
    "abonnements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "year",
  "in": "query",
  "required": true,
  "schema": {
    "type": "integer",
    "minimum": 1000,
    "maximum": 9999
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu annuel autorisé ou reçus annuels enregistrés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/AnnualReceiptGroupingPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID/année invalide ou requête/corps inconnu."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Droits actuels requis manquants."
}
```

#### HTTP 404

```json
{
  "description": "Abonnement ou source absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Historique/devise/instantané annuel non prouvé, aucun candidat admis ou borne dépassée ; demander son propriétaire sans total tronqué ni repli d’émission."
}
```

#### HTTP 500

```json
{
  "description": "Lecture indisponible ; aucune écriture métier tentée."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read",
    "abonnements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /abonnements/{id}/fiscal-groupings

Lire les regroupements fiscaux annuels existants autorisés

`list_annual_receipt_groupings`

Requiert receipts:read ET paiements:read ET abonnements:read explicitement attribués. Ces lectures annuelles concernent l’UUID d’un abonnement existant, pas un UUID de paiement/document ni un groupe libre. Fournir l’année documentaire obligatoire (1000–9999) ; les règles natives de date/année de reçu s’appliquent, pas la date d’enregistrement. preview_annual_receipt_grouping suit hooks/cerfa-year : abonnement annuel existant, association FR/défaut sans noCerfa:true, paiements COMPLETED non déjà liés à un reçu fiscal et fiscalContribution(payment,{annual:true}) positive sur cette année. Les instantanés fiscaux figés priment. Contrairement à la file unitaire, ce sélecteur annuel n’exclut pas imported, finalized:false ni ignoreCerfa ; l’aperçu décrit ce sélecteur sans certification indépendante ni droit d’émettre. Tous les paiements, l’abonnement parent, contacts et cibles conservées exigent les droits actuels d’organisation/association/collecte. Seuls les historiques EUR prouvés sont admis, le propriétaire PDF annuel n’ayant pas de paramètre explicite de devise. Le scan complet est borné à 200 paiements COMPLETED ; dépassement refusé sans troncature des droits/totaux. Dates/devises/instantanés inconnus ne deviennent ni zéro ni EUR. Aucun candidat admis donne un refus de revue propriétaire, pas une preuve d’absence de document. amountMinor est la somme fiscale candidate en unités mineures EUR (5000 = 50 EUR), distincte du montant nominal et du total documentaire émis. emissionSupported:false/TARGETED_ANNUAL_OWNER_REQUIRED signifie qu’aucune commande annuelle ciblée n’est offerte actuellement ; le daemon annuel exporté est global et ne doit jamais être invoqué pour un appelant. Ne pas contourner par émission unitaire, marqueurs, import ou routes internes. list_annual_receipt_groupings lit les documents annuels du catalogue pour cet abonnement et cette année en réadmettant toutes les sources ; les inaccessibles sont omis. scanComplete désigne seulement ce scan borné des documents autorisés, jamais un historique prestataire complet ni l’absence d’opération en cours. Montants/devises historiques restent enregistrés, y compris null. Aucune génération, écriture de groupe, modification fiscale, requête prestataire ou email. L’accès PDF est séparé ; présence ne prouve ni capture, règlement bancaire, validité juridique ni livraison. Seul year est accepté, sans corps GET.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read",
    "abonnements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "year",
  "in": "query",
  "required": true,
  "schema": {
    "type": "integer",
    "minimum": 1000,
    "maximum": 9999
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu annuel autorisé ou reçus annuels enregistrés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/AnnualReceiptGroupingRecords"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID/année invalide ou requête/corps inconnu."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Droits actuels requis manquants."
}
```

#### HTTP 404

```json
{
  "description": "Abonnement ou source absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Historique/devise/instantané annuel non prouvé, aucun candidat admis ou borne dépassée ; demander son propriétaire sans total tronqué ni repli d’émission."
}
```

#### HTTP 500

```json
{
  "description": "Lecture indisponible ; aucune écriture métier tentée."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read",
    "abonnements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/cancellation-preview

Prévisualiser l’annulation d’un reçu exact

`preview_receipt_cancellation`

Requiert receipts:cancel ET receipts:read ET paiements:read explicitement attribués, avec une demande explicite d’annuler ce document exact. Il s’agit d’une annulation documentaire, jamais d’annuler/rembourser le paiement, modifier la facturation ou corriger le montant fiscal. Appeler d’abord preview_receipt_cancellation avec kind et l’UUID documentaire du catalogue ; cet aperçu est en lecture seule. Seul un document local unitaire RECORDED actuellement autorisé, lié à un paiement exact, est admis. Groupes, annuels, externes, documents masqués et anciens rattachements d’annulation nécessitent leur propriétaire. Le fiscal exige en plus l’instantané unitaire complet lu par le daemon d’annulation, avec montant/devise documentaire total cohérents et date stockée prise en charge ; les instantanés partiels/absents sont refusés car le daemon lit le montant total du paiement. Fournir exactement expectedRevision, une idempotencyKey stable et reason (3–500 caractères) à request_receipt_cancellation. Journal durable et réservation par document précèdent l’annulation inline équivalente au propriétaire natif : marquer l’original supprimé avec son motif, détacher sa référence exacte du paiement et bloquer uniquement sa file documentaire pour empêcher un remplacement automatique. État financier, montants, association, facturation et partage fiscal figé sont conservés. Le marqueur fiscal peut ensuite être traité par le daemon natif de document/email d’annulation ; aucun daemon global, PDF ou mailer n’est appelé ici. QUEUED acquitte les marqueurs de demande, sans affirmer PDF d’annulation, notification ni remplacement. Un résultat multi-document partiel est UNCERTAIN, jamais rejoué automatiquement. Après doute, lire get_receipt_cancellation_request avec l’UUID initial et le même principal/organisation. Ne pas changer de clé, réinitialiser les exclusions ou appeler l’interne. Le statut réadmet le paiement source figé et peut retourner les métadonnées de l’original et du document courant de remplacement. replacementRelation CURRENT_PAYMENT_DOCUMENT est une référence courante observée, pas une preuve de chaîne juridique de remplacement. Un original/remplacement null peut refléter des droits indisponibles ou aucune référence observée ; il ne permet aucune réémission. Aucune correction de montant/identité ni remplacement automatique n’est exposé. Champs/paramètres inconnus et corps GET refusés ; aucune certification de règlement bancaire, capture, validité juridique ou livraison email.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu d’annulation observé ou demande enregistrée ; lire state et les documents observés séparément.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, motif, corps ou paramètres invalides."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Document, source ou demande absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou historique d’annulation non pris en charge ; aucune mutation forcée ni réémission."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal durable de demande indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /receipts/{kind}/{id}/cancellation-requests

Demander une annulation documentaire tracée

`request_receipt_cancellation`

Requiert receipts:cancel ET receipts:read ET paiements:read explicitement attribués, avec une demande explicite d’annuler ce document exact. Il s’agit d’une annulation documentaire, jamais d’annuler/rembourser le paiement, modifier la facturation ou corriger le montant fiscal. Appeler d’abord preview_receipt_cancellation avec kind et l’UUID documentaire du catalogue ; cet aperçu est en lecture seule. Seul un document local unitaire RECORDED actuellement autorisé, lié à un paiement exact, est admis. Groupes, annuels, externes, documents masqués et anciens rattachements d’annulation nécessitent leur propriétaire. Le fiscal exige en plus l’instantané unitaire complet lu par le daemon d’annulation, avec montant/devise documentaire total cohérents et date stockée prise en charge ; les instantanés partiels/absents sont refusés car le daemon lit le montant total du paiement. Fournir exactement expectedRevision, une idempotencyKey stable et reason (3–500 caractères) à request_receipt_cancellation. Journal durable et réservation par document précèdent l’annulation inline équivalente au propriétaire natif : marquer l’original supprimé avec son motif, détacher sa référence exacte du paiement et bloquer uniquement sa file documentaire pour empêcher un remplacement automatique. État financier, montants, association, facturation et partage fiscal figé sont conservés. Le marqueur fiscal peut ensuite être traité par le daemon natif de document/email d’annulation ; aucun daemon global, PDF ou mailer n’est appelé ici. QUEUED acquitte les marqueurs de demande, sans affirmer PDF d’annulation, notification ni remplacement. Un résultat multi-document partiel est UNCERTAIN, jamais rejoué automatiquement. Après doute, lire get_receipt_cancellation_request avec l’UUID initial et le même principal/organisation. Ne pas changer de clé, réinitialiser les exclusions ou appeler l’interne. Le statut réadmet le paiement source figé et peut retourner les métadonnées de l’original et du document courant de remplacement. replacementRelation CURRENT_PAYMENT_DOCUMENT est une référence courante observée, pas une preuve de chaîne juridique de remplacement. Un original/remplacement null peut refléter des droits indisponibles ou aucune référence observée ; il ne permet aucune réémission. Aucune correction de montant/identité ni remplacement automatique n’est exposé. Champs/paramètres inconnus et corps GET refusés ; aucune certification de règlement bancaire, capture, validité juridique ou livraison email.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "reason": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "reason"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu d’annulation observé ou demande enregistrée ; lire state et les documents observés séparément.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, motif, corps ou paramètres invalides."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Document, source ou demande absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou historique d’annulation non pris en charge ; aucune mutation forcée ni réémission."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal durable de demande indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-cancellation-requests/{requestId}

Lire l’annulation et la référence actuelle de remplacement

`get_receipt_cancellation_request`

Requiert receipts:cancel ET receipts:read ET paiements:read explicitement attribués, avec une demande explicite d’annuler ce document exact. Il s’agit d’une annulation documentaire, jamais d’annuler/rembourser le paiement, modifier la facturation ou corriger le montant fiscal. Appeler d’abord preview_receipt_cancellation avec kind et l’UUID documentaire du catalogue ; cet aperçu est en lecture seule. Seul un document local unitaire RECORDED actuellement autorisé, lié à un paiement exact, est admis. Groupes, annuels, externes, documents masqués et anciens rattachements d’annulation nécessitent leur propriétaire. Le fiscal exige en plus l’instantané unitaire complet lu par le daemon d’annulation, avec montant/devise documentaire total cohérents et date stockée prise en charge ; les instantanés partiels/absents sont refusés car le daemon lit le montant total du paiement. Fournir exactement expectedRevision, une idempotencyKey stable et reason (3–500 caractères) à request_receipt_cancellation. Journal durable et réservation par document précèdent l’annulation inline équivalente au propriétaire natif : marquer l’original supprimé avec son motif, détacher sa référence exacte du paiement et bloquer uniquement sa file documentaire pour empêcher un remplacement automatique. État financier, montants, association, facturation et partage fiscal figé sont conservés. Le marqueur fiscal peut ensuite être traité par le daemon natif de document/email d’annulation ; aucun daemon global, PDF ou mailer n’est appelé ici. QUEUED acquitte les marqueurs de demande, sans affirmer PDF d’annulation, notification ni remplacement. Un résultat multi-document partiel est UNCERTAIN, jamais rejoué automatiquement. Après doute, lire get_receipt_cancellation_request avec l’UUID initial et le même principal/organisation. Ne pas changer de clé, réinitialiser les exclusions ou appeler l’interne. Le statut réadmet le paiement source figé et peut retourner les métadonnées de l’original et du document courant de remplacement. replacementRelation CURRENT_PAYMENT_DOCUMENT est une référence courante observée, pas une preuve de chaîne juridique de remplacement. Un original/remplacement null peut refléter des droits indisponibles ou aucune référence observée ; il ne permet aucune réémission. Aucune correction de montant/identité ni remplacement automatique n’est exposé. Champs/paramètres inconnus et corps GET refusés ; aucune certification de règlement bancaire, capture, validité juridique ou livraison email.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:cancel",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu d’annulation observé ou demande enregistrée ; lire state et les documents observés séparément.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptCancellationRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, motif, corps ou paramètres invalides."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Document, source ou demande absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou historique d’annulation non pris en charge ; aucune mutation forcée ni réémission."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal durable de demande indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:cancel",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/delivery-preview

Prévisualiser le renvoi au destinataire documentaire prouvé

`preview_receipt_delivery`

Requiert receipts:send ET receipts:read ET paiements:read explicitement attribués. Appeler d’abord preview_receipt_delivery avec kind et l’UUID documentaire du catalogue, distinct d’un UUID de paiement/abonnement. L’aperçu donne un destinataire masqué et expectedRevision ; il n’envoie aucun mail et n’écrit rien. Seul un original local RECORDED avec montant/devise/numéro documentaires connus et PDF existant utilisable est admis. Le destinataire documentaire enregistré doit correspondre à tous les paiements contributeurs actuels et, pour l’annuel, à l’abonnement actuel. Une destination absente, modifiée ou ambiguë est refusée ; aucune destination libre n’est acceptée. Les originaux prestataires nécessitent leur propriétaire sûr et ne sont pas récupérés. Transmettre ensuite exactement expectedRevision avec une idempotencyKey stable à request_receipt_delivery. Droits, sources, original et destinataire sont revérifiés avant journal/réservation durables et outbox idempotente native mailer.sendMailSystem. L’email contient le lien natif Unisoft du document original, sans nouveau PDF ni numéro ; l’outil ne retourne aucune URL publique/prestataire ni identifiant et ne joint pas de PDF. QUEUED acquitte seulement un email enregistré en file, jamais SENT ni DELIVERED. Après perte de réponse, lire get_receipt_delivery_request avec l’UUID initial, le même principal API et la même organisation. PENDING/UNCERTAIN ne permet aucun rejeu automatique, nouvelle clé/principal ou route interne. Une seule demande de renvoi externe est admise par document ; toute suivante nécessite son propriétaire. La lecture de statut n’envoie rien et n’interroge aucun prestataire. Un reçu et son montant en unités mineures (5000 eur = 50 EUR) sont documentaires, sans preuve de validité juridique, capture, règlement bancaire ou livraison. Aucune génération, annulation, mutation de paiement ou récupération prestataire. Champs/paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu de renvoi observé ou demande email enregistrée ; lire state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée invalide ou inconnue."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source/demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Original, destinataire, révision ou historique nécessitant son propriétaire ; aucun repli sur une adresse libre ou régénération."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Configuration de renvoi ou journal durable indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /receipts/{kind}/{id}/delivery-requests

Mettre en file l’email d’un reçu existant sans réémission

`request_receipt_delivery`

Requiert receipts:send ET receipts:read ET paiements:read explicitement attribués. Appeler d’abord preview_receipt_delivery avec kind et l’UUID documentaire du catalogue, distinct d’un UUID de paiement/abonnement. L’aperçu donne un destinataire masqué et expectedRevision ; il n’envoie aucun mail et n’écrit rien. Seul un original local RECORDED avec montant/devise/numéro documentaires connus et PDF existant utilisable est admis. Le destinataire documentaire enregistré doit correspondre à tous les paiements contributeurs actuels et, pour l’annuel, à l’abonnement actuel. Une destination absente, modifiée ou ambiguë est refusée ; aucune destination libre n’est acceptée. Les originaux prestataires nécessitent leur propriétaire sûr et ne sont pas récupérés. Transmettre ensuite exactement expectedRevision avec une idempotencyKey stable à request_receipt_delivery. Droits, sources, original et destinataire sont revérifiés avant journal/réservation durables et outbox idempotente native mailer.sendMailSystem. L’email contient le lien natif Unisoft du document original, sans nouveau PDF ni numéro ; l’outil ne retourne aucune URL publique/prestataire ni identifiant et ne joint pas de PDF. QUEUED acquitte seulement un email enregistré en file, jamais SENT ni DELIVERED. Après perte de réponse, lire get_receipt_delivery_request avec l’UUID initial, le même principal API et la même organisation. PENDING/UNCERTAIN ne permet aucun rejeu automatique, nouvelle clé/principal ou route interne. Une seule demande de renvoi externe est admise par document ; toute suivante nécessite son propriétaire. La lecture de statut n’envoie rien et n’interroge aucun prestataire. Un reçu et son montant en unités mineures (5000 eur = 50 EUR) sont documentaires, sans preuve de validité juridique, capture, règlement bancaire ou livraison. Aucune génération, annulation, mutation de paiement ou récupération prestataire. Champs/paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu de renvoi observé ou demande email enregistrée ; lire state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée invalide ou inconnue."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source/demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Original, destinataire, révision ou historique nécessitant son propriétaire ; aucun repli sur une adresse libre ou régénération."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Configuration de renvoi ou journal durable indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-delivery-requests/{requestId}

Lire une demande de renvoi sans nouvel envoi

`get_receipt_delivery_request`

Requiert receipts:send ET receipts:read ET paiements:read explicitement attribués. Appeler d’abord preview_receipt_delivery avec kind et l’UUID documentaire du catalogue, distinct d’un UUID de paiement/abonnement. L’aperçu donne un destinataire masqué et expectedRevision ; il n’envoie aucun mail et n’écrit rien. Seul un original local RECORDED avec montant/devise/numéro documentaires connus et PDF existant utilisable est admis. Le destinataire documentaire enregistré doit correspondre à tous les paiements contributeurs actuels et, pour l’annuel, à l’abonnement actuel. Une destination absente, modifiée ou ambiguë est refusée ; aucune destination libre n’est acceptée. Les originaux prestataires nécessitent leur propriétaire sûr et ne sont pas récupérés. Transmettre ensuite exactement expectedRevision avec une idempotencyKey stable à request_receipt_delivery. Droits, sources, original et destinataire sont revérifiés avant journal/réservation durables et outbox idempotente native mailer.sendMailSystem. L’email contient le lien natif Unisoft du document original, sans nouveau PDF ni numéro ; l’outil ne retourne aucune URL publique/prestataire ni identifiant et ne joint pas de PDF. QUEUED acquitte seulement un email enregistré en file, jamais SENT ni DELIVERED. Après perte de réponse, lire get_receipt_delivery_request avec l’UUID initial, le même principal API et la même organisation. PENDING/UNCERTAIN ne permet aucun rejeu automatique, nouvelle clé/principal ou route interne. Une seule demande de renvoi externe est admise par document ; toute suivante nécessite son propriétaire. La lecture de statut n’envoie rien et n’interroge aucun prestataire. Un reçu et son montant en unités mineures (5000 eur = 50 EUR) sont documentaires, sans preuve de validité juridique, capture, règlement bancaire ou livraison. Aucune génération, annulation, mutation de paiement ou récupération prestataire. Champs/paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:send",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu de renvoi observé ou demande email enregistrée ; lire state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptDeliveryRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée invalide ou inconnue."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites actuels manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source/demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Original, destinataire, révision ou historique nécessitant son propriétaire ; aucun repli sur une adresse libre ou régénération."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; lire la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Configuration de renvoi ou journal durable indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:send",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/provider-access

Lire l’accès vérifié à un original KESHER natif

`get_provider_receipt_access`

Requiert receipts:read ET paiements:read. Accès en lecture seule à l’original KESHER exact, limité aux paiements natifs KESHER/KESHER.BIT et à un document KESHER unitaire RECORDED actuellement autorisé. Seuls les paiements COMPLETED non importés, sans état de remboursement ni part fiscale mixte, avec automaticDocuments:true, sont admis. Hors carte, annuels, groupes et autres prestataires restent non pris en charge. Le propriétaire natif KesherDocuments.validatePayment et verifiedDocument/GetTranData vérifie configuration actuelle organisation/association, projet, corrélation de transaction, montant/devise et référence du document live unique ; ref doit correspondre exactement à l’original enregistré. Aucune génération, réconciliation, préparation/complétion d’opération, synchronisation, mutation de paiement ni mail. Identifiants prestataire, transactions et URL fournisseur ne sont jamais retournés. get_provider_receipt_access retourne métadonnées et chemin REST provider-pdf authentifié de même origine, pas un lien de partage public/signé. VERIFIED_PROVIDER_REFERENCE vérifie la référence ; pdfAvailability:NOT_CHECKED ne promet pas un PDF utilisable. Effectuer le GET sur la même origine/environnement API de confiance avec les mêmes identifiants d’en-tête, jamais dans l’URL. Le binaire répète les contrôles et télécharge uniquement l’URL HTTPS fraîchement vérifiée sur les hôtes natifs autorisés, sans redirection ni port non standard, avec délai de 15 secondes/plafond de 25 Mio et signature PDF. Aucune URL stockée arbitraire n’est récupérée. Le transport natif prestataire est lui-même une lecture bornée sans redirection. 409 signale original non pris en charge/non prouvé ou source modifiée ; 503 signale lecture prestataire/configuration/PDF indisponible, sans effet métier. Ne pas émettre/régénérer pour réessayer l’accès. Montants inconnus restent null ; référence/PDF ou COMPLETED ne prouve ni validité juridique, capture ou règlement bancaire. Paramètres inconnus et corps GET refusés. Utiliser download_provider_receipt_pdf via le MCP pour récupérer le fichier original privé.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Référence prestataire vérifiée et instructions d’accès authentifié ; PDF non encore contrôlé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptProviderAccess"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Kind/UUID invalide ou entrée de lecture inattendue."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Droits actuels requis manquants."
}
```

#### HTTP 404

```json
{
  "description": "Original/source actuel absent, masqué, incohérent ou hors des droits."
}
```

#### HTTP 409

```json
{
  "description": "Original prestataire non pris en charge, non prouvé ou source modifiée."
}
```

#### HTTP 500

```json
{
  "description": "Lecture indisponible ; aucun effet métier."
}
```

#### HTTP 503

```json
{
  "description": "Lecture sûre prestataire/configuration/PDF indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /receipts/{kind}/{id}/provider-pdf

Télécharger le PDF original KESHER natif vérifié

`download_provider_receipt_pdf`

Requiert receipts:read ET paiements:read. Accès en lecture seule à l’original KESHER exact, limité aux paiements natifs KESHER/KESHER.BIT et à un document KESHER unitaire RECORDED actuellement autorisé. Seuls les paiements COMPLETED non importés, sans état de remboursement ni part fiscale mixte, avec automaticDocuments:true, sont admis. Hors carte, annuels, groupes et autres prestataires restent non pris en charge. Le propriétaire natif KesherDocuments.validatePayment et verifiedDocument/GetTranData vérifie configuration actuelle organisation/association, projet, corrélation de transaction, montant/devise et référence du document live unique ; ref doit correspondre exactement à l’original enregistré. Aucune génération, réconciliation, préparation/complétion d’opération, synchronisation, mutation de paiement ni mail. Identifiants prestataire, transactions et URL fournisseur ne sont jamais retournés. get_provider_receipt_access retourne métadonnées et chemin REST provider-pdf authentifié de même origine, pas un lien de partage public/signé. VERIFIED_PROVIDER_REFERENCE vérifie la référence ; pdfAvailability:NOT_CHECKED ne promet pas un PDF utilisable. Effectuer le GET sur la même origine/environnement API de confiance avec les mêmes identifiants d’en-tête, jamais dans l’URL. Le binaire répète les contrôles et télécharge uniquement l’URL HTTPS fraîchement vérifiée sur les hôtes natifs autorisés, sans redirection ni port non standard, avec délai de 15 secondes/plafond de 25 Mio et signature PDF. Aucune URL stockée arbitraire n’est récupérée. Le transport natif prestataire est lui-même une lecture bornée sans redirection. 409 signale original non pris en charge/non prouvé ou source modifiée ; 503 signale lecture prestataire/configuration/PDF indisponible, sans effet métier. Ne pas émettre/régénérer pour réessayer l’accès. Montants inconnus restent null ; référence/PDF ou COMPLETED ne prouve ni validité juridique, capture ou règlement bancaire. Paramètres inconnus et corps GET refusés.

Le MCP renvoie le fichier privé réel dans une ressource embarquée avec son type MIME et son blob base64, ainsi que filename, byteLength et le SHA-256 des octets décodés. Utiliser la capacité fichiers de l’hôte pour enregistrer ou joindre ces octets sous le nom renvoyé et vérifier leur taille et leur SHA-256. L’URI unisoft identifie uniquement cette réponse. Elle ne constitue ni une URL publique ni une référence de téléchargement réutilisable. Fournir le fichier au destinataire autorisé, sans recopier le blob dans le texte du chat, publier un document financier ou inventer une URL de partage. Le propriétaire REST authentifié recontrôle l’organisation, les permissions et toutes les sources ou preuves d’export requises à chaque appel. REST conserve sa réponse binaire. Le fichier prouve uniquement la récupération de ces octets. Il ne prouve ni règlement bancaire, ni validité juridique du document, ni remise à un destinataire.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:read",
  "additional": [
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "kind",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "RECEIPT",
      "FISCAL_RECEIPT"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Octets du PDF original prestataire vérifié existant, 25 Mio maximum.",
  "content": {
    "application/pdf": {
      "schema": {
        "type": "string",
        "format": "binary"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Kind/UUID invalide ou entrée de lecture inattendue."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Droits actuels requis manquants."
}
```

#### HTTP 404

```json
{
  "description": "Original/source actuel absent, masqué, incohérent ou hors des droits."
}
```

#### HTTP 409

```json
{
  "description": "Original prestataire non pris en charge, non prouvé ou source modifiée."
}
```

#### HTTP 500

```json
{
  "description": "Lecture indisponible ; aucun effet métier."
}
```

#### HTTP 503

```json
{
  "description": "Lecture sûre prestataire/configuration/PDF indisponible."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:read",
  "x-unisoft-additional-scopes": [
    "paiements:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-file": {
    "mimeType": "application/pdf",
    "maxBytes": 26214400
  }
}
```

## GET /paiements/{id}/fiscal-receipt-preview

Consulter l’éligibilité native au reçu fiscal

`preview_fiscal_receipt`

Requiert receipts:issue ET receipts:read ET paiements:read explicitement attribués. Reçu ordinaire et reçu fiscal sont distincts ; paymentId/id est l’UUID du paiement, requestId l’UUID d’idempotence initial et receipt.id un UUID documentaire. Appeler d’abord preview_fiscal_receipt et exiger eligible:true ; transmettre exactement expectedRevision avec une idempotencyKey stable à request_fiscal_receipt. L’éligibilité suit le sélecteur fiscal natif et getReceiptAmounts/fiscalContribution, avec la politique figée ; aucun choix cerfa, partage fiscal ni qualification juridique n’est créé. Seuls les paiements unitaires COMPLETED actuellement autorisés, déjà cerfa:true, avec part fiscale positive, devise/date connues, émetteur exact et facturation complète sont pris en charge. FR, US, UK, CA, DE, CH et le défaut natif suivent le modèle configuré du propriétaire, pas une certification fiscale indépendante. Paiements annuels, NEDARIM, SEPA_XML, formats externes, imports, remboursements, documents existants, exclusions et anciens échecs fiscaux nécessitent leur propriétaire. L’aperçu est une observation en lecture seule pouvant devenir périmée. Le POST journalise et réserve durablement le paiement avant un seul receipt_queue.reset(kind=cerfa) avec organisation et CAS BSON exact. Le traitement natif peut ensuite émettre un document numéroté et envoyer son email habituel sauf dontSendReceipt ; QUEUED acquitte uniquement la file, jamais ISSUED ni DELIVERED. Le statut réadmet les droits et peut ajouter séparément les métadonnées actuelles du reçu enregistré. PENDING/UNCERTAIN, perte de réponse ou PDF absent ne permet aucun rejeu automatique, nouvelle clé ni substitution d’identifiants. Consulter la demande d’origine avec le même principal et la même organisation. receipt:null ne prouve aucune absence d’émission en cours. Les montants sont en unités mineures (5000 eur = 50 EUR), sans nouvel encaissement ni preuve de validité juridique, capture ou règlement bancaire. Aucun générateur, prestataire, daemon ou mailer n’est appelé directement. Paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Éligibilité observée ou demande enregistrée ; lire l’état métier.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID ou corps invalide, paramètres/champs inconnus."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits actuels requis manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source ou demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou éligibilité/historique fiscal non pris en charge ; demander son propriétaire sans modifier les marqueurs fiscaux."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; consulter la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal indisponible ; conserver la clé initiale sans rejeu."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements/{id}/fiscal-receipt-requests

Demander un reçu fiscal éligible par sa file

`request_fiscal_receipt`

Requiert receipts:issue ET receipts:read ET paiements:read explicitement attribués. Reçu ordinaire et reçu fiscal sont distincts ; paymentId/id est l’UUID du paiement, requestId l’UUID d’idempotence initial et receipt.id un UUID documentaire. Appeler d’abord preview_fiscal_receipt et exiger eligible:true ; transmettre exactement expectedRevision avec une idempotencyKey stable à request_fiscal_receipt. L’éligibilité suit le sélecteur fiscal natif et getReceiptAmounts/fiscalContribution, avec la politique figée ; aucun choix cerfa, partage fiscal ni qualification juridique n’est créé. Seuls les paiements unitaires COMPLETED actuellement autorisés, déjà cerfa:true, avec part fiscale positive, devise/date connues, émetteur exact et facturation complète sont pris en charge. FR, US, UK, CA, DE, CH et le défaut natif suivent le modèle configuré du propriétaire, pas une certification fiscale indépendante. Paiements annuels, NEDARIM, SEPA_XML, formats externes, imports, remboursements, documents existants, exclusions et anciens échecs fiscaux nécessitent leur propriétaire. L’aperçu est une observation en lecture seule pouvant devenir périmée. Le POST journalise et réserve durablement le paiement avant un seul receipt_queue.reset(kind=cerfa) avec organisation et CAS BSON exact. Le traitement natif peut ensuite émettre un document numéroté et envoyer son email habituel sauf dontSendReceipt ; QUEUED acquitte uniquement la file, jamais ISSUED ni DELIVERED. Le statut réadmet les droits et peut ajouter séparément les métadonnées actuelles du reçu enregistré. PENDING/UNCERTAIN, perte de réponse ou PDF absent ne permet aucun rejeu automatique, nouvelle clé ni substitution d’identifiants. Consulter la demande d’origine avec le même principal et la même organisation. receipt:null ne prouve aucune absence d’émission en cours. Les montants sont en unités mineures (5000 eur = 50 EUR), sans nouvel encaissement ni preuve de validité juridique, capture ou règlement bancaire. Aucun générateur, prestataire, daemon ou mailer n’est appelé directement. Paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Éligibilité observée ou demande enregistrée ; lire l’état métier.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID ou corps invalide, paramètres/champs inconnus."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits actuels requis manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source ou demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou éligibilité/historique fiscal non pris en charge ; demander son propriétaire sans modifier les marqueurs fiscaux."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; consulter la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal indisponible ; conserver la clé initiale sans rejeu."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /fiscal-receipt-requests/{requestId}

Lire le statut d’une demande de reçu fiscal sans rejeu

`get_fiscal_receipt_request`

Requiert receipts:issue ET receipts:read ET paiements:read explicitement attribués. Reçu ordinaire et reçu fiscal sont distincts ; paymentId/id est l’UUID du paiement, requestId l’UUID d’idempotence initial et receipt.id un UUID documentaire. Appeler d’abord preview_fiscal_receipt et exiger eligible:true ; transmettre exactement expectedRevision avec une idempotencyKey stable à request_fiscal_receipt. L’éligibilité suit le sélecteur fiscal natif et getReceiptAmounts/fiscalContribution, avec la politique figée ; aucun choix cerfa, partage fiscal ni qualification juridique n’est créé. Seuls les paiements unitaires COMPLETED actuellement autorisés, déjà cerfa:true, avec part fiscale positive, devise/date connues, émetteur exact et facturation complète sont pris en charge. FR, US, UK, CA, DE, CH et le défaut natif suivent le modèle configuré du propriétaire, pas une certification fiscale indépendante. Paiements annuels, NEDARIM, SEPA_XML, formats externes, imports, remboursements, documents existants, exclusions et anciens échecs fiscaux nécessitent leur propriétaire. L’aperçu est une observation en lecture seule pouvant devenir périmée. Le POST journalise et réserve durablement le paiement avant un seul receipt_queue.reset(kind=cerfa) avec organisation et CAS BSON exact. Le traitement natif peut ensuite émettre un document numéroté et envoyer son email habituel sauf dontSendReceipt ; QUEUED acquitte uniquement la file, jamais ISSUED ni DELIVERED. Le statut réadmet les droits et peut ajouter séparément les métadonnées actuelles du reçu enregistré. PENDING/UNCERTAIN, perte de réponse ou PDF absent ne permet aucun rejeu automatique, nouvelle clé ni substitution d’identifiants. Consulter la demande d’origine avec le même principal et la même organisation. receipt:null ne prouve aucune absence d’émission en cours. Les montants sont en unités mineures (5000 eur = 50 EUR), sans nouvel encaissement ni preuve de validité juridique, capture ou règlement bancaire. Aucun générateur, prestataire, daemon ou mailer n’est appelé directement. Paramètres inconnus et corps GET refusés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Éligibilité observée ou demande enregistrée ; lire l’état métier.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/FiscalReceiptRequest"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID ou corps invalide, paramètres/champs inconnus."
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise."
}
```

#### HTTP 403

```json
{
  "description": "Les droits actuels requis manquent."
}
```

#### HTTP 404

```json
{
  "description": "Source ou demande absente, incohérente ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "Aperçu périmé, conflit d’idempotence ou éligibilité/historique fiscal non pris en charge ; demander son propriétaire sans modifier les marqueurs fiscaux."
}
```

#### HTTP 500

```json
{
  "description": "Résultat inconnu ; consulter la demande initiale sans rejeu."
}
```

#### HTTP 503

```json
{
  "description": "Journal indisponible ; conserver la clé initiale sans rejeu."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /paiements/{id}/receipt-requests

Demander la première admission en file d’un reçu ordinaire

`request_ordinary_receipt`

Requiert l’attribution explicite receipts:issue ET receipts:read ET paiements:read. Il s’agit d’une demande à la file existante des reçus ordinaires, pas d’une émission synchrone. L’UUID du paiement désigne la source ; requestId est l’UUID d’idempotence initial et l’UUID documentaire est distinct. Seule la première admission d’un paiement unitaire COMPLETED actuellement autorisé, avec association exacte, part ordinaire positive, devise/date stockées valides et identité de facturation imprimée complète est prise en charge. Les formats locaux FR, GR et CH, ou le format natif par défaut, sont admis ; NEDARIM, SEPA_XML, formats documentaires externes, imports, historiques de remboursement, groupes, exclusions manuelles, documents existants et anciens échecs nécessitent leur propriétaire et sont refusés. Les instantanés fiscaux font autorité ; la commande ne change ni montant, devise, association, choix fiscal, facturation, finalisation ni préférences de notification. Le traitement natif peut ensuite produire un document numéroté et envoyer son email habituel sauf si la préférence stockée dontSendReceipt l’empêche. QUEUED signifie admission en file acquittée, jamais ISSUED, email livré, capture ou règlement bancaire. Un journal durable par principal/organisation et une réservation du paiement sont acquis avant l’unique appel au reset natif. Une autre clé ou un autre principal ne peut pas relancer ce paiement. PENDING/UNCERTAIN, y compris après perte de réponse ou d’écriture finale du journal, ne permet jamais de rejeu automatique ; consulter le statut de la demande initiale. Aucun prestataire, moteur PDF ou mailer n’est appelé directement par ces points d’accès. Les identifiants, restrictions de collecte et toutes les références sources conservées sont réadmis ; les instantanés historiques ne fournissent aucun droit.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du paiement source actuel, distinct d’un UUID documentaire ou d’abonnement."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid",
            "description": "UUID stable fourni par l’appelant pour cette demande exacte de reçu ordinaire. Le réutiliser uniquement pour obtenir le résultat enregistré ; ne jamais le changer après une incertitude."
          }
        },
        "required": [
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Demande de file enregistrée ; lire state et reason, pas seulement success:true.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptQueueRequestResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID/corps invalide, champs ou paramètres inconnus, ou corps de lecture non vide. Envoyer uniquement idempotencyKey dans le corps POST et aucun paramètre de requête."
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites requis ou l’accès actuel du principal manquent ; ne pas substituer d’identifiants."
}
```

#### HTTP 404

```json
{
  "description": "La demande, le paiement, l’association ou une source conservée est absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "IDEMPOTENCY_CONFLICT ou éligibilité/historique documentaire nécessitant son propriétaire. Ne pas changer les marqueurs, choix fiscaux ou clés de demande pour contourner le refus."
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun résultat ne peut être déduit. Consulter la même clé de demande avant toute autre action."
}
```

#### HTTP 503

```json
{
  "description": "RECEIPT_JOURNAL_UNAVAILABLE ou RECEIPT_JOURNAL_INVALID : le journal de demande est indisponible ; aucun reset sans journal n’est tenté. Conserver la clé de demande initiale."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /receipt-requests/{requestId}

Lire une demande de file de reçu ordinaire sans rejeu

`get_ordinary_receipt_request`

Requiert l’attribution explicite receipts:issue ET receipts:read ET paiements:read. Il s’agit d’une demande à la file existante des reçus ordinaires, pas d’une émission synchrone. L’UUID du paiement désigne la source ; requestId est l’UUID d’idempotence initial et l’UUID documentaire est distinct. Seule la première admission d’un paiement unitaire COMPLETED actuellement autorisé, avec association exacte, part ordinaire positive, devise/date stockées valides et identité de facturation imprimée complète est prise en charge. Les formats locaux FR, GR et CH, ou le format natif par défaut, sont admis ; NEDARIM, SEPA_XML, formats documentaires externes, imports, historiques de remboursement, groupes, exclusions manuelles, documents existants et anciens échecs nécessitent leur propriétaire et sont refusés. Les instantanés fiscaux font autorité ; la commande ne change ni montant, devise, association, choix fiscal, facturation, finalisation ni préférences de notification. Le traitement natif peut ensuite produire un document numéroté et envoyer son email habituel sauf si la préférence stockée dontSendReceipt l’empêche. QUEUED signifie admission en file acquittée, jamais ISSUED, email livré, capture ou règlement bancaire. Un journal durable par principal/organisation et une réservation du paiement sont acquis avant l’unique appel au reset natif. Une autre clé ou un autre principal ne peut pas relancer ce paiement. PENDING/UNCERTAIN, y compris après perte de réponse ou d’écriture finale du journal, ne permet jamais de rejeu automatique ; consulter le statut de la demande initiale. Aucun prestataire, moteur PDF ou mailer n’est appelé directement par ces points d’accès. Les identifiants, restrictions de collecte et toutes les références sources conservées sont réadmis ; les instantanés historiques ne fournissent aucun droit. Observation du journal en lecture seule pour le même principal API et la même organisation d’origine. Retourne la demande enregistrée et, lorsqu’elles sont accessibles, les métadonnées actuelles du reçu. Aucun reset, file, génération, synchronisation prestataire ou email n’est relancé. Un processus arrêté en PENDING reste non résolu ; un reçu apparaissant plus tard est observé séparément sans réécrire l’acquittement initial de la file.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "receipts:issue",
  "additional": [
    "receipts:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "requestId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID d’idempotence initial fourni à request_ordinary_receipt, avec le même principal API et la même organisation."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Demande de file enregistrée ; lire state et reason, pas seulement success:true.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReceiptQueueRequestResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID/corps invalide, champs ou paramètres inconnus, ou corps de lecture non vide. Envoyer uniquement idempotencyKey dans le corps POST et aucun paramètre de requête."
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide."
}
```

#### HTTP 403

```json
{
  "description": "Les droits explicites requis ou l’accès actuel du principal manquent ; ne pas substituer d’identifiants."
}
```

#### HTTP 404

```json
{
  "description": "La demande, le paiement, l’association ou une source conservée est absent, incohérent ou hors des droits actuels."
}
```

#### HTTP 409

```json
{
  "description": "IDEMPOTENCY_CONFLICT ou éligibilité/historique documentaire nécessitant son propriétaire. Ne pas changer les marqueurs, choix fiscaux ou clés de demande pour contourner le refus."
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun résultat ne peut être déduit. Consulter la même clé de demande avant toute autre action."
}
```

#### HTTP 503

```json
{
  "description": "RECEIPT_JOURNAL_UNAVAILABLE ou RECEIPT_JOURNAL_INVALID : le journal de demande est indisponible ; aucun reset sans journal n’est tenté. Conserver la clé de demande initiale."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "receipts:issue",
  "x-unisoft-additional-scopes": [
    "receipts:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schémas

```json
{
  "components": {
    "schemas": {
      "ReceiptCatalogResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ReceiptCatalogEntry"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "count",
              "hasMore",
              "nextCursor"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 200
              },
              "hasMore": {
                "type": "boolean",
                "description": "Vaut true lorsqu’une autre lecture bornée est possible ; ne révèle aucun total autorisé. Un lot filtré ou inaccessible peut ne renvoyer aucune entrée avec hasMore:true."
              },
              "nextCursor": {
                "type": "string",
                "nullable": true,
                "description": "Continuation opaque, dans l’ordre croissant stable de kind puis UUID du document. Conservez les mêmes filtres et poursuivez jusqu’à hasMore:false, y compris après une page vide."
              }
            }
          }
        }
      },
      "ReceiptCatalogEntry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "kind",
          "status",
          "associationId",
          "annual",
          "subscriptionId",
          "paymentIds",
          "contactIds",
          "number",
          "year",
          "recordedAt",
          "amountMinor",
          "currency"
        ],
        "description": "Métadonnées explicites d’un reçu enregistré, après réadmission de toutes ses sources actuelles. Aucune identité de facturation, snapshot, URL prestataire, configuration privée ni preuve de livraison n’est incluse.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID stable du document, distinct des identifiants de paiement et d’abonnement. À utiliser avec kind pour accéder au document."
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ],
            "description": "RECEIPT est un reçu ordinaire de recus ; FISCAL_RECEIPT est un reçu fiscal de cerfas, y compris les reçus annuels."
          },
          "status": {
            "type": "string",
            "enum": [
              "RECORDED",
              "WITHHELD",
              "UNKNOWN"
            ],
            "description": "RECORDED signifie que deleted est absent/null/false ; WITHHELD signifie deleted:true, pouvant désigner une annulation ou une publication en attente ; UNKNOWN conserve un marqueur deleted invalide. Aucun statut ne garantit livraison, disponibilité du PDF ou validité juridique."
          },
          "associationId": {
            "type": "string",
            "description": "Association émettrice actuelle autorisée, MAIN ou UUID d’association. Une association historique absente désigne MAIN ; une association secondaire inconnue n’est jamais remplacée par MAIN."
          },
          "annual": {
            "type": "boolean",
            "description": "Vaut true uniquement pour les reçus fiscaux avec cerfaYear:true. Leur champ paiement enregistré désigne l’abonnement, et non un paiement unique."
          },
          "subscriptionId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Identifiant d’abonnement annuel provenant du champ paiement du document ; null pour les documents non annuels."
          },
          "paymentIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Tous les UUID des paiements sources actuellement réadmis, triés. Les reçus annuels utilisent paiements[] ; les reçus groupés exigent le groupe actuel complet. Aucun groupe partiel ni total annuel partiel n’est renvoyé."
          },
          "contactIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Contacts distincts des paiements sources actuels, après réadmission dans la même organisation. Identifiants seuls ; les identités de facturation historiques ne sont jamais renvoyées."
          },
          "number": {
            "type": "string",
            "nullable": true,
            "maxLength": 200,
            "description": "Champ num enregistré, entier positif ou nul, rendu en texte ; null si absent ou invalide. Les références externes sont exclues car certaines donnent accès au téléchargement."
          },
          "year": {
            "type": "integer",
            "nullable": true,
            "minimum": 1,
            "maximum": 9999,
            "description": "Année documentaire enregistrée, sans déduction à partir de la date actuelle ou des dates des paiements."
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Champ datetime valide du document enregistré, normalisé en instant ISO. Il décrit l’enregistrement documentaire, sans garantir le règlement bancaire ni la livraison d’un email. Les valeurs historiques invalides ou non prises en charge restent null."
          },
          "amountMinor": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Uniquement document.amountMinor enregistré, en unités monétaires mineures : par exemple 5000 pour EUR 50. Les valeurs absentes, fractionnaires, négatives ou non sûres restent null. Aucun montant n’est recalculé depuis les paiements actuels, choix fiscaux ou snapshots."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$",
            "description": "Uniquement le champ devise valide enregistré sur le document, normalisé en minuscules. Aucun repli sur l’organisation ou le paiement ; les anciens documents annuels ou externes peuvent avoir currency:null."
          }
        }
      },
      "ReceiptAccessResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "receipt",
              "access"
            ],
            "properties": {
              "receipt": {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              "access": {
                "$ref": "#/components/schemas/ReceiptPdfAccess"
              }
            }
          }
        }
      },
      "ReceiptPdfAccess": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "reason",
          "method",
          "path",
          "requiredScope",
          "contentType",
          "filename"
        ],
        "description": "Accès à un PDF original déjà stocké. La disponibilité est contrôlée à la lecture et peut changer avant le téléchargement ; aucun document ni lien porteur de droits n’est créé.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ],
            "description": "AVAILABLE indique qu’un fichier local ordinaire avec une signature PDF vient de passer le contrôle de stockage ; pour UNAVAILABLE, consulter reason. Ce contrôle ne prouve ni règlement bancaire ni validité juridique."
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER",
              "STORAGE_NOT_CONFIGURED",
              "PDF_UNAVAILABLE",
              "PDF_INVALID",
              "PDF_TOO_LARGE",
              null
            ],
            "description": "Vaut null lorsque le PDF est disponible. EXTERNAL_ACCESS_REQUIRES_SAFE_OWNER nécessite un propriétaire de lecture du prestataire validant l’organisation, la configuration et la destination. STORAGE_NOT_CONFIGURED nécessite un répertoire de stockage configuré par un chemin absolu. PDF_UNAVAILABLE nécessite de restaurer l’original stocké ou l’accès au stockage. PDF_INVALID nécessite un original stocké valide ; PDF_TOO_LARGE dépasse la limite de 25 MiB. Ne pas régénérer, synchroniser ou émettre un document pour réessayer cette lecture."
          },
          "method": {
            "type": "string",
            "nullable": true,
            "enum": [
              "GET",
              null
            ]
          },
          "path": {
            "type": "string",
            "nullable": true,
            "description": "Lorsque le PDF est disponible, chemin relatif /integrations/v2/receipts/{kind}/{id}/pdf sur la même origine API de confiance. Effectuer un GET avec les mêmes identifiants autorisés dans Authorization ou X-API-Key, et X-Org-Id pour un accès root. Ce point d’accès exige une authentification ; ce n’est pas un lien de partage anonyme ou temporaire. Ne jamais placer les identifiants dans son URL."
          },
          "requiredScope": {
            "type": "string",
            "enum": [
              "receipts:read"
            ]
          },
          "contentType": {
            "type": "string",
            "enum": [
              "application/pdf"
            ]
          },
          "filename": {
            "type": "string",
            "description": "Nom de fichier PDF ASCII proposé, dérivé uniquement du type et de l’UUID du document."
          }
        }
      },
      "AnnualReceiptGroupingPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscriptionId",
          "associationId",
          "year",
          "paymentIds",
          "count",
          "amountMinor",
          "currency",
          "expectedRevision",
          "emissionSupported",
          "reason",
          "selection"
        ],
        "properties": {
          "subscriptionId": {
            "type": "string",
            "format": "uuid"
          },
          "associationId": {
            "type": "string"
          },
          "year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "paymentIds": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "enum": [
              "eur"
            ]
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "emissionSupported": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "TARGETED_ANNUAL_OWNER_REQUIRED"
            ]
          },
          "selection": {
            "type": "string",
            "enum": [
              "NATIVE_ANNUAL_SELECTOR"
            ]
          }
        }
      },
      "AnnualReceiptGroupingRecords": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscriptionId",
          "year",
          "receipts",
          "scanComplete",
          "coverage"
        ],
        "properties": {
          "subscriptionId": {
            "type": "string",
            "format": "uuid"
          },
          "year": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 9999
          },
          "receipts": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ReceiptCatalogEntry"
            }
          },
          "scanComplete": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "coverage": {
            "type": "string",
            "enum": [
              "CURRENT_AUTHORISED_ANNUAL_RECORDS"
            ]
          }
        }
      },
      "ReceiptCancellationPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "documentId",
          "paymentId",
          "expectedRevision",
          "operation",
          "paymentUnchanged",
          "fiscalCancellationDocument"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "operation": {
            "type": "string",
            "enum": [
              "CANCEL_DOCUMENT"
            ]
          },
          "paymentUnchanged": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "fiscalCancellationDocument": {
            "type": "string",
            "enum": [
              "NATIVE_DAEMON",
              "NOT_APPLICABLE"
            ]
          }
        }
      },
      "ReceiptCancellationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "kind",
          "documentId",
          "paymentId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          },
          "original": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          },
          "replacement": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          },
          "replacementRelation": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CURRENT_PAYMENT_DOCUMENT",
              null
            ]
          }
        }
      },
      "ReceiptDeliveryPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "documentId",
          "expectedRevision",
          "recipient",
          "amountMinor",
          "currency",
          "documentNumber",
          "delivery",
          "originalOnly"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "recipient": {
            "type": "string"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string"
          },
          "documentNumber": {
            "type": "string"
          },
          "delivery": {
            "type": "string",
            "enum": [
              "EMAIL_LINK"
            ]
          },
          "originalOnly": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "ReceiptDeliveryRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "kind",
          "documentId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "documentId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT",
              "FISCAL_RECEIPT"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "ReceiptProviderAccess": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "receipt",
          "access"
        ],
        "properties": {
          "receipt": {
            "$ref": "#/components/schemas/ReceiptCatalogEntry"
          },
          "access": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "status",
              "pdfAvailability",
              "method",
              "path",
              "requiredScopes",
              "contentType",
              "maxBytes"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "VERIFIED_PROVIDER_REFERENCE"
                ]
              },
              "pdfAvailability": {
                "type": "string",
                "enum": [
                  "NOT_CHECKED"
                ]
              },
              "method": {
                "type": "string",
                "enum": [
                  "GET"
                ]
              },
              "path": {
                "type": "string"
              },
              "requiredScopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "contentType": {
                "type": "string",
                "enum": [
                  "application/pdf"
                ]
              },
              "maxBytes": {
                "type": "integer",
                "enum": [
                  26214400
                ]
              }
            }
          }
        }
      },
      "FiscalReceiptPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "paymentId",
          "eligible",
          "reason",
          "expectedRevision",
          "amountMinor",
          "currency",
          "format"
        ],
        "properties": {
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "eligible": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1,
            "nullable": true
          },
          "currency": {
            "type": "string",
            "nullable": true
          },
          "format": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "FiscalReceiptRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "targetId",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "queueAcknowledged"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "targetId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true
          },
          "receipt": {
            "type": "object",
            "nullable": true,
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ]
          }
        }
      },
      "ReceiptQueueRequestResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ReceiptQueueRequest"
          }
        }
      },
      "ReceiptQueueRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "paymentId",
          "kind",
          "state",
          "reason",
          "requestedAt",
          "updatedAt",
          "ordinaryAmountMinor",
          "currency",
          "queueAcknowledged",
          "receipt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "paymentId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "RECEIPT"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "REJECTED",
              "UNCERTAIN"
            ],
            "description": "État du journal de demande, distinct de l’état documentaire. QUEUED acquitte uniquement l’admission dans la file native. PENDING peut inclure un travail interrompu ; UNCERTAIN ne permet jamais un rejeu."
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "description": "Motif fixe d’admission en file, de refus ou d’incertitude ; aucune erreur privée du propriétaire n’est retournée."
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ordinaryAmountMinor": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Part ordinaire admise lors de la demande, en unités monétaires mineures ; 5000 eur signifie 50 EUR. Ce n’est ni un montant documentaire émis ni une preuve de règlement bancaire."
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "pattern": "^[a-z]{3}$"
          },
          "queueAcknowledged": {
            "type": "boolean",
            "nullable": true,
            "description": "Vrai uniquement pour QUEUED, faux pour une demande REJECTED enregistrée, null pour PENDING/UNCERTAIN. Null ne prouve pas que la file soit restée inchangée."
          },
          "receipt": {
            "type": "object",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReceiptCatalogEntry"
              },
              {
                "enum": [
                  null
                ]
              }
            ],
            "nullable": true,
            "description": "Document actuellement enregistré et autorisé séparément lorsqu’il est observé par la lecture de statut, sinon null. Une valeur null ne prouve pas qu’aucune émission ne soit en cours. Son état et l’accès au PDF restent des observations distinctes."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
