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

# Budgets

OpenAPI 3.0.3 · API 2.0.0

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

## פעולות

## GET /banking/budgets

Discover analytical Budget accounts for an association

`list_banking_budgets`

Requires explicitly granted budgets:read; banking:read and payment scopes do not grant it. Campaign-restricted keys are refused. Reads organisation-owned analytical Budget accounts, distinct from bank accounts and merchant balances. Required assoc is a current legal association ID; MAIN and the main budget ID PRINCIPAL are different references. Legacy SERVICE accounts are excluded. No mutation, settled-account reactivation, exchange-rate request, provider call or synchronisation occurs; shared authentication may record key usage. Income/expenses and allocation transfers affect a budget, not a bank transfer or settlement. A number is returned only when the canonical Budget calculator can run on fully admitted sources for one association/currency with proven units, explicit zero payment fees and no effective historical conversion. Imports, in-kind, deleted payments and future movements are excluded. Payment amounts are minor units internally, operation amounts are major units; response amountMajor is ALWAYS a decimal string in MAJOR units. Never divide it by 100. Unknown stays UNKNOWN with amountMajor/currency null and a reason; absence of a safe result never means zero. No total across currencies or bank-settlement claim is permitted. Unknown query parameters and non-empty bodies are rejected. Lists GENERAL/PRINCIPAL, autonomous LIVRET, event GROUPE_LIVRET, CAISSE and CAMPAGNE. Session child livrets are represented by their group and are not duplicated. Global organisation-owned livrets are readable in the selected association context; that context does not assert exclusive ownership. archived is stored metadata, not the settled-account journal or proof of a zero balance. The bounded catalogue refuses more than 5000 records per source. It contains no balance; request the exact type/id detail with assoc and currency.

### אימות

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

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

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

### פרמטרים

