Paramètres de l'Organisation

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.

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.

Points d’Accès API

Obtenir les Paramètres de l’Organisation

Récupérer la configuration de l’organisation :

GET /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}

Réponse :

{
  "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 :

PUT /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
Body:
{
  "name": "New Organization Name"
}

Réponse :

{
  "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 :

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 :

{
  "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}

{
  "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

{
  "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 :

{
  "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

Notifications Email

Champ : enableEmail Type : boolean Défaut : true API : PUT /organizations/{id}/settings

{
  "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

{
  "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 :

{
  "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 :

{
  "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

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 :

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 :

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 :

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 :

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

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

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

Clôture de Période

Gestion des périodes comptables

Piste d'Audit

Suivre les changements de paramètres

Autorisations

Gérer l’accès settings:write

Préférences Utilisateur

Paramètres utilisateur individuels

​Aperçu

​Points d’Accès API

​Obtenir les Paramètres de l’Organisation

​Mettre à Jour le Nom de l’Organisation

​Mettre à Jour les Paramètres de l’Organisation

​Paramètres Configurables

​Nom de l’Organisation

​Période Comptable

​Notifications Email

​Notifications SMS

​Paramètres de Prêt

​Paramètres de Dividendes

​Paramètres Immuables

​Code Devise

​Échelle des Montants

​Fuseau Horaire

​Format de Date

​Arrondi Directionnel

​Champs en Lecture Seule

​Cas d’Utilisation Courants

​Changer le Nom de l’Organisation

​Activer les Notifications Email

​Passer de Mensuel à Trimestriel

​Configurer les Règles de Prêt

​Bonnes Pratiques

​Dépannage

​Sujets Connexes

Clôture de Période

Piste d'Audit

Autorisations

Préférences Utilisateur

Aperçu

Points d’Accès API

Obtenir les Paramètres de l’Organisation

Mettre à Jour le Nom de l’Organisation

Mettre à Jour les Paramètres de l’Organisation

Paramètres Configurables

Nom de l’Organisation

Période Comptable

Notifications Email

Notifications SMS

Paramètres de Prêt

Paramètres de Dividendes

Paramètres Immuables

Code Devise

Échelle des Montants

Fuseau Horaire

Format de Date

Arrondi Directionnel

Champs en Lecture Seule

Cas d’Utilisation Courants

Changer le Nom de l’Organisation

Activer les Notifications Email

Passer de Mensuel à Trimestriel

Configurer les Règles de Prêt

Bonnes Pratiques

Dépannage

Sujets Connexes