chore(multiInvoices): add new methods for multiinvoice receipts

Author: raul-facturapi

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.17.0] 2026-04-27
+### Added
+- Add `receipts.toInvoice` to create customer invoices from multiple receipt keys.
+- Add `receipts.previewToInvoicePdf` to generate PDF previews for multi-invoice payloads.
+
 ## [4.16.0] 2026-04-23
 ### Added
 - Add new export catalogs for customs regimes, transport keys, SCT permits, COFEPRIS sectors, pharmaceutical forms, special transport conditions, customs documents, transport types, transport figures, ISTMO registry, loading keys, maritime configurations, rail traffic, containers, rail cars, rail service types, transfer reasons, incoterms, and customs units.

src/resources/receipts.ts

@@ -2,6 +2,9 @@ import {
   BinaryDownload,
   GenericResponse,
   Invoice,
+  MultiInvoiceInput,
+  MultiInvoiceResult,
+  PreviewMultiInvoicePdfInput,
   Receipt,
   SearchResult,
   SendEmailBody,
@@ -62,6 +65,29 @@ export default class Receipts {
     return this.client.post('/receipts/global-invoice', { body: data });
   }
 
+  /**
+   * Creates an invoice from multiple receipts by key.
+   * Supports dry-run summaries when `dry_run` is true.
+   * @param data Multi-invoice request data
+   * @returns Invoice object or dry-run summary
+   */
+  toInvoice(data: MultiInvoiceInput): Promise<MultiInvoiceResult> {
+    return this.client.post('/receipts/multi-invoice', { body: data });
+  }
+
+  /**
+   * Generates a PDF preview for a multi-invoice request before stamping.
+   * @param data Multi-invoice preview data
+   * @returns PDF file in a stream (Node.js) or Blob (browser)
+   */
+  previewToInvoicePdf(
+    data: PreviewMultiInvoicePdfInput,
+  ): Promise<BinaryDownload> {
+    return this.client.post('/receipts/multi-invoice/preview/pdf', {
+      body: data,
+    });
+  }
+
   /**
    * Marks a receipt as canceled. The receipt won't be available for invoicing anymore.
    * @param id

src/types/receipt.ts

@@ -1,5 +1,6 @@
 import type { ReceiptStatus } from '../enums';
 import type { InvoiceItem } from './common';
+import type { Invoice } from './invoice';
 
 export interface Receipt {
   id: string;
@@ -23,3 +24,19 @@ export interface Receipt {
   status: ReceiptStatus;
   self_invoice_url: string;
 }
+
+export interface MultiInvoiceInput {
+  keys: string[];
+  customer?: Record<string, any>;
+  use?: string;
+  dry_run?: boolean;
+  payment_form?: string | null;
+}
+
+export type MultiInvoiceResult = Invoice | Record<string, any>;
+
+export interface PreviewMultiInvoicePdfInput {
+  keys: string[];
+  customer?: Record<string, any> | null;
+  use?: string;
+}

test/node/runtime-compat.node.test.ts

@@ -103,6 +103,78 @@ describe('runtime compatibility (node)', () => {
     expect(result.available).toBe(true);
   });
 
+  it('posts multi-invoice payload to receipts endpoint', async () => {
+    const client = createClient();
+    const payload = {
+      keys: ['rcp_key_1', 'rcp_key_2'],
+      dry_run: true,
+      use: 'G03',
+    };
+
+    globalThis.fetch = vi.fn(async (url, options) => {
+      expect(url).toBe('https://api.test.local/v2/receipts/multi-invoice');
+      expect(options?.method).toBe('POST');
+      expect(getHeader(options?.headers, 'Authorization')).toBe(
+        'Bearer sk_test_123',
+      );
+      expect(getHeader(options?.headers, 'Content-Type')).toBe(
+        'application/json',
+      );
+      expect(options?.body).toBe(JSON.stringify(payload));
+
+      return new Response(JSON.stringify({ total: 1234 }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }) as typeof fetch;
+
+    const result = await client.receipts.toInvoice(payload);
+    expect((result as Record<string, unknown>).total).toBe(1234);
+  });
+
+  it('downloads multi-invoice preview pdf', async () => {
+    const client = createClient();
+    const payload = {
+      keys: ['rcp_key_1'],
+      use: 'G03',
+    };
+
+    globalThis.fetch = vi.fn(async (url, options) => {
+      expect(url).toBe(
+        'https://api.test.local/v2/receipts/multi-invoice/preview/pdf',
+      );
+      expect(options?.method).toBe('POST');
+      expect(getHeader(options?.headers, 'Authorization')).toBe(
+        'Bearer sk_test_123',
+      );
+      expect(getHeader(options?.headers, 'Content-Type')).toBe(
+        'application/json',
+      );
+      expect(options?.body).toBe(JSON.stringify(payload));
+
+      return new Response(new Blob([Buffer.from('pdf-binary-content')]), {
+        status: 200,
+        headers: { 'content-type': 'application/pdf' },
+      });
+    }) as typeof fetch;
+
+    const pdf = await client.receipts.previewToInvoicePdf(payload);
+
+    expect(pdf instanceof Blob).toBe(false);
+    expect(typeof (pdf as any).pipe).toBe('function');
+
+    const chunks: Buffer[] = [];
+    await new Promise<void>((resolve, reject) => {
+      (pdf as any).on('data', (chunk: unknown) => {
+        chunks.push(Buffer.from(chunk as Uint8Array));
+      });
+      (pdf as any).on('error', reject);
+      (pdf as any).on('end', resolve);
+    });
+
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('pdf-binary-content');
+  });
+
   it('surfaces API message from non-OK JSON responses', async () => {
     const client = createClient();
 

test/web/runtime-compat.web.test.ts

@@ -87,6 +87,83 @@ describe('runtime compatibility (web simulation)', () => {
     );
   });
 
+  it('posts multi-invoice payload in web-like runtime', async () => {
+    const client = createClient();
+    const payload = {
+      keys: ['rcp_key_1', 'rcp_key_2'],
+      dry_run: true,
+      use: 'G03',
+    };
+
+    globalThis.fetch = vi.fn(async (url, options) => {
+      expect(url).toBe('https://api.test.local/v2/receipts/multi-invoice');
+      expect(options?.method).toBe('POST');
+      expect(getHeader(options?.headers, 'Authorization')).toBe(
+        'Bearer sk_test_123',
+      );
+      expect(getHeader(options?.headers, 'Content-Type')).toBe(
+        'application/json',
+      );
+      expect(options?.body).toBe(JSON.stringify(payload));
+
+      return new Response(JSON.stringify({ total: 1234 }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }) as typeof fetch;
+
+    const result = await client.receipts.toInvoice(payload);
+    expect((result as Record<string, unknown>).total).toBe(1234);
+  });
+
+  it('returns Blob for multi-invoice preview pdf in web-like runtime', async () => {
+    const client = createClient();
+    (globalThis as any).Buffer = undefined;
+    const payload = {
+      keys: ['rcp_key_1'],
+      use: 'G03',
+    };
+
+    globalThis.fetch = vi.fn(async (url, options) => {
+      expect(url).toBe(
+        'https://api.test.local/v2/receipts/multi-invoice/preview/pdf',
+      );
+      expect(options?.method).toBe('POST');
+      expect(getHeader(options?.headers, 'Authorization')).toBe(
+        'Bearer sk_test_123',
+      );
+      expect(getHeader(options?.headers, 'Content-Type')).toBe(
+        'application/json',
+      );
+      expect(options?.body).toBe(JSON.stringify(payload));
+
+      return {
+        ok: true,
+        headers: {
+          get(name: string) {
+            return name.toLowerCase() === 'content-type'
+              ? 'application/pdf'
+              : null;
+          },
+        },
+        body: undefined,
+        async blob() {
+          return new Blob(['pdf-binary-content']);
+        },
+        async json() {
+          return {};
+        },
+        async text() {
+          return '';
+        },
+      } as unknown as Response;
+    }) as typeof fetch;
+
+    const pdf = await client.receipts.previewToInvoicePdf(payload);
+    expect(pdf instanceof Blob).toBe(true);
+    expect(await (pdf as Blob).text()).toBe('pdf-binary-content');
+  });
+
   it('falls back to raw text on malformed JSON error bodies in web-sim', async () => {
     const client = createClient();