Comment YAOKA s'intègre
techniquement chez Qualibox.
Cette page détaille le fonctionnement de l'intégration : comment l'API REST s'appelle, comment un OF est créé puis facturé, comment Pennylane reçoit les factures, où sont stockés les PDFs, comment les webhooks fonctionnent. Lisible par les devs comme par les non-devs de l'équipe.
Un service en ligne qui s'occupe de tout ce qui touche aux factures : les générer, les rendre conformes à la loi, les envoyer dans Pennylane, suivre les paiements.
Vous n'avez pas besoin de comprendre comment ça marche en interne. Vous nous donnez les infos (qui facture qui, pour quoi, pour combien), nous on s'occupe du PDF, de la conformité légale, du suivi compta. Vos clients OFs voient toujours Qualibox, jamais YAOKA.
4 étapes, du moment où un OF s'inscrit chez vous au moment où il encaisse.
Un OF s'inscrit chez vous
Côté Qualibox
Votre formulaire habituel. SIRET, IBAN, email contact, logo.
Côté YAOKA (silencieux)
Aucune action côté nous, on n'existe pas encore pour cet OF.
Votre code dit "hé YAOKA, voici un nouvel OF"
Côté Qualibox
Un seul appel à notre API depuis votre backend. Vos devs recoivent : un identifiant pour cet OF + une clé d'accès secrète à stocker.
Côté YAOKA (silencieux)
On crée tout : la fiche OF dans notre base, le compte Pennylane via notre partenariat, on prépare la numérotation des factures.
Pennylane envoie un email à l'OF
Côté Qualibox
Rien à faire côté Qualibox — c'est Pennylane qui pilote ce moment.
Côté YAOKA (silencieux)
L'OF clique sur le lien Pennylane pour valider que Pennylane est sa Plateforme Agréée (obligation 2026). Un clic, 30 secondes.
À chaque fin de session de formation
Côté Qualibox
Votre code dit « hé YAOKA, émets cette facture » (1 appel). Vous récupérez immédiatement un lien vers le PDF et l'envoyez à l'OF / au client via votre système email habituel.
Côté YAOKA (silencieux)
On crée la facture, génère le PDF Factur-X conforme, push dans Pennylane. Quand l'OF est payé, on vous prévient.
Pour vos devs — exactement ce qu'il faut, rien de plus.
4 endpoints suffisent pour 90% des cas d'usage Qualibox. Authentification par Bearer token, idempotency via header, webhooks signés HMAC. Stack indépendante (Node, Python, Go, peu importe — c'est du REST). La documentation complète couvre tous les endpoints, la sandbox, les erreurs.
Setup de l'environnement
YAOKA vous fournit un client_id + client_secret OAuth (depuis le dashboard admin YAOKA). Stockez-les en variables d'environnement côté serveur — jamais dans le navigateur.
# .env.local (dev) / vault de prod YAOKA_CLIENT_ID=qualibox YAOKA_CLIENT_SECRET=sec_xxxxxxxxxxxxxxxxxxxxxxxxxxxx YAOKA_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx YAOKA_BASE_URL=https://app.yaoka.fr
Connecter un OF (OAuth flow)
L'OF clique sur un bouton 'Connecter YAOKA' dans Qualibox. Vous le redirigez vers /api/auth/oauth2/authorize. Il crée son compte YAOKA (ou se connecte), valide les scopes demandés, et revient chez vous avec un code que vous échangez contre un access_token + refresh_token. Stockez-les dans votre table users (un set par OF connecté).
# 1. Redirection depuis Qualibox vers YAOKA
GET https://app.yaoka.fr/api/auth/oauth2/authorize
?client_id=$YAOKA_CLIENT_ID
&response_type=code
&redirect_uri=https://app.qualibox.fr/oauth/callback
&scope=openid+email+invoices:write+customers:write+quotes:write
&state=<random-csrf-token>
# 2. YAOKA → écran de consent → callback Qualibox avec ?code=xxx&state=yyy
# 3. Qualibox échange le code (POST côté serveur)
POST https://app.yaoka.fr/api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=xxx
&redirect_uri=https://app.qualibox.fr/oauth/callback
&client_id=$YAOKA_CLIENT_ID
&client_secret=$YAOKA_CLIENT_SECRET
# Réponse
{
"access_token": "RANDOM_32CHARS",
"refresh_token": "RANDOM_32CHARS",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid email invoices:write ..."
}Émettre une facture pour un OF
Avec l'access_token de l'OF (et son organizationId que vous récupérez via /api/auth/oauth2/userinfo après l'OAuth). Pré-requis : un customerId obtenu via POST /api/v1/orgs/[orgId]/customers. finalize:true assigne immédiatement le numéro (FAC-YYYY-NNNN), génère le PDF Factur-X (conforme art. 242 nonies A CGI), et push dans Pennylane si l'OAuth Pennylane est connecté côté OF.
POST /api/v1/orgs/AbC123XyZ/invoices HTTP/1.1
Authorization: Bearer $ACCESS_TOKEN
Idempotency-Key: session-789-invoice
Content-Type: application/json
{
"customerId": "cus_xxx",
"lines": [
{
"label": "Formation bureautique - Session juin 2026",
"quantity": 14,
"unitPrice": 350,
"vatRate": 0
}
],
"dueInDays": 30,
"finalize": true
}
# Réponse 201
{
"invoiceId": "inv_aBc123",
"number": "FAC-2026-0042",
"status": "finalized",
"totalTtc": "4900.00",
"currency": "EUR",
"pdfUrl": "https://xxx.ufs.sh/f/.../FAC-2026-0042.pdf" ← CDN uploadthing
}Recevoir et vérifier un webhook
Configurez l'URL de réception dans le dashboard Webhooks. À chaque événement (invoice.paid, quote.accepted, etc.), on POST chez vous avec une signature HMAC SHA-256. Retry exponentiel sur 24h en cas de 5xx.
// Node.js / Next.js Route Handler
import { createHmac, timingSafeEqual } from "node:crypto";
export async function POST(req: Request) {
const rawBody = await req.text();
const header = req.headers.get("x-yaoka-signature") ?? "";
const [tsPart, sigPart] = header.split(",");
const ts = tsPart.split("=")[1];
const sig = sigPart.split("=")[1];
const signed = ts + "." + rawBody;
const expected = createHmac("sha256", process.env.YAOKA_WEBHOOK_SECRET!)
.update(signed)
.digest("hex");
if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
return new Response("Invalid signature", { status: 401 });
}
const { event, data } = JSON.parse(rawBody);
// event: "invoice.paid" | "quote.accepted" | "org.provisioned" | ...
// Traitez l'événement, répondez 200 dans les 10s.
return new Response("ok", { status: 200 });
}Pour aller plus vite
- Serveur MCP officiel :
npx -y @yaoka/partners-mcp— vos devs Cursor / Claude Desktop appellent l'API en langage naturel. - OpenAPI 3.1 spec téléchargeable sur
/api/v1/openapi.json— import direct dans Postman, Insomnia, ou génération de SDK. - Sandbox illimitée : les OFs en mode test ne sont pas facturés et n'ont pas d'effet réel (pas de push Pennylane). Cassez tout sans risque.
- Idempotency keys obligatoirement sur tous les POST mutables — retry safe par défaut, fenêtre 24h.
Vos OFs ne sauront jamais qu'on existe. C'est exactement le but.
L'organisme de formation
Voit
Qualibox (toujours, c'est son outil)
Email Pennylane (1× pour valider sa désignation)
Ses factures (mais elles sont envoyées par votre code à vous, depuis vos serveurs email)
Ne voit jamais
L'URL app.yaoka.fr
Le mot "YAOKA" nulle part
Vous, équipe Qualibox
Voit
Votre app Qualibox (votre outil principal)
Notre API (intégrée par vos devs)
Notre dashboard admin (pour suivre vos OFs, votre facture mensuelle YAOKA)
Ne voit jamais
Les écrans de l'OF — il vit dans Qualibox
Nous (YAOKA)
Voit
Les données métier en backend
Les logs, le monitoring, les factures émises
Rien de privé qui ne soit pas strictement nécessaire à la facturation
Ne voit jamais
Rien — on est invisibles pour vos OFs par construction
Septembre 2026 — ce qui change, en français, pour quelqu'un qui ne suit pas l'actualité fiscale.
1. Factur-X devient obligatoire
Aujourd'hui une facture peut être un PDF lambda. À partir du 1er septembre 2026, elle doit être au format Factur-X : un PDF qui contient en plus un fichier XML caché (lisible par les administrations sans intervention humaine). C'est un format européen.
2. Chaque entreprise doit désigner une PDP
PDP = Plateforme de Dématérialisation Partenaire. C'est une entreprise agréée par l'État qui sert d'intermédiaire entre les entreprises et le fisc. Pennylane est PDP (et c'est aussi un logiciel de compta très utilisé). Quand on crée le compte Pennylane d'un OF, il reçoit un email pour confirmer que Pennylane est sa PDP. Un clic.
3. Toutes les factures B2B doivent passer par cette PDP
On ne peut plus envoyer une facture en direct au client — elle doit transiter par la PDP qui la transmet au fisc. C'est justement ce que YAOKA fait : on génère le Factur-X, on le push dans Pennylane, Pennylane le transmet au client et au fisc.
Concrètement pour vous : sans YAOKA (ou un équivalent), vos clients OFs ne peuvent plus facturer légalement à partir de sept. 2026. Avec YAOKA, vous offrez la conformité intégrée à votre offre Qualibox — c'est un argument commercial énorme.
Conçu comme une plateforme bancaire, pas comme un SaaS.
Cloisonnement strict des données
Les données d'un OF ne peuvent JAMAIS être lues par un autre OF, ni par un autre partenaire. C'est verrouillé au niveau du code, pas juste un check applicatif.
Chaque facture est unique et infalsifiable
Numérotation continue, jamais réinitialisée, validée par notre code. C'est ce que la loi française exige (art. 242 nonies A CGI).
Vos secrets sont chiffrés
Les tokens Pennylane et les clés d'accès API sont stockés chiffrés en base. Personne ne peut les lire, même nos devs internes.
Tout est tracé
Chaque appel API de Qualibox vers nous est enregistré (qui, quand, quoi, depuis quelle IP). Vous pouvez auditer à tout moment.
Votre clé maître est révocable
Si elle fuite (ex: un dev part fâché), vous la révoquez en 1 clic. Une nouvelle clé est générée et l'ancienne ne marche plus instantanément.
Notifications signées cryptographiquement
Quand on vous envoie un message webhook (ex: facture payée), vous vérifiez la signature pour être sûr que ça vient bien de nous et pas d'un attaquant.
Les mots qu'on utilise, expliqués.
API
Un moyen pour le code d'une app (Qualibox) de parler au code d'une autre app (YAOKA), sans humain entre les deux. Comme un téléphone entre deux logiciels.
Endpoint
Une adresse précise dans notre API. Ex: "crée un OF" est un endpoint, "émets une facture" en est un autre.
OAuth client (client_id + client_secret)
L'identité de Qualibox dans le système YAOKA. On vous donne un client_id (public) + un client_secret (à garder secret). Ils servent à initier les flows OAuth pour le compte de vos OFs.
access_token
Le jeton qu'un OF connecté vous a délégué pour appeler l'API YAOKA en son nom. Reçu après l'OAuth flow, valide 1h, renouvelable via refresh_token.
OF
Organisme de Formation. Vos clients, en gros.
Factur-X
Le format de facture obligatoire à partir de sept. 2026. C'est un PDF avec un fichier XML caché dedans (le PDF est lu par les humains, le XML par les machines).
Pennylane
Un logiciel de comptabilité français très utilisé. C'est aussi une PDP (voir ci-dessous). On y push automatiquement chaque facture émise.
PDP
Plateforme de Dématérialisation Partenaire. Une entreprise agréée par l'État pour transmettre les factures électroniques entre entreprises et au fisc. Pennylane est une PDP.
Sandbox
Un mode "bac à sable" pour tester sans rien casser. Les factures sandbox ne sont pas envoyées à Pennylane, pas facturées chez nous, et peuvent être supprimées librement.
Webhook
Un message automatique qu'on vous envoie quand quelque chose d'important se passe (ex: une facture est payée). Vous configurez une adresse URL chez vous, on push dessus.
OAuth
Un protocole pour donner accès à un service tiers sans partager son mot de passe. Quand l'OF « connecte » Pennylane à YAOKA, c'est un OAuth.
Les vraies questions qu'on nous pose.
Si demain Qualibox arrête le partenariat, qu'est-ce qui se passe pour mes OFs ?
Tous leurs comptes Pennylane sont à eux (créés à leur nom, sous leur SIRET). Ils gardent l'accès complet à leur compta et leurs factures. Côté YAOKA, on archive tout pendant 10 ans (obligation légale) et on vous donne un export complet sur simple demande.
Pourquoi pas faire un partenariat direct avec Pennylane sans passer par YAOKA ?
Vous pourriez, mais ça veut dire que vous codez vous-même : génération Factur-X, gestion de la numérotation légale, archivage 10 ans, certification, mises à jour réglementaires. C'est ~12-18 mois de dev avec une équipe spécialisée. YAOKA, c'est 2 semaines d'intégration pour un de vos devs.
Mes OFs ont déjà un compte Pennylane. Ça marche aussi ?
Oui — quand on « crée » un compte Pennylane via notre API, on vérifie d'abord si le SIRET existe déjà chez eux. Si oui, on linke. Si non, on crée.
Et si l'OF refuse de désigner Pennylane comme PDP ?
Vos OFs ne peuvent pas refuser — ils DOIVENT avoir une PDP désignée à partir de sept. 2026, sinon ils n'ont plus le droit de facturer en B2B. On les force pas — on leur propose la solution la plus simple (Pennylane est la PDP la plus utilisée en France).
Combien de temps prend l'intégration côté Qualibox ?
1-2 semaines pour un dev expérimenté. Notre API est volontairement simple : 7 endpoints principaux. Vous trouverez la doc technique complète sur /partners/dev.
Vous avez d'autres partenaires comme nous ?
Aujourd'hui Qualibox est notre premier partenaire OAuth. On veut faire vivre cette intégration au top avant d'en signer d'autres. C'est une bonne nouvelle pour vous : vous êtes prioritaires sur le roadmap.
L'IA YAOKA, c'est quoi le rapport ?
C'est notre produit core — un copilote business pour TPE qui fait briefing matinal, relances auto, alertes cashflow, etc. Pas inclus dans le pack « Partners API » pour Qualibox aujourd'hui, mais on pourra vous le proposer en upsell si vos OFs sont demandeurs.
Pour aller plus loin techniquement.
Toute l'intégration est documentée publiquement. L'authentification, les 15+ endpoints REST, la sandbox, les webhooks signés, l'OpenAPI 3.1 et le serveur MCP officiel pour les agents IA.