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

# Promesses de don

OpenAPI 3.0.3 · API 2.0.0

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

Promesses de don : montant auquel un contact s’est engagé, honoré progressivement par des paiements (collection dettes_v2). CRUD complet et opération de génération de lien de paiement. `montant`/`reste`/`payed` sont exprimés en unités MAJEURES (PAS en centimes). Autorisations : `promesses:read`/`promesses:write`.

## Opérations

## GET /promesses

Lister les promesses de don

`list_promesses`

Autorisation requise : `promesses:read`. Liste les promesses de don de l’organisation, enrichies des champs calculés `payed`/`reste`/`status` et du nom du donateur. Exclut les promesses annulées sauf si `includeCanceled=true`. Résultats paginés, de la plus récente à la plus ancienne.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filtrer par identifiant du contact donateur."
}
```

```json
{
  "name": "typeId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filtrer par identifiant du livret/de la campagne associé(e)."
}
```

```json
{
  "name": "occasion",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filtrer par occasion (correspondance exacte)."
}
```

```json
{
  "name": "includeCanceled",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Inclure les promesses annulées (false par défaut)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Promesse"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## POST /promesses

Créer une promesse de don

`create_promesse`

Autorisation requise : `promesses:write`. Crée une promesse pour un contact de l’organisation. `montant` est exprimé en unités MAJEURES de la devise (par ex. 50 = 50 €), PAS en centimes. La devise est toujours déduite de `assoc` (MAIN par défaut) et ne peut pas être remplacée. `organisation` est imposée côté serveur.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_f851c3ded6b9eee2d078"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Promesse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MONTANT",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_MONTANT"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "promesses:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /promesses/{id}

Obtenir une promesse de don

`get_promesse`

Autorisation requise : `promesses:read`. Renvoie la promesse avec les valeurs `payed`/`reste`/`status` recalculées.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Promesse"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /promesses/{id}

Modifier une promesse de don

`update_promesse`

Autorisation requise : `promesses:write`. Modifie n’importe quel sous-ensemble des champs modifiables de la promesse. `assoc`/`devise` ne sont PAS modifiables (fixés à la création). Les champs calculés (reste/payed/status) ne sont jamais acceptés.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expectedReceiptRevision": {
            "type": "integer",
            "minimum": 0,
            "description": "Révision du reçu renvoyée lors de la dernière lecture ; permet de refuser une modification fiscale devenue obsolète."
          },
          "cerfa": {
            "type": "boolean",
            "description": "Choix du reçu fiscal applicable uniquement aux paiements futurs. Les paiements et documents existants conservent leur traitement d’origine.",
            "default": true
          },
          "contactId": {
            "type": "string"
          },
          "montant": {
            "type": "number",
            "description": "Unités majeures de la devise, > 0."
          },
          "name": {
            "type": "string"
          },
          "occasion": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "typeId": {
            "type": "string",
            "description": "Rattacher à un autre livret/une autre campagne (ou null pour détacher)."
          }
        },
        "additionalProperties": false,
        "description": "N’importe quel sous-ensemble de ces champs. `assoc` et `devise` ne sont PAS modifiables (fixés à la création). Les champs calculés (reste/payed/status) ne sont jamais acceptés."
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Promesse"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MONTANT",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_MONTANT"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND ou CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND or CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "promesses:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /promesses/{id}

Annuler une promesse de don

`delete_promesse`

Autorisation requise : `promesses:write`. Supprime la promesse de manière logique (active=false, state=CANCELED) — elle disparaît des listes actives, mais n’est jamais supprimée physiquement.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "promesses:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /promesses/{id}/payment-link

Créer ou récupérer le lien de paiement d’une promesse

`create_promesse_payment_link`

Autorisation requise : `promesses:write`. Crée ou réutilise une URL de page de paiement hébergée afin que le donateur puisse honorer sa promesse. Renvoie 409 si la promesse est annulée, déjà entièrement payée ou couverte par un abonnement actif.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/PromessePaymentLink"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PLEDGE_FULFILLED, PLEDGE_CANCELED ou PLEDGE_COVERED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "PLEDGE_FULFILLED, PLEDGE_CANCELED or PLEDGE_COVERED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "promesses:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /promesses/{id}/history

Consulter une observation du solde et l’historique enregistré d’une promesse

