YAOKA Partners API

#C'est quoi cette API ?

L'API YAOKA Partners est un service web qui s'occupe de toute la facturation française pour vos clients OFs : générer les factures, les rendre conformes à la loi 2026, les pousser dans Pennylane, suivre les paiements.

Votre code Qualibox envoie des messages chez nous (ex: "crée une facture pour le client X, montant 1200 €"), et on s'occupe du reste. C'est une API REST classique — pas de truc exotique.

#Prérequis avant de commencer

Avant de coder, assurez-vous d'avoir :

• Une master API key YAOKA — on vous la donne après le call de démo. Ressemble à sk_qbx_test_xxxxxxxxxxxx. La test dedans = mode sandbox (gratuit, sans effets réels).
• Un client HTTP — n'importe lequel : fetch en JS, requests en Python, le client HTTP de Go, ou juste cURL pour tester.
• Capacité à recevoir des webhooks — une URL HTTPS publique côté Qualibox qui peut recevoir nos messages POST. Pour tester en local : ngrok ou cloudflare tunnel.
• Une base de données chez vous pour stocker, pour chaque OF que vous provisionnez : son orgId YAOKA + son apiKey per-org.

#Vocabulaire

Tous les termes qu'on utilise dans la doc, définis.

#Quickstart en 10 minutes

Du zéro à une vraie facture émise. Copiez-collez, ça marche.

Étape 0 — Stocker votre master key

Mettez votre clé dans une variable d'environnement. JAMAIS dans le code en clair, JAMAIS dans le browser.

# Dans votre fichier .env du backend Qualibox
YAOKA_MASTER_KEY=sk_qbx_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Étape 1 — Provisionner un OF

Premier appel. On crée l'OF dans notre DB et un compte Pennylane à son nom (en mode test, le compte Pennylane est mocké).

curl -X POST https://app.yaoka.fr/api/v1/orgs \
  -H "Authorization: Bearer $YAOKA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "FormaPro Excellence",
    "siret": "12345678901234",
    "email": "contact@formapro.fr",
    "firstName": "Marie",
    "lastName": "Dupont",
    "qualiboxRefId": "qbx-of-4567"
  }'

Ce que vous recevez :

{
  "orgId": "org_abc123",
  "apiKey": "sk_org_test_xyz789",
  "slug": "formapro-excellence",
  "isSandbox": true,
  "pennylane": {
    "companyId": 5184271,
    "simulated": true
  }
}

Étape 2 — Créer un client

Avec la per-org API key, créez un client (le client de l'OF — c'est lui qui va recevoir la facture).

curl -X POST https://app.yaoka.fr/api/v1/orgs/org_abc123/customers \
  -H "Authorization: Bearer sk_org_test_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "qbx-cust-9912",
    "type": "company",
    "name": "ACME Industries",
    "siret": "98765432109876",
    "emails": ["compta@acme.fr"]
  }'

Retour : { "customerId": "cust_qrs", "created": true }

Étape 3 — Émettre la facture (avec PDF Factur-X)

Le moment magique. On crée la facture, on génère le PDF Factur-X conforme, on push dans Pennylane. Le finalize: true dit "c'est pas un brouillon, attribue un numéro légal et fais tout le tralala".

curl -X POST https://app.yaoka.fr/api/v1/orgs/org_abc123/invoices \
  -H "Authorization: Bearer sk_org_test_xyz789" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "cust_qrs",
    "lines": [{
      "label": "Formation Excel niveau 2 — 14h",
      "quantity": 1,
      "unitPrice": 1200,
      "vatRate": 0
    }],
    "dueInDays": 30,
    "finalize": true
  }'

Retour :

{
  "invoiceId": "inv_klm",
  "number": "FAC-2026-0042",
  "status": "finalized",
  "totalTtc": 1200,
  "pdfUrl": "https://utfs.io/f/xxxxx.pdf",
  "pennylane": {
    "synced": true,
    "pennylaneImportId": "..."
  }
}

Le pdfUrl pointe vers le PDF Factur-X — c'est ce que vous attachez/linkez dans l'email que Qualibox envoie au client OF.

#Authentification

Comment prouver à YAOKA que c'est bien vous qui appelez.

Header HTTP

Toutes les requêtes utilisent un header standard Authorization: Bearer <votre-clé>. Comme partout en REST.

Authorization: Bearer sk_qbx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: <uuid>   # recommandé sur tous les POST

Deux types de clés

