@facturino/node 1.1.0 → 2.0.0

package/README.md

@@ -13,35 +13,107 @@ npm install @facturino/node
 
 ## Usage
 
+The recommended path is decision-first: identity → final tax decision →
+create the decision-backed draft immediately → your chosen collection flow.
+Facturino imposes no payment service provider and no payment method: an
+immediate capture, a bank transfer, a direct debit or payment on agreed terms
+all fit the same contract.
+
 ```typescript
 import Facturino from '@facturino/node'
 
 const facturino = new Facturino('fac_test_xxx')
 
-const invoice = await facturino.invoices.create({
-  customerId: 'cus_xxx',
-  buyer: {
-    companyName: 'Acme SAS',
-    siret: '55208131766522',
-    address: { line1: '10 rue de la Paix', postalCode: '75002', city: 'Paris', country: 'FR' },
-  },
+// 1. Decide before the final amount is presented, the invoice is issued,
+//    or collection starts.
+const decision = await facturino.taxDecisions.create({
+  taxSource: 'facturino',   // or 'integration' to supply your own VAT
+  customerId: 'cus_8f2k4m9n',
+  effectiveAt: '2026-09-15',
+  currency: 'eur',
+  priceMode: 'tax_exclusive',
   lines: [{
-    description: 'Consulting',
-    quantity: '1',      // decimal string
-    unit: 'flat_rate',
-    unitPrice: 10000,   // 100.00 EUR (centimes)
-    vatRate: 2000,      // 20.00% (centièmes de pourcent)
-    vatCode: 'S',
+    reference: 'abo-pro',
+    description: 'Abonnement Pro',
+    category: 'electronically_supplied_services',
+    rateCategory: 'standard',
+    unitAmount: 2900,   // integer cents
+    quantity: '1',      // decimal STRING, never a float
   }],
-  dates: { issued: '2026-07-01', due: '2026-07-31' },
-  payment: { terms: 'Paiement à 30 jours', termsDays: 30, method: 'transfer', latePaymentRate: '10.00', collectionFee: '40.00' },
+}, { idempotencyKey: `order-${orderId}` })
+
+// 2. Act only on a final decision. `pending_verification` does not mean
+//    "nothing to charge": totals and amountToCharge are null, not 0.
+if (decision.status !== 'final') {
+  return askForMissingEvidence(decision.issues)
+}
+
+// 3. Create the decision-backed draft immediately: no VAT is restated,
+//    the amounts are the decision's.
+const invoice = await facturino.invoices.create({
+  customerId: decision.customerId,
+  taxDecisionId: decision.id,
+  decisionLines: [{ taxLineRef: 'abo-pro', unit: 'month' }],
+  buyer: buyerSnapshot,
+  dates: { issued: '2026-09-15', due: '2026-10-15' },
+  payment: paymentTerms,
 })
 
-const finalized = await facturino.invoices.finalize(invoice.id)
+// 4. Choose your collection flow — see the two variants below.
+```
 
-// One-shot: pass `autoFinalize: true` (and optionally
-// `autoSend: { email: true, pa: true }`) to `invoices.create(...)` to
-// finalize — and deliver by email and/or to the PA — in a single call.
+**Immediate collection** — capture the decided amount, verify, then finalize:
+
+```typescript
+// Capture exactly amountToCharge through your payment provider, payment
+// processor, bank transfer or external collection flow. Carry `decision.id`
+// in the provider metadata, order reference or custom reference. The
+// settlement keeps its OWN financial reference (charge id, transfer
+// wording…): the two identifiers are different things and must stay distinct.
+const settlement = await yourCollectionProcess.capture({
+  amount: decision.amountToCharge!,   // never a locally computed total
+  currency: decision.currency,
+  metadata: { taxDecisionId: decision.id },
+})
+
+// Re-read the decision by its own id and verify what was actually captured.
+const source = await facturino.taxDecisions.retrieve(decision.id)
+if (settlement.amount !== source.amountToCharge) throw new Error('amount mismatch')
+if (settlement.currency !== source.currency) throw new Error('currency mismatch')
+
+await facturino.invoices.finalize(invoice.id)
+
+// Record the REAL payment — its real date, method and the settlement's
+// financial reference (never the decision id).
+await facturino.payments.create(invoice.id, {
+  amount: settlement.amount,
+  // transfer, card, check, cash, direct_debit, sepa, paypal or other
+  method: settlement.method,
+  reference: settlement.reference,
+  paidAt: settlement.paidAt,
+})
+
+// Send to the platform only on the channel the FROZEN decision states.
+if (source.invoiceChannel === 'einvoicing') {
+  await facturino.invoices.send(invoice.id)
+}
+```
+
+**Payment on terms** — finalize and deliver now, collect later:
+
+```typescript
+await facturino.invoices.finalize(invoice.id)
+if (decision.invoiceChannel === 'einvoicing') {
+  await facturino.invoices.send(invoice.id)
+}
+
+// …once the transfer arrives, record the REAL collection date.
+await facturino.payments.create(invoice.id, {
+  amount: decision.amountToCharge!,
+  method: 'transfer',
+  reference: 'VIR-2026-000871',
+  paidAt: '2026-10-12',
+})
 ```
 
 ## Configuration
