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

> **Cette version de l’API est obsolète.** Utilisez la dernière version pour toute nouvelle intégration. [Voir la documentation actuelle](/integrations/v2/docs?lang=fr)

# Promesses de don

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "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/PromesseCreate"
      }
    }
  }
}
```

### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

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

### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

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

## Schémas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Nombre de résultats par page."
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Curseur opaque renvoyé par la requête précédente."
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "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}$"
        },
        "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
      }
    },
    "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"
          }
        }
      },
      "PromesseCreate": {
        "type": "object",
        "required": [
          "contactId",
          "montant"
        ],
        "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."
          },
          "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."
          }
        }
      },
      "PromesseUpdate": {
        "type": "object",
        "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.",
        "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",
            "default": true,
            "description": "Choix du reçu fiscal applicable uniquement aux paiements futurs. Les paiements et documents existants conservent leur traitement d’origine."
          },
          "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)."
          }
        }
      },
      "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"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