Selon l'endpoint, vous utilisez l'une ou l'autre :

• Master key (sk_qbx_*) — UNE seule pour tout Qualibox. Permet de créer des OFs. Ne donne PAS accès aux opérations métier d'un OF. À stocker en env var côté backend.
• Per-org key (sk_org_*) — UNE par OF, retournée à la création de l'OF. Permet TOUT pour CET OF (clients, devis, factures…). À stocker dans votre DB Qualibox, indexée par votre référence interne.

#Sandbox vs Live

Le mode de votre master key détermine si c'est pour de vrai ou pour tester.

#Idempotency (anti-double-facture)

Comment éviter qu'un retry réseau crée 2 factures.

Imaginez : vous envoyez POST /invoices, votre dev timeout au bout de 30s sans réponse, votre code retry. Sans précaution, on crée 2 factures.

La solution : envoyez un header Idempotency-Key: <uuid-unique>. Si on voit le même key dans les 24h, on ne fait pas l'action 2 fois — on renvoie la réponse du 1er appel.

# 1er appel
curl -X POST .../invoices \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '...'
# → { "invoiceId": "inv_aaa", "number": "FAC-2026-0042" }

# 2e appel (même Idempotency-Key, même body)
curl -X POST .../invoices \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '...'
# → { "invoiceId": "inv_aaa", "number": "FAC-2026-0042" } (idem)

#Format des erreurs

Toutes les erreurs ont le même format JSON.

{
  "error": {
    "code": "validation_error",
    "message": "Le champ 'siret' doit contenir 14 chiffres",
    "field": "siret"
  }
}

Le champ code est stable — vous pouvez switcher dessus dans votre code pour réagir différemment selon le type d'erreur. Le message est lisible humain et peut changer entre versions.

#Rate limits

Combien d'appels par minute on accepte.

• Master key : 100 requêtes / minute
• Per-org key : 60 requêtes / minute
• Burst : 20 req/s pendant 5s autorisé (token bucket)

Chaque réponse contient les headers X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement, vous recevez un 429 — backoff exponentiel recommandé.

#Provisioning — créer un OF

Master key requise.

Crée un OF dans YAOKA. En mode live, crée aussi le compte Pennylane via notre Reseller API. Retourne une per-org API key (montrée 1 fois).

Response

{
  "orgId": "org_abc123",
  "apiKey": "sk_org_test_xyz789",
  "slug": "formapro-excellence",
  "createdAt": "2026-05-23T14:30:00Z",
  "externalRefId": "qbx-of-4567",
  "isSandbox": true,
  "mode": "test",
  "pennylane": {
    "companyId": 5184271,
    "simulated": true,
    "error": null
  }
}

Status d'un OF (provisioning, Pennylane, stats 30j). Accepte master key OU per-org key.

OAuth Pennylane (post-provisioning)

Pour que YAOKA puisse pousser les factures dans le Pennylane de l'OF, l'OF doit autoriser l'accès via OAuth. Lancé depuis Qualibox. En sandbox, le flow est mocké (call /complete avec n'importe quel code suffit).

Body : { "redirectUri": "https://qualibox.fr/yaoka-callback" }. Renvoie { authUrl, state, sandbox }. Qualibox redirige l'OF vers authUrl.

Après que Pennylane ait redirigé l'OF avec un ?code=&state=, Qualibox POST le code ici. Body : { "code": "...", "state": "..." }. Réponse : { connected: true, pennylaneCompanyId }.

#Clients (de l'OF)

Per-org key requise. Les clients sont les entreprises/personnes que l'OF facture.

Exemple POST

{
  "externalRef": "qbx-cust-9912",
  "type": "company",
  "name": "ACME Industries",
  "siret": "98765432109876",
  "emails": ["compta@acme.fr"],
  "phone": "+33102030405",
  "address": {
    "street": "1 rue Test",
    "city": "Paris",
    "postalCode": "75001",
    "country": "FR"
  }
}

#Devis

Per-org key requise. Numérotation DEV-YYYY-NNNN automatique.

Exemple POST

{
  "customerId": "cust_qrs",
  "lines": [
    {
      "label": "Formation Excel niveau 2 — 14h",
      "quantity": 1,
      "unitPrice": 1200,
      "vatRate": 0
    }
  ],
  "validUntilDays": 30,
  "paymentConditions": "30 jours fin de mois"
}

Le status passe par : draft → finalized → sent → accepted → invoiced (ou declined / expired). Utilisez PATCH pour faire évoluer le status.

