> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paramètres de l'Organisation

> Configurer les détails de l'organisation et les préférences opérationnelles

## Aperçu

Les **Paramètres de l'Organisation** contrôlent la configuration principale de votre organisation, notamment le nom, la période comptable, les préférences de notification et les règles avancées de prêts/dividendes.

<Note>
  **Autorisation requise** :

  * `settings:read` (pour voir les paramètres)
  * `settings:write` (pour modifier les paramètres)

  Certains paramètres comme la devise et le fuseau horaire sont **immuables** après la création de l'organisation afin de garantir l'intégrité des données.
</Note>

***

## Points d'Accès API

### Obtenir les Paramètres de l'Organisation

**Récupérer la configuration de l'organisation :**

```http theme={null}
GET /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
```

**Réponse :**

```json theme={null}
{
  "message": "Organization details retrieved successfully",
  "data": {
    "id": "org-abc123",
    "numericId": 42,
    "name": "Agatabo Cooperative ABC",
    "type": "TONTINE",
    "currencyCode": "RWF",
    "amountScale": 0,
    "accountingPeriod": "MONTHLY",
    "enableEmail": true,
    "enableSms": false,
    "directionalRounding": false,
    "timezone": "Africa/Kigali",
    "dateFormat": "DD/MM/YYYY",
    "loanSettings": { ... },
    "dividendSettings": { ... },
    "onboardingCompleted": true,
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}
```

***

### Mettre à Jour le Nom de l'Organisation

**Mettre à jour le nom d'affichage de l'organisation :**

```http theme={null}
PUT /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
Body:
{
  "name": "New Organization Name"
}
```

**Réponse :**

```json theme={null}
{
  "message": "Organization updated successfully",
  "data": {
    "id": "org-abc123",
    "name": "New Organization Name",
    ...
  }
}
```

***

### Mettre à Jour les Paramètres de l'Organisation

**Mettre à jour les paramètres opérationnels :**

```http theme={null}
PUT /organizations/{id}/settings
Headers:
  x-organization-id: {organizationId}
Body:
{
  "accountingPeriod": "MONTHLY",
  "enableEmail": true,
  "enableSms": false,
  "loanSettings": { ... },
  "dividendSettings": { ... }
}
```

**Champs du corps de requête :**

| Champ              | Type    | Obligatoire | Description                                        |
| ------------------ | ------- | ----------- | -------------------------------------------------- |
| `accountingPeriod` | enum    | Non         | Type de période : `MONTHLY`, `QUARTERLY`, `YEARLY` |
| `enableEmail`      | boolean | Non         | Activer les notifications email                    |
| `enableSms`        | boolean | Non         | Activer les notifications SMS                      |
| `loanSettings`     | object  | Non         | Politiques et règles de prêts                      |
| `dividendSettings` | object  | Non         | Paramètres de distribution des dividendes          |

**Réponse :**

```json theme={null}
{
  "message": "Organization settings updated successfully"
}
```

**Important** : `accountingPeriod` ne peut pas être modifié après la clôture de périodes.

***

## Paramètres Configurables

### Nom de l'Organisation

**Champ** : `name`

**Description** : Nom d'affichage utilisé dans l'application

**Exemple** : "Agatabo Cooperative ABC"

**API** : `PUT /organizations/{organizationId}`

```json theme={null}
{
  "name": "New Organization Name"
}
```

**Utilisation** : Apparaît sur les rapports, tableaux de bord et communications membres

***

### Période Comptable

**Champ** : `accountingPeriod`

**Valeurs** : `MONTHLY`, `QUARTERLY`, `YEARLY`

**Défaut** : `MONTHLY`

**API** : `PUT /organizations/{id}/settings`

```json theme={null}
{
  "accountingPeriod": "MONTHLY"
}
```

**Fréquence :**

* **MONTHLY** : Clôturer les comptes chaque mois (recommandé)
* **QUARTERLY** : Clôturer les comptes tous les 3 mois
* **YEARLY** : Clôturer les comptes annuellement

**Validation** : Impossible de modifier après la clôture de périodes.

**Erreur si des périodes sont clôturées :**

