@beel_es/sdk 1.2.0 → 2.0.0

package/README.md

@@ -62,8 +62,22 @@ const company = beel.company('company-uuid');
 // Invoices — full lifecycle
 const { invoices, pagination } = await company.invoices.list({ status: 'ISSUED' });
 await company.invoices.issue('invoice-uuid');
-await company.invoices.void('invoice-uuid', { reason: 'Billing error' });
-await company.invoices.createCorrective('invoice-uuid', { ... });
+// A void is only for an invoice issued by mistake; `issued_in_error: true` is required
+// once it has been sent or paid. An operation that did happen gets a corrective instead.
+await company.invoices.void('invoice-uuid', { reason: 'Duplicate', issued_in_error: true });
+await company.invoices.createCorrective('invoice-uuid', {
+  rectification_type: 'PARTIAL',
+  rectification_code: 'R1',
+  reason: 'Discount granted after the sale',
+  circumstance_date: '2026-09-01', // when the art. 80 circumstance happened, if any
+  lines: [ ... ],
+});
+// Exchange issued simplified invoices for a full one with the customer identified
+await company.invoices.createSimplifiedExchange({
+  simplified_invoice_ids: ['simplified-uuid'],
+  recipient: { customer_id: 'customer-uuid' },
+});
+const records = await company.invoices.verifactuRecords('invoice-uuid'); // registration, cancellation
 const pdf = await company.invoices.getPdf('invoice-uuid');
 
 // Customers, products, series
@@ -75,11 +89,74 @@ await company.series.ensureDefaults(); // idempotent seeding of the typed defaul
 await company.recurringInvoices.create({ ... });
 await company.recurringInvoices.setStatus('rec-uuid', { status: 'PAUSED' });
 
+// Scheduling — one PUT sets or moves it, one DELETE clears it
+await company.invoices.schedule.set('invoice-uuid', { scheduled_for: '2026-12-01' });
+await company.invoices.schedule.clear('invoice-uuid');
+
+// Derive a new invoice from an existing one
+const copy = await company.invoices.derive({ from_invoice_id: 'invoice-uuid' });
+
+// Fiscal configuration of this NIF
+const verifactu = await company.verifactuConfiguration.get();
+await company.verifactuConfiguration.update({ enabled: true });
+const taxes = await company.taxConfiguration.get();
+
 // Company health
 const summary = await company.fiscalSummary({ year: 2026 });
 const readiness = await company.issuingReadiness();
 ```
 
+Whether an invoice reaches AEAT is a fact of the **NIF**, resolved at issue time — not a
+per-invoice choice. `enabled` is the only writable field of the VeriFactu configuration.
+
+### Payment connections (Stripe per NIF)
+
+A connection links Stripe to one NIF so its charges auto-generate invoices under it. It is
+addressed by **its own UUID**, not by the provider slug — a NIF can hold several
+connections of the same provider. The slug only appears when you start an authorization.
+
+```typescript
+const { connections } = await company.paymentConnections.list();
+
+const { authorization_url } = await company.paymentConnections.authorize({
+  provider: 'stripe',
+});
+
+const events = company.paymentConnections.events(connections[0].id);
+const { events: pending } = await events.list({ needs_action: true });
+
+// Recovery levers for a charge that did not invoice
+await events.retry('event-uuid');
+const { invoice_id } = await events.draft('event-uuid'); // review before issuing
+await events.resolve('event-uuid');
+
+await company.paymentConnections.disconnect(connections[0].id);
+```
+
+## Catalogs and preferences
+
+```typescript
+const taxTypes = await beel.catalogs.taxTypes();
+const options = await beel.catalogs.invoiceCustomizationOptions();
+await beel.catalogs.updateMe({ language: 'es' }); // the language belongs to the person
+```
+
+## Any endpoint: `beel.raw`
+
+A route reaches the generated types as soon as the contract is synced, but its ergonomic
+wrapper is written by hand. `beel.raw` lets you call anything in the contract today,
+without waiting for a release:
+
+```typescript
+const { data } = await beel.raw.GET('/v1/companies/{company_id}/invoice-customization', {
+  params: { path: { company_id: 'company-uuid' } },
+});
+```
+
+It is the same client the resources use — authentication, retries and `Idempotency-Key`
+still apply — and it stays typed: a path, parameter or body the contract does not have
+will not compile. What you give up is the sugar and the naming stability of the wrappers.
+
 ## Accounts (managed accounts, members & webhooks)
 
 For integrators managing several accounts (provisioning, gestorías, platforms):
@@ -227,8 +304,11 @@ app.post('/webhooks/beel', express.raw({ type: 'application/json' }), (req, res)
       req.headers['beel-signature'] as string,
     );
 
+    // "Send test" deliveries carry a synthetic `data`: acknowledge and stop.
+    if (event.test) return res.status(200).send('OK');
+
     if (event.type === 'verifactu.status.updated') {
-      console.log(event.data.new_status); // 'ACCEPTED' | 'REJECTED'
+      console.log(event.data.new_status); // 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'VOIDED'
     }
 
     res.status(200).send('OK');