@@ -50,10 +122,156 @@ const finalized = await facturino.invoices.finalize(invoice.id)
 const facturino = new Facturino('fac_test_xxx', {
   maxRetries: 3,      // retries on 429/5xx
   timeout: 30000,     // ms
-  apiVersion: '2026-03-01',
+  apiVersion: '2026-09-01',
 })
 ```
 
+## Tax decisions
+
+The full walkthrough lives in [Usage](#usage). A decision is immutable: it
+fixes the VAT, the exact `amountToCharge` and the reporting obligations of one
+commercial operation, then never changes. Only a `final` decision carries
+amounts, and the amount always comes from the decision — never from a locally
+computed total.
+
+### Optional: carrying the decision id through a PSP
+
+These are examples, not requirements. If you collect through a PSP, keep the
+decision id on the payment so step 4 can verify what was actually captured.
+
+Stripe — any field that survives the round trip works; `metadata` is the usual one:
+
+```typescript
+const intent = await stripe.paymentIntents.create({
+  amount: decision.amountToCharge!,
+  currency: decision.currency,
+  metadata: { facturino_tax_decision_id: decision.id },
+})
+```
+
+PayPal has no `metadata`; carry the decision id in `custom_id`, and convert the
+cents to decimal units for the order amount:
+
+```typescript
+custom_id: decision.id,
+amount: {
+  currency_code: decision.currency.toUpperCase(),
+  value: (decision.amountToCharge! / 100).toFixed(2),
+},
+```
+
+### What a decision states
+
+| Field | Meaning |
+|---|---|
+| `status` | `final`, `pending_verification` or `unsupported`. Only `final` carries amounts. |
+| `amountToCharge` | Exact amount to debit, integer cents. `null` unless `final`. |
+| `totals` | `totalHT` / `totalVAT` / `totalTTC`, integer cents. `null` unless `final`. |
+| `invoiceChannel` | `einvoicing` or `none` — whether the invoice travels the network. |
+| `transactionReporting` | `ereporting`, `none` or `outside_scope`. |
+| `paymentReporting` | `fr212`, `ereporting` or `none`. |
+| `foreignTaxReviewRequired` | A foreign tax may apply; review it outside Facturino. |
+| `vies` | VIES status only (`valid`, `invalid`, `unavailable`, `invalid_format`). |
+| `issues` | What is missing, when the decision is not final. |
+| `obligationReasons` | Why each axis carries the obligation it does. |
+| `expiresAt` / `expired` | Past this instant the decision no longer opens a payment. |
+
+`create()` requires an `Idempotency-Key` (255 characters at most; the SDK checks
+it before sending). The API answers `201` on creation and `200` when the same
+key already produced that decision — both return the decision, so your code
+reads one shape either way. Reusing the same key with a different body answers
+`409` and raises `ConflictError`.
+
+Facturino decides **French VAT and the matching French obligations**. It does
+not provide worldwide tax compliance: when a foreign tax may apply, the decision
+says so through `foreignTaxReviewRequired`. An operation whose `invoiceChannel`
+is `none` is not deposited on a certified platform — its obligation, if any,
+goes through e-reporting.
+
+### Missing evidence, then a retry
+
+A decision that lacks a location or business-status proof comes back
+`pending_verification`. Supply the evidence and retry the SAME operation:
+
+```typescript
+const retried = await facturino.taxDecisions.create({
+  ...sameOperation,
+  retryOfTaxDecisionId: pending.id,
+  locationEvidence: [{
+    kind: 'billing_address',
+    country: 'FR',
+    postalCode: '75002',
+    thirdParty: false,
+    source: 'declared',
+    collectedAt: '2026-09-15',
+  }],
+}, { idempotencyKey: `order-${orderId}-retry-${pending.id}` })
+```
+
+Send the territorial **signal**, never the raw one: a country and, where the
+territory needs it, a postal code — not an IP address, a PSP payload or bank
+account details. `reference` is a bounded opaque identifier such as a charge id.
+
+## Three status axes
+
+A document has three states that do not follow from one another. The historical
+`status` field stays populated as their projection.
+
+```typescript
+invoice.documentStatus     // draft | finalized | cancelled
+invoice.transmissionStatus // not_applicable | pending | sending | deposited | transmitted | approved | rejected
+invoice.transmissionDetail // available | received | suspended | refused | null
+invoice.paymentStatus      // unpaid | partially_paid | paid | partially_refunded | refunded
+```
+
+Recording a payment never moves the transmission axis, and a refund does not
+erase the collection that happened.
+
+## Supplying your own VAT (`taxSource: 'integration'`)
+
+If your own tax engine concludes the VAT, create the decision under the
+`integration` source: the same commercial and territorial data, plus the VAT
+per line (`vatRate`, `vatCode`, and `vatexCode` for exempt categories).
+Facturino validates the coherence of the supplied values and refuses any
+detectable contradiction (`integration_vat_incoherent`) — it never silently
+corrects a rate. The amounts, the legal mentions and the three reporting axes
+are still decided server-side, by the same engines. The invoice is then created
+exactly like a facturino-sourced one, and carries `taxSource: 'integration'`.
+
+```typescript
+const decision = await facturino.taxDecisions.create({
+  taxSource: 'integration',
+  customerId: 'cus_xxx',
+  effectiveAt: '2026-09-15',
+  currency: 'eur',
+  priceMode: 'tax_exclusive',
+  lines: [{
+    reference: 'consulting',
+    description: 'Consulting',
+    category: 'services',
+    unitAmount: 10000,  // 100.00 EUR (integer cents)
+    quantity: '1',      // decimal string
+    vatRate: 2000,      // 20.00% — supplied, never corrected
+    vatCode: 'S',
+  }],
+}, { idempotencyKey: `order-${orderId}` })
+
+const invoice = await facturino.invoices.create({
+  customerId: 'cus_xxx',
+  taxDecisionId: decision.id,
+  decisionLines: [{ taxLineRef: 'consulting', unit: 'flat_rate' }],
+  buyer: buyerSnapshot,
+  dates: { issued: '2026-09-15', due: '2026-10-15' },
+  payment: { terms: 'Paiement à 30 jours', termsDays: 30, method: 'transfer', latePaymentRate: '10.00', collectionFee: '40.00' },
+})
+
+const finalized = await facturino.invoices.finalize(invoice.id)
+
+// One-shot: pass `autoFinalize: true` (and optionally
+// `autoSend: { email: true }`) to finalize — and deliver by email — in a
+// single call.
+```
+
 ## Amounts
 
 Monetary values are integers in **centimes** (10000 = 100.00 EUR).
@@ -74,8 +292,15 @@ const page = await facturino.invoices.list({ status: 'draft' })
 ## Resources
 
 ```typescript
