Réglages et indicateurs
Votre identité sur les factures et le portail, le fuseau horaire de facturation, les indicateurs et l'import d'abonnés.
Endpoints
GET /api/v1/billing/settingsPATCH /api/v1/billing/settingsGET /api/v1/billing/metricsPOST /api/v1/billing/importsGET /api/v1/billing/imports/{id}POST /api/v1/billing/imports/{id}/commitGET /api/v1/billing/addonPOST /api/v1/billing/addon/activate
Réglages
GET /api/v1/billing/settings
PATCH /api/v1/billing/settingsLes réglages sont communs à la sandbox et au live de votre entreprise, et restent accessibles en live même sans l'option Abonnements. Tant qu'ils n'ont jamais été enregistrés, la lecture renvoie les valeurs par défaut avec "id": null.
PATCH accepte n'importe quel sous-ensemble des champs. Une chaîne vide efface le champ.
| Champ | Description |
|---|---|
| timezone | Fuseau de facturation, par exemple Africa/Abidjan. Africa/Douala par défaut. Décide du jour d'échéance, de l'heure des rappels et des heures de silence. |
| default_locale | fr (par défaut) ou en : langue des pages et des messages quand le client n'en a pas |
| sender_display_name | Nom affiché comme expéditeur des messages, 100 caractères au plus |
| support_phone | Numéro de contact affiché aux clients, au format E.164 |
| support_email | Adresse de réponse des emails envoyés aux clients |
| portal_logo_url | Logo https affiché sur le portail, les pages de paiement et les factures. Sans logo, celui de l'entreprise est utilisé. null revient au logo de l'entreprise. |
| logo_url | Lecture seule : le logo réellement affiché (importé depuis le dashboard, portal_logo_url ou celui de l'entreprise) |
| portal_primary_color | Couleur principale, #abc ou #aabbcc |
| allow_portal_cancellation | Les abonnés peuvent résilier depuis le portail. true par défaut. |
| legal_name | Raison sociale imprimée sur les factures |
| legal_identifier | Identifiant légal (NIU, RCCM…), 100 caractères au plus |
| legal_address | Adresse imprimée sur les factures, 500 caractères au plus |
La réponse ajoute, en lecture seule :
uses_own_whatsapp_number: les rappels partent de votre propre numéro WhatsApp plutôt que du numéro partagé de Genuka Pay. Ce branchement se fait sur demande auprès de Genuka ;whatsapp_connection_idne se modifie pas par l'API (422whatsapp_connection_managed_by_genuka).company_defaults: les valeurs tirées du profil de votre entreprise, pour pré-remplir un formulaire.
Ce qui n'est pas réglable
Le calendrier des relances, les heures de silence (21 h – 8 h) et le numéro des factures (INV-000001) sont fixes. Le délai de grâce se règle par formule, avec grace_days.
Indicateurs
GET /api/v1/billing/metrics?from=2026-10-01&to=2026-10-31from et to sont des dates AAAA-MM-JJ, toutes les deux ou aucune : le mois en cours par défaut, 366 jours au plus. Les indicateurs portent sur l'application de la clé.
| Champ | Définition |
|---|---|
| mrr | Revenu mensuel récurrent, en unité mineure : somme des abonnements active et past_due, ramenée au mois (une formule annuelle compte pour un douzième). Valeur actuelle, indépendante de la période. |
| currency | Devise principale des montants |
| by_currency | Détail { "XAF": { "mrr", "overdue_amount", "active_subscriptions" } } quand vous facturez dans plusieurs devises, sinon null |
| active_subscriptions | Abonnements active et past_due (essais exclus) |
| overdue_amount | Reste à payer des factures ouvertes dont l'échéance est passée |
| cancellations | Abonnements terminés pendant la période, hors ceux dont la première facture n'a jamais été payée |
| renewal_on_time_rate | Part des factures échues pendant la période et payées au plus tard le jour de leur échéance |
| recovery_rate | Parmi les factures passées en retard, part payée avant la suspension |
| reachable_rate | Part des abonnés actifs ayant au moins un contact vérifié et joignable |
| channel_conversion | Par canal (whatsapp, sms, email) : part des rappels livrés suivis d'un paiement dans les 24 heures |
| period | { from, to, timezone } |
Les taux sont des décimaux entre 0 et 1, ou null quand il n'y a rien à mesurer.
Importer des abonnés existants
Pour reprendre des abonnés gérés ailleurs, importez un fichier CSV depuis le dashboard (Abonnements → Abonnés → Importer) ou par l'API. Dans les deux cas, vous voyez un aperçu ligne par ligne avant de confirmer.
- Jusqu'à 5 000 lignes, 5 Mo. Séparateur virgule, point-virgule ou tabulation. UTF-8 ou Windows-1252.
- Les en-têtes sont reconnus en français ou en anglais, sans tenir compte des accents ni de la casse. Les colonnes inconnues sont ignorées.
| Colonne | Requise | Autres en-têtes acceptés |
|---|---|---|
| name | Oui | nom, nom_complet, nom_client, full_name, customer_name |
| phone | Oui | telephone, tel, whatsapp, numero, mobile, phone_number |
| next_due_date | Oui | prochaine_echeance, echeance, due_date, next_due. Date AAAA-MM-JJ, aujourd'hui ou plus tard. |
| price_id | Oui, sauf formule par défaut choisie à l'import | formule, formule_id, plan, price |
| Non | mail, courriel, e_mail | |
| external_id | Non | reference, reference_client, client_id, member_id |
| beneficiary_name | Non | beneficiaire, nom_beneficiaire, eleve, student, beneficiary |
| beneficiary_reference | Non | matricule, reference_beneficiaire, beneficiary_ref |
| cycles_billed | Non | echeances_payees, periods_paid, installments_paid |
Chaque ligne valide crée un client (ou reprend celui qui a déjà ce numéro) et un abonnement active dont la période en cours se termine à next_due_date. La première facture est émise 3 jours avant cette date. Webhooks : customer.created et subscription.created, avec context.source: "import".
Importer par l'API
- Envoyez le contenu du fichier en texte, dans un corps JSON signé comme toute requête :
curl -X POST "https://api-pay.genuka.com/api/v1/billing/imports" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"csv": "name,phone,next_due_date\nAwa Ndiaye,+237690123456,2026-11-05\n",
"file_name": "eleves.csv",
"price_id": "01k79y8m0n2p4q6r8s0t2v4w6x",
"consent_attested": true
}'| Paramètre | Type | Requis | Description |
|---|---|---|---|
| csv | string | Oui, sauf si file est envoyé | Contenu du fichier CSV, 5 Mo au plus |
| file | file | Non | Alternative à csv : le fichier lui-même, envoyé en multipart/form-data (.csv ou .txt, 5 Mo au plus). N'envoyez pas les deux. |
| file_name | string | Non | Nom affiché pour l'import |
| price_id | string | Non | Formule des lignes qui n'en indiquent pas |
| consent_attested | boolean | Oui | true : vous attestez que chaque abonné a accepté de recevoir vos rappels |
Réponse 201 : l'aperçu, sans rien créer. rows_total, rows_valid et rows_invalid résument le fichier ; rows détaille chaque ligne avec ses erreurs (code : required, invalid_phone, invalid_date, past_date, unknown_price, duplicate_in_file, already_subscribed, price_unavailable, free_plan_subscription_limit…). Un fichier illisible ou sans colonne requise renvoie 422 sur csv (ou file).
- Confirmez avec
POST /api/v1/billing/imports/{id}/commit. Les lignes valides sont créées en arrière-plan : la réponse202a le statutcommitting, suivez l'avancement avecGET /api/v1/billing/imports/{id}jusqu'àcommitted(oufailed). Les lignes devenues invalides entre-temps sont ignorées et signalées. Un second appel une fois l'import terminé renvoie409import_already_committed.
Option Abonnements
GET /api/v1/billing/addonRenvoie votre offre en cours et votre consommation des limites de l'offre Gratuite, comme sur la page Option Abonnements du dashboard :
{
"data": {
"object": "billing_addon",
"active": false,
"plan": "free",
"free_plan_applies": true,
"free_plan": { "surcharge_rate": 0.02, "max_active_subscriptions": 50, "monthly_messages": 100, "manual_payments": false },
"usage": { "active_subscriptions": 12, "messages_this_month": 37 },
"environment": "live",
"status": null,
"available_tiers": []
}
}| Champ | Description |
|---|---|
| active | L'option payante est en vigueur pour l'environnement de la clé. Toujours true en sandbox. |
| plan | free ou paid |
| free_plan_applies | Les limites de l'offre Gratuite s'appliquent à cet environnement (live sans option payante) |
| free_plan | Les limites de l'offre Gratuite : majoration des frais sur chaque paiement d'abonnement, nombre maximum d'abonnements actifs, messages WhatsApp et SMS par mois calendaire |
| usage | Vos abonnements live non résiliés ni terminés, et les messages WhatsApp et SMS envoyés ce mois-ci |
| status, subscription_id, current_period_end, access_until, cancel_at_period_end | Votre abonnement à l'option, null sans abonnement |
| open_invoice, payment_url | Facture de l'option à payer, s'il y en a une |
| available_tiers | Offres payantes disponibles |
POST /api/v1/billing/addon/activate (corps : price_id, l'une des available_tiers) vous abonne à une offre payante. L'option est un abonnement ordinaire facturé par Genuka Pay : elle prend effet dès que cet abonnement donne accès (première facture payée, ou pendant l'essai de l'offre s'il y en a un). L'activation se fait normalement depuis le dashboard. Erreurs : 409 subscriptions_addon_exists (une autre offre est déjà active), 503 subscriptions_addon_unavailable (pas encore en vente). Limite : 10 appels par minute.
How is this guide?
Last updated on