`get_promesse_history`

Autorisations requises : `promesses:read` ET `paiements:read`. Lecture seule : aucun calcul de cache persistant, initialisation de calendrier, synchronisation, appel au prestataire ni vérification bancaire. Renvoie le solde ACTUEL observé à cette lecture, les affectations ACTUELLES connues des paiements et uniquement les événements CREATED/EDITED/CANCELED/REACTIVATED réellement enregistrés dans le journal. Aucun snapshot de solde historique n’est disponible : le montant actuel de la promesse ne prouve ni son ancien montant ni son ancien solde. Ne pas construire une courbe de solde historique en additionnant ces lignes. Aucun événement de création, édition, remboursement ou couverture n’est déduit des champs actuels ; un paiement remboursé conserve sa date métier initiale et contribue zéro actuellement. Les montants sont en unités mineures (5000 = 50.00 EUR) ; les anciens champs dettes[].montant et _manualPayed sont convertis depuis les unités majeures. Priorité des affectations : pledgeAllocations, subscriptionAllocations, carte du calendrier d’abonnement, budgets des anciens abonnements proratisés par subscription.max, anciennes ventilations ponctuelles dettes, puis cible DETTE directe. Une carte vide explicite retire toute affectation et bloque le repli historique. Seul l’état exact COMPLETED contribue actuellement, imports compris ; REFUNDED, REFUND_PENDING et les autres états contribuent zéro, sans transition de remboursement inventée. COMPLETED est le résultat enregistré et peut précéder la capture chez certains prestataires. Le propriétaire pur arrondit globalement les contributions et plafonne le payé au montant actuellement promis ; la somme des lignes arrondies individuellement ne correspond pas nécessairement à ce plafond. Chaque paiement, abonnement et membre de ventilation nécessaire est vérifié dans l’organisation, les collectes autorisées, l’association et la devise ; un membre requis inaccessible provoque 404, un historique monétaire incohérent ou ambigu provoque 409. Les devises absentes ne sont pas devinées et aucune devise n’est convertie ni mélangée. Une association historique absente signifie MAIN. Les enregistrements supprimés logiquement sont exclus, sans constituer une annulation financière. Événements et paiements sont triés par date enregistrée DESC puis id DESC, les lignes sans date en dernier ; les affectations actuelles ne constituent pas un historique de réaffectation. Les collections sont lues séparément, sans transaction ni instantané historique. Aucun paramètre de requête ni corps non vide n’est accepté. Maximum de 2000 enregistrements par collection historique chargée et 200 membres par affectation ; un dépassement provoque PLEDGE_HISTORY_LIMIT_EXCEEDED au lieu d’un solde incomplet. La projection explicite exclut l’identité du donateur, les notes, les acteurs, les snapshots privés, les moyens de paiement réutilisables et la configuration marchande.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Identifiant de la promesse.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observation actuelle du solde, affectations actuelles connues des paiements et événements financiers enregistrés.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PledgeHistoryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, UNKNOWN_QUERY_PARAMETER ou UNEXPECTED_REQUEST_BODY. Retirer les entrées non prises en charge.",
  "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"
          }
        }
      }
    }
  }
}
```

#### 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"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE : promesses:read et paiements:read sont tous deux requis.",
  "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"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : la promesse ou un membre historique requis est absent, supprimé, étranger à l’organisation ou hors des collectes autorisées.",
  "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"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_PLEDGE_HISTORY : données monétaires historiques incomplètes ou incohérentes ; vérifier la promesse et les affectations dans Unisoft. PLEDGE_HISTORY_LIMIT_EXCEEDED : l’historique dépasse la lecture bornée et nécessite un export dédié du propriétaire.",
  "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"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR.",
  "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"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## Schémas

```json
{
  "components": {
    "schemas": {
      "Promesse": {
        "type": "object",
        "description": "Promesse de don : montant qu’un contact s’est engagé à verser et que les paiements honorent progressivement. Stockée dans dettes_v2.",
        "properties": {
          "cerfa": {
            "type": "boolean",
            "default": true,
            "description": "Choix du reçu fiscal applicable uniquement aux paiements futurs. Les paiements et documents existants conservent leur traitement d’origine."
          },
          "receiptRevision": {
            "type": "integer",
            "readOnly": true
          },
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "contact": {
            "type": "string",
            "description": "Identifiant du contact donateur."
          },
          "contactName": {
            "type": "string",
            "readOnly": true,
            "description": "Nom complet du donateur (calculé à la lecture)."
          },
          "montant": {
            "type": "number",
            "description": "Montant de la promesse en unités majeures de la devise (par ex. 50 = 50 €), PAS en centimes — contrairement à Paiement.amount."
          },
          "devise": {
            "type": "string",
            "description": "Code de devise (en minuscules, par ex. \"eur\")."
          },
          "assoc": {
            "type": "string",
            "description": "Identifiant de l’association à laquelle la promesse est rattachée (\"MAIN\" par défaut)."
          },
          "name": {
            "type": "string",
            "description": "Libellé libre de la promesse."
          },
          "type": {
            "type": "string",
            "description": "Catégorie/type en texte libre."
          },
          "occasion": {
            "type": "string",
            "description": "Campagne/occasion de rattachement (texte libre)."
          },
          "typeId": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant du livret OU de la campagne auquel la promesse est rattachée (sélecteur admin « Livret »). Pour une campagne, la promesse est comptabilisée dans son total ; pour un livret, dans son budget."
          },
          "active": {
            "type": "boolean"
          },
          "payed": {
            "type": "number",
            "readOnly": true,
            "description": "Montant déjà payé (unités majeures). Calculé à partir des paiements associés — jamais enregistré."
          },
          "reste": {
            "type": "number",
            "readOnly": true,
            "description": "Montant restant à payer (unités majeures). Calculé — jamais enregistré."
          },
          "hasActiveAbonnement": {
            "type": "boolean",
            "readOnly": true,
            "description": "Indique si un abonnement actif honore cette promesse."
          },
          "status": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "OPEN",
              "PARTIAL",
              "FULFILLED",
              "COVERED",
              "CANCELED"
            ],
            "description": "Cycle de vie calculé : OPEN (aucun paiement), PARTIAL (partiel), FULFILLED (reste<=0), COVERED (payée par un abonnement actif), CANCELED (annulée)."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "editDatetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "UnisoftRequest_f851c3ded6b9eee2d078": {
        "type": "object",
        "properties": {
          "cerfa": {
            "type": "boolean",
            "description": "Choix du reçu fiscal applicable uniquement aux paiements futurs. Les paiements et documents existants conservent leur traitement d’origine.",
            "default": true
          },
          "contactId": {
            "type": "string",
            "description": "Identifiant du contact donateur (doit appartenir à l’organisation)."
          },
          "montant": {
            "type": "number",
            "description": "Montant de la promesse en unités majeures de la devise (par ex. 50 = 50 €), PAS en centimes. Doit être > 0."
          },
          "name": {
            "type": "string",
            "description": "Libellé libre de la promesse."
          },
          "occasion": {
            "type": "string",
            "description": "Campagne/occasion de rattachement (texte libre)."
          },
          "type": {
            "type": "string",
            "description": "Catégorie/type en texte libre."
          },
          "assoc": {
            "type": "string",
            "description": "Association à laquelle la promesse est rattachée (\"MAIN\" par défaut). FIXÉE à la création — elle détermine la devise et le reçu, et NE PEUT PLUS être modifiée. Consultez GET /associations pour la liste des associations disponibles."
          },
          "typeId": {
            "type": "string",
            "description": "Identifiant facultatif du livret OU de la campagne auxquels rattacher la promesse (sélecteur admin « Livret »). Si c’est une campagne, la promesse contribue à son total ; si c’est un livret, à son budget."
          }
        },
        "required": [
          "contactId",
          "montant"
        ],
        "additionalProperties": false
      },
      "PromessePaymentLink": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "description": "URL de la page de paiement hébergée permettant d’honorer la promesse."
          },
          "reste": {
            "type": "number",
            "description": "Montant restant (unités majeures)."
          },
          "devise": {
            "type": "string"
          }
        }
      },
      "PledgeHistoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "observation",
              "payments",
              "events",
              "limitations"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "observation": {
                "$ref": "#/components/schemas/PledgeHistoryObservation"
              },
              "payments": {
                "type": "array",
                "maxItems": 2000,
                "items": {
                  "$ref": "#/components/schemas/PledgeHistoryPayment"
                }
              },
              "events": {
                "type": "array",
                "maxItems": 2000,
                "items": {
                  "$ref": "#/components/schemas/PledgeHistoryEvent"
                }
              },
              "limitations": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "NO_HISTORICAL_BALANCE_SNAPSHOTS",
                    "CURRENT_ALLOCATIONS_NOT_ALLOCATION_HISTORY",
                    "RECORDED_RESULTS_NOT_BANK_SETTLEMENT"
                  ]
                }
              }
            }
          }
        }
      },
      "PledgeHistoryObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "observedAt",
          "amountMinor",
          "currency",
          "assoc",
          "paidMinor",
          "remainingMinor",
          "manualPaidMinor",
          "hasActiveSubscription"
        ],
        "properties": {
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Heure UTC de cette lecture. Les collections sont lues séparément ; il ne s’agit pas d’un instantané atomique de la base."
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Montant actuellement promis en unités mineures : 5000 représente 50.00 EUR. Le propriétaire des promesses conserve montant en unités majeures."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "assoc": {
            "type": "string"
          },
          "paidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Solde payé actuel calculé par le propriétaire pur depuis les paiements COMPLETED admis et l’ajustement manuel actuel, plafonné au montant actuellement promis."
          },
          "remainingMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Reste impayé actuel, ramené au minimum à zéro par le propriétaire. Il ne s’agit ni d’un solde historique ni d’une instruction de recouvrer une promesse annulée."
          },
          "manualPaidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Ajustement actuel _manualPayed converti depuis les unités majeures. Aucune identité de paiement ni date historique n’est démontrée."
          },
          "hasActiveSubscription": {
            "type": "boolean",
            "description": "Couverture actuelle par un abonnement ACTIVE avec active=true. La couverture est indépendante de l’encaissement et n’est jamais antidatée."
          }
        }
      },
      "PledgeHistoryPayment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "state",
          "recordedAt",
          "amountMinor",
          "currency",
          "assoc",
          "imported",
          "allocatedMinor",
          "creditedMinor",
          "allocationSource"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,63}$"
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Date métier enregistrée du paiement normalisée en UTC, ou null si absente/invalide. Cette date ne désigne ni un remboursement, ni une réaffectation, ni un règlement bancaire."
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Montant total enregistré du paiement, dans sa devise enregistrée."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "assoc": {
            "type": "string"
          },
          "imported": {
            "type": "boolean",
            "nullable": true
          },
          "allocatedMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Affectation actuelle à cette promesse, arrondie en unités mineures par le propriétaire pur. Elle peut valoir zéro après retrait d’affectation. Les budgets des anciens abonnements sont proratisés par subscription.max. La somme des affectations arrondies individuellement peut différer du payé arrondi globalement et plafonné."
          },
          "creditedMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "allocatedMinor lorsque l’état enregistré exact est COMPLETED ; zéro sinon, y compris pour REFUNDED et REFUND_PENDING. Les imports COMPLETED sont inclus, contrairement aux totaux budgétaires monétaires ordinaires. Il s’agit d’une contribution actuelle, jamais d’une transition historique de solde."
          },
          "allocationSource": {
            "type": "string",
            "enum": [
              "PLEDGE_MAP",
              "SUBSCRIPTION_MAP",
              "SCHEDULE_MAP",
              "LEGACY_SUBSCRIPTION",
              "LEGACY_PAYMENT",
              "DIRECT"
            ]
          }
        }
      },
      "PledgeHistoryEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "recordedAt",
          "amountMinor",
          "currency",
          "beforeAmountMinor",
          "afterAmountMinor"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "CREATED",
              "EDITED",
              "CANCELED",
              "REACTIVATED"
            ]
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Montant promis explicitement enregistré dans un événement CREATED ; null si absent ou invalide. Il ne représente pas le solde de la promesse à cette date.",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "beforeAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Ancien montant promis explicitement enregistré dans EDITED data.changes.montant.before ; null si absent ou invalide. Aucune devise n’est déduite de la promesse actuelle.",
            "nullable": true
          },
          "afterAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Nouveau montant promis explicitement enregistré dans EDITED data.changes.montant.after ; null si absent ou invalide. Aucun solde payé n’est déduit.",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
