Switag par Switag

L'API qui propulse Switag.

Backend HTTP du portefeuille mobile Switag. JSON-only, OpenAPI 3.1, hébergé en Côte d'Ivoire. Cette page est l'entrée technique — pas de produit ici.

API live v1.0.0
60+
endpoints
9
pays UEMOA
JSON
only
OAS 3.1
OpenAPI

Démarrer

Swagger UI →
Référence interactive. « Try it out » sur chaque endpoint, directement dans le navigateur.
OpenAPI YAML →
Spec brute. À importer dans Postman, Stoplight ou pour générer un client mobile.
Healthz →
Probe live + ping Postgres. Utilisé par le load balancer pour la rotation.
GitHub →
Code source du backend Go. Pull requests bienvenues si tu es de l'équipe.

Endpoints disponibles

GET
/healthz
Liveness + ping base de données
POST
/v1/auth/phone/start
Envoyer un OTP par SMS au numéro saisi
POST
/v1/auth/phone/verify
Valider l'OTP → renvoie signup_token (signup) ou access_token (login)
POST
/v1/auth/identity/set
Saisir nom + prénom · signup_token requis
POST
/v1/auth/tag/set
Choisir le FlexTag · signup_token requis
POST
/v1/auth/pin/set
Définir le PIN → finalise le signup, renvoie l'access_token

Architecture en bref

Auth
JWT access ~1h + signup/login tokens court-vivants. Firebase Phone Auth en option. Triple facteur sur le refresh (phone + PIN + device).
Ledger
Double-entrée Postgres. Idempotency-key obligatoire sur toute écriture argentée. Rejouer la même clé = même résultat, jamais de double-débit.
Realtime
SSE /v1/me/events avec ring buffer par utilisateur et replay via Last-Event-ID. Heartbeat 5s pour traverser les proxies.
Mobile
Kotlin Multiplatform Compose. Android + iOS partagent commonMain — UI, API client, store, navigation.

Domaines fonctionnels

Auth & Profil →
Signup OTP, login, /me, sécurité (single-device mode, révocation à distance).
Wallet & Transferts →
Account, transactions paginées, P2P par tag, refund 1h, cash-in agent.
Tontines →
Épargne rotative collective — 3 sous-types : rotative, enchères, accumulation.
Cagnottes →
Collectes ponctuelles type cagnotte de mariage / santé / projet, avec tag public partageable.
Notifications →
Flux SSE temps réel (balance, transactions, tontines, cagnottes) + push FCM via le token enregistré sur l'appareil.
Devices →
Multi-device, listing, révocation à distance depuis le profil, registration des tokens FCM.

Authentification — flow complet

/v1/auth/phone/start → SMS OTP ├─ Signup → /phone/verify → signup_token │ → /identity/set │ → /tag/set │ → /pin/set → access_token └─ Login → /phone/verify → login_token → /pin/verify → access_token Refresh silencieux : /v1/auth/refresh (phone + PIN + device enregistré) Firebase Auth : /v1/auth/firebase/exchange (alternative au flow OTP)

SDK & Clients

Mobile (KMP)
Client Ktor partagé : mobile/shared/src/commonMain/kotlin/ci/pluxce/flexapp/api/SwitagApi.kt. Android + iOS l'utilisent tel quel.
Web (TypeScript)
Next.js dans web/. Landing produit + futur back-office partenaires/agents.
Auto-gen
openapi-generator consomme /openapi.yaml et produit un client dans n'importe quel langage en une commande.

Erreurs

Toute réponse non-2xx partage l'enveloppe ErrorBody. code est machine-readable et stable entre releases ; message est en français, prêt à afficher.

409 Conflict · ErrorBody 
{
  "code":    "tag_taken",
  "message": "Ce tag est déjà utilisé"
}

Quickstart

terminal · demande un OTP 
curl -X POST https://api.switag.com/v1/auth/phone/start \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+225 0707076277","purpose":"signup"}'