```json theme={null}
{
  "message": "Cannot change accounting period after closing periods. Please contact support."
}
```

**Recommandation** : Utilisez `MONTHLY` pour les organisations actives. Utilisez `QUARTERLY` ou `YEARLY` seulement pour les organisations à faible activité.

Voir : [Clôture de Période](/fr/tontines/advanced/period-closing)

***

### Notifications Email

**Champ** : `enableEmail`

**Type** : boolean

**Défaut** : `true`

**API** : `PUT /organizations/{id}/settings`

```json theme={null}
{
  "enableEmail": true
}
```

**Lorsque activé**, envoie des notifications email pour :

* Approbations de prêts
* Rappels de paiement de prêt
* Confirmations de paiement de prêt
* Rappels de contribution
* Annonces générales

**Exigences** :

* Les membres doivent avoir des adresses email dans leurs profils
* Le service email doit être configuré par l'administrateur système

***

### Notifications SMS

**Champ** : `enableSms`

**Type** : boolean

**Défaut** : `false`

**API** : `PUT /organizations/{id}/settings`

```json theme={null}
{
  "enableSms": true
}
```

**Lorsque activé**, envoie des notifications SMS pour :

* Approbations de prêts
* Rappels de paiement de prêt
* Notifications urgentes

**Exigences** :

* Les membres doivent avoir des numéros de téléphone dans leurs profils
* Le service SMS Pindo doit être configuré par l'administrateur
* Des crédits SMS doivent être disponibles

**Coût** : Les SMS entraînent des frais par message

***

### Paramètres de Prêt

**Champ** : `loanSettings`

**Type** : objet JSON

**API** : `PUT /organizations/{id}/settings`

**Exemple de configuration :**

```json theme={null}
{
  "loanSettings": {
    "min_loan_amount": 50000,
    "max_loan_amount": 5000000,
    "interest_rate": 10,
    "coverage_ratio": 1.2,
    "min_savings_ratio": 0.3,
    "max_loan_percentage": 3.0,
    "disbursement_fee_percentage": 1.0
  }
}
```

**Champs disponibles :**

| Champ                         | Type   | Description                             |
| ----------------------------- | ------ | --------------------------------------- |
| `min_loan_amount`             | number | Montant minimum de prêt autorisé        |
| `max_loan_amount`             | number | Montant maximum de prêt autorisé        |
| `interest_rate`               | number | Taux d'intérêt par défaut (pourcentage) |
| `coverage_ratio`              | number | Ratio prêt/nantissement                 |
| `min_savings_ratio`           | number | Épargne minimum en % du prêt            |
| `max_loan_percentage`         | number | Prêt max comme multiple de l'épargne    |
| `disbursement_fee_percentage` | number | Frais facturés au décaissement (%)      |

**Important** :

* Les champs de pourcentage sont stockés comme décimales en base (10 % = 0.1)
* L'API accepte les pourcentages et convertit automatiquement
* Des paramètres invalides peuvent empêcher la création de prêts
* Modifier avec assistance technique

***

### Paramètres de Dividendes

**Champ** : `dividendSettings`

**Type** : objet JSON

**API** : `PUT /organizations/{id}/settings`

**Exemple de configuration :**

```json theme={null}
{
  "dividendSettings": {
    "default_distribution_method": "by_contribution",
    "min_pool_amount": 100000,
    "require_minimum_savings": true,
    "minimum_savings_balance": 10000
  }
}
```

**Champs disponibles :**

| Champ                         | Type    | Description                                          |
| ----------------------------- | ------- | ---------------------------------------------------- |
| `default_distribution_method` | string  | Méthode de distribution : `by_contribution`, `equal` |
| `min_pool_amount`             | number  | Montant minimum pour créer un bassin de dividendes   |
| `require_minimum_savings`     | boolean | Exiger une épargne minimum pour l'éligibilité        |
| `minimum_savings_balance`     | number  | Solde d'épargne minimum requis                       |

Voir : [Aperçu des Dividendes](/fr/tontines/dividends/overview)

***

## Paramètres Immuables

Ces champs sont définis à la création de l'organisation et **ne peuvent pas être modifiés** via API :

### Code Devise

**Champ** : `currencyCode`