+// Tax decisions (immutable — no update, no delete)
+facturino.taxDecisions.create(params, { idempotencyKey })
+facturino.taxDecisions.retrieve('taxdec_xxx')
+
 // Invoices
-facturino.invoices.create(params)
+facturino.invoices.create({ taxDecisionId, decisionLines, ... })  // always backed by a FINAL decision
+// `deposits` and `schedule` are settled server-side against the decided
+// amount; the decided total never changes. A create without a decision is
+// rejected locally, before any HTTP call.
 facturino.invoices.get('inv_xxx')
 facturino.invoices.get('inv_xxx', { expand: ['customer', 'credit_notes'] })
 facturino.invoices.update('inv_xxx', params)
@@ -100,19 +325,32 @@ facturino.customers.lookup({ siret: '73282932000074' })
 // Products
 facturino.products.list({ q: 'consult', category: 'services', active: true })
 
-// Quotes
+// Quotes — convert, decide, bind, finalize: ONE invoice throughout.
 facturino.quotes.create(params)
 facturino.quotes.send('quo_xxx')
 facturino.quotes.accept('quo_xxx')
-facturino.quotes.convert('quo_xxx')  // -> draft invoice
 facturino.quotes.clone('quo_xxx')    // -> duplicated draft quote
 
+// A converted quote yields a COMMERCIAL draft: it states the operation and no
+// VAT (`taxSource: null`). Bind a final decision to that same invoice, then
+// finalize it — never create a second one.
+const { invoiceId } = await facturino.quotes.convert('quo_xxx')
+const decision = await facturino.taxDecisions.create(decisionInput, { idempotencyKey })
+await facturino.invoices.bindTaxDecision(invoiceId, {
+  taxDecisionId: decision.id,
+  decisionLines: [{ taxLineRef: 'l1', unit: 'unit' }],
+})
+await facturino.invoices.finalize(invoiceId)
+
 // Credit Notes