```json
{
  "name": "assoc",
  "in": "query",
  "required": true,
  "description": "Legal association ID from list_associations; MAIN denotes the primary association, not a bank or budget account. No foreign or historical alias is admitted.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[0-9a-fA-F-]{36})$"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Admitted stored observations with explicit partial coverage and unknown values.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingBudgetsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_ASSOCIATION, INVALID_CURRENCY, INVALID_DATE, INVALID_LIMIT, INVALID_CURSOR, INVALID_QUERY_PARAMETER, INVALID_BUDGET_TARGET, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: the object or association is absent, foreign or outside the admitted context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY or BUDGET_CATALOG_LIMIT: stored identity/ownership cannot be admitted safely, or the bounded catalogue is too large. Do not bypass through an internal route.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No provider or financial write was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

### OpenAPI

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

## GET /banking/budgets/{type}/{id}

Read a qualified Budget balance for one association and currency

`get_banking_budget`

Requires explicitly granted budgets:read; banking:read and payment scopes do not grant it. Campaign-restricted keys are refused. Reads organisation-owned analytical Budget accounts, distinct from bank accounts and merchant balances. Required assoc is a current legal association ID; MAIN and the main budget ID PRINCIPAL are different references. Legacy SERVICE accounts are excluded. No mutation, settled-account reactivation, exchange-rate request, provider call or synchronisation occurs; shared authentication may record key usage. Income/expenses and allocation transfers affect a budget, not a bank transfer or settlement. A number is returned only when the canonical Budget calculator can run on fully admitted sources for one association/currency with proven units, explicit zero payment fees and no effective historical conversion. Imports, in-kind, deleted payments and future movements are excluded. Payment amounts are minor units internally, operation amounts are major units; response amountMajor is ALWAYS a decimal string in MAJOR units. Never divide it by 100. Unknown stays UNKNOWN with amountMajor/currency null and a reason; absence of a safe result never means zero. No total across currencies or bank-settlement claim is permitted. Unknown query parameters and non-empty bodies are rejected. Requires a target discovered by list_banking_budgets. currency must be explicit; no current association currency repairs historical money. The audited canonical /100 payment unit is supported for eur/usd/gbp/ils/cad/aud/chf; other currencies remain UNKNOWN/CURRENCY_UNIT_UNVERIFIED. GROUPE_LIVRET admits its current organisation-owned session children, then composes disjoint canonical LIVRET balances for the group ID and children; internal allocation transfers cancel. It never calls the native unscoped group lookup. Any missing/nonzero fee gives MISSING_OR_UNPROVEN_FEES; effective converted values give HISTORICAL_CONVERSION_UNPROVEN; unsupported SERVICE gives LEGACY_SERVICE_UNSUPPORTED; malformed money/relations give AMBIGUOUS_BUDGET_SOURCE; more than 5000 records in a calculation source, more than 100 session children, or more than 100000 source visits across group calculations gives SOURCE_LIMIT_EXCEEDED. More than 200 debt allocations on one payment gives AMBIGUOUS_BUDGET_SOURCE. The reason describes a prerequisite, never an instruction to reconstruct the budget by summing donation pages, alter fees, invoke an internal route or retry a financial action. asOf bounds admitted source dates; multiple database reads are not an atomic snapshot. AVAILABLE is the canonical arithmetic for the admitted local sources, not proof of completeness, final fees, bank reception or provider settlement.

### אימות

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

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

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

### פרמטרים

```json
{
  "name": "type",
  "in": "path",
  "required": true,
  "description": "Exact analytical Budget type returned by the catalogue.",
  "schema": {
    "type": "string",
    "enum": [
      "GENERAL",
      "LIVRET",
      "GROUPE_LIVRET",
      "CAISSE",
      "CAMPAGNE"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "PRINCIPAL for GENERAL; otherwise the local UUID returned with the matching type. A bank UUID or association ID is not a budget ID.",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "assoc",
  "in": "query",
  "required": true,
  "description": "Legal association ID from list_associations; MAIN denotes the primary association, not a bank or budget account. No foreign or historical alias is admitted.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[0-9a-fA-F-]{36})$"
  }
}
```

```json
{
  "name": "currency",
  "in": "query",
  "required": true,
  "description": "Required lowercase three-letter denomination for this single-currency observation.",
  "schema": {
    "type": "string",
    "pattern": "^[a-z]{3}$"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Admitted stored observations with explicit partial coverage and unknown values.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingBudgetResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_ASSOCIATION, INVALID_CURRENCY, INVALID_DATE, INVALID_LIMIT, INVALID_CURSOR, INVALID_QUERY_PARAMETER, INVALID_BUDGET_TARGET, UNEXPECTED_QUERY_PARAMETERS or UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, disabled organisation or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: the object or association is absent, foreign or outside the admitted context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY or BUDGET_CATALOG_LIMIT: stored identity/ownership cannot be admitted safely, or the bounded catalogue is too large. Do not bypass through an internal route.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. No provider or financial write was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

### OpenAPI

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

## סכמות

```json
{
  "components": {
    "schemas": {
      "BankingBudgetsResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "context",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BankingBudget"
            }
          },
          "context": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "assoc"
            ],
            "properties": {
              "assoc": {
                "type": "string"
              }
            }
          },
          "coverage": {
            "$ref": "#/components/schemas/BankingBudgetCoverage"
          }
        }
      },
      "BankingBudget": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "label",
          "archived"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "LIVRET",
              "GROUPE_LIVRET",
              "CAISSE",
              "CAMPAGNE"
            ]
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "BankingBudgetCoverage": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "complete",
          "limitations"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "CANONICAL_BUDGET"
            ]
          },
          "complete": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "LEGACY_SERVICES_EXCLUDED",
                "AMBIGUOUS_MONEY_NOT_CALCULATED",
                "NO_BANK_SETTLEMENT_PROOF"
              ]
            }
          }
        }
      },
      "BankingReadError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "BankingBudgetResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "coverage"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/BankingBudgetDetail"
          },
          "coverage": {
            "$ref": "#/components/schemas/BankingBudgetCoverage"
          }
        }
      },
      "BankingBudgetDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "label",
          "archived",
          "context",
          "balance"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "GENERAL",
              "LIVRET",
              "GROUPE_LIVRET",
              "CAISSE",
              "CAMPAGNE"
            ]
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          },
          "context": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "assoc",
              "currency",
              "asOf"
            ],
            "properties": {
              "assoc": {
                "type": "string"
              },
              "currency": {
                "type": "string",
                "pattern": "^[a-z]{3}$"
              },
              "asOf": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "balance": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "availability",
              "amountMajor",
              "currency",
              "reason"
            ],
            "properties": {
              "availability": {
                "type": "string",
                "enum": [
                  "AVAILABLE",
                  "UNKNOWN"
                ]
              },
              "amountMajor": {
                "type": "string",
                "nullable": true,
                "pattern": "^-?\\d+(?:\\.\\d+)?$",
                "description": "Signed decimal string in MAJOR units of currency: 12.34 eur means EUR 12.34. Never divide by 100. Invalid or missing amounts remain null; zero is returned only when explicitly recorded."
              },
              "currency": {
                "type": "string",
                "nullable": true,
                "pattern": "^[a-z]{3}$"
              },
              "reason": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "SOURCE_LIMIT_EXCEEDED",
                  "CURRENCY_UNIT_UNVERIFIED",
                  "AMBIGUOUS_BUDGET_SOURCE",
                  "LEGACY_SERVICE_UNSUPPORTED",
                  "MISSING_OR_UNPROVEN_FEES",
                  "HISTORICAL_CONVERSION_UNPROVEN",
                  "UNSAFE_BUDGET_RESULT",
                  null
                ]
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
