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

# Budgets

OpenAPI 3.0.3 · API 2.0.0

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

## Opérations

## GET /banking/budgets

Découvrir les comptes Budget d’une association

`list_banking_budgets`

Exige budgets:read, attribué explicitement ; banking:read et les droits sur les paiements ne le confèrent pas. Les clés limitées à des collectes sont refusées. Lit les comptes analytiques Budget de l’organisation, distincts des comptes bancaires et soldes marchands. assoc est obligatoire et désigne une association légale actuelle ; MAIN et l’identifiant du budget principal PRINCIPAL sont distincts. Les anciens comptes SERVICE sont exclus. Aucune mutation, réactivation de compte soldé, demande de taux, requête prestataire ni synchronisation ; l’authentification partagée peut enregistrer l’usage de la clé. Recettes, dépenses et transferts d’affectation agissent sur le budget, sans virement bancaire ni règlement. Un nombre est renvoyé seulement si le calculateur Budget canonique peut travailler sur des sources entièrement admises pour une association/devise, avec unités prouvées, frais de paiement explicitement nuls et aucune conversion historique effective. Imports, dons en nature, paiements supprimés et mouvements futurs sont exclus. En interne, les paiements sont en unités mineures et les opérations en majeures ; amountMajor est TOUJOURS une chaîne décimale en unités MAJEURES. Ne jamais diviser par 100. Une inconnue reste UNKNOWN avec amountMajor/currency à null et un motif ; l’absence de résultat sûr ne signifie jamais zéro. Aucun total entre devises ni affirmation de règlement bancaire n’est permis. Les paramètres inconnus et les corps non vides sont refusés. Liste GENERAL/PRINCIPAL, LIVRET autonome, GROUPE_LIVRET d’événement, CAISSE et CAMPAGNE. Les livrets de session sont représentés par leur groupe et ne sont pas comptés deux fois. Les livrets globaux de l’organisation sont consultables dans le contexte d’association choisi, sans que ce contexte affirme une propriété exclusive. archived est une métadonnée enregistrée, pas le journal de solde ni une preuve de solde nul. Le catalogue borné refuse plus de 5000 enregistrements par source. Il ne contient aucun solde ; demander le détail du type/id exact avec assoc et currency.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "assoc",
  "in": "query",
  "required": true,
  "description": "Identifiant d’association légale issu de list_associations ; MAIN désigne l’association principale, pas un compte bancaire ni un budget. Aucun alias étranger ou historique n’est admis.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[0-9a-fA-F-]{36})$"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observations enregistrées admises, avec couverture partielle et inconnues explicites.",
  "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 ou UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, organisation désactivée ou CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : objet ou association absent, étranger ou hors du contexte admis.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY ou BUDGET_CATALOG_LIMIT : l’identité/propriété enregistrée ne peut pas être admise sûrement, ou le catalogue dépasse sa borne. Ne pas contourner par une route interne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Aucune requête prestataire ni écriture financière n’a été tentée.",
  "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}

Lire un solde Budget qualifié pour une association et une devise

`get_banking_budget`

