**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Promesses

OpenAPI 3.0.3 · API 2.0.0

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

Donation pledges (« promesses de dons »): an amount a contact committed to give, fulfilled by payments over time (collection dettes_v2). Full CRUD + a payment-link endpoint. `montant`/`reste`/`payed` are in MAJOR currency units (NOT cents). Scopes: `promesses:read`/`promesses:write`.

## פעולות

## GET /promesses

List donation pledges

`list_promesses`

Required scope: `promesses:read`. Lists the org's pledges, each enriched with computed `payed`/`reste`/`status` + the donor name. Excludes canceled pledges unless `includeCanceled=true`. Paginated, newest first.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filter by donor contact id."
}
```

```json
{
  "name": "typeId",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filter by attached livret/campagne id."
}
```

```json
{
  "name": "occasion",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filter by occasion (exact match)."
}
```

```json
{
  "name": "includeCanceled",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Include canceled pledges (default false)."
}
```

### תגובות

#### 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": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "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

Create a donation pledge

`create_promesse`

Required scope: `promesses:write`. Creates a pledge for a contact of the org. `montant` is in MAJOR currency units (e.g. 50 = 50€), NOT cents. The currency is always derived from `assoc` (MAIN by default) and cannot be overridden. `organisation` is forced server-side.

### אימות

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

### הרשאות נדרשות

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

### גוף הבקשה

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

### תגובות

#### 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_NOT_FOUND",
  "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}

Get a donation pledge

`get_promesse`

Required scope: `promesses:read`. Returns the pledge with freshly computed `payed`/`reste`/`status`.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```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": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

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

Update a donation pledge

`update_promesse`

Required scope: `promesses:write`. Updates any subset of the pledge's editable fields. `assoc`/`devise` are NOT modifiable (fixed at creation). Computed fields (reste/payed/status) are never accepted.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```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": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expectedReceiptRevision": {
            "type": "integer",
            "minimum": 0,
            "description": "Receipt revision returned by the last read; rejects a stale fiscal edit."
          },
          "cerfa": {
            "type": "boolean",
            "description": "Tax receipt choice for future payments only. Existing payments and documents retain their original treatment.",
            "default": true
          },
          "contactId": {
            "type": "string"
          },
          "montant": {
            "type": "number",
            "description": "Major currency units, > 0."
          },
          "name": {
            "type": "string"
          },
          "occasion": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "typeId": {
            "type": "string",
            "description": "Re-attach to another livret/campagne (or null to detach)."
          }
        },
        "additionalProperties": false,
        "description": "Any subset of these fields. `assoc` and `devise` are NOT editable (fixed at creation). Computed fields (reste/payed/status) are never accepted."
      }
    }
  }
}
```

### תגובות

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

Cancel a donation pledge

`delete_promesse`

Required scope: `promesses:write`. Soft-deletes the pledge (active=false, state=CANCELED) — it disappears from active lists but is never physically removed.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```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": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

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

Create or retrieve the payment link of a pledge

`create_promesse_payment_link`

Required scope: `promesses:write`. Creates or reuses a hosted payment-page URL so the donor can fulfil the pledge. Refuses (409) if the pledge is canceled, already fully paid, or covered by an active subscription.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