**Défaut** : `RWF` (Franc rwandais)

**Exemples de valeurs** : `RWF`, `USD`, `KES`, `TZS`

**Pourquoi immuable** : Changer de devise corromprait les enregistrements financiers existants. Toutes les transactions, soldes et rapports sont dans cette devise.

***

### Échelle des Montants

**Champ** : `amountScale`

**Défaut** : `0` (nombres entiers)

**Valeurs** :

* `0` = Nombres entiers (ex. 10000)
* `2` = Deux décimales (ex. 10000.50)

**Utilisation** :

* `0` pour les devises sans subdivisions (RWF)
* `2` pour les devises avec cents (USD)

**Pourquoi immuable** : Changer la précision décimale corromprait les montants en base de données.

***

### Fuseau Horaire

**Champ** : `timezone`

**Défaut** : `Africa/Kigali`

**Exemples de valeurs** : `Africa/Kigali`, `Africa/Nairobi`, `Africa/Dar_es_Salaam`, `UTC`

**Utilisation** :

* Les horodatages de transaction sont affichés dans ce fuseau horaire
* Les filtres de plage de dates utilisent ce fuseau horaire
* Les dates "au" des rapports sont calculées dans ce fuseau horaire

**Pourquoi immuable** : Les horodatages historiques deviendraient ambigus si le fuseau horaire changeait.

***

### Format de Date

**Champ** : `dateFormat`

**Défaut** : `DD/MM/YYYY`

**Exemples de valeurs** :

* `DD/MM/YYYY` (10/06/2026)
* `MM/DD/YYYY` (06/10/2026)
* `YYYY-MM-DD` (2026-06-10)

**Remarque** : Actuellement stocké en base mais pas activement utilisé par le backend. Le formatage d'affichage est géré par le frontend.

***

### Arrondi Directionnel

**Champ** : `directionalRounding`

**Défaut** : `false`

**Valeurs** :

* `false` = Arrondi standard (0.5 arrondi vers le haut)
* `true` = Arrondi bancaire (arrondi au pair le plus proche)

**Remarque** : Actuellement stocké en base mais pas activement utilisé. L'arrondi est géré par la fonction `quantizeByFlow`.

***

## Champs en Lecture Seule

**ID de l'Organisation** : `id` - UUID généré par le système

**ID Numérique** : `numericId` - Numéro séquentiel de l'organisation

**Type d'Organisation** : `type` - Toujours `TONTINE`

**Créé Le** : `createdAt` - Horodatage de création de l'organisation

**Onboarding Terminé** : `onboardingCompleted` - Statut de l'assistant de configuration

***

## Cas d'Utilisation Courants

### Changer le Nom de l'Organisation

**Appel API :**

```bash theme={null}
curl -X PUT "/organizations/org-abc123" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agatabo Cooperative XYZ"
  }'
```

**Résultat** : Le nom change immédiatement dans toute l'application.

***

### Activer les Notifications Email

**Appel API :**

```bash theme={null}
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEmail": true
  }'
```

**Vérifier** : Les membres ont des adresses email dans leurs profils.

***

### Passer de Mensuel à Trimestriel

**Exigence** : Aucune période clôturée (impossible de changer après clôture).

**Appel API :**

```bash theme={null}
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "accountingPeriod": "QUARTERLY"
  }'
```

**Si des périodes sont déjà clôturées** : Erreur retournée - contactez le support pour migration.

***

### Configurer les Règles de Prêt

**Appel API :**

```bash theme={null}
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "loanSettings": {
      "min_loan_amount": 100000,
      "max_loan_amount": 10000000,
      "interest_rate": 12,
      "max_loan_percentage": 3.0
    }
  }'
```

**Effet** : La création de prêt valide selon ces règles.

***

## Bonnes Pratiques

