Multi-Tenancy

La plateforme Voki utilise une architecture multi-tenant avec isolation complète des données par tenant. Ce guide explique le fonctionnement du système de tenants et comment interagir correctement avec l'API.

Concept

Chaque entreprise (cliente de Voki) est un tenant indépendant. L'isolation est garantie par :

• Un schéma PostgreSQL séparé par tenant
• Un JWT avec claim de tenant pour l'authentification
• Un header X-Tenant dans toutes les requêtes authentifiées

Identification du Tenant

Chaque tenant possède un slug unique qui l'identifie. Le slug est défini lors de la création du tenant et ne peut pas être modifié.

Exemples de slugs : avanter, clinica-abc, empresa-xyz

Fonctionnement

1. Connexion

Lors de la connexion, le tenant est indiqué dans le corps de la requête :

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "utilisateur@entreprise.com",
    "password": "motdepasse123",
    "tenant": "avanter"
  }'

Le token JWT retourné contient le tenant dans les claims :

{
  "sub": "user_uuid",
  "tenant": "avanter",
  "role": "manager",
  "exp": 1708387200
}

2. Requêtes Authentifiées

Après la connexion, toutes les requêtes doivent inclure :

• Authorization: Bearer {token} - Token JWT
• X-Tenant: {slug} - Slug du tenant

curl -X GET https://voki.avanter.com.br/api/v1/users \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Important

Le header X-Tenant doit correspondre au tenant du token JWT. En cas de divergence, la requête sera rejetée avec 401 Unauthorized.

3. Isolation des Données

Chaque requête opère exclusivement sur les données du tenant authentifié :

• Un utilisateur du tenant avanter n'accède jamais aux données du tenant clinica-abc
• Toutes les requêtes SQL sont exécutées dans le schéma du tenant
• Les IDs sont uniques au sein de chaque tenant, mais peuvent se répéter entre tenants

Architecture Technique

┌─────────────────────────────────────────────────┐
│                  PostgreSQL 16                    │
│                                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
│  │   public     │  │   avanter   │  │ clinica  │ │
│  │  (partagé)   │  │  (tenant)   │  │ (tenant) │ │
│  │             │  │             │  │          │ │
│  │ - companies │  │ - users     │  │ - users  │ │
│  │ - plans     │  │ - calls     │  │ - calls  │ │
│  │             │  │ - customers │  │ - ...    │ │
│  └─────────────┘  └─────────────┘  └──────────┘ │
└─────────────────────────────────────────────────┘

• Schéma public : Données partagées (entreprises, plans, configurations globales)
• Schéma par tenant : Données isolées (utilisateurs, appels, clients, enregistrements, etc.)

Création d'un Nouveau Tenant

Les nouveaux tenants sont créés via le flux d'inscription :

# 1. Valider le document
curl -X POST https://voki.avanter.com.br/api/signup/validate-document \
  -H "Content-Type: application/json" \
  -d '{"document": "12.345.678/0001-90", "document_type": "cnpj"}'

# 2. S'inscrire
curl -X POST https://voki.avanter.com.br/api/signup/register \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Nouvelle Entreprise",
    "document": "12.345.678/0001-90",
    "document_type": "cnpj",
    "admin_name": "Administrateur",
    "admin_email": "admin@nouvelleentreprise.com",
    "admin_password": "motDePasseSecure123",
    "plan": "professional"
  }'

# 3. Checkout (Asaas)
curl -X POST https://voki.avanter.com.br/api/signup/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "nouvelle-entreprise",
    "plan": "professional",
    "success_url": "https://...",
    "cancel_url": "https://..."
  }'

Bonnes Pratiques

1. Stockez le slug du tenant avec le token dans votre client
2. Incluez toujours le header X-Tenant - même si le token contient déjà le tenant
3. Ne codez pas les slugs en dur - obtenez-les depuis la connexion ou la configuration
4. Gérez les erreurs 401 - elles peuvent indiquer un token expiré OU un tenant invalide
5. Renouvelez les tokens avant leur expiration en utilisant le refresh token

Limites par Plan

Chaque tenant possède des limites basées sur le plan souscrit :

Ressource	Starter	Professional	Enterprise
Appels simultanés	2	10	Illimité
Utilisateurs	5	50	Illimité
Départements	3	20	Illimité
Enregistrement	Oui	Oui	Oui
Transcription IA	Non	Oui	Oui
Analytics avancé	Non	Oui	Oui

Consultez le plan actuel via GET /api/v1/billing/plan.