```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": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

#### 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 or 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

Read a pledge balance observation and recorded history

`get_promesse_history`

Required scopes: `promesses:read` AND `paiements:read`. Read-only: no persistent cache calculation, schedule initialization, synchronization, provider request or bank verification. Returns the CURRENT balance observed at this read, CURRENT known payment allocations and only actually persisted CREATED/EDITED/CANCELED/REACTIVATED journal events. No historical balance snapshots are available: the current pledge amount does not prove its earlier amount or balance. Do not build a historical balance curve by cumulatively adding these rows. No creation/edit/refund/coverage event is synthesized from current fields; a refunded payment retains its original business date and contributes zero now. Monetary fields are minor units (5000 = 50.00 EUR); legacy dettes[].montant and _manualPayed are converted from major units. Allocation precedence: pledgeAllocations, subscriptionAllocations, subscription schedule map, legacy subscription budgets prorated by subscription.max, legacy one-off dettes, direct DETTE. An explicit empty map detaches all and blocks legacy fallback. Only exact COMPLETED contributes now, including imported payments; REFUNDED, REFUND_PENDING and other states contribute zero, without an invented refund transition. COMPLETED is the stored result and can precede capture for some providers. The pure owner globally rounds contributions and caps paid at the current promised amount; individually rounded payment rows need not sum to that cap. Every required payment, subscription and interpreted pledge member is checked against organisation, allowed campaigns, association and currency; inaccessible required members return 404, inconsistent or ambiguous monetary history returns 409. Missing currencies are not guessed and no currencies are converted or mixed. Legacy missing association means MAIN. Soft-deleted records are excluded, which is not a financial reversal. Events and payments sort by recorded datetime DESC then id DESC, with undated records last; current allocation is not allocation-change history. Collections are read separately, without a transaction or historical snapshot. No query parameters or nonempty request body are accepted. At most 2000 records per loaded history collection and 200 allocation members per record; overflow returns PLEDGE_HISTORY_LIMIT_EXCEEDED rather than an incomplete balance. The explicit projection excludes donor identity, notes, actors, private snapshots, reusable payment methods and merchant configuration.

### אימות

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

### הרשאות נדרשות

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

### פרמטרים

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

### תגובות

#### HTTP 200

```json
{
  "description": "Current balance observation, current known payment allocations and persisted financial journal events.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PledgeHistoryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, UNKNOWN_QUERY_PARAMETER or UNEXPECTED_REQUEST_BODY. Remove unsupported inputs.",
  "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": "Missing or invalid authentication.",
  "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: both promesses:read and paiements:read are required.",
  "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: the pledge or a required historical member is absent, deleted, foreign or outside the allowed campaigns.",
  "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: incomplete or inconsistent historical monetary data; review the pledge and allocations in Unisoft. PLEDGE_HISTORY_LIMIT_EXCEEDED: history exceeds the bounded read and requires a dedicated owner export.",
  "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
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "Promesse": {
        "type": "object",
        "description": "A donation pledge (« promesse de don »): an amount a contact committed to give, that payments progressively fulfil. Stored in dettes_v2.",
        "properties": {
          "cerfa": {
            "type": "boolean",
            "default": true,
            "description": "Tax receipt choice for future payments only. Existing payments and documents retain their original treatment."
          },
          "receiptRevision": {
            "type": "integer",
            "readOnly": true
          },
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "contact": {
            "type": "string",
            "description": "Contact id of the donor."
          },
          "contactName": {
            "type": "string",
            "readOnly": true,
            "description": "Donor full name (computed on read)."
          },
          "montant": {
            "type": "number",
            "description": "Pledged amount in MAJOR currency units (e.g. 50 = 50€), NOT cents — unlike Paiement.amount."
          },
          "devise": {
            "type": "string",
            "description": "Currency code (lower-case, e.g. \"eur\")."
          },
          "assoc": {
            "type": "string",
            "description": "Association id the pledge belongs to (\"MAIN\" by default)."
          },
          "name": {
            "type": "string",
            "description": "Free-text label of the pledge."
          },
          "type": {
            "type": "string",
            "description": "Free-text category/type."
          },
          "occasion": {
            "type": "string",
            "description": "Campaign/occasion grouping (free text)."
          },
          "typeId": {
            "type": "string",
            "nullable": true,
            "description": "Id of the livret OR campagne the pledge is attached to (the admin \"Livret\" picker). When it is a campagne, the pledge is counted in that campaign's total; when a livret, in its budget."
          },
          "active": {
            "type": "boolean"
          },
          "payed": {
            "type": "number",
            "readOnly": true,
            "description": "Amount already paid (major units). Computed from linked payments — never stored."
          },
          "reste": {
            "type": "number",
            "readOnly": true,
            "description": "Remaining amount to pay (major units). Computed — never stored."
          },
          "hasActiveAbonnement": {
            "type": "boolean",
            "readOnly": true,
            "description": "Whether an active subscription is fulfilling this pledge."
          },
          "status": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "OPEN",
              "PARTIAL",
              "FULFILLED",
              "COVERED",
              "CANCELED"
            ],
            "description": "Computed lifecycle: OPEN (nothing paid), PARTIAL, FULFILLED (reste<=0), COVERED (an active subscription pays it), CANCELED."
          },
          "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": "Tax receipt choice for future payments only. Existing payments and documents retain their original treatment.",
            "default": true
          },
          "contactId": {
            "type": "string",
            "description": "Donor contact id (must belong to the org)."
          },
          "montant": {
            "type": "number",
            "description": "Pledged amount in MAJOR currency units (e.g. 50 = 50€), NOT cents. Must be > 0."
          },
          "name": {
            "type": "string",
            "description": "Free-text label of the pledge."
          },
          "occasion": {
            "type": "string",
            "description": "Campaign/occasion grouping (free text)."
          },
          "type": {
            "type": "string",
            "description": "Free-text category/type."
          },
          "assoc": {
            "type": "string",
            "description": "Association the pledge belongs to (\"MAIN\" by default). FIXED at creation — it determines the currency and the receipt, and CANNOT be changed afterwards. List the available associations via GET /associations."
          },
          "typeId": {
            "type": "string",
            "description": "Optional id of the livret OR campagne to attach the pledge to (the admin \"Livret\" picker). If it is a campagne, the pledge counts toward that campaign's total; if a livret, toward its budget."
          }
        },
        "required": [
          "contactId",
          "montant"
        ],
        "additionalProperties": false
      },
      "PromessePaymentLink": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "description": "Hosted payment page URL to fulfil the pledge."
          },
          "reste": {
            "type": "number",
            "description": "Remaining amount (major units)."
          },
          "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": "Time of this read in UTC. The collections are read separately; this is not an atomic database snapshot."
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Current promised amount in minor units: 5000 means 50.00 EUR. The pledge owner stores montant in major units."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "assoc": {
            "type": "string"
          },
          "paidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Current paid balance calculated by the pure pledge owner from admitted COMPLETED payments and the current manual paid adjustment, capped at the current promised amount."
          },
          "remainingMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Current unpaid remainder, clamped to zero by the pledge owner. This is not a historical balance or a statement that a canceled pledge should still be collected."
          },
          "manualPaidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Current _manualPayed adjustment converted from major units. It has no demonstrated payment identity or historical date."
          },
          "hasActiveSubscription": {
            "type": "boolean",
            "description": "Current coverage by an ACTIVE subscription with active=true. Coverage is independent of payment collection and is never backdated."
          }
        }
      },
      "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": "Stored payment business datetime normalized to UTC, or null if absent/invalid. This date is not a refund date, allocation-change date or bank-settlement timestamp."
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Whole recorded payment amount, in the recorded payment currency."
          },
          "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": "Current allocation to this pledge, rounded to minor units through the pure owner. It may be zero after detachment. Legacy subscription budgets use subscription.max proration. Summing individually rounded allocations may differ from the globally rounded and capped paid balance."
          },
          "creditedMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "allocatedMinor when the exact stored state is COMPLETED; zero otherwise, including REFUNDED and REFUND_PENDING. Imported COMPLETED payments are included, unlike ordinary monetary budget totals. This is a current contribution, never a historical balance transition."
          },
          "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": "Promised amount explicitly recorded by a CREATED event; null when absent or invalid. It is not the pledge balance at that date.",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "beforeAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Prior promised amount explicitly recorded in EDITED data.changes.montant.before; null when absent or invalid. No currency is inferred from the current pledge.",
            "nullable": true
          },
          "afterAmountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "New promised amount explicitly recorded in EDITED data.changes.montant.after; null when absent or invalid. No paid balance is inferred.",
            "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"
      }
    }
  }
}
```
