@scell/sdk 1.7.0 → 1.9.0

package/README.md

@@ -44,9 +44,10 @@ const apiClient = new ScellApiClient('your-api-key');
 
 ### Create an Invoice
 
+> **Note:** Invoice numbers are automatically generated by Scell.io. Draft invoices receive a temporary number, and the definitive fiscal number is assigned when the invoice is submitted.
+
 ```typescript
 const { data: invoice } = await apiClient.invoices.create({
-  invoice_number: 'FACT-2024-001',
   direction: 'outgoing',
   output_format: 'facturx',
   issue_date: '2024-01-15',
@@ -87,6 +88,65 @@ const { data: invoice } = await apiClient.invoices.create({
 console.log('Invoice created:', invoice.id);
 ```
 
+### International Invoicing
+
+For non-French parties, SIRET is not required. Use VAT numbers for EU businesses and `legal_id` with a scheme code for non-EU businesses.
+
+#### Invoice with Belgian Buyer (EU)
+
+```typescript
+const { data: invoice } = await apiClient.invoices.create({
+  issue_date: '2026-03-29',
+  due_date: '2026-04-28',
+  currency: 'EUR',
+  // French seller (SIRET required)
+  seller_siret: '12345678901234',
+  seller_name: 'Ma Société SAS',
+  seller_country: 'FR',
+  seller_vat_number: 'FR12345678901',
+  seller_address: { line1: '10 rue de Paris', postal_code: '75001', city: 'Paris', country: 'FR' },
+  // Belgian buyer (no SIRET, VAT number instead)
+  buyer_name: 'Entreprise Belge SPRL',
+  buyer_country: 'BE',
+  buyer_vat_number: 'BE0123456789',
+  buyer_address: { line1: '15 Avenue Louise', postal_code: '1050', city: 'Bruxelles', country: 'BE' },
+  lines: [
+    { description: 'Consulting services', quantity: 10, unit_price: 150.00, vat_rate: 0 },
+  ],
+  format: 'ubl',
+});
+```
+
+> **Note:** For intra-community B2B transactions (e.g. FR -> BE, FR -> DE), VAT rate is typically 0% under the reverse charge mechanism. The buyer accounts for VAT in their own country.
+
+#### Invoice with UK Buyer (Non-EU)
+
+For non-EU buyers, use `buyer_legal_id` and `buyer_legal_id_scheme` in addition to the VAT number:
+
+```typescript
+const { data: invoice } = await apiClient.invoices.create({
+  issue_date: '2026-03-29',
+  due_date: '2026-04-28',
+  currency: 'GBP',
+  seller_siret: '12345678901234',
+  seller_name: 'Ma Société SAS',
+  seller_country: 'FR',
+  seller_vat_number: 'FR12345678901',
+  seller_address: { line1: '10 rue de Paris', postal_code: '75001', city: 'Paris', country: 'FR' },
+  // UK buyer — legal_id with scheme
+  buyer_name: 'British Ltd',
+  buyer_country: 'GB',
+  buyer_vat_number: 'GB123456789',
+  buyer_legal_id: '12345678',
+  buyer_legal_id_scheme: '0088',  // UK Company Number scheme
+  buyer_address: { line1: '20 Baker Street', postal_code: 'W1U 3BW', city: 'London', country: 'GB' },
+  lines: [
+    { description: 'Design services', quantity: 5, unit_price: 200.00, vat_rate: 0 },
+  ],
+  format: 'ubl',
+});
+```
+
 ### Create a Signature Request
 
 ```typescript

package/dist/index.d.mts

@@ -183,7 +183,7 @@ interface Address {
     line2?: string | undefined;
     postal_code: string;
     city: string;
-    country?: string | undefined;
+    country: string;
 }
 /**
  * Pagination metadata
@@ -276,7 +276,11 @@ interface InvoiceLine {
  * Invoice party (seller or buyer)
  */
 interface InvoiceParty {
-    siret: Siret;
+    siret?: Siret;
+    vat_number?: string;
+    legal_id?: string;
+    legal_id_scheme?: string;
+    country: string;
     name: string;
     address: Address;
 }
@@ -332,8 +336,6 @@ interface InvoiceLineInput {
 interface CreateInvoiceInput {
     /** Your external reference ID */
     external_id?: string | undefined;
-    /** Invoice number (required) */
-    invoice_number: string;
     /** Direction: outgoing (sale) or incoming (purchase) */
     direction: InvoiceDirection;
     /** Output format for electronic invoice */
@@ -351,13 +353,29 @@ interface CreateInvoiceInput {
     /** Total including tax */
     total_ttc: number;
     /** Seller SIRET (14 digits) */
-    seller_siret: Siret;
+    seller_siret?: Siret;
+    /** Seller VAT number */
+    seller_vat_number?: string;
+    /** Seller country (ISO 3166-1 alpha-2) */
+    seller_country: string;
+    /** Seller legal identifier */
+    seller_legal_id?: string;
+    /** Seller legal identifier scheme */
+    seller_legal_id_scheme?: string;
     /** Seller company name */
     seller_name: string;
     /** Seller address */
     seller_address: Address;
     /** Buyer SIRET (14 digits) */
-    buyer_siret: Siret;
+    buyer_siret?: Siret;
+    /** Buyer VAT number */
+    buyer_vat_number?: string;
+    /** Buyer country (ISO 3166-1 alpha-2) */
+    buyer_country: string;
+    /** Buyer legal identifier */
+    buyer_legal_id?: string;
+    /** Buyer legal identifier scheme */
+    buyer_legal_id_scheme?: string;
     /** Buyer company name */
     buyer_name: string;
     /** Buyer address */
@@ -3091,6 +3109,8 @@ interface Company {
     siret: Siret;
     siren: Siren | null;
     vat_number: string | null;
+    legal_id: string | null;
+    legal_id_scheme: string | null;
     legal_form: string | null;
     address_line1: string;
     address_line2: string | null;
@@ -3111,7 +3131,9 @@ interface Company {
  */
 interface CreateCompanyInput {
     name: string;
-    siret: Siret;
+    siret?: Siret;
+    legal_id?: string;
+    legal_id_scheme?: string;
     vat_number?: string | undefined;
     legal_form?: string | undefined;
     address_line1: string;

package/dist/index.d.ts

@@ -183,7 +183,7 @@ interface Address {
     line2?: string | undefined;
     postal_code: string;
     city: string;
-    country?: string | undefined;
+    country: string;
 }
 /**
  * Pagination metadata
@@ -276,7 +276,11 @@ interface InvoiceLine {
  * Invoice party (seller or buyer)
  */
 interface InvoiceParty {
-    siret: Siret;
+    siret?: Siret;
+    vat_number?: string;
+    legal_id?: string;
+    legal_id_scheme?: string;
+    country: string;
     name: string;
     address: Address;
 }
@@ -332,8 +336,6 @@ interface InvoiceLineInput {
 interface CreateInvoiceInput {
     /** Your external reference ID */
     external_id?: string | undefined;
-    /** Invoice number (required) */
-    invoice_number: string;
     /** Direction: outgoing (sale) or incoming (purchase) */
     direction: InvoiceDirection;
     /** Output format for electronic invoice */
@@ -351,13 +353,29 @@ interface CreateInvoiceInput {
     /** Total including tax */
     total_ttc: number;
     /** Seller SIRET (14 digits) */
-    seller_siret: Siret;
+    seller_siret?: Siret;
+    /** Seller VAT number */
+    seller_vat_number?: string;
+    /** Seller country (ISO 3166-1 alpha-2) */
+    seller_country: string;
+    /** Seller legal identifier */
+    seller_legal_id?: string;
+    /** Seller legal identifier scheme */
+    seller_legal_id_scheme?: string;
     /** Seller company name */
     seller_name: string;
     /** Seller address */
     seller_address: Address;
     /** Buyer SIRET (14 digits) */
-    buyer_siret: Siret;
+    buyer_siret?: Siret;
+    /** Buyer VAT number */
+    buyer_vat_number?: string;
+    /** Buyer country (ISO 3166-1 alpha-2) */
+    buyer_country: string;
+    /** Buyer legal identifier */
+    buyer_legal_id?: string;
+    /** Buyer legal identifier scheme */
+    buyer_legal_id_scheme?: string;
     /** Buyer company name */
     buyer_name: string;
     /** Buyer address */
@@ -3091,6 +3109,8 @@ interface Company {
     siret: Siret;
     siren: Siren | null;
     vat_number: string | null;
+    legal_id: string | null;
+    legal_id_scheme: string | null;
     legal_form: string | null;
     address_line1: string;
     address_line2: string | null;
@@ -3111,7 +3131,9 @@ interface Company {
  */
 interface CreateCompanyInput {
     name: string;
-    siret: Siret;
+    siret?: Siret;
+    legal_id?: string;
+    legal_id_scheme?: string;
     vat_number?: string | undefined;
     legal_form?: string | undefined;
     address_line1: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scell/sdk",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Official TypeScript SDK for Scell.io - Electronic invoicing (Factur-X) and signatures (eIDAS) API",
   "author": "Scell.io <contact@scell.io>",
   "license": "MIT",

package/src/types/common.ts

@@ -45,7 +45,7 @@ export interface Address {
   line2?: string | undefined;
   postal_code: string;
   city: string;
-  country?: string | undefined;
+  country: string;
 }
 
 /**

package/src/types/companies.ts

@@ -14,6 +14,8 @@ export interface Company {
   siret: Siret;
   siren: Siren | null;
   vat_number: string | null;
+  legal_id: string | null;
+  legal_id_scheme: string | null;
   legal_form: string | null;
   address_line1: string;
   address_line2: string | null;
@@ -35,7 +37,9 @@ export interface Company {
  */
 export interface CreateCompanyInput {
   name: string;
-  siret: Siret;
+  siret?: Siret;
+  legal_id?: string;
+  legal_id_scheme?: string;
   vat_number?: string | undefined;
   legal_form?: string | undefined;
   address_line1: string;

package/src/types/invoices.ts

@@ -57,7 +57,11 @@ export interface InvoiceLine {
  * Invoice party (seller or buyer)
  */
 export interface InvoiceParty {
-  siret: Siret;
+  siret?: Siret;
+  vat_number?: string;
+  legal_id?: string;
+  legal_id_scheme?: string;
+  country: string;
   name: string;
   address: Address;
 }
@@ -116,8 +120,6 @@ export interface InvoiceLineInput {
 export interface CreateInvoiceInput {
   /** Your external reference ID */
   external_id?: string | undefined;
-  /** Invoice number (required) */
-  invoice_number: string;
   /** Direction: outgoing (sale) or incoming (purchase) */
   direction: InvoiceDirection;
   /** Output format for electronic invoice */
@@ -135,13 +137,29 @@ export interface CreateInvoiceInput {
   /** Total including tax */
   total_ttc: number;
   /** Seller SIRET (14 digits) */
-  seller_siret: Siret;
+  seller_siret?: Siret;
+  /** Seller VAT number */
+  seller_vat_number?: string;
+  /** Seller country (ISO 3166-1 alpha-2) */
+  seller_country: string;
+  /** Seller legal identifier */
+  seller_legal_id?: string;
+  /** Seller legal identifier scheme */
+  seller_legal_id_scheme?: string;
   /** Seller company name */
   seller_name: string;
   /** Seller address */
   seller_address: Address;
   /** Buyer SIRET (14 digits) */
-  buyer_siret: Siret;
+  buyer_siret?: Siret;
+  /** Buyer VAT number */
+  buyer_vat_number?: string;
+  /** Buyer country (ISO 3166-1 alpha-2) */
+  buyer_country: string;
+  /** Buyer legal identifier */
+  buyer_legal_id?: string;
+  /** Buyer legal identifier scheme */
+  buyer_legal_id_scheme?: string;
   /** Buyer company name */
   buyer_name: string;
   /** Buyer address */