#Factures clients

Per-org key requise. Numérotation FAC-YYYY-NNNN continue (jamais réinitialisée — art. 242 nonies A CGI).

Créer + finaliser en 1 call

{
  "customerId": "cust_qrs",
  "lines": [
    {
      "label": "Formation Excel niveau 2 — 14h",
      "quantity": 1,
      "unitPrice": 1200,
      "vatRate": 0
    }
  ],
  "dueInDays": 30,
  "paymentMethods": ["transfer"],
  "qualiopiRefId": "qbx-session-9988",
  "finalize": true
}

Marquer payée

PATCH /orgs/{id}/invoices/{invoiceId}
{
  "status": "paid",
  "paidAt": "2026-06-15T10:30:00Z",
  "paymentMethods": ["transfer"]
}

Marquer une facture payée déclenche le webhook invoice.paid chez vous.

#Factures fournisseurs

Per-org key requise. Upload de PDFs émis par les fournisseurs de l'OF.

Exemple POST

{
  "supplierName": "Imprimerie Martin",
  "supplierSiren": "111222333",
  "invoiceNumber": "F-2026-118",
  "amountHt": 350,
  "amountTax": 70,
  "amountTtc": 420,
  "date": "2026-05-18T00:00:00Z",
  "dueDate": "2026-06-18T00:00:00Z",
  "fileUrl": "https://your-storage.com/invoice.pdf",
  "fileName": "facture-imprimerie-2026-05.pdf",
  "createdByUserId": "qbx-user-123"
}

#Notes de frais

Per-org key requise. Notes de frais des employés de l'OF.

Exemple POST

{
  "submittedById": "qbx-user-456",
  "title": "Déplacement client ACME — mai 2026",
  "amountHt": 23.75,
  "amountTax": 4.75,
  "amount": 28.50,
  "date": "2026-05-18T00:00:00Z",
  "category": "repas",
  "fileUrl": "https://your-storage.com/recu.jpg",
  "fileName": "recu-restaurant.jpg"
}

#C'est quoi un webhook ?

Un webhook est un message qu'on vous envoie (vs. l'API où c'est VOUS qui nous appelez). Quand un événement se passe chez nous (ex: facture payée), on POST un message JSON sur une URL HTTPS que vous nous donnez.

Cela évite que vous ayez à poller ("dis YAOKA, est-ce que la facture est payée ?" toutes les 5 min) — on vous prévient instantanément.

#Configurer les webhooks chez Qualibox

Étape 1 — Créer un endpoint chez vous

Côté Qualibox, créez une route HTTPS publique qui accepte des POST JSON. Exemple en Next.js :

// app/api/yaoka/webhooks/route.ts (côté Qualibox)
export async function POST(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-yaoka-signature");

  // 1. Vérifier la signature (voir section suivante)
  if (!verifyYaokaSignature(rawBody, signature, process.env.YAOKA_WEBHOOK_SECRET)) {
    return new Response("Invalid signature", { status: 401 });
  }

  // 2. Parser
  const event = JSON.parse(rawBody);

  // 3. Réagir selon le type
  switch (event.event) {
    case "invoice.paid":
      await markInvoicePaidInQualibox(event.data.invoiceId);
      break;
    case "org.provisioned":
      await markOFProvisioned(event.data.orgId);
      break;
    // ...
  }

  // 4. Répondre 200 RAPIDEMENT (sinon YAOKA va retry)
  return new Response("OK", { status: 200 });
}

Étape 2 — Nous donner l'URL

Dans votre dashboard admin YAOKA (ou par email pendant la phase sandbox), donnez-nous :

• L'URL : ex https://api.qualibox.fr/yaoka/webhooks
• Un secret partagé (qu'on génère ensemble) — sert à signer chaque message

#Vérifier la signature HMAC

Critique pour la sécurité — sans ça, n'importe qui peut vous envoyer de faux messages.

À chaque webhook, on inclut un header X-Yaoka-Signature: t=<timestamp>,v1=<hmac_hex>. Le HMAC est calculé sur `${timestamp}.${rawBody}` avec votre secret partagé.

Vérification en Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyYaokaSignature(
  rawBody: string,
  header: string | null,
  secret: string
): boolean {
  if (!header) return false;

  const [tsPart, sigPart] = header.split(",");
  const ts = tsPart.split("=")[1];
  const sig = sigPart.split("=")[1];

  // 1. Recalculer la signature attendue
  const signedPayload = `${ts}.${rawBody}`;
  const expected = createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  // 2. Comparer en timing-safe (évite les attaques par mesure de temps)
  return timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  );
}

