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

> **גרסה זו של ה־API מיושנת.** לחיבורים חדשים יש להשתמש בגרסה העדכנית ביותר. [לתיעוד העדכני](/integrations/v2/docs?lang=he)

# Promesses

OpenAPI 3.0.3 · API 1.0.0

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

### תגובות

#### 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",
    "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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### 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",
    "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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

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

### תגובות

#### 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",
    "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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### 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",
    "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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

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

## סכמות

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      },
      "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": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      }
    },
    "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"
          }
        }
      },
      "PromesseCreate": {
        "type": "object",
        "required": [
          "contactId",
          "montant"
        ],
        "properties": {
          "cerfa": {
            "type": "boolean",
            "default": true,
            "description": "Tax receipt choice for future payments only. Existing payments and documents retain their original treatment."
          },
          "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."
          }
        }
      },
      "PromesseUpdate": {
        "type": "object",
        "description": "Any subset of these fields. `assoc` and `devise` are NOT editable (fixed at creation). Computed fields (reste/payed/status) are never accepted.",
        "properties": {
          "expectedReceiptRevision": {
            "type": "integer",
            "minimum": 0,
            "description": "Receipt revision returned by the last read; rejects a stale fiscal edit."
          },
          "cerfa": {
            "type": "boolean",
            "default": true,
            "description": "Tax receipt choice for future payments only. Existing payments and documents retain their original treatment."
          },
          "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)."
          }
        }
      },
      "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"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