-facturino.creditNotes.create(params)
+facturino.creditNotes.create({ relatedInvoiceId, creditNoteType, reasonCode, creditedLines })
+// A credit note inherits the fiscal position of the invoice it corrects —
+// source, snapshot and lines. It never restates any VAT.
 facturino.creditNotes.finalize('crn_xxx')
 
 // Recurring Invoices
-facturino.recurringInvoices.create(params)
+facturino.recurringInvoices.create({ ..., taxInputs })     // each occurrence decided on its own date,
+                                                           // under the recurrence's single fiscal source
 facturino.recurringInvoices.pause('rec_xxx')
 facturino.recurringInvoices.resume('rec_xxx')
 
@@ -163,8 +401,39 @@ app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
 
 ## Idempotency
 
+An `Idempotency-Key` protects the **replay of one request**. It is not a
+deduplicator: the API never decides on its own that two requests "mean the same
+thing".
+
+- **Same key + same canonical body** — the first 2xx response is replayed
+  verbatim, and the operation is not executed a second time.
+- **Same key + different body** — `409 idempotency_error`. A key belongs to a
+  request, not to an endpoint.
+- **Different keys** — two distinct operations, even with byte-identical bodies.
+  Two requests describing the same operation are **not** deduplicated
+  automatically; the key, and only the key, declares that two sends are the same
+  attempt.
+- **Canonical body** — JSON object keys are compared in a stable order, so
+  reordering them does not change the request. Changing a value, adding or
+  removing a field does. Array order is significant: two lines swapped are two
+  different documents.
+- **Failure before execution** (validation, read-only field, sanitisation)
+  releases the key, so a corrected retry with the same key runs.
+- **Business refusal during execution** is stored and replayed; the operation is
+  not re-executed.
+- **Scope** — 24 hours, per API key. `POST /v1/tax-decisions` additionally
+  carries a durable business idempotency that never expires.
+
 ```typescript
-await facturino.invoices.create(params, { idempotencyKey: 'unique-id' })
+// Same key + same body -> the first response, replayed.
+await facturino.invoices.create(params, { idempotencyKey: 'order-4821' })
+
+// Retry with new evidence is NOT idempotency. It takes a NEW decision on the
+// same commercial operation: use a NEW key and link the previous decision.
+await facturino.taxDecisions.create(
+  { ...operation, retryOfTaxDecisionId: suspended.id },
+  { idempotencyKey: 'order-4821-retry-1' },
+)
 ```
 
 ## Errors

package/dist/cjs/client.d.ts

@@ -1,5 +1,5 @@
 import type { FacturinoConfig, RequestOptions } from './types.js';
-export declare const VERSION = "1.1.0";
+export declare const VERSION = "2.0.0";
 /** HTTP client with retries, exponential backoff, and structured errors. */
 export declare class HttpClient {
     private readonly apiKey;

package/dist/cjs/client.js

@@ -5,11 +5,11 @@ const errors_js_1 = require("./errors.js");
 const DEFAULT_BASE_URL = 'https://facturino.com/api';
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_TIMEOUT = 30000;
-const DEFAULT_API_VERSION = '2026-03-01';
+const DEFAULT_API_VERSION = '2026-09-01';
 const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503]);
 const INITIAL_RETRY_DELAY_MS = 500;
 const MAX_RETRY_DELAY_MS = 30000;
