Official SDKs & API Reference

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ── B2B Invoice (Factur-X) ──────────────────────────────────────────
6const { data: invoice } = await scell.invoices.create({
7  direction: 'outgoing',
8  output_format: 'facturx',          // 'facturx' | 'ubl' | 'cii'
9  issue_date: '2026-06-01',
10  due_date: '2026-07-01',
11  currency: 'EUR',
12
13  // Seller (flat fields — server validates per country)
14  seller_name: 'QR Communication SAS',
15  seller_siret: '90347842500015',     // required if seller_country=FR
16  seller_vat_number: 'FR42903478425',
17  seller_country: 'FR',
18  seller_address: {
19    line1: '123 Avenue de la République',
20    postal_code: '75011',
21    city: 'Paris',
22    country: 'FR',
23  },
24
25  // Buyer — option 1: flat fields
26  buyer_name: 'GN IMMO',
27  buyer_siret: '49438068600076',      // required if buyer_country=FR && !buyer_is_individual
28  buyer_vat_number: 'FR42494380686',
29  buyer_country: 'FR',
30  buyer_address: {
31    line1: '453 Route Nationale 7',
32    postal_code: '13670',
33    city: 'Verquières',
34    country: 'FR',
35  },
36
37  // Amounts (HT + TVA = TTC)
38  total_ht: 2500.00,
39  total_tax: 500.00,
40  total_ttc: 3000.00,
41
42  // Lines (min 1)
43  lines: [
44    {
45      description: 'Prestation conseil transformation digitale',
46      quantity: 10,
47      unit: 'HUR',                    // UN/ECE Rec 20 (optional)
48      unit_price: 250.00,
49      tax_rate: 20.0,                 // 0 | 5.5 | 10 | 20
50      total_ht: 2500.00,
51      total_ttc: 3000.00,
52    },
53  ],
54});
55
56console.log(invoice.invoice_number);  // 'FAC-2026-000042'
57console.log(invoice.status);          // 'draft'
58console.log(invoice.download_url);    // presigned S3 URL
59
60// ── B2C Invoice (individual — no SIRET/VAT required) ────────────────
61const { data: b2cInvoice } = await scell.invoices.create({
62  direction: 'outgoing',
63  output_format: 'facturx',
64  issue_date: '2026-06-01',
65  due_date: '2026-06-15',
66  currency: 'EUR',
67  seller_name: 'QR Communication SAS',
68  seller_siret: '90347842500015',
69  seller_country: 'FR',
70  seller_address: { line1: '123 Avenue de la République', postal_code: '75011', city: 'Paris', country: 'FR' },
71  buyer_name: 'Marie Dupont',
72  buyer_is_individual: true,          // BT-46/47/48 omitted, no L441-10
73  buyer_country: 'FR',
74  buyer_address: { line1: '12 Rue des Lilas', postal_code: '75011', city: 'Paris', country: 'FR' },
75  total_ht: 150.00,
76  total_tax: 30.00,
77  total_ttc: 180.00,
78  lines: [{ description: 'Formation individuelle', quantity: 1, unit_price: 150.00, tax_rate: 20.0, total_ht: 150.00, total_ttc: 180.00 }],
79});
80
81// ── With buyer_id (registry shortcut) ───────────────────────────────
82const { data: fromRegistry } = await scell.invoices.create({
83  direction: 'outgoing',
84  output_format: 'facturx',
85  issue_date: '2026-06-01',
86  due_date: '2026-07-01',
87  currency: 'EUR',
88  seller_name: 'QR Communication SAS',
89  seller_siret: '90347842500015',
90  seller_country: 'FR',
91  seller_address: { line1: '123 Avenue de la République', postal_code: '75011', city: 'Paris', country: 'FR' },
92  buyer_id: '019e2dbe-362a-7105-87a5-f45fad1382ed',  // auto-snapshot
93  total_ht: 2500.00,
94  total_tax: 500.00,
95  total_ttc: 3000.00,
96  lines: [{ description: 'Consulting', quantity: 10, unit_price: 250.00, tax_rate: 20.0, total_ht: 2500.00, total_ttc: 3000.00 }],
97});
98
99// ── Sub-tenant scoping ──────────────────────────────────────────────
100const { data: subInvoice } = await scell.invoices.create({
101  sub_tenant_id: '019d5ea8-0000-0000-0000-000000000000',
102  direction: 'outgoing',
103  output_format: 'facturx',
104  issue_date: '2026-06-01',
105  due_date: '2026-07-01',
106  currency: 'EUR',
107  buyer_id: '019e2dbe-362a-7105-87a5-f45fad1382ed',
108  total_ht: 1000.00,
109  total_tax: 200.00,
110  total_ttc: 1200.00,
111  lines: [{ description: 'Service', quantity: 1, unit_price: 1000.00, tax_rate: 20.0, total_ht: 1000.00, total_ttc: 1200.00 }],
112});
113
114// ── Standard invoice from a quote (parent_quote_id, since v2.21.0) ──
115// Lien soft vers un devis source pour tracabilite (devis -> facture).
116// IMPORTANT : parent_quote_id est accepte UNIQUEMENT pour invoice_type='standard'
117// (ou champ omis). Pour une facture d'acompte ou de solde, utiliser les
118// endpoints dedies POST /quotes/{id}/convert-to-deposit / convert-to-balance.
119// Backend : 404 PARENT_QUOTE_NOT_FOUND si le devis n'appartient pas au tenant,
120// 422 si invoice_type='deposit' ou 'balance' est combine avec parent_quote_id.
121const { data: fromQuote } = await scell.invoices.create({
122  direction: 'outgoing',
123  output_format: 'facturx',
124  issue_date: '2026-06-01',
125  due_date: '2026-07-01',
126  currency: 'EUR',
127  parent_quote_id: '019e3f00-7c8d-7000-9000-000000000001',  // UUID du devis source
128  buyer_id: '019e2dbe-362a-7105-87a5-f45fad1382ed',
129  total_ht: 2500.00,
130  total_tax: 500.00,
131  total_ttc: 3000.00,
132  lines: [{ description: 'Consulting (devis DEV-2026-0042)', quantity: 10, unit_price: 250.00, tax_rate: 20.0, total_ht: 2500.00, total_ttc: 3000.00 }],
133});
134

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Update a draft invoice (only draft status allowed)
6// All fields are optional — partial update via PUT /invoices/{id}
7const { data: invoice } = await scell.invoices.update(
8  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
9  {
10    // Change due date
11    due_date: '2026-08-15',
12
13    // Update buyer info
14    buyer_name: 'GN IMMO — Siège social',
15    buyer_email: 'comptabilite@gnimmo.com',
16
17    // Update buyer address
18    buyer_address: {
19      line1: '453 Route Nationale 7',
20      postal_code: '13670',
21      city: 'Verquières',
22      country: 'FR',
23    },
24
25    // Add shipping address (BG-13 EN16931)
26    buyer_shipping_address: {
27      name: 'Entrepôt Lyon',
28      line1: '15 Rue de l\'Industrie',
29      postal_code: '69003',
30      city: 'Lyon',
31      country: 'FR',
32    },
33
34    // Replace lines entirely
35    lines: [
36      {
37        description: 'Audit transformation digitale',
38        quantity: 5,
39        unit_price: 300.00,
40        vat_rate: 20.0,
41      },
42      {
43        description: 'Accompagnement mensuel',
44        quantity: 3,
45        unit_price: 500.00,
46        vat_rate: 20.0,
47      },
48    ],
49  }
50);
51
52console.log(invoice.status);  // still 'draft'
53

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Submit a draft invoice to the PDP network (Peppol/Chorus Pro)
6// Idempotent — calling twice returns the same transmitted_at
7const invoice = await scell.invoices.submit('019dfae2-abef-73e4-b6b2-e4cdae938f3b');
8
9console.log(invoice.status);         // 'transmitted'
10console.log(invoice.transmitted_at); // ISO 8601
11
12// Bulk submit multiple invoices at once
13const results = await scell.invoices.bulkSubmit([
14  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
15  '019dfae2-abef-73e4-b6b2-e4cdae938f3c',
16]);
17

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Mark an outgoing invoice as paid (manual payment)
6// Accepted statuses: validated, transmitted, sent, accepted
7// Returns 422 INVOICE_NOT_PAYABLE if status is draft or already paid
8const { data: invoice } = await scell.invoices.markPaid(
9  '019dfae2-abef-73e4-b6b2-e4cdae938f3b'
10);
11// invoice.status === 'paid'
12// invoice.paid_at === '2026-06-15T14:30:00Z'
13// invoice.payment_method === 'manual'
14
15// With optional payment details
16const { data: detailed } = await scell.invoices.markPaid(
17  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
18  {
19    payment_reference: 'VIR-2026-0542',
20    paid_at: '2026-06-14T09:00:00Z',
21    note: 'Virement reçu — relevé BNP 06/2026',
22  }
23);
24

