verifactu-sdk API

---

verifactu-sdk API / VerifactuClient

Class: VerifactuClient

Defined in: src/client/VerifactuClient.ts:170

High-level SDK client.

Example

const client = new VerifactuClient({
  environment: 'preproduction',
  mode: 'verifactu',
  certificate: { pfx: readFileSync('./cert.pfx'), passphrase: 'changeme' },
  taxpayer: { nif: 'B12345678', legalName: 'Eloi Baulenas' },
  billingSystem: { ... },
});

const response = await client.registerInvoice(invoice);
console.log(response.csv);

Constructors

Constructor

new VerifactuClient(options): VerifactuClient

Defined in: src/client/VerifactuClient.ts:182

Parameters

options

VerifactuClientOptions

Client configuration. See VerifactuClientOptions.

Returns

VerifactuClient

Methods

registerInvoice()

registerInvoice(invoice): Promise<RegisterInvoiceResponse>

Defined in: src/client/VerifactuClient.ts:216

Register a single invoice (alta) with the AEAT.

The method runs the full happy-path pipeline: schema validation → business rules → hash chain → XAdES signing (if applicable) → SOAP envelope build → AEAT call (flow-controlled) → response parse.

Parameters

invoice

Invoice

Public English-named invoice payload.

Returns

Promise<RegisterInvoiceResponse>

The AEAT response with CSV, throttling delay and per-record state.

Throws

If the payload fails the Zod schema.

Throws

If a business rule is violated locally.

Throws

If the AEAT returns a <soapenv:Fault>.

Throws

If the transport fails.

---

cancelInvoice()

cancelInvoice(input): Promise<RegisterInvoiceResponse>

Defined in: src/client/VerifactuClient.ts:237

Cancel (anular) a previously registered invoice.

Parameters

input

CancelInvoiceInput

Public English-named cancellation payload.

Returns

Promise<RegisterInvoiceResponse>

The AEAT response with CSV, throttling delay and per-record state.

Throws

On schema failure.

Throws

On business-rule violation.

Throws

On AEAT-side fault.

Throws

On transport failure.

---

registerBatch()

registerBatch(records): AsyncIterable<RegisterInvoiceResponse>

Defined in: src/client/VerifactuClient.ts:258

Submit a batch of mixed alta/anulación records in a single envelope.

The batch is automatically split into ≤ 1000-record chunks; the SDK iterates the chunks while honouring the flow-control delay. Each chunk's response is yielded individually so callers can stream-process them.

Parameters

records

readonly (Invoice | CancelInvoiceInput)[]

Public English-named records (alta or cancellation).

Returns

AsyncIterable<RegisterInvoiceResponse>

Async iterable yielding one RegisterInvoiceResponse per chunk.

---

queryInvoices()

queryInvoices(filter): AsyncIterable<QueryResultPage>

Defined in: src/client/VerifactuClient.ts:309

Query previously submitted records (VERI*FACTU mode only).

Returns an async iterable that automatically pages through the AEAT response, propagating the ClavePaginacion cursor.

Parameters

filter

QueryFilter

Query filter (year + period required).

Returns

AsyncIterable<QueryResultPage>

Yields

One QueryResultPage at a time, in chronological order.

Throws

If the client is configured for 'onRequest' mode (the consulta service is only available for voluntary submissions).

---

renderQr()

renderQr(input, options?): Promise<RenderedQr>

Defined in: src/client/VerifactuClient.ts:380

Build and render the mandatory tax QR for an invoice.

The QR URL is computed via buildQrUrl using the SDK's configured Environment and Mode; the rendering format defaults to PNG.

Parameters

input

RenderQrInput

Identifier triple and total amount of the invoice.

options?

RenderQrOptions & object = {}

Rendering options (format, size, language).

Returns

Promise<RenderedQr>

The verification URL plus the rendered payload.