#Liste des événements

15 types d'événements envoyés en webhook.

Format du payload

POST https://api.qualibox.fr/yaoka/webhooks
Content-Type: application/json
X-Yaoka-Signature: t=1748901234,v1=<hmac_hex>
X-Yaoka-Event-Id: evt_abc123

{
  "event": "invoice.paid",
  "eventId": "evt_abc123",
  "timestamp": 1748901234,
  "data": {
    "orgId": "org_abc",
    "invoiceId": "inv_klm",
    "invoiceNumber": "FAC-2026-0042",
    "totalTtc": 1200,
    "paidAt": "2026-05-23T15:30:00Z"
  }
}

Tous les événements

#Serveur MCP — bonus pour vos devs IA

Si vos devs utilisent Cursor, Claude Code, Windsurf ou tout agent IA, on a un package npm qui transforme notre API en tools utilisables directement par l'IA.

MCP = Model Context Protocol. Un standard ouvert (créé par Anthropic) qui permet à n'importe quel agent IA d'utiliser des outils externes. Notre serveur MCP expose 9 tools (créer un OF, émettre une facture, marquer payée, etc.).

Installation

# Pas d'installation locale — on lance directement via npx
npx -y @yaoka/partners-mcp

# Ou via pnpm dlx, bunx, peu importe

Configuration Claude Desktop

Édite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "yaoka": {
      "command": "npx",
      "args": ["-y", "@yaoka/partners-mcp"],
      "env": {
        "YAOKA_API_KEY": "sk_qbx_test_xxxxxxxxxxxx"
      }
    }
  }
}

Configuration Cursor

Édite ~/.cursor/mcp.json (ou .cursor/mcp.json à la racine de ton projet pour un scope projet) :

{
  "mcpServers": {
    "yaoka": {
      "command": "npx",
      "args": ["-y", "@yaoka/partners-mcp"],
      "env": {
        "YAOKA_API_KEY": "sk_qbx_test_xxxxxxxxxxxx"
      }
    }
  }
}

Configuration Windsurf / Cline / autres

La même config JSON fonctionne partout — c'est le standard MCP. Pour Windsurf : ~/.codeium/windsurf/mcp_config.json. Pour Cline (VS Code) : dans les settings de l'extension.

Redémarrez le client après config. Vous verrez les 9 tools YAOKA dans la liste disponible. Demandez par exemple : "Crée un OF FormaPro avec SIRET 12345678901234, email contact@formapro.fr" — l'IA appellera yaoka_provision_org toute seule.

Les 9 tools exposés

Usage depuis votre backend Next.js

import { experimental_createMCPClient } from "ai";
import { Experimental_StdioMCPTransport } from "ai/mcp-stdio";

const yaoka = await experimental_createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: "npx",
    args: ["-y", "@yaoka/partners-mcp"],
    env: { YAOKA_API_KEY: process.env.YAOKA_API_KEY! },
  }),
});

const tools = await yaoka.tools();
// Passer à n'importe quel LLM (Claude, Perplexity, GPT, Gemini)

Forker / patcher le serveur en local

Si vous voulez ajouter des tools custom, modifier le comportement, ou juste comprendre comment ça marche, le code source est ouvert sur npm et facile à lancer en local.

# 1. Clone le package depuis npm
npm pack @yaoka/partners-mcp
tar -xzf yaoka-partners-mcp-*.tgz && cd package

# 2. Installer les deps
pnpm install   # ou npm install

# 3. Build TypeScript
pnpm build     # → dist/

# 4. Lancer en mode dev (rebuild auto)
pnpm dev

# 5. Tester avec MCP Inspector (UI graphique pour debug)
npx @modelcontextprotocol/inspector node ./dist/index.js

MCP Inspector lance une UI sur http://localhost:5173 où vous voyez les tools, lancez des appels, et inspectez les requêtes/réponses. Pratique pour debug avant de wire dans Claude Desktop ou Cursor.

Pour pointer votre fork local sur la prod YAOKA : YAOKA_API_KEY=sk_qbx_test_… dans .env.local. Pour pointer sur votre dev local YAOKA (port 3000) : YAOKA_BASE_URL=http://localhost:3000.

#Erreurs courantes et solutions

#FAQ