1import { ScellApiClient } from '@scell/sdk';
2import { writeFileSync } from 'node:fs';
3
4const scell = new ScellApiClient('sk_live_your_api_key');
5
6// Download as Factur-X (PDF/A-3b + embedded CII XML)
7const facturx = await scell.invoices.download(
8  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
9  'facturx'
10);
11writeFileSync('invoice.pdf', Buffer.from(facturx));
12
13// Download as plain PDF (visual only, no embedded XML)
14const pdf = await scell.invoices.download(
15  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
16  'pdf'
17);
18
19// Download as raw XML (CII EN16931)
20const xml = await scell.invoices.download(
21  '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
22  'xml'
23);
24

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Delete a draft invoice — only 'draft' status allowed
6// Returns 422 if invoice is validated/transmitted/paid (ISCA immutability)
7await scell.invoices.delete('019dfae2-abef-73e4-b6b2-e4cdae938f3b');
8

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Read PDF and encode to base64
6const pdfBytes = await fs.readFile('contrat.pdf');
7const base64Pdf = pdfBytes.toString('base64');
8
9const signature = await scell.signatures.create({
10  // Required
11  title: 'Contrat de prestation',
12  document: base64Pdf,
13  document_name: 'contrat.pdf',
14  signers: [
15    {
16      first_name: 'Marie',
17      last_name: 'Dupont',
18      email: 'marie.dupont@example.com',
19      auth_method: 'email',
20      // Custom message with {OTP} placeholder (max 500 chars)
21      message: 'Bonjour Marie, votre contrat est pret. Code OTP: {OTP}',
22    },
23  ],
24  // Optional: where the signature box is dropped on the PDF
25  signature_positions: [
26    { page: 1, x: 70, y: 80, unit: 'percent' }, // unit: 'percent' (default) | 'pixel'
27  ],
28  // Optional: redirects after signing / cancelling
29  redirect_complete_url: 'https://yourapp.com/contracts/done',
30  redirect_cancel_url: 'https://yourapp.com/contracts/cancelled',
31  // Optional: 10-year eIDAS archiving
32  archive_enabled: true,
33});
34
35console.log(signature.id);
36console.log(signature.status);                    // 'pending' | 'waiting_signers' | ...
37console.log(signature.signers[0].signing_url);    // https://sign.scell.io/sign/{id}/{signerId}?...&signature=HMAC
38
39// Cancel a signature request
40await scell.signatures.cancel(signature.id);
41
42// Send a reminder to pending signers
43await scell.signatures.remind(signature.id);
44
45// Download the signed document
46const signed = await scell.signatures.download(signature.id, 'signed');
47
48// List signatures — scope automatique au tenant courant via sk_live_* / sk_test_*.
49// Filtres disponibles : status, environment ('production' | 'sandbox'), company_id,
50// sub_tenant_id (anti-IDOR — limité aux sub_tenants du tenant courant), per_page (max 100).
51const pending = await scell.signatures.list({
52  status: 'pending',
53  environment: 'production',
54  sub_tenant_id: '019d5ea8-0000-0000-0000-000000000000',
55  per_page: 50,
56});
57
58// --- Demande de signature au nom d'un sub-tenant (depuis 2026-05-11) ---
59// Passer sub_tenant_id dans le payload POST. La company emettrice
60// devient la 1re company du sub-tenant. 404 SUB_TENANT_NOT_FOUND si
61// le sub_tenant n'appartient pas au tenant courant.
62const signatureSub = await scell.signatures.create({
63  sub_tenant_id: '019d5ea8-0000-0000-0000-000000000000',
64  title: 'Contrat de prestation',
65  document: base64Pdf,
66  document_name: 'contrat.pdf',
67  signers: [{ first_name: 'Marie', last_name: 'Dupont', email: 'marie@example.com', auth_method: 'email' }],
68});
69

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ── Total credit note (refund entire invoice) ───────────────────────
6const { data: totalCN } = await scell.creditNotes.create({
7  invoice_id: '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
8  reason: 'Annulation de la prestation',
9  type: 'total',
10});
11// totalCN.status === 'draft'
12// totalCN.credit_note_number === 'AVO-2026-000005'
13
14// ── Partial credit note (specific lines) ────────────────────────────
15const { data: partialCN } = await scell.creditNotes.create({
16  invoice_id: '019dfae2-abef-73e4-b6b2-e4cdae938f3b',
17  reason: 'Remboursement partiel — 2 articles retournés',
18  type: 'partial',
19  items: [
20    {
21      invoice_line_id: '019dfae2-bbbb-0000-0000-000000000001',
22      quantity: 2,    // credit 2 of original quantity
23    },
24  ],
25});
26
27// ── Check remaining creditable amount ───────────────────────────────
28const { data: remaining } = await scell.creditNotes.remainingCreditable(
29  '019dfae2-abef-73e4-b6b2-e4cdae938f3b'
30);
31// remaining.total_ht, remaining.total_ttc, remaining.lines[]
32
33// ── Update a draft credit note ──────────────────────────────────────
34const { data: updated } = await scell.creditNotes.update(partialCN.id, {
35  reason: 'Remboursement partiel — 3 articles retournés (corrigé)',
36});
37
38// ── Send credit note (irreversible — enters ISCA chain) ─────────────
39await scell.creditNotes.send(partialCN.id);
40
41// ── Download as PDF ─────────────────────────────────────────────────
42const pdf = await scell.creditNotes.download(partialCN.id);
43
44// ── Delete a draft (only draft status — ISCA compliance) ────────────
45await scell.creditNotes.delete(totalCN.id);
46
47// ── List with filters ───────────────────────────────────────────────
48const { data: list, meta } = await scell.creditNotes.list({
49  status: 'draft',
50  per_page: 25,
51});
52

1import { ScellClient } from '@scell/sdk';
2
3const client = new ScellClient('your_bearer_token');
4
5// Create a company
6const company = await client.companies.create({
7  name: 'ACME Corp',
8  siren: '123456789',
9  vat_number: 'FR12345678901',
10  address: {
11    street: '10 Rue de la Paix',
12    city: 'Paris',
13    postal_code: '75002',
14    country: 'FR',
15  },
16});
17
18// List all companies
19const companies = await client.companies.list();
20
21// Update a company
22await client.companies.update(company.id, { name: 'ACME Corp Updated' });
23
24// Initiate KYC/KYB verification
25await client.companies.initiateKyc(company.id);
26
27// Check KYC status
28const kyc = await client.companies.kycStatus(company.id);
29console.log(kyc.status); // 'pending' | 'approved' | 'rejected'
30

1import { ScellClient } from '@scell/sdk';
2
3const client = new ScellClient(process.env.SCELL_API_KEY!);
4
5// Référentiel sociétés par pays (GET /v1/reference/countries, authentifié).
6// Permet d'adapter un formulaire de saisie acheteur/vendeur au pays choisi.
7
8// 1. Lister tous les pays catalogués
9const countries = await client.reference.countries();
10
11// 2. Récupérer un pays précis (code ISO 3166-1 alpha-2)
12const fr = await client.reference.country('FR');
13
14console.log(fr);
15// {
16//   code: 'FR',
17//   name: 'France',
18//   known: true,
19//   is_eu: true,
20//   currency: 'EUR',
21//   vat: {
22//     label: 'Numéro de TVA intracommunautaire',
23//     example: 'FR12345678901',
24//     regex: '^FR[A-Z0-9]{2}\\d{9}$',   // utilisable via new RegExp(regex)
25//     vies_checkable: true,             // vérifié contre le registre VIES
26//   },
27//   national_id: {
28//     label: 'SIREN / SIRET',
29//     scheme: '0002',                   // code ISO 6523 du registre
30//     example: '12345678901234',
31//     regex: '^(\\d{9}|\\d{14})$',
32//     required_for_b2b: true,
33//   },
34//   legal_forms: [
35//     { code: 'SAS', label: 'SAS — Société par actions simplifiée' },
36//     { code: 'SARL', label: 'SARL — Société à responsabilité limitée' },
37//     // ...
38//   ],
39// }
40
41// 3. Construire dynamiquement un formulaire adapté au pays sélectionné
42const de = await client.reference.country('DE');
43const idLabel = de.national_id.label;          // "Handelsregisternummer"
44const idRegex = de.national_id.regex;          // null => saisie libre acceptée
45const legalFormOptions = de.legal_forms;        // pour une liste déroulante
46const validate = idRegex ? new RegExp(idRegex) : null;
47
48// Un pays non catalogué renvoie known=false + un format permissif (regex null) :
49// le client doit alors accepter la saisie libre, sans bloquer.
50const xx = await client.reference.country('ZZ');
51console.log(xx.known); // false
52

1interface CountryReference {
2  code: string;            // ISO 3166-1 alpha-2 (FR, DE, BE, …)
3  name: string | null;     // nom du pays
4  known: boolean;          // false = pays non catalogué (fallback permissif)
5  is_eu: boolean;          // appartenance à l'Union européenne
6  currency: string | null; // devise ISO 4217 (EUR, SEK, …)
7
8  vat: {
9    label: string;              // libellé localisé ("Numéro de TVA intracommunautaire")
10    example: string | null;     // exemple ("FR12345678901")
11    regex: string | null;       // motif ancré JS-compatible, null si non vérifié
12    vies_checkable: boolean;    // vérifiable contre le registre VIES (UE)
13  };
14
15  national_id: {
16    label: string;              // libellé du registre ("SIREN / SIRET", "KvK-nummer", …)
17    scheme: string | null;      // code ISO 6523 / Peppol EAS ("0002" SIRENE, "0106" KvK)
18    example: string | null;     // exemple ("12345678901234")
19    regex: string | null;       // motif ancré, null = format non vérifié → saisie libre
20    required_for_b2b: boolean;  // identifiant requis en B2B pour ce pays
21  };
22
23  legal_forms: Array<{
24    code: string;   // code stable ("SAS", "GMBH", "LTD", …)
25    label: string;  // libellé pour une liste déroulante
26  }>;
27}

1import { ScellClient } from '@scell/sdk';
2
3const client = new ScellClient('your_bearer_token');
4
5// Create a new API key
6const key = await client.apiKeys.create({
7  name: 'Production Key',
8  environment: 'live', // 'live' | 'test'
9});
10
11console.log(key.id);
12console.log(key.key); // sk_live_... (shown only once)
13
14// List all API keys
15const keys = await client.apiKeys.list();
16
17// Delete an API key
18await client.apiKeys.delete(key.id);
19

1import { ScellClient } from '@scell/sdk';
2
3const client = new ScellClient('your_bearer_token');
4
5// Create a webhook endpoint
6const webhook = await client.webhooks.create({
7  url: 'https://yourapp.com/webhooks/scell',
8  events: [
9    'invoice.created',
10    'invoice.validated',
11    'signature.completed',
12    'balance.low',
13  ],
14  active: true,
15});
16
17console.log(webhook.id);
18console.log(webhook.secret); // wh_sec_... (for signature verification)
19
20// List all webhooks
21const list = await client.webhooks.list();
22
23// Update a webhook
24await client.webhooks.update(webhook.id, {
25  events: ['invoice.created', 'signature.completed'],
26});
27
28// Test a webhook (sends a test payload)
29await client.webhooks.test(webhook.id);
30
31// Regenerate the signing secret
32const newSecret = await client.webhooks.regenerateSecret(webhook.id);
33
34// View delivery logs
35const logs = await client.webhooks.logs(webhook.id);
36
37// Delete a webhook
38await client.webhooks.delete(webhook.id);
39

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ─── Compliance overview ───────────────────────────────
6const status = await scell.fiscal.compliance();
7console.log(status.is_compliant);   // true | false
8console.log(status.isca_status);
9
10// ─── Immutable ledger entries ──────────────────────────
11const entries = await scell.fiscal.entries();
12
13// ─── Closings ──────────────────────────────────────────
14const closings = await scell.fiscal.closings();
15await scell.fiscal.dailyClosing(); // Trigger a daily closing
16
17// ─── Integrity verification ───────────────────────────
18const integrity = await scell.fiscal.integrity();
19const history = await scell.fiscal.integrityHistory();
20const forDate = await scell.fiscal.integrityForDate('2026-03-30');
21
22// ─── Fiscal rules engine ──────────────────────────────
23const rules = await scell.fiscal.rules();
24const newRule = await scell.fiscal.createRule({
25  key: 'auto_daily_closing',
26  value: true,
27  description: 'Automatically trigger daily closings at midnight',
28});
29await scell.fiscal.updateRule(newRule.id, { value: false });
30const detail = await scell.fiscal.ruleDetail('auto_daily_closing');
31const ruleHist = await scell.fiscal.ruleHistory('auto_daily_closing');
32await scell.fiscal.exportRules();
33await scell.fiscal.replayRules();
34
35// ─── TSA Anchors ──────────────────────────────────────
36const anchors = await scell.fiscal.anchors();
37
38// ─── Kill switch (emergency halt) ─────────────────────
39const ksStatus = await scell.fiscal.killSwitchStatus();
40// activate/deactivate require the fiscal:admin scope + a reason >= 20 chars.
41// In production, the 1st call returns 403 OOB_CONFIRMATION_REQUIRED and emails
42// a confirmation_token — re-call with it to apply.
43await scell.fiscal.killSwitchActivate({
44  reason: 'Incident de securite confirme, gel des emissions',
45  // confirmation_token: '...', // production only
46});
47await scell.fiscal.killSwitchDeactivate({
48  reason: 'Incident resolu, reprise de la facturation normale',
49  // confirmation_token: '...',
50});
51
52// ─── Exports ──────────────────────────────────────────
53const fec = await scell.fiscal.fecExport();
54const forensic = await scell.fiscal.forensicExport();
55const attestation = await scell.fiscal.attestation(2026);
56const download = await scell.fiscal.attestationDownload(2026);
57
58// ─── ISCA self-attestation (NOMINATIVE — depuis v1.17.0) ──
59// Auto-attestation pour le tenant courant (donnees KYB)
60const tenantPdf = await scell.fiscal.iscaSelfAttestationDownload();
61fs.writeFileSync('attestation-tenant.pdf', Buffer.from(tenantPdf));
62
63// Auto-attestation pour un sub_tenant specifique
64const subPdf = await scell.fiscal.iscaSelfAttestationDownload('019d5ea8-...');
65fs.writeFileSync('attestation-sub-tenant.pdf', Buffer.from(subPdf));
66
67// Documents de conformite (non-nominatifs)
68const measures = await scell.fiscal.iscaMeasuresRegisterDownload();
69const dossier = await scell.fiscal.iscaTechnicalDossierDownload();
70

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Get overview statistics
6const overview = await scell.stats.overview();
7console.log(overview.total_invoices);
8console.log(overview.total_signatures);
9console.log(overview.total_revenue);
10
11// Get monthly breakdown
12const monthly = await scell.stats.monthly();
13monthly.forEach(m => {
14  console.log(m.month, m.invoices_count, m.revenue);
15});
16

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// List billing invoices
6const invoices = await scell.billing.invoices();
7
8// Get a specific billing invoice
9const inv = await scell.billing.showInvoice('billing_inv_id');
10
11// Download billing invoice PDF
12const pdf = await scell.billing.downloadInvoice('billing_inv_id');
13
14// Get current usage metrics
15const usage = await scell.billing.usage();
16console.log(usage.invoices_used);
17console.log(usage.signatures_used);
18console.log(usage.credits_remaining);
19
20// Top up credits
21await scell.billing.topUp({ amount: 100, payment_method: 'card' });
22
23// Confirm a pending top-up
24await scell.billing.confirmTopUp({ top_up_id: 'tu_id', confirmation_code: '1234' });
25
26// Pay a Scell.io billing invoice (depuis v2.2.0 - Wave 6 2026-05-10)
27// Initiates a Stripe PaymentIntent. Use the client_secret with Stripe.js
28// to complete the payment client-side; webhook marks invoice as paid.
29const intent = await scell.billing.payInvoice('billing_inv_id');
30console.log(intent.clientSecret);     // Pass to stripe.confirmCardPayment()
31console.log(intent.paymentIntentId);  // pi_xxx
32console.log(intent.amount);           // amount in cents (EUR)
33console.log(intent.status);           // requires_payment_method | requires_confirmation
34
35// List billing transactions
36const transactions = await scell.billing.transactions();
37

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Create a B2B buyer (French company — SIRET required)
6const buyer = await scell.buyers.create({
7  name: 'GN IMMO',
8  is_individual: false,
9  siret: '49438068600076',
10  vat_number: 'FR42494380686',
11  email: 'contact@gnimmo.com',
12  country: 'FR',
13  billing_address: {
14    line1: '453 Route Nationale 7',
15    postal_code: '13670',
16    city: 'Verquières',
17    country: 'FR',
18  },
19});
20
21// Create a B2C buyer (individual — no SIRET/VAT)
22const individual = await scell.buyers.create({
23  name: 'Marie Dupont',
24  is_individual: true,
25  email: 'marie.dupont@gmail.com',
26  country: 'FR',
27  billing_address: {
28    line1: '12 Rue des Lilas',
29    postal_code: '75011',
30    city: 'Paris',
31    country: 'FR',
32  },
33});
34
35// Use buyer_id when creating invoices (auto-snapshot)
36const invoice = await scell.invoices.create({
37  buyer_id: buyer.id,
38  due_date: '2026-07-15',
39  lines: [
40    { description: 'Consulting', quantity: 1, unit_price: 2500, tax_rate: 20 },
41  ],
42});
43

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Create a service product
6const service = await scell.products.create({
7  name: 'Consulting journalier',
8  description: 'Accompagnement technique sur site',
9  revenue_category: 'service',
10  unit: 'C62',
11  unit_price_ht: 1200,
12  default_tax_rate: 20,
13  sku: 'CONS-JOUR',
14  is_active: true,
15});
16
17// Create a goods product
18const goods = await scell.products.create({
19  name: 'Licence logicielle annuelle',
20  revenue_category: 'goods',
21  unit: 'C62',
22  unit_price_ht: 499,
23  default_tax_rate: 20,
24  default_discount_rate: 10,
25  sku: 'LIC-ANNUAL',
26});
27
28// Use product_id when creating a quote line (auto-fill + soft link)
29const quote = await scell.quotes.create({
30  buyer_id: 'buyer_uuid',
31  lines: [
32    {
33      product_id: service.id,  // pre-fills all line fields from the product
34      quantity: 3,
35    },
36  ],
37});
38
39// Save an ad-hoc line back to the catalogue
40const invoice = await scell.invoices.create({
41  buyer_id: 'buyer_uuid',
42  lines: [
43    {
44      description: 'Formation React avancée',
45      quantity: 1,
46      unit_price_ht: 800,
47      tax_rate: 20,
48      save_to_catalog: true,           // atomic backend upsert by name/SKU
49      product_category_id: 'cat_uuid', // optional: assign to a category
50    },
51  ],
52});
53

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// List all active products
6const { data: products } = await scell.products.list({ is_active: true });
7
8// Filter by revenue category
9const { data: services } = await scell.products.list({
10  revenue_category: 'service',
11  per_page: 50,
12});
13
14// Full-text search across name, description, and SKU
15const { data: results } = await scell.products.list({ q: 'consulting' });
16
17// Get a single product
18const product = await scell.products.get('product_uuid');
19
20// List product categories
21const { data: categories } = await scell.productCategories.list();
22
23// Create a category and assign products to it
24const category = await scell.productCategories.create({
25  name: 'Prestations de service',
26  color: '#0066FF',
27  position: 1,
28});
29
30// Assign product to category
31await scell.products.update(product.id, {
32  product_category_id: category.id,
33});
34

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ---------------------------------------------------------------------------
6// Mode 1 — Acheteur déjà enregistré dans le registre (buyer_id)
7// ---------------------------------------------------------------------------
8// Pré-résout le contexte TVA pour une ligne STANDARD (20 % par défaut FR→FR).
9// Le sub-tenant (s'il existe) est résolu côté serveur depuis la clé d'API.
10const fr = await scell.buyers.resolveVatContext({
11  buyer_id: '019cb416-b6db-730c-b3a5-f8b7a4512eb1',
12  line: {
13    category: 'STANDARD',
14    place_of_supply: 'FR',
15  },
16});
17
18console.log(fr.resolution);
19// {
20//   rate: 20,
21//   category: 'STANDARD',
22//   en16931_code: 'S',
23//   exemption_reason: null,
24//   justification: 'TVA française standard (art. 278 CGI)',
25//   is_auto_resolved: true,
26//   rule: 'R1_fr_domestic'
27// }
28
29// ---------------------------------------------------------------------------
30// Mode 2 — Acheteur inline (B2B UE avec numéro de TVA vérifié VIES)
31// ---------------------------------------------------------------------------
32// Autoliquidation (reverse charge) déclenchée automatiquement par la règle R2.
33const ue = await scell.buyers.resolveVatContext({
34  buyer: {
35    country: 'DE',
36    is_individual: false,
37    vat_number: 'DE123456789',
38    vat_number_valid: true, // typiquement validé via VIES en amont
39  },
40  line: { category: 'STANDARD' },
41});
42
43console.log(ue.resolution);
44// {
45//   rate: 0,
46//   category: 'REVERSE_CHARGE',
47//   en16931_code: 'AE',
48//   exemption_reason: 'reverse_charge',
49//   justification: 'TVA non applicable, art. 259-1 du CGI (autoliquidation)',
50//   is_auto_resolved: true,
51//   rule: 'R2_eu_b2b_vat_valid'
52// }
53
54// ---------------------------------------------------------------------------
55// Mode 3 — B2C UE sans numéro de TVA (TVA française restante)
56// ---------------------------------------------------------------------------
57// Règle R3 : pas de numéro de TVA valide → TVA du prestataire (art. 259-2 CGI).
58const b2cUe = await scell.buyers.resolveVatContext({
59  buyer: {
60    country: 'IT',
61    is_individual: true, // particulier italien
62  },
63  line: { category: 'STANDARD' },
64});
65
66console.log(b2cUe.resolution.rate); // 20 (TVA française)
67console.log(b2cUe.resolution.rule); // 'R3_eu_b2c_no_vat'
68
69// ---------------------------------------------------------------------------
70// Mode 4 — Override art. 259 A CGI via place_of_supply
71// ---------------------------------------------------------------------------
72// Service immobilier rendu en France à un client UE → TVA française même
73// si le buyer a un numéro de TVA valide (lieu de prestation = France).
74const immo = await scell.buyers.resolveVatContext({
75  buyer: {
76    country: 'DE',
77    is_individual: false,
78    vat_number: 'DE123456789',
79    vat_number_valid: true,
80  },
81  line: {
82    category: 'STANDARD',
83    place_of_supply: 'FR', // override 259 A : lieu du bien immobilier
84    service_nature: 'real_estate_service',
85  },
86});
87
88console.log(immo.resolution.rate); // 20 (TVA française appliquée)
89console.log(immo.resolution.rule); // 'R6_place_of_supply_override'
90
91// ---------------------------------------------------------------------------
92// Warnings — incohérence détectée si line.tax_rate est fourni
93// ---------------------------------------------------------------------------
94const check = await scell.buyers.resolveVatContext({
95  buyer_id: '019cb416-b6db-730c-b3a5-f8b7a4512eb1',
96  line: {
97    category: 'STANDARD',
98    tax_rate: 10, // valeur saisie par l'utilisateur, à valider
99  },
100});
101
102if (check.warnings.length > 0) {
103  console.warn('Incohérence TVA détectée :', check.warnings);
104  // [{ code: 'VAT_RATE_MISMATCH', expected: 20, actual: 10,
105  //    message: 'Le taux saisi diffère du taux résolu (R1_fr_domestic).' }]
106}
107
108// ---------------------------------------------------------------------------
109// Mode 5 — Livraison intracommunautaire de BIENS (supply_type='goods')
110// ---------------------------------------------------------------------------
111// supply_type discrimine l'exonération : biens → INTRACOM_GOODS (K, art. 262 ter)
112// au lieu de REVERSE_CHARGE (AE, services). À TOUJOURS renseigner pour une vente
113// transfrontalière de biens physiques.
114const biens = await scell.buyers.resolveVatContext({
115  buyer: { country: 'DE', is_individual: false, vat_number: 'DE123456789', vat_number_valid: true },
116  line: { category: 'INTRACOM_GOODS', supply_type: 'goods' },
117});
118console.log(biens.resolution.en16931_code);    // 'K'
119console.log(biens.resolution.exemption_reason); // 'intracom_goods'
120
121// ---------------------------------------------------------------------------
122// Émission : résolution AUTORITAIRE serveur + 409 VAT_CORRECTION_REQUIRED
123// ---------------------------------------------------------------------------
124// À la création, le serveur RE-RÉSOUT la TVA de chaque ligne. Si le taux fourni
125// est incohérent (ex : 20 % sur une vente intra-UE B2B au lieu de l'autoliquidation)
126// ET qu'aucune raison d'override n'est donnée, l'API renvoie un 409 et NE persiste
127// PAS la facture. Le builder `createInvoiceLine` émet les champs au bon endroit.
128import { createInvoiceLine, VatCorrectionRequiredError } from '@scell/sdk';
129
130try {
131  await scell.invoices.create({
132    direction: 'outgoing',
133    output_format: 'facturx',
134    issue_date: '2026-06-04',
135    currency: 'EUR',
136    // ... seller / buyer (B2B UE avec numéro TVA valide) ...
137    lines: [
138      createInvoiceLine({ category: 'REVERSE_CHARGE' })
139        .description('Prestation de conseil')
140        .unitPrice(1000)
141        .supplyType('services') // → AE, art. 283-2 (mention auto sur la facture)
142        .build(),
143    ],
144  } as Parameters<typeof scell.invoices.create>[0]);
145} catch (e) {
146  if (e instanceof VatCorrectionRequiredError) {
147    for (const c of e.corrections) {
148      console.warn(
149        `Ligne ${c.line_index} : ${c.provided_rate}% → ${c.suggested_rate}% ` +
150          `(${c.suggested_category}) — ${c.mention ?? ''}`
151      );
152    }
153    // → Accepter les taux suggérés, OU ajouter .overrideReason('...') sur la ligne.
154  }
155}
156

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ── Create a quote with signature ───────────────────────────────────
6const { data: quote } = await scell.quotes.create({
7  issue_date: '2026-06-01',
8  expiration_date: '2026-09-01',     // optional, defaults to +90 days
9  currency: 'EUR',
10  title: 'Proposition commerciale — Audit digital',
11  description: 'Prestation complète d\'audit et accompagnement.',
12
13  // Buyer (flat fields or buyer_id)
14  buyer_name: 'GN IMMO',
15  buyer_siret: '49438068600076',
16  buyer_country: 'FR',
17  buyer_email: 'contact@gnimmo.com',
18  buyer_address: {
19    line1: '453 Route Nationale 7',
20    postal_code: '13670',
21    city: 'Verquières',
22    country: 'FR',
23  },
24
25  // Signature options
26  signature_required: true,
27
28  // Callback URL — buyer is redirected here after accept/refuse
29  callback_url: 'https://myapp.com/quotes/callback',
30
31  // Lines
32  lines: [
33    {
34      description: 'Audit transformation digitale',
35      detail: 'Analyse SI existant + recommandations (5 jours)',
36      quantity: 5,
37      unit: 'jour',
38      unit_price_ht: 800.00,
39      tax_rate: 20.0,
40    },
41    {
42      description: 'Accompagnement mensuel',
43      quantity: 3,
44      unit: 'mois',
45      unit_price_ht: 1200.00,
46      tax_rate: 20.0,
47    },
48  ],
49});
50
51// quote.quote_number === 'DEV-2026-000012'
52// quote.status === 'draft'
53// quote.public_url === 'https://scell.io/q/{token}'
54
55// ── Send by email (generates public signable link) ──────────────────
56await scell.quotes.send(quote.id);
57
58// ── Duplicate a quote ───────────────────────────────────────────────
59const { data: copy } = await scell.quotes.duplicate(quote.id);
60
61// ── Convert accepted quote to deposit invoice (type 386) ────────────
62const { data: deposit } = await scell.quotes.convertToDeposit(quote.id, {
63  amount: 2000.00,     // or use percent: 30
64});
65// deposit.invoice_type === 'deposit'
66// deposit.invoice_number === 'FAC-2026-000043'
67
68// ── Convert to balance invoice (type 380 + BG-22 auto-deduction) ────
69const { data: balance } = await scell.quotes.convertToBalance(quote.id);
70

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// Create a sub-tenant
6const tenant = await scell.subTenants.create({
7  name: 'Partner Corp',
8  external_id: 'partner-001',
9  email: 'admin@partner-corp.com',
10  company: {
11    name: 'Partner Corp',
12    siren: '111222333',
13    address: {
14      street: '20 Boulevard Haussmann',
15      city: 'Paris',
16      postal_code: '75009',
17      country: 'FR',
18    },
19  },
20});
21
22console.log(tenant.id);
23console.log(tenant.tenant_key); // sk_live_... (cle secrete sk_*, pas de format tk_*)
24
25// List all sub-tenants
26const list = await scell.subTenants.list();
27
28// Get a specific sub-tenant
29const detail = await scell.subTenants.get(tenant.id);
30
31// Find by external ID
32const found = await scell.subTenants.findByExternalId('partner-001');
33
34// Update a sub-tenant
35await scell.subTenants.update(tenant.id, { name: 'Partner Corp (Updated)' });
36
37// Get sub-tenant stats
38const stats = await scell.subTenants.statsOverview(tenant.id);
39
40// Delete a sub-tenant
41await scell.subTenants.delete(tenant.id);
42
43// --- Supervision SuperPDP ---
44// Path: /api/v1/tenant/sub-tenants/{id}/... (middleware tenant.key).
45
46// Statut OAuth2 + KYB courant (cache 5 min)
47const status = await scell.subTenants.getSuperPdpStatus(tenant.id);
48
49// Forcer un poll cote SuperPDP (rate-limit 1/min)
50// 422 MISSING_ACCESS_TOKEN -> e.authorize_url a ouvrir dans le navigateur
51try {
52  await scell.subTenants.refreshSuperPdpStatus(tenant.id);
53} catch (e) {
54  if (e.code === 'MISSING_ACCESS_TOKEN') {
55    window.open(e.authorize_url, '_blank', 'noopener');
56  }
57}
58
59// Generer une URL OAuth fresh (sans passer par refresh)
60const { authorize_url, state } = await scell.subTenants.superpdpAuthorize(tenant.id);
61
62// Regenerer une URL signee (7j) pour reprendre le tunnel onboarding
63const { resume_url } = await scell.subTenants.getResumeUrl(tenant.id);
64
65// --- Delete avec politique ISCA ---
66try {
67  await scell.subTenants.delete(tenant.id);
68} catch (e) {
69  if (e.code === 'SUB_TENANT_HAS_COMPANIES') {
70    // Demander confirmation a l'utilisateur, puis cascade
71    await scell.subTenants.delete(tenant.id, { cascade: true });
72  } else if (e.code === 'SUB_TENANT_HAS_FISCAL_ENTRIES') {
73    // Factures emises -> impossible de supprimer. Desactiver a la place.
74    await scell.subTenants.update(tenant.id, { is_active: false });
75  }
76}
77
78// --- Suivi de seuils micro-entrepreneur (auto-entrepreneur FR) ---
79
80// Jauges de seuils (franchise TVA base/majoree + plafond du regime micro).
81// Regles datees (loi 2025-1044). Lecture seule, informational.
82const { data, disclaimer } = await scell.subTenants.getThresholds(tenant.id);
83for (const g of data.gauges) {
84  // g.category: 'goods' | 'service' | 'accommodation'
85  // g.kind: 'vat_franchise_base' | 'vat_franchise_majored' | 'micro_ceiling'
86  // g.level: null | 'warning_80' | 'warning_90' | 'base_exceeded' | 'majored_exceeded' | 'micro_ceiling_exceeded'
87  console.log(`${g.category}/${g.kind}: ${g.percent}% (${g.level ?? 'ok'})`);
88  if (g.actionable) {
89    console.warn(`Seuil franchi — projection: ${g.projected_crossing_date}`);
90  }
91}
92console.info(disclaimer); // toujours afficher le disclaimer (info non contractuelle)
93
94// Declarer le statut fiscal. vat_status='liable' bascule la facturation vers la
95// TVA (factures suivantes avec TVA, retrait de la mention art. 293 B).
96// vat_number requis (422 sinon). La demarche URSSAF/INPI reste a charge de l'AE.
97const res = await scell.subTenants.updateFiscalStatus(tenant.id, {
98  vat_status: 'liable',
99  vat_number: 'FR12345678901',
100});
101console.log(res.message);
102
103// --- Clotures par sous-tenant + telechargement CSV ---
104const { data: closings } = await scell.fiscal.closings({
105  closing_type: 'monthly',        // 'daily' | 'monthly' | 'annual'
106  sub_tenant_id: tenant.id,
107});
108const csv = await scell.fiscal.downloadClosing(closings[0].id); // ArrayBuffer (CSV)
109

1// TypeScript — @scell/sdk v2.13.0
2import { ScellClient } from '@scell/sdk';
3const client = new ScellClient({ apiKey: 'sk_live_...' });
4
5// Créer / remplacer l'échéancier
6await client.quotes.paymentSchedule.set('quote-uuid', [
7  { amount_type: 'percent', amount_value: 30,
8    milestone_label: 'À la commande',
9    auto_generate: true, due_date: '2026-06-01' },
10  { amount_type: 'percent', amount_value: 70,
11    milestone_label: 'À la livraison' },
12]);
13
14// Tracker du solde restant
15const summary = await client.quotes.paymentSchedule.summary('quote-uuid');
16// → { schedule, invoiced: { gross_ttc, net_ttc, remaining_ttc, remaining_pct }, next_due, overdue, superpdp_status }
17
18// Convertir une ligne en facture d'acompte
19const invoice = await client.quotes.paymentSchedule.convertLine(
20  'quote-uuid', 'line-uuid',
21  { send_email: true }
22);
23
24// 4 presets disponibles
25const presets = await client.quotes.paymentSchedule.presets();
26

1// TypeScript
2const result = await client.invoices.sendByEmail('invoice-uuid', {
3  recipient_email: 'compta@buyer.com', // optionnel
4  cc: ['manager@buyer.com'],
5  message: 'Merci pour votre confiance',
6});
7// → { sent_to, sent_at, message_id, cc }
8

1// TypeScript
2// Tenant master
3const branding = await client.branding.tenant.get();
4// → { is_complete, missing_fields, brand_logo_url, brand_primary_color, ... }
5
6await client.branding.tenant.update({
7  brand_logo_url: 'https://cdn.scell.io/.../logo.png',
8  brand_primary_color: '#1A73E8',
9  brand_email_footer: 'Société XYZ — SIRET 123456789',
10});
11
12// Sub-tenant
13await client.branding.subTenants.update('sub-tenant-uuid', {
14  brand_primary_color: '#10B981',
15});
16
17// Upload logo (presigned S3)
18const signed = await client.branding.tenant.uploadLogo('image/png');
19// Then PUT the file to signed.url, then persist signed.public_url
20
21// Preview — render the branded email as HTML (before sending anything)
22const html = await client.branding.tenant.preview();
23// e.g. show it in <iframe srcDoc={html} /> for a live preview
24const subHtml = await client.branding.subTenants.preview('sub-tenant-uuid');
25
26// Since v3.2.0 — direct multipart upload of the email logo (no presign round-trip)
27const updated = await client.branding.tenant.uploadLogoFile(file, 'logo.svg');
28// jpeg/png/webp/svg, max 2 MB — SVGs are normalized server-side
29await client.branding.subTenants.uploadLogoFile('sub-tenant-uuid', file);
30
31// Since v3.2.0 — live preview with NON-persisted overrides (try before saving)
32const draft = await client.branding.tenant.preview({
33  brand_primary_color: '#0066FF',
34  brand_email_footer: 'Essai de pied de page',
35});
36
37// Since v3.2.0 — toggle branding + computed footer
38await client.branding.tenant.update({ brand_email_enabled: false });
39// branding.computed_email_footer (read-only): footer computed from the company,
40// used at render time when brand_email_footer is empty
41

1// TypeScript — @scell/sdk v2.13.1
2import { ScellClient } from '@scell/sdk';
3const client = new ScellClient({ apiKey: 'sk_live_...' });
4
5await client.quotes.create({
6  issue_date: '2026-05-24',
7  valid_until: '2026-06-24',
8  buyer_id: 'buyer-uuid',
9  lines: [{ description: 'Mission', quantity: 1, unit_price_ht: 12000, tax_rate: 20 }],
10  total_ht: 12000, total_tax: 2400, total_ttc: 14400,
11  callback_url: 'https://mon-site.com/devis-signe',
12});
13
14// Buyer signe -> redirige vers :
15// https://mon-site.com/devis-signe?status=signed&quote_id=...&quote_number=DEV-2026-0042
16//
17// Buyer refuse avec motif "Prix trop élevé" -> :
18// https://mon-site.com/devis-signe?status=refused&quote_id=...&quote_number=...&reason=Prix+trop+%C3%A9lev%C3%A9
19

1// TypeScript — @scell/sdk v2.14.0
2const summary = await client.quotes.paymentSchedule.summary('quote-uuid');
3
4// summary.lines est maintenant peuplé : PaymentScheduleLine[]
5summary.lines.forEach((line) => {
6  const isNext = line.id === summary.next_due?.line_id;
7  const isOverdue = line.is_overdue;
8  const isPast = line.status === 'invoiced';
9  // → render tracker visuel avec highlight
10});
11
12// summary.invoiced.remaining_ttc = montant restant à facturer
13// summary.invoiced.remaining_pct = % restant
14

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ── 1. First deposit: create a new group ────────────────────────
6const deposit1 = await scell.invoices.create({
7  invoice_type: 'deposit',
8  deposit_total_ht: 10000,                          // Total deal = 10 000 € HT
9  deposit_reference_text: 'Proposition commerciale signée le 15/05/2026',
10  direction: 'outgoing',
11  output_format: 'facturx',
12  issue_date: '2026-05-15',
13  due_date: '2026-05-30',
14  total_ht: 3000,                                    // 30% deposit
15  total_tax: 600,
16  total_ttc: 3600,
17  seller_siret: '12345678901234',
18  seller_name: 'Ma Société',
19  seller_address: { line1: '1 rue Example', postal_code: '75001', city: 'Paris', country: 'FR' },
20  buyer_name: 'Client SA',
21  buyer_siret: '98765432109876',
22  buyer_address: { line1: '2 avenue Test', postal_code: '69001', city: 'Lyon', country: 'FR' },
23  lines: [{ description: 'Acompte 30%', quantity: 1, unit_price: 3000, tax_rate: 20, total_ht: 3000, total_tax: 600, total_ttc: 3600 }],
24});
25// deposit1.deposit_group_id = deposit1.id (self-reference)
26
27// ── 2. Second deposit: join the group ───────────────────────────
28const deposit2 = await scell.invoices.create({
29  invoice_type: 'deposit',
30  deposit_group_id: deposit1.deposit_group_id,       // Link to group
31  // deposit_total_ht and deposit_reference_text inherited from group leader
32  direction: 'outgoing',
33  output_format: 'facturx',
34  issue_date: '2026-06-15',
35  total_ht: 7000,                                    // Remaining 70% → auto-converted to balance
36  total_tax: 1400,
37  total_ttc: 8400,
38  seller_siret: '12345678901234',
39  seller_name: 'Ma Société',
40  seller_address: { line1: '1 rue Example', postal_code: '75001', city: 'Paris', country: 'FR' },
41  buyer_name: 'Client SA',
42  buyer_siret: '98765432109876',
43  buyer_address: { line1: '2 avenue Test', postal_code: '69001', city: 'Lyon', country: 'FR' },
44  lines: [{ description: 'Solde 70%', quantity: 1, unit_price: 7000, tax_rate: 20, total_ht: 7000, total_tax: 1400, total_ttc: 8400 }],
45});
46// deposit2.invoice_type === 'balance' (auto-converted: sum = 100%)
47// deposit2.parent_invoice_ids === [deposit1.id] (BG-22 deductions)
48
49// ── 3. Check group progress ─────────────────────────────────────
50const invoice = await scell.invoices.get(deposit1.id);
51console.log(invoice.deposit_group_progress);
52// { deposit_total_ht: 10000, sum_deposits_ht: 3000, remaining_ht: 7000,
53//   progress_percent: 30, has_balance: true, invoices_count: 2 }
54