-exports.VERSION = '1.1.0';
+exports.VERSION = '2.0.0';
 /** HTTP client with retries, exponential backoff, and structured errors. */
 class HttpClient {
     constructor(apiKey, config = {}) {

package/dist/cjs/index.d.ts

@@ -17,6 +17,7 @@ import { ReceivedInvoices } from './resources/received-invoices.js';
 import { Reporting } from './resources/reporting.js';
 import { AccountResource } from './resources/account.js';
 import { Billing } from './resources/billing.js';
+import { TaxDecisions } from './resources/taxDecisions.js';
 import { Usage } from './resources/usage.js';
 import { Validate } from './resources/validate.js';
 import { Reference } from './resources/reference.js';
@@ -42,6 +43,7 @@ declare class Facturino {
     readonly jobs: Jobs;
     readonly reference: Reference;
     readonly sandbox: Sandbox;
+    readonly taxDecisions: TaxDecisions;
     readonly usage: Usage;
     readonly validate: Validate;
     readonly webhooks: Webhooks;
@@ -53,7 +55,7 @@ declare class Facturino {
 }
 export default Facturino;
 export { Facturino };
-export type { FacturinoConfig, RequestOptions, PaginationParams, PaginatedResponse, ApiErrorBody, Address, Contact, ContactRole, LineItem, VatBreakdown, Totals, CustomerRef, CustomerSnapshot, LifecycleEntry, Currency, Unit, VatCode, VatexCode, PaymentMethod, InvoiceType, InvoiceStatus, InvoiceDates, InvoicePaymentTerms, InvoiceEinvoicing, InvoicePortal, InvoiceArchive, InvoiceFiles, Invoice, InvoiceExpandField, InvoiceExpanded, InvoiceRetrieveParams, InvoiceBuyerParam, InvoiceCreateDates, InvoiceCreateParams, InvoiceLineItemParam, InvoiceUpdateParams, InvoiceListParams, IncomingInvoiceCreateParams, InvoiceStatusResponse, InvoiceVerifyResponse, DocumentUrlResponse, JobResponse, PaymentLinkResponse, PaymentLinkCreateParams, PaymentTokenResponse, Payment, PaymentCreateParams, Customer, CustomerCreateParams, CustomerUpdateParams, CustomerListParams, CustomerLookupParams, SireneLookupResponse, SireneCompany, Product, PriceHistoryEntry, ProductCreateParams, ProductUpdateParams, ProductListParams, QuoteStatus, QuoteDates, QuoteSignature, Quote, QuoteCreateParams, QuoteUpdateParams, QuoteListParams, CreditNoteType, CreditNoteStatus, CreditNoteReasonCode, CreditNote, CreditNoteCreateParams, CreditNoteUpdateParams, CreditNoteListParams, WebhookEventType, WebhookEvent, EventListParams, WebhookEndpoint, WebhookEndpointCreateParams, WebhookEndpointUpdateParams, RecurringFrequency, RecurringInvoice, RecurringInvoiceCreateParams, RecurringInvoiceUpdateParams, RecurringInvoiceListParams, BankDetails, InvoiceSettings, CreditNoteSettings, CreditNoteNumberingMode, Company, CompanyUpdateParams, CgvResponse, FecExportParams, EReportingType, EReportingStatus, EReportingLine, EReportingLineResponse, EReporting, EReportingCreateParams, EReportingListParams, JobType, JobStatus, Job, SandboxResetResponse, SimulateStatusParams, SimulateStatusResponse, ReceivedInvoiceStatus, ReceivedInvoice, ReceivedInvoiceListParams, ReceivedInvoiceRefuseParams, ReceivedInvoiceRecordPaymentParams, ReceivedInvoiceActionResponse, VatReportParams, VatReportBreakdown, VatReport, RevenueReportParams, RevenueReportBreakdownItem, RevenueReport, AccountPlan, Account, BillingCycle, BillingSubscription, PlatformInvoice, UsageMeter, UsageSummary, ValidateParams, ValidateResponse, LegalForm, NafCode, LegalFormInput, NafCodeInput, PaProvider, HealthStatus, } from './types.js';
+export type { FacturinoConfig, RequestOptions, PaginationParams, PaginatedResponse, ApiErrorBody, Address, Contact, ContactRole, LineItem, VatBreakdown, Totals, CustomerRef, CustomerSnapshot, LifecycleEntry, Currency, Unit, VatCode, VatexCode, PaymentMethod, InvoiceType, InvoiceStatus, InvoiceDates, InvoicePaymentTerms, InvoiceEinvoicing, InvoicePortal, InvoiceArchive, InvoiceFiles, Invoice, InvoiceExpandField, InvoiceExpanded, InvoiceRetrieveParams, InvoiceBuyerParam, InvoiceCreateDates, InvoiceCreateParams, InvoiceBindTaxDecisionParams, CommercialDraft, CommercialDraftLine, InvoiceLineItemParam, InvoiceUpdateParams, InvoiceListParams, IncomingInvoiceCreateParams, InvoiceStatusResponse, InvoiceVerifyResponse, DocumentUrlResponse, JobResponse, PaymentLinkResponse, PaymentLinkCreateParams, PaymentTokenResponse, Payment, PaymentCreateParams, Customer, CustomerCreateParams, CustomerUpdateParams, CustomerListParams, CustomerLookupParams, SireneLookupResponse, SireneCompany, Product, PriceHistoryEntry, ProductCreateParams, ProductUpdateParams, ProductListParams, QuoteStatus, QuoteDates, QuoteSignature, Quote, QuoteCreateParams, QuoteUpdateParams, QuoteListParams, CreditNoteType, CreditNoteStatus, CreditNoteReasonCode, CreditNote, CreditNoteCreateParams, CreditNoteUpdateParams, CreditNoteListParams, WebhookEventType, WebhookEvent, EventListParams, WebhookEndpoint, WebhookEndpointCreateParams, WebhookEndpointUpdateParams, RecurringFrequency, RecurringInvoice, RecurringInvoiceCreateParams, RecurringInvoiceUpdateParams, RecurringInvoiceListParams, BankDetails, InvoiceSettings, CreditNoteSettings, CreditNoteNumberingMode, Company, CompanyUpdateParams, CgvResponse, FecExportParams, EReportingType, EReportingStatus, EReportingLine, EReportingLineResponse, EReporting, EReportingCreateParams, EReportingListParams, JobType, JobStatus, Job, SandboxResetResponse, SimulateStatusParams, SimulateStatusResponse, ReceivedInvoiceStatus, ReceivedInvoice, ReceivedInvoiceListParams, ReceivedInvoiceRefuseParams, ReceivedInvoiceRecordPaymentParams, ReceivedInvoiceActionResponse, VatReportParams, VatReportBreakdown, VatReport, RevenueReportParams, RevenueReportBreakdownItem, RevenueReport, AccountPlan, Account, BillingCycle, BillingSubscription, PlatformInvoice, UsageMeter, UsageSummary, ValidateParams, ValidateResponse, PriceMode, SupplyCategory, PrimarySupplyCategory, RateCategory, GoodsMovement, TaxDecisionStatus, TaxDecisionDiscount, TaxDecisionLineParam, TaxDecisionCreateParams, TaxDecision, TaxDecisionLine, TaxDecisionCustomer, TaxDecisionIssue, TaxDecisionObligationReason, TaxDecisionVatBreakdownEntry, LocationEvidenceKind, LocationEvidenceParam, LocationEvidenceResult, NonEuBusinessEvidenceParam, NonEuBusinessEvidenceResult, EvidenceSource, ViesResult, InvoiceChannel, TransactionReporting, PaymentReporting, TaxSource, TaxSnapshot, DocumentStatus, TransmissionStatus, TransmissionDetail, PaymentStatus, DecisionBackedLineParam, InvoiceCreateBaseParams, CreditedLineParam, RecurringTaxLineParam, RecurringIntegrationTaxLineParam, RecurringTaxInputsParam, FacturinoTaxDecisionCreateParams, IntegrationTaxDecisionCreateParams, IntegrationTaxDecisionLineParam, LegalForm, NafCode, LegalFormInput, NafCodeInput, PaProvider, HealthStatus, } from './types.js';
 export { FacturinoError, ApiError, InvalidRequestError, ValidationError, AuthenticationError, PermissionError, NotFoundError, ConflictError, RateLimitError, PlanLimitError, ApiInternalError, ConnectionError, } from './errors.js';
 export { Webhooks } from './webhooks.js';
 export { AutoPaginatingList } from './pagination.js';

package/dist/cjs/index.js

@@ -21,6 +21,7 @@ const received_invoices_js_1 = require("./resources/received-invoices.js");
 const reporting_js_1 = require("./resources/reporting.js");
 const account_js_1 = require("./resources/account.js");
 const billing_js_1 = require("./resources/billing.js");
+const taxDecisions_js_1 = require("./resources/taxDecisions.js");
 const usage_js_1 = require("./resources/usage.js");
 const validate_js_1 = require("./resources/validate.js");
 const reference_js_1 = require("./resources/reference.js");
@@ -47,6 +48,7 @@ class Facturino {
         this.jobs = new jobs_js_1.Jobs(client);
         this.reference = new reference_js_1.Reference(client);
         this.sandbox = new sandbox_js_1.Sandbox(client);
+        this.taxDecisions = new taxDecisions_js_1.TaxDecisions(client);
         this.usage = new usage_js_1.Usage(client);
         this.validate = new validate_js_1.Validate(client);
         this.webhooks = new webhooks_js_1.Webhooks();

package/dist/cjs/resources/companies.d.ts

@@ -11,7 +11,7 @@ export interface CompanyCreateParams {
     tvaIntracom?: string;
     rcs?: string;
     capitalSocial?: string;
-    vatRegime?: 'normal' | 'franchise' | 'simplified' | 'debit';
+    vatRegime?: 'normal' | 'normal_quarterly' | 'franchise' | 'simplified' | 'debit';
     email?: string;
     phone?: string;
     website?: string;

package/dist/cjs/resources/invoices.d.ts

@@ -1,12 +1,20 @@
 import type { HttpClient } from '../client.js';
 import { AutoPaginatingList } from '../pagination.js';
 import { Payments } from './payments.js';
-import type { Invoice, InvoiceCreateParams, InvoiceUpdateParams, InvoiceListParams, InvoiceRetrieveParams, InvoiceStatusResponse, InvoiceVerifyResponse, DocumentUrlResponse, JobResponse, PaymentLinkResponse, PaymentLinkCreateParams, PaymentTokenResponse, PaginatedResponse, LifecycleEntry, IncomingInvoiceCreateParams, ReceivedInvoice, RequestOptions } from '../types.js';
+import type { Invoice, InvoiceCreateParams, InvoiceBindTaxDecisionParams, InvoiceUpdateParams, InvoiceListParams, InvoiceRetrieveParams, InvoiceStatusResponse, InvoiceVerifyResponse, DocumentUrlResponse, JobResponse, PaymentLinkResponse, PaymentLinkCreateParams, PaymentTokenResponse, PaginatedResponse, LifecycleEntry, IncomingInvoiceCreateParams, ReceivedInvoice, RequestOptions } from '../types.js';
 /** Manages invoice lifecycle — creation, finalization, sending, and document retrieval. */
 export declare class Invoices {
     private readonly client;
     readonly payments: Payments;
     constructor(client: HttpClient);
+    /**
+     * Create an invoice — ALWAYS backed by a FINAL tax decision (`taxDecisionId`
+     * + `decisionLines`), whatever its fiscal source. The decided VAT, amounts
+     * and mentions are copied verbatim and frozen; `deposits` and `schedule` are
+     * settled server-side against the decided amount, inside the creation
+     * transaction. The types enforce this at compile time; the checks below turn
+     * the same misuse into an immediate local error instead of a round trip.
+     */
     create(params: InvoiceCreateParams, options?: RequestOptions): Promise<Invoice>;
     list(params?: InvoiceListParams): AutoPaginatingList<Invoice>;
     /**
@@ -19,6 +27,28 @@ export declare class Invoices {
     update(id: string, params: InvoiceUpdateParams): Promise<Invoice>;
     /** Soft-delete (draft only). */
     del(id: string): Promise<void>;
+    /**
+     * Bind a FINAL tax decision to a commercial draft that already exists —
+     * typically the one `quotes.convert()` produced.
+     *
+     * This closes the quote cycle on ONE document:
+     *
+     * ```ts
+     * const { invoiceId } = await facturino.quotes.convert(quoteId)
+     * const decision = await facturino.taxDecisions.create({ ... }, { idempotencyKey })
+     * await facturino.invoices.bindTaxDecision(invoiceId, {
+     *   taxDecisionId: decision.id,
+     *   decisionLines: [{ taxLineRef: 'l1', unit: 'unit' }],
+     * })
+     * await facturino.invoices.finalize(invoiceId)
+     * ```
+     *
+     * The invoice stays a DRAFT: binding freezes the VAT, `finalize()` issues it.
+     * Idempotent on the decision — replaying the same call returns the same
+     * invoice. Binding a different decision to a bound invoice, or the same
+     * decision to a second invoice, is a conflict.
+     */
+    bindTaxDecision(id: string, params: InvoiceBindTaxDecisionParams, options?: RequestOptions): Promise<Invoice>;
     /** Assign number and lock. Irreversible. */
     finalize(id: string, options?: RequestOptions): Promise<Invoice>;
     /** Submit to PA. Returns 202 (async). */

package/dist/cjs/resources/invoices.js

@@ -9,7 +9,27 @@ class Invoices {
         this.client = client;
         this.payments = new payments_js_1.Payments(client);
     }
+    /**
+     * Create an invoice — ALWAYS backed by a FINAL tax decision (`taxDecisionId`
+     * + `decisionLines`), whatever its fiscal source. The decided VAT, amounts
+     * and mentions are copied verbatim and frozen; `deposits` and `schedule` are
+     * settled server-side against the decided amount, inside the creation
+     * transaction. The types enforce this at compile time; the checks below turn
+     * the same misuse into an immediate local error instead of a round trip.
+     */
     async create(params, options) {
+        const runtime = params;
+        if (typeof runtime.taxDecisionId !== 'string' || runtime.taxDecisionId.length === 0) {
+            throw new Error(`'taxDecisionId' is required: every invoice is backed by a FINAL tax decision `
+                + `(facturino or integration source). Create one with taxDecisions.create() first.`);
+        }
+        if (!Array.isArray(runtime.decisionLines) || runtime.decisionLines.length === 0) {
+            throw new Error(`'decisionLines' is required: one presentation line per decision line, matched by 'taxLineRef'.`);
+        }
+        if ('lines' in runtime && runtime.lines !== undefined) {
+            throw new Error(`'lines' is not part of the invoice contract: the VAT of an invoice comes from its `
+                + `tax decision. Send 'decisionLines' (presentation only).`);
+        }
         return this.client.post('/v1/invoices', params, options);
     }
     list(params) {
@@ -33,6 +53,37 @@ class Invoices {
     async del(id) {
         await this.client.del(`/v1/invoices/${id}`);
     }
+    /**
+     * Bind a FINAL tax decision to a commercial draft that already exists —
+     * typically the one `quotes.convert()` produced.
+     *
+     * This closes the quote cycle on ONE document:
+     *
+     * ```ts
+     * const { invoiceId } = await facturino.quotes.convert(quoteId)
+     * const decision = await facturino.taxDecisions.create({ ... }, { idempotencyKey })
+     * await facturino.invoices.bindTaxDecision(invoiceId, {
+     *   taxDecisionId: decision.id,
+     *   decisionLines: [{ taxLineRef: 'l1', unit: 'unit' }],
+     * })
+     * await facturino.invoices.finalize(invoiceId)
+     * ```
+     *
+     * The invoice stays a DRAFT: binding freezes the VAT, `finalize()` issues it.
+     * Idempotent on the decision — replaying the same call returns the same
+     * invoice. Binding a different decision to a bound invoice, or the same
+     * decision to a second invoice, is a conflict.
+     */
+    async bindTaxDecision(id, params, options) {
+        const runtime = params;
+        if (typeof runtime.taxDecisionId !== 'string' || runtime.taxDecisionId.length === 0) {
+            throw new Error(`'taxDecisionId' is required: a draft is fiscalised by binding a FINAL tax decision to it.`);
+        }
+        if (!Array.isArray(runtime.decisionLines) || runtime.decisionLines.length === 0) {
+            throw new Error(`'decisionLines' is required: one presentation line per decision line, matched by 'taxLineRef'.`);
+        }
+        return this.client.post(`/v1/invoices/${id}/bind-tax-decision`, params, options);
+    }
     /** Assign number and lock. Irreversible. */
     async finalize(id, options) {
         return this.client.post(`/v1/invoices/${id}/finalize`, undefined, options);

package/dist/cjs/resources/taxDecisions.d.ts

@@ -0,0 +1,31 @@
+import type { HttpClient } from '../client.js';
+import type { TaxDecision, TaxDecisionCreateParams, RequestOptions } from '../types.js';
+export declare class TaxDecisions {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Take a decision on a commercial operation.
+     *
+     * Business idempotency is durable here, beyond the 24-hour transport window,
+     * and it is keyed on the KEY — not on the operation. The SAME
+     * `idempotencyKey` with the SAME canonical body always replays the SAME
+     * decision, so a retry after a lost response costs nothing and charges
+     * nothing twice. Two DIFFERENT keys describing the same operation produce TWO
+     * decisions: nothing matches them up, and reusing one key with a different
+     * body answers `409`.
+     *
+     * Only a `final` decision carries amounts. On `pending_verification` or
+     * `unsupported`, `totals` and `amountToCharge` are `null` — never `0` — and
+     * `issues` says what is missing.
+     */
+    create(params: TaxDecisionCreateParams, options: RequestOptions & {
+        idempotencyKey: string;
+    }): Promise<TaxDecision>;
+    /**
+     * Read a decision back — typically after a payment capture, to check that the
+     * captured amount, currency and buyer match what was decided.
+     */
+    retrieve(id: string): Promise<TaxDecision>;
+    /** Alias of {@link TaxDecisions.retrieve}, for consistency with the other resources. */
+    get(id: string): Promise<TaxDecision>;
+}