<Note>
  **Configuration des paramètres de l'organisation :**

  **Configuration initiale :**

  * ✅ Définir correctement la devise et l'échelle des montants (immuables !)
  * ✅ Vérifier que le fuseau horaire correspond à l'emplacement physique
  * ✅ Choisir une période comptable appropriée (mensuelle recommandée)
  * ✅ Configurer les paramètres de prêt avant de décaisser le premier prêt
  * ✅ Tester les notifications avec votre propre email/téléphone

  **Gestion continue :**

  * ✅ Limiter l'autorisation `settings:write` aux administrateurs de confiance
  * ✅ Documenter les configurations personnalisées (paramètres de prêts/dividendes)
  * ✅ Examiner les journaux d'audit après les changements de paramètres
  * ✅ Tester les paramètres dans un environnement de staging d'abord (si disponible)
  * ✅ Communiquer les changements de paramètres aux membres de l'organisation

  **Période comptable :**

  * ✅ Choisir le type de période avant la première clôture
  * ✅ Impossible de changer après clôture de périodes (planifier à l'avance)
  * ✅ Mensuel offre le meilleur suivi pour les organisations actives
  * ✅ Trimestriel réduit la charge administrative des petits groupes

  **Paramètres de prêts/dividendes :**

  * ✅ Conserver une sauvegarde de la configuration JSON
  * ✅ Valider le JSON avant enregistrement (un JSON invalide casse les fonctionnalités)
  * ✅ Utiliser correctement les champs de pourcentage (10 % = saisir 10, pas 0.1)
  * ✅ Modifier avec assistance technique en cas de doute
</Note>

***

## Dépannage

**Q : Impossible de modifier les paramètres de l'organisation**

R : Vérifiez :

* Vous avez l'autorisation `settings:write`
* Vous êtes connecté comme utilisateur de l'organisation
* La bonne organisation est sélectionnée via l'en-tête `x-organization-id`

Contactez l'administrateur pour accorder l'autorisation.

***

**Q : Devise ou précision décimale incorrecte**

R : **Si aucune transaction n'est enregistrée** :

* Contacter l'administrateur système pour mettre à jour manuellement la base de données
* Risqué - sauvegarde d'abord

**Si des transactions sont déjà enregistrées** :

* Impossible de changer (corromprait les données existantes)
* Peut nécessiter export, création d'une nouvelle organisation, réimport
* Contactez le support pour assistance de migration

***

**Q : Changement de période comptable rejeté**

R : Erreur : "Cannot change accounting period after closing periods"

**Cause** : Vous avez déjà clôturé au moins une période.

**Solution** : Impossible de changer. La période comptable est verrouillée après la première clôture. Contactez le support si absolument nécessaire.

***

**Q : Notifications non envoyées**

R : Vérifiez :

* `enableEmail` ou `enableSms` est `true`
* Les membres ont des adresses email/numéros de téléphone valides
* Le service email/SMS est configuré par l'administrateur
* Vérifier le dossier spam (emails)
* Vérifier que des crédits SMS sont disponibles (SMS)

***

**Q : Les paramètres de prêt ne s'appliquent pas**

R : Vérifiez :

* Les paramètres ont été enregistrés avec succès (vérifier la réponse)
* Le JSON est valide (pas d'erreurs de syntaxe)
* Les champs de pourcentage utilisent les bonnes valeurs
* Actualiser l'application pour charger les nouveaux paramètres

**Debug** : Voir les paramètres actuels avec `GET /organizations/{id}` pour confirmer l'enregistrement.

***

**Q : Impossible de changer le fuseau horaire**

R : Le fuseau horaire est immuable. Impossible de le changer après création de l'organisation.

**Pourquoi** : Les horodatages historiques de transactions deviendraient ambigus.

**Solution de contournement** : Aucune. Le fuseau horaire est permanent.

***

## Sujets Connexes

<CardGroup cols={2}>
  <Card title="Clôture de Période" icon="lock" href="/fr/tontines/advanced/period-closing">
    Gestion des périodes comptables
  </Card>

  <Card title="Piste d'Audit" icon="file-magnifying-glass" href="/fr/tontines/advanced/audit-trail">
    Suivre les changements de paramètres
  </Card>

  <Card title="Autorisations" icon="shield" href="/fr/tontines/settings/permissions">
    Gérer l'accès settings:write
  </Card>

  <Card title="Préférences Utilisateur" icon="user-gear" href="/fr/tontines/settings/user-preferences">
    Paramètres utilisateur individuels
  </Card>
</CardGroup>