verifactu-sdk API / VerifactuClient
Class: VerifactuClient
Defined in: src/client/VerifactuClient.ts:188
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: { ... },
hashStore: new SqliteHashStore(new Database('verifactu.sqlite')),
});
const response = await client.registerInvoice(invoice);
console.log(response.csv);Constructors
Constructor
new VerifactuClient(
options):VerifactuClient
Defined in: src/client/VerifactuClient.ts:201
Parameters
options
Client configuration. See VerifactuClientOptions.
Returns
VerifactuClient
Methods
registerInvoice()
registerInvoice(
input):Promise<RegisterInvoiceResponse>
Defined in: src/client/VerifactuClient.ts:249
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.
Once the AEAT answers, the record's hash becomes the chain tail even if the record was rejected: the chain links every record generated (Orden HAC/1177/2024 art. 7.i), so a rejection is fixed by a later subsanación rather than by rewinding the chain. Nothing is persisted when the call throws. Retry with the same invoice (same generatedAt): its hash comes out identical, so if the lost attempt had reached the AEAT the retry is answered as a duplicate — see RegisterInvoiceRecordResult.duplicateRecord.
Chain updates are serialised per client, so concurrent calls on one instance never read the same tail.
Parameters
input
Public English-named invoice payload. billingSystem defaults to the client's option; chainLink and hash are computed.
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 rejects the envelope with a <soapenv:Fault>.
Throws
If the transport fails.
cancelInvoice()
cancelInvoice(
request):Promise<RegisterInvoiceResponse>
Defined in: src/client/VerifactuClient.ts:280
Cancel (anular) a previously registered invoice.
Chains and persists exactly like registerInvoice, including the retry contract on generatedAt.
Parameters
request
Public English-named cancellation payload, completed like the input of registerInvoice.
Returns
Promise<RegisterInvoiceResponse>
The AEAT response with CSV, throttling delay and per-record state.
Throws
On schema failure.
Throws
On business-rule violation.
Throws
If the AEAT rejects the envelope with a <soapenv:Fault>.
Throws
On transport failure.
registerBatch()
registerBatch(
records):AsyncIterable<RegisterInvoiceResponse>
Defined in: src/client/VerifactuClient.ts:319
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.
Records chain to each other in order, across chunks. Once a chunk is answered, its last record becomes the chain tail — whatever each record's state, as in registerInvoice — and only then is the response yielded, so stopping the iteration early never loses an answered chunk. A chunk that throws persists nothing; retrying the remaining records with the same generatedAt values reproduces their hashes.
The client's chain lock is held from the first next() until the iteration completes, throws or is closed (break / return()): always finish or close the iterator, or later calls on this client wait forever.
Parameters
records
readonly (RegisterInvoiceInput | CancelInvoiceRequest)[]
Public English-named records (alta or cancellation), completed like the input of registerInvoice.
Returns
AsyncIterable<RegisterInvoiceResponse>
Async iterable yielding one RegisterInvoiceResponse per chunk.
queryInvoices()
queryInvoices(
filter):AsyncIterable<QueryResultPage>
Defined in: src/client/VerifactuClient.ts:376
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
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:447
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
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.