1import { ScellApiClient } from '@scell/sdk';
2
3const scell = new ScellApiClient('sk_live_your_api_key');
4
5// ── Create a recurring invoice profile (an editable template) ───────
6// Each emission snapshots the CURRENT state of this profile into a real
7// invoice (ISCA chain per emitted invoice). Editing the profile only
8// affects FUTURE emissions, never invoices already issued.
9const { data: profile } = await scell.recurringInvoices.create({
10  title: 'Abonnement SaaS — Plan Pro',
11
12  // Buyer: use buyer_id (registry) OR the flat buyer_* fields below.
13  buyer_id: 'b1f2c3d4-5e6f-7081-92a3-b4c5d6e7f809',
14  // buyer_name: 'GN IMMO',
15  // buyer_country: 'FR',
16  // buyer_is_individual: false,
17  // buyer_siret: '49438068600076',
18  // buyer_vat_number: 'FR42494380686',
19  // buyer_email: 'compta@gnimmo.com',
20  // buyer_address: { line1: '453 Route Nationale 7', postal_code: '13670', city: 'Verquières', country: 'FR' },
21  // buyer_shipping_address: { name: 'Entrepôt Lyon', line1: '12 Rue du Dôme', postal_code: '69003', city: 'Lyon', country: 'FR' },
22
23  currency: 'EUR',                 // optional, defaults to 'EUR'
24  output_format: 'facturx',        // 'facturx' | 'ubl' | 'cii'
25  payment_terms: 'Paiement à 30 jours.',
26
27  // Lines — same shape as a standard invoice line
28  lines: [
29    {
30      description: 'Abonnement mensuel Plan Pro',
31      quantity: 1,
32      unit_price: 49.0,
33      vat_rate: 20,
34      unit: 'mois',
35    },
36    {
37      description: 'Utilisateurs additionnels',
38      quantity: 5,
39      unit_price: 9.0,
40      vat_rate: 20,
41      discount: 10,                // % discount on this line (optional)
42      category: 'subscription',    // free-text grouping (optional)
43    },
44  ],
45
46  // Recurrence cadence
47  recurrence: {
48    interval_unit: 'month',        // 'day' | 'week' | 'month' | 'year'
49    interval_count: 1,             // every N units (default 1)
50    day_of_month: 1,               // 1..31 — clamped to month length (e.g. 31 → 28/29/30)
51    // day_of_week: 1,             // 1..7 ISO (Mon..Sun) — only for interval_unit 'week'
52  },
53
54  start_date: '2026-07-01',        // first emission (ISO date)
55
56  // End condition
57  end_mode: 'after_occurrences',   // 'never' | 'on_date' | 'after_occurrences'
58  max_occurrences: 12,             // required when end_mode = 'after_occurrences'
59  // end_date: '2027-06-30',       // required when end_mode = 'on_date'
60
61  emission_mode: 'auto_send',      // 'draft' | 'auto_send' (default 'auto_send')
62  notify_before_days: 3,           // 0..30 — J-N reminder before each emission
63
64  metadata: { plan: 'pro', crm_id: 'sub_9981' },
65});
66
67// profile.status === 'active'
68// profile.next_occurrence_at === '2026-07-01'
69console.log(profile.id, profile.next_occurrence_at);
70