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

# Pledges

OpenAPI 3.0.3 · API 2.0.0

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

## Opérations

## POST /promesses/{id}/reminder/preview

Prévisualiser une relance de promesse sans créer de lien

`preview_promesse_reminder`

Droits requis : `promesses:read`, `paiements:read` ET `contacts:read`. Aperçu pur : aucune file, aucun lien, journal de relance, recalcul de cache, initialisation d’échéancier ni appel prestataire. Le propriétaire canonique du message met en forme cette seule promesse encaissable à partir des affectations courantes, de l’association et de la devise validées ; les promesses réglées, annulées, couvertes ou sans adresse e-mail sont refusées. Les montants renvoyés sont en unités mineures (5000 = 50.00 EUR) ; l’entrée montant du propriétaire est convertie depuis les unités majeures. La devise n’est jamais devinée ni convertie ; les données monétaires historiques absentes sont refusées. Le lien affiché est un exemple non fonctionnel. Le snapshot renvoyé doit être transmis sans modification à l’envoi. automaticExcluded décrit uniquement l’exclusion automatique, sans interdire un envoi manuel demandé séparément. L’état de repos est informatif et ne bloque pas un aperçu pur. Aucun paramètre de requête n’est accepté. L’organisation, l’identité API et les références scalaires exactes sont contrôlées. Les sorties excluent la configuration privée, les erreurs brutes et les identifiants de paiement. La garde de repos s’applique à la mise en file ; le transport asynchrone et l’arrivée en boîte de réception ne sont pas garantis hors des périodes de repos.  Une garde durable par organisation/ressource bloque aussi une autre clé après PENDING, UNCERTAIN ou absence de preuve de clôture terminale, même après expiration du dédoublonnage natif par minute/jour. REMINDER_PREVIOUS_RESULT_UNCERTAIN exige d’observer puis de vérifier l’intention existante dans Unisoft ; ne jamais inventer une nouvelle clé ni contourner la garde. Les réservations de ressource exigent des acquittements positifs, exacts et durables d’insertion/CAS. Une preuve de clôture n’est écrite qu’après acquittement positif du journal terminal ; un simple QUEUED/UPDATED/REFUSED enregistré ne peut accorder un autre propriétaire. Une erreur accessoire de tenue de la clôture conserve l’effet positivement prouvé et maintient la garde.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:read",
  "additional": [
    "paiements:read",
    "contacts: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": {},
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat observé de la relance.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderPreview"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED ou UNEXPECTED_REQUEST_BODY. Retirer les champs et paramètres de requête non pris en charge.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL ou CAMPAIGN_RESTRICTED_KEY. L’envoi et la configuration exigent des droits attribués explicitement.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : une référence scalaire exacte requise est absente, étrangère, supprimée ou hors des collectes autorisées.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME ou REST_STATUS_UNAVAILABLE bloque l’envoi. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED ou IDEMPOTENCY_CONFLICT exige de revoir l’intention courante. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES ou une limite bornée d’historique/lecture refuse une dépendance indisponible. Ne jamais rejouer une commande incertaine avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Un résultat inconnu n’autorise pas un nouvel envoi.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN ou REMINDER_RESERVATION_UNCERTAIN. Un acquittement durable d’écriture est absent ou contradictoire ; aucun nouvel effet ni réessai n’est autorisé. Observer la demande existante avec la même identité. REMINDER_RESOURCE_RESERVATION_UNCERTAIN n’accorde aucun propriétaire de ressource et n’autorise aucun effet ultérieur.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## POST /promesses/{id}/reminder/send

Mettre en file une relance de promesse explicitement demandée

`send_promesse_reminder`

Droits requis : `promesses:read`, `paiements:read`, `contacts:read` ET attribution explicite de `promesses:reminders:send`. Envoyer un e-mail pour cette promesse exacte, avec son solde courant validé et le modèle canonique de relance. Appeler d’abord l’aperçu et conserver son snapshot ; une modification du solde, du contact, d’une affectation, du modèle ou de l’expéditeur est refusée par REMINDER_SNAPSHOT_CHANGED avant l’envoi. Les contrôles du snapshot sont des lectures optimistes séparées, sans transaction avec les écritures internes. Journaliser la commande avant de créer le lien de paiement ou l’élément en file ; elle est liée à l’identité API, à l’organisation et à idempotencyKey. La même clé avec l’entrée exacte relit le résultat existant ; une entrée différente renvoie IDEMPOTENCY_CONFLICT. Une commande PENDING ou UNCERTAIN doit uniquement être observée, jamais relancée avec une autre clé. La déduplication native par jour UTC peut renvoyer REFUSED/REMINDER_ALREADY_QUEUED. Chabbat et Yom Tov sont contrôlés par le calendrier canonique Europe/Paris ; REST_TIME bloque l’envoi. forceRest=true exige restOverrideReason et une demande explicite de l’utilisateur pour déroger à cette période de repos ; ne jamais l’ajouter automatiquement après un refus. Les exclusions de configuration concernent uniquement les relances automatiques ; l’envoi manuel reste une intention explicite distincte. QUEUED signifie enregistré dans la file d’e-mails, jamais livré. Consulter la commande pour observer QUEUED_OR_IN_FLIGHT, SMTP_ACCEPTED ou un rapport DELIVERED explicite. SMTP_ACCEPTED ne prouve pas l’arrivée en boîte de réception. deliveryRead=UNAVAILABLE signifie que l’observation facultative de livraison a échoué ; cela n’annule pas la commande. Aucun paramètre de requête n’est accepté. L’organisation, l’identité API et les références scalaires exactes sont contrôlées. Les sorties excluent la configuration privée, les erreurs brutes et les identifiants de paiement. La garde de repos s’applique à la mise en file ; le transport asynchrone et l’arrivée en boîte de réception ne sont pas garantis hors des périodes de repos.  Une garde durable par organisation/ressource bloque aussi une autre clé après PENDING, UNCERTAIN ou absence de preuve de clôture terminale, même après expiration du dédoublonnage natif par minute/jour. REMINDER_PREVIOUS_RESULT_UNCERTAIN exige d’observer puis de vérifier l’intention existante dans Unisoft ; ne jamais inventer une nouvelle clé ni contourner la garde. Les réservations de ressource exigent des acquittements positifs, exacts et durables d’insertion/CAS. Une preuve de clôture n’est écrite qu’après acquittement positif du journal terminal ; un simple QUEUED/UPDATED/REFUSED enregistré ne peut accorder un autre propriétaire. Une erreur accessoire de tenue de la clôture conserve l’effet positivement prouvé et maintient la garde.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "promesses:reminders:send",
  "additional": [
    "promesses:read",
    "paiements:read",
    "contacts: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"
          },
          "expectedSnapshot": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "forceRest": {
            "type": "boolean"
          },
          "restOverrideReason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "pattern": "\\S"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedSnapshot"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "forceRest": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "forceRest",
              "restOverrideReason"
            ],
            "additionalProperties": true
          },
          {
            "type": "object",
            "properties": {
              "forceRest": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "additionalProperties": true,
            "not": {
              "required": [
                "restOverrideReason"
              ]
            }
          }
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat observé de la relance.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED ou UNEXPECTED_REQUEST_BODY. Retirer les champs et paramètres de requête non pris en charge.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL ou CAMPAIGN_RESTRICTED_KEY. L’envoi et la configuration exigent des droits attribués explicitement.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : une référence scalaire exacte requise est absente, étrangère, supprimée ou hors des collectes autorisées.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME ou REST_STATUS_UNAVAILABLE bloque l’envoi. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED ou IDEMPOTENCY_CONFLICT exige de revoir l’intention courante. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES ou une limite bornée d’historique/lecture refuse une dépendance indisponible. Ne jamais rejouer une commande incertaine avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Un résultat inconnu n’autorise pas un nouvel envoi.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN ou REMINDER_RESERVATION_UNCERTAIN. Un acquittement durable d’écriture est absent ou contradictoire ; aucun nouvel effet ni réessai n’est autorisé. Observer la demande existante avec la même identité. REMINDER_RESOURCE_RESERVATION_UNCERTAIN n’accorde aucun propriétaire de ressource et n’autorise aucun effet ultérieur.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## GET /promesses/reminders/commands/{requestId}

Observer une commande de relance et sa livraison enregistrée

`get_promesse_reminder_command`

Observation en lecture seule d’une commande de la même organisation et de l’identité API ayant effectué l’envoi. Nécessite promesses:reminders:send, promesses:read, paiements:read et contacts:read. Chaque cible est de nouveau autorisée dans le périmètre courant des collectes. PENDING ou UNCERTAIN ne signifie pas un échec d’envoi et n’autorise jamais un réessai. QUEUED_OR_IN_FLIGHT ne distingue pas l’attente d’un worker actif ; SMTP_ACCEPTED prouve seulement l’acceptation par le prestataire. DELIVERED exige un rapport explicite de livraison et deliveredAt. UNKNOWN ou deliveryRead=UNAVAILABLE laisse la livraison inconnue. Aucun contrôle prestataire, renvoi ni réessai n’est effectué. Aucun paramètre de requête n’est accepté. L’organisation, l’identité API et les références scalaires exactes sont contrôlées. Les sorties excluent la configuration privée, les erreurs brutes et les identifiants de paiement. La garde de repos s’applique à la mise en file ; le transport asynchrone et l’arrivée en boîte de réception ne sont pas garantis hors des périodes de repos.  Une garde durable par organisation/ressource bloque aussi une autre clé après PENDING, UNCERTAIN ou absence de preuve de clôture terminale, même après expiration du dédoublonnage natif par minute/jour. REMINDER_PREVIOUS_RESULT_UNCERTAIN exige d’observer puis de vérifier l’intention existante dans Unisoft ; ne jamais inventer une nouvelle clé ni contourner la garde. Les réservations de ressource exigent des acquittements positifs, exacts et durables d’insertion/CAS. Une preuve de clôture n’est écrite qu’après acquittement positif du journal terminal ; un simple QUEUED/UPDATED/REFUSED enregistré ne peut accorder un autre propriétaire. Une erreur accessoire de tenue de la clôture conserve l’effet positivement prouvé et maintient la garde.

### Authentification

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

### Permissions requises

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

### Paramètres

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

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat observé de la relance.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED ou UNEXPECTED_REQUEST_BODY. Retirer les champs et paramètres de requête non pris en charge.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL ou CAMPAIGN_RESTRICTED_KEY. L’envoi et la configuration exigent des droits attribués explicitement.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : une référence scalaire exacte requise est absente, étrangère, supprimée ou hors des collectes autorisées.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME ou REST_STATUS_UNAVAILABLE bloque l’envoi. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED ou IDEMPOTENCY_CONFLICT exige de revoir l’intention courante. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES ou une limite bornée d’historique/lecture refuse une dépendance indisponible. Ne jamais rejouer une commande incertaine avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Un résultat inconnu n’autorise pas un nouvel envoi.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN ou REMINDER_RESERVATION_UNCERTAIN. Un acquittement durable d’écriture est absent ou contradictoire ; aucun nouvel effet ni réessai n’est autorisé. Observer la demande existante avec la même identité. REMINDER_RESOURCE_RESERVATION_UNCERTAIN n’accorde aucun propriétaire de ressource et n’autorise aucun effet ultérieur.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## GET /promesses/reminders/rules

Consulter les règles et exclusions des relances automatiques de promesses

`get_promesse_reminder_rules`

Nécessite promesses:read ET contacts:read ainsi qu’une clé couvrant toute l’organisation ; les clés limitées à des collectes sont refusées car ces règles configurent toute l’organisation. Lecture seule : une configuration absente renvoie initialized=false et les valeurs par défaut documentées sans rien insérer. channel vaut toujours EMAIL ; frequency est en jours 1..365 et graceDays vaut 7. excludeContacts contient les UUID exacts des contacts CRM exclus uniquement des relances automatiques. template et subject sont des textes rédigés par l’organisation avec les variables canoniques {prenom}, {nom}, {organisation}, {liste}, {total}, {nombre}, {lien} ; le propriétaire ajoute le lien de paiement s’il manque. Le cron existant applique les périodes de repos ; une modification ne le lance jamais immédiatement. revision est un jeton opaque de concurrence optimiste. Aucun paramètre de requête n’est accepté. L’organisation, l’identité API et les références scalaires exactes sont contrôlées. Les sorties excluent la configuration privée, les erreurs brutes et les identifiants de paiement. La garde de repos s’applique à la mise en file ; le transport asynchrone et l’arrivée en boîte de réception ne sont pas garantis hors des périodes de repos.  Une garde durable par organisation/ressource bloque aussi une autre clé après PENDING, UNCERTAIN ou absence de preuve de clôture terminale, même après expiration du dédoublonnage natif par minute/jour. REMINDER_PREVIOUS_RESULT_UNCERTAIN exige d’observer puis de vérifier l’intention existante dans Unisoft ; ne jamais inventer une nouvelle clé ni contourner la garde. Les réservations de ressource exigent des acquittements positifs, exacts et durables d’insertion/CAS. Une preuve de clôture n’est écrite qu’après acquittement positif du journal terminal ; un simple QUEUED/UPDATED/REFUSED enregistré ne peut accorder un autre propriétaire. Une erreur accessoire de tenue de la clôture conserve l’effet positivement prouvé et maintient la garde.

### Authentification

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

### Permissions requises

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

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat observé de la relance.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderRules"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED ou UNEXPECTED_REQUEST_BODY. Retirer les champs et paramètres de requête non pris en charge.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL ou CAMPAIGN_RESTRICTED_KEY. L’envoi et la configuration exigent des droits attribués explicitement.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : une référence scalaire exacte requise est absente, étrangère, supprimée ou hors des collectes autorisées.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME ou REST_STATUS_UNAVAILABLE bloque l’envoi. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED ou IDEMPOTENCY_CONFLICT exige de revoir l’intention courante. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES ou une limite bornée d’historique/lecture refuse une dépendance indisponible. Ne jamais rejouer une commande incertaine avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Un résultat inconnu n’autorise pas un nouvel envoi.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN ou REMINDER_RESERVATION_UNCERTAIN. Un acquittement durable d’écriture est absent ou contradictoire ; aucun nouvel effet ni réessai n’est autorisé. Observer la demande existante avec la même identité. REMINDER_RESOURCE_RESERVATION_UNCERTAIN n’accorde aucun propriétaire de ressource et n’autorise aucun effet ultérieur.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /promesses/reminders/rules

Modifier les règles de relance automatique et les exclusions de contacts

`update_promesse_reminder_rules`

Nécessite l’attribution explicite de promesses:reminders:write ainsi que promesses:read et contacts:read ; les clés limitées à des collectes sont refusées. Lire d’abord les règles et transmettre expectedRevision. Seuls patch.active, frequency, excludeContacts, template et subject sont modifiables. Les champs absents sont conservés ; excludeContacts remplace toute la liste d’exclusion automatique, avec au plus 1000 UUID CRM uniques de l’organisation. Un template/subject vide rétablit le défaut du propriétaire. Aucun e-mail, lien de paiement ni lancement du cron n’est initié. La commande est journalisée avant une écriture conditionnelle comparant les champs de configuration admis ; REMINDER_RULES_CHANGED refuse une entrée obsolète. La configuration doit déjà exister (initialized=true) ; REMINDER_RULES_UNINITIALIZED exige une initialisation dans Unisoft, car aucun index unique du propriétaire ne protège la création sûre d’un singleton historique absent. La même idempotencyKey/entrée renvoie le résultat précédent sans rejouer une écriture incertaine. Aucun paramètre de requête n’est accepté. L’organisation, l’identité API et les références scalaires exactes sont contrôlées. Les sorties excluent la configuration privée, les erreurs brutes et les identifiants de paiement. La garde de repos s’applique à la mise en file ; le transport asynchrone et l’arrivée en boîte de réception ne sont pas garantis hors des périodes de repos.  Une garde durable par organisation/ressource bloque aussi une autre clé après PENDING, UNCERTAIN ou absence de preuve de clôture terminale, même après expiration du dédoublonnage natif par minute/jour. REMINDER_PREVIOUS_RESULT_UNCERTAIN exige d’observer puis de vérifier l’intention existante dans Unisoft ; ne jamais inventer une nouvelle clé ni contourner la garde. Les réservations de ressource exigent des acquittements positifs, exacts et durables d’insertion/CAS. Une preuve de clôture n’est écrite qu’après acquittement positif du journal terminal ; un simple QUEUED/UPDATED/REFUSED enregistré ne peut accorder un autre propriétaire. Une erreur accessoire de tenue de la clôture conserve l’effet positivement prouvé et maintient la garde.

### Authentification

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

### Permissions requises

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

### 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}$"
          },
          "patch": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "active": {
                "type": "boolean"
              },
              "frequency": {
                "type": "integer",
                "minimum": 1,
                "maximum": 365
              },
              "excludeContacts": {
                "type": "array",
                "maxItems": 1000,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "template": {
                "type": "string",
                "maxLength": 4000
              },
              "subject": {
                "type": "string",
                "maxLength": 200
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "patch"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat observé de la relance.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED ou UNEXPECTED_REQUEST_BODY. Retirer les champs et paramètres de requête non pris en charge.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL ou CAMPAIGN_RESTRICTED_KEY. L’envoi et la configuration exigent des droits attribués explicitement.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : une référence scalaire exacte requise est absente, étrangère, supprimée ou hors des collectes autorisées.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME ou REST_STATUS_UNAVAILABLE bloque l’envoi. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED ou IDEMPOTENCY_CONFLICT exige de revoir l’intention courante. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES ou une limite bornée d’historique/lecture refuse une dépendance indisponible. Ne jamais rejouer une commande incertaine avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Un résultat inconnu n’autorise pas un nouvel envoi.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN ou REMINDER_RESERVATION_UNCERTAIN. Un acquittement durable d’écriture est absent ou contradictoire ; aucun nouvel effet ni réessai n’est autorisé. Observer la demande existante avec la même identité. REMINDER_RESOURCE_RESERVATION_UNCERTAIN n’accorde aucun propriétaire de ressource et n’autorise aucun effet ultérieur.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## Schémas

```json
{
  "components": {
    "schemas": {
      "PledgeReminderPreview": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "pledgeId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "subject": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "snapshot": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "paidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "remainingMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$"
          },
          "assoc": {
            "type": "string"
          },
          "automaticExcluded": {
            "type": "boolean"
          },
          "rest": {
            "$ref": "#/components/schemas/PledgeReminderRest"
          },
          "linkIsPreview": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "pledgeId",
          "contactId",
          "channel",
          "subject",
          "message",
          "snapshot",
          "amountMinor",
          "paidMinor",
          "remainingMinor",
          "currency",
          "assoc",
          "automaticExcluded",
          "rest",
          "linkIsPreview"
        ]
      },
      "PledgeReminderRest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "blocked": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "enum": [
              "Europe/Paris"
            ]
          }
        },
        "required": [
          "blocked",
          "reason",
          "until",
          "timeZone"
        ]
      },
      "PledgeReminderCommand": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "SEND",
              "RULES"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "UPDATED",
              "REFUSED",
              "UNCERTAIN"
            ]
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "targetIds": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "outcomes": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "targetId": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "QUEUED",
                    "DUPLICATE",
                    "REFUSED",
                    "UNCERTAIN"
                  ]
                }
              },
              "required": [
                "targetId",
                "status"
              ]
            }
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "deliveryRead": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ]
          },
          "deliveries": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "targetId": {
                  "type": "string"
                },
                "sendId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "QUEUED_OR_IN_FLIGHT",
                    "SMTP_ACCEPTED",
                    "DELIVERED",
                    "FAILED",
                    "CANCELED",
                    "UNCERTAIN",
                    "UNKNOWN"
                  ]
                }
              },
              "required": [
                "targetId",
                "sendId",
                "state"
              ]
            }
          }
        },
        "required": [
          "requestId",
          "action",
          "status",
          "requestedAt",
          "completedAt",
          "targetIds",
          "error",
          "outcomes",
          "retryable",
          "deliveryRead",
          "deliveries"
        ]
      },
      "PledgeReminderRules": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "active": {
            "type": "boolean"
          },
          "frequency": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365
          },
          "excludeContacts": {
            "type": "array",
            "maxItems": 1000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "template": {
            "type": "string",
            "maxLength": 4000
          },
          "subject": {
            "type": "string",
            "maxLength": 200
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "initialized": {
            "type": "boolean"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "graceDays": {
            "type": "integer",
            "enum": [
              7
            ]
          },
          "exclusionScope": {
            "type": "string",
            "enum": [
              "AUTOMATIC_ONLY"
            ]
          },
          "timeZone": {
            "type": "string",
            "enum": [
              "Europe/Paris"
            ]
          }
        },
        "required": [
          "active",
          "frequency",
          "excludeContacts",
          "template",
          "subject",
          "revision",
          "initialized",
          "channel",
          "graceDays",
          "exclusionScope",
          "timeZone"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