Exige budgets:read, attribué explicitement ; banking:read et les droits sur les paiements ne le confèrent pas. Les clés limitées à des collectes sont refusées. Lit les comptes analytiques Budget de l’organisation, distincts des comptes bancaires et soldes marchands. assoc est obligatoire et désigne une association légale actuelle ; MAIN et l’identifiant du budget principal PRINCIPAL sont distincts. Les anciens comptes SERVICE sont exclus. Aucune mutation, réactivation de compte soldé, demande de taux, requête prestataire ni synchronisation ; l’authentification partagée peut enregistrer l’usage de la clé. Recettes, dépenses et transferts d’affectation agissent sur le budget, sans virement bancaire ni règlement. Un nombre est renvoyé seulement si le calculateur Budget canonique peut travailler sur des sources entièrement admises pour une association/devise, avec unités prouvées, frais de paiement explicitement nuls et aucune conversion historique effective. Imports, dons en nature, paiements supprimés et mouvements futurs sont exclus. En interne, les paiements sont en unités mineures et les opérations en majeures ; amountMajor est TOUJOURS une chaîne décimale en unités MAJEURES. Ne jamais diviser par 100. Une inconnue reste UNKNOWN avec amountMajor/currency à null et un motif ; l’absence de résultat sûr ne signifie jamais zéro. Aucun total entre devises ni affirmation de règlement bancaire n’est permis. Les paramètres inconnus et les corps non vides sont refusés. Exige une cible découverte par list_banking_budgets. currency doit être explicite ; la devise actuelle de l’association ne répare pas les montants historiques. L’unité /100 du calculateur est vérifiée pour eur/usd/gbp/ils/cad/aud/chf ; les autres devises restent UNKNOWN/CURRENCY_UNIT_UNVERIFIED. GROUPE_LIVRET réadmet ses enfants de session actuels dans l’organisation puis compose les soldes LIVRET canoniques disjoints de l’identifiant de groupe et des enfants ; les transferts d’affectation internes se compensent. La recherche native de groupe sans filtre d’organisation n’est jamais appelée. Un frais absent/non nul donne MISSING_OR_UNPROVEN_FEES ; une conversion effective donne HISTORICAL_CONVERSION_UNPROVEN ; SERVICE non pris en charge donne LEGACY_SERVICE_UNSUPPORTED ; montants/relations malformés donnent AMBIGUOUS_BUDGET_SOURCE ; plus de 5000 lignes dans une source de calcul, plus de 100 enfants de session ou plus de 100000 visites de sources dans une composition de groupe donne SOURCE_LIMIT_EXCEEDED. Plus de 200 affectations de promesse sur un paiement donne AMBIGUOUS_BUDGET_SOURCE. Le motif décrit un préalable, jamais une consigne de reconstruire le budget par addition de pages de dons, changer les frais, appeler une route interne ou rejouer une action financière. asOf borne les dates admises ; plusieurs lectures ne forment pas un snapshot atomique. AVAILABLE est l’arithmétique canonique des sources locales admises, sans preuve d’exhaustivité, de frais définitifs, de réception bancaire ni de règlement prestataire.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "type",
  "in": "path",
  "required": true,
  "description": "Type analytique Budget exact renvoyé par le catalogue.",
  "schema": {
    "type": "string",
    "enum": [
      "GENERAL",
      "LIVRET",
      "GROUPE_LIVRET",
      "CAISSE",
      "CAMPAGNE"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "PRINCIPAL pour GENERAL ; sinon l’UUID local renvoyé avec le type correspondant. Un UUID bancaire ou identifiant d’association n’est pas un identifiant de budget.",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "assoc",
  "in": "query",
  "required": true,
  "description": "Identifiant d’association légale issu de list_associations ; MAIN désigne l’association principale, pas un compte bancaire ni un budget. Aucun alias étranger ou historique n’est admis.",
  "schema": {
    "type": "string",
    "pattern": "^(MAIN|[0-9a-fA-F-]{36})$"
  }
}
```

```json
{
  "name": "currency",
  "in": "query",
  "required": true,
  "description": "Devise obligatoire en trois lettres minuscules pour cette observation dans une seule devise.",
  "schema": {
    "type": "string",
    "pattern": "^[a-z]{3}$"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observations enregistrées admises, avec couverture partielle et inconnues explicites.",
  "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 ou UNEXPECTED_REQUEST_BODY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, organisation désactivée ou CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND : objet ou association absent, étranger ou hors du contexte admis.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_ASSOCIATION_CONTEXT, INVALID_BANK_HISTORY, INVALID_TRANSACTION_HISTORY, INVALID_BUDGET_HISTORY ou BUDGET_CATALOG_LIMIT : l’identité/propriété enregistrée ne peut pas être admise sûrement, ou le catalogue dépasse sa borne. Ne pas contourner par une route interne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/BankingReadError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Aucune requête prestataire ni écriture financière n’a été tentée.",
  "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
  }
}
```

## Schémas

```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": "Chaîne décimale signée en unités MAJEURES de currency : 12.34 eur signifie EUR 12.34. Ne jamais diviser par 100. Les montants absents ou invalides restent null ; zéro est renvoyé uniquement s’il est explicitement enregistré."
              },
              "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"
      }
    }
  }
}
```
