SDKs officiels & Référence API

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  invoice_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_tva: 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_ht: 250.00,
49      tva_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  invoice_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_tva: 30.00,
77  total_ttc: 180.00,
78  lines: [{ description: 'Formation individuelle', quantity: 1, unit_price_ht: 150.00, tva_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  invoice_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_tva: 500.00,
95  total_ttc: 3000.00,
96  lines: [{ description: 'Consulting', quantity: 10, unit_price_ht: 250.00, tva_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  invoice_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_tva: 200.00,
110  total_ttc: 1200.00,
111  lines: [{ description: 'Service', quantity: 1, unit_price_ht: 1000.00, tva_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  invoice_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_tva: 500.00,
131  total_ttc: 3000.00,
132  lines: [{ description: 'Consulting (devis DEV-2026-0042)', quantity: 10, unit_price_ht: 250.00, tva_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('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 ──────────────────────────────────────
39const ksStatus = await scell.fiscal.killSwitchStatus();
40await scell.fiscal.activateKillSwitch();
41await scell.fiscal.deactivateKillSwitch();
42
43// ─── Exports ──────────────────────────────────────────
44const fec = await scell.fiscal.fecExport();
45const forensic = await scell.fiscal.forensicExport();
46const attestation = await scell.fiscal.attestation(2026);
47const download = await scell.fiscal.attestationDownload(2026);
48
49// ─── ISCA self-attestation (NOMINATIVE — depuis v1.17.0) ──
50// Auto-attestation pour le tenant courant (donnees KYB)
51const tenantPdf = await scell.fiscal.iscaSelfAttestationDownload();
52fs.writeFileSync('attestation-tenant.pdf', Buffer.from(tenantPdf));
53
54// Auto-attestation pour un sub_tenant specifique
55const subPdf = await scell.fiscal.iscaSelfAttestationDownload('019d5ea8-...');
56fs.writeFileSync('attestation-sub-tenant.pdf', Buffer.from(subPdf));
57
58// Documents de conformite (non-nominatifs)
59const measures = await scell.fiscal.iscaMeasuresRegisterDownload();
60const dossier = await scell.fiscal.iscaTechnicalDossierDownload();
61

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// ---------------------------------------------------------------------------
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

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

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
20

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
5try {
6  const invoice = await scell.invoices.create({ /* ... */ });
7} catch (error) {
8  if (error.status === 422) {
9    // Validation error — check error.errors for field-level details
10    console.error('Validation:', error.errors);
11    // { "seller.siren": ["The siren must be 9 digits."] }
12  } else if (error.status === 401) {
13    // Invalid or expired API key
14    console.error('Authentication failed');
15  } else if (error.status === 402) {
16    // Insufficient credits
17    console.error('Insufficient balance — top up credits');
18  } else if (error.status === 404) {
19    // Resource not found
20    console.error('Resource not found');
21  } else if (error.status === 429) {
22    // Rate limited — retry after error.retryAfter seconds
23    console.error('Rate limited, retry after', error.retryAfter, 'seconds');
24  } else if (error.status >= 500) {
25    // Server error — retry with exponential backoff
26    console.error('Server error, retrying...');
27  }
28}
29