Cas d’usage
Génération de factures en lot (bulk endpoint)
POST /v1/tenant/invoices/bulk — jusqu'à 50 factures par appel
Pour les workflows de facturation mensuelle (SaaS récurrent, paie, abonnements), Scell.io expose un endpoint bulk `POST /api/v1/tenant/invoices/bulk` qui accepte un tableau de 1 à 50 factures par requête. Chaque facture est traitée individuellement, le résultat retourne un tableau de réponses avec un statut par item (success / error). En cas d'échec partiel, les factures réussies sont créées (pas de transaction globale) et celles en erreur retournent un code détaillé. Pour les volumes > 50, paginer côté client. Le bulk respecte le rate limit global mais consomme un seul slot par appel.
À retenir
- Max 50 factures par requête
- Pas de transaction globale : succès partiels acceptés
- Réponse : tableau de résultats avec `index`, `status`, `invoice_id` ou `error`
- Consomme 1 slot rate-limit (vs 50 appels unitaires)
- Idempotency-Key valable au niveau du batch
- Latence ~3-5s pour 50 Factur-X EN16931
Exemple de code
import { ScellClient } from '@scell/sdk';
const scell = new ScellClient({ apiKey: process.env.SCELL_SECRET_KEY! });
const subscriptions = await loadActiveSubscriptions(); // 200 abonnés
// Chunker en batches de 50
for (let i = 0; i < subscriptions.length; i += 50) {
const chunk = subscriptions.slice(i, i + 50);
const batch = await scell.invoices.createBulk({
invoices: chunk.map((sub) => ({
format: 'factur-x',
buyer: sub.buyer,
lines: [{ description: `Abonnement ${sub.plan}`, quantity: 1, unit_price: sub.amount, vat_rate: 20 }],
external_id: sub.id, // pour le rapprochement
})),
});
for (const result of batch.results) {
if (result.status === 'error') console.error(`Index ${result.index}:`, result.error);
}
}