VeriFacTu Node Library

https://github.com/zarpilla/verifactu-node-lib
Admin
A JavaScript/TypeScript library for generating electronic invoices compatible with VeriFacTu of the...
Tokens:23,733
Snippets:196
Trust Score:5.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /api/verifactu/config

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Returns the software configuration (without secrets) used by the example Express server. The configuration is built from environment variables.

```APIDOC
## GET /api/verifactu/config

### Description
Returns the software configuration (without secrets) used by the example Express server. The configuration is built from environment variables.

### Method
GET

### Endpoint
/api/verifactu/config

### Parameters
No parameters are documented in the source.

### Request Example
No request body is documented in the source.

### Response
No response schema is documented in the source.
```

--------------------------------

### toStringRegexp usage example

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Example usage of toStringRegexp. The first call returns the string, the second throws because the input does not match the pattern.

```typescript
const nif = toStringRegexp(/^\d{8}[A-Z]$/);
nif("12345678Z");   // "12345678Z"
nif("BAD");         // throws
```

--------------------------------

### GET /api/verifactu/config

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Returns non-sensitive software configuration including software name, version, and feature flags. No request body required.

```APIDOC
## GET /api/verifactu/config

### Description
Exposes non-sensitive software configuration. No request body.

### Method
GET

### Endpoint
/api/verifactu/config

### Parameters
None

### Response
#### Success Response (200)
- **software** (object) - Software configuration.
  - **name** (string) - Software name.
  - **version** (string) - Software version.
  - **useOnlyVerifactu** (boolean) - Indicates if only VeriFactu is used.
  - **useMulti** (boolean) - Indicates if multi-use is enabled.

#### Response Example
{
  "software": {
    "name": "<SOFTWARE_CONFIG.name>",
    "version": "<SOFTWARE_CONFIG.version>",
    "useOnlyVerifactu": true,
    "useMulti": true
  }
}
```

--------------------------------

### Error handling and first record example

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Example showing error handling when calling createVerifactuInvoice without a previousId, which creates the first record in the chain. The verifactuXml is base64-decoded to UTF-8 for inspection. Catches errors and logs the error message.

```typescript
import { createVerifactuInvoice, Invoice, Software } from 'verifactu-node-lib';

try {
    // Omit previousId -> first record in chain (RegistroAnterior removed)
    const result = await createVerifactuInvoice(invoice, software);
    // Decode the XML for inspection
    const xml = Buffer.from(result.verifactuXml, 'base64').toString('utf8');
    console.log(xml);
} catch (error) {
    console.error('Error creando factura:', error instanceof Error ? error.message : String(error));
}
```

--------------------------------

### Basic call to createVerifactuInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Example showing a typical call to createVerifactuInvoice with an invoice, software object, and a previous invoice for chaining. The result fields qrcode, chainInfo, and verifactuXml are logged. Uses the alias export createVerifactuInvoice.

```typescript
import { createVerifactuInvoice, Invoice, Software, PreviousInvoiceId } from 'verifactu-node-lib';

const software: Software = {
    developerName: "Mi Empresa Desarrolladora S.L.",
    developerIrsId: "B12345678",
    name: "Mi Software de Facturación",
    id: "SOFT_001",
    version: "1.0.0",
    number: "12345",
    useOnlyVerifactu: true,
    useMulti: true,
    useCurrentMulti: false
};

const invoice: Invoice = {
    issuer: { irsId: "99999990S", name: "Mi Empresa S.L." },
    recipient: { irsId: "B87654321", name: "Cliente S.A.", country: "ES" },
    id: { number: "FAC-100", issuedTime: new Date("2024-03-18T10:00:00.000Z") },
    type: "F1",
    description: { text: "Servicios de consultoría" },
    vatLines: [{ vatOperation: "S1", base: 1000.00, rate: 21, amount: 210.00, vatKey: "01" }],
    total: 1210.00,
    amount: 210.00
};

const previousInvoice: PreviousInvoiceId = {
    issuerIrsId: "99999990S",
    number: "FAC-099",
    issuedTime: new Date("2024-03-17T10:00:00.000Z"),
    hash: "abc123def456789..."
};

const result = await createVerifactuInvoice(invoice, software, previousInvoice);
console.log(result.qrcode);        // data:image/png;base64,...
console.log(result.chainInfo);     // next chaining info (including new hash)
console.log(result.verifactuXml);  // base64 SOAP XML
```

--------------------------------

### POST /api/verifactu/invoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Creates a VeriFactu invoice via the example Express server. The endpoint accepts invoice data, an optional previous invoice, and a testing flag, and returns the full VerifactuResult on success or an error message on failure.

```APIDOC
## POST /api/verifactu/invoice

### Description
Creates a VeriFactu invoice by invoking the core library's `createVerifactuInvoice` function. The request body contains the invoice data, an optional previous invoice for chaining, and a testing flag. The response returns the full `VerifactuResult` on success or an error message on failure.

### Method
POST

### Endpoint
/api/verifactu/invoice

### Parameters
#### Request Body
- **invoice** (object) - Required - Invoice data (type `Invoice`).
- **previousInvoice** (object) - Optional - Previous invoice for chaining (type `PreviousInvoiceId`).
- **testing** (boolean) - Optional - Default `false`. Passed as the `isTesting` argument to `createVerifactuInvoice`.

### Request Example
{
  "invoice": { ... },
  "previousInvoice": { ... },
  "testing": false
}

### Response
#### Success Response (200)
- **success** (boolean) - Always `true`.
- **data** (object) - The full `VerifactuResult` (`qrcode`, `chainInfo`, `verifactuXml`, `wsld`, `endpoint`, `hash`).

#### Response Example
{
  "success": true,
  "data": { ... VerifactuResult ... }
}

#### Error Response (400)
- **success** (boolean) - Always `false`.
- **error** (string) - The error message thrown by `createVerifactuInvoice` (e.g., validation errors, NIF pattern errors).

#### Error Response Example
{
  "success": false,
  "error": "<error message>"
}

### Validation
Before the handler, the `validateInvoiceData` middleware rejects with `400` if:
- No `invoice` in body: `Campo "invoice" es obligatorio`
- Missing `invoice.issuer.irsId` or `invoice.issuer.name`: `Datos del emisor incompletos`
- Missing `invoice.id.number` or `invoice.id.issuedTime`: `Datos de identificación de factura incompletos`
- Empty/missing `invoice.vatLines`: `Debe incluir al menos una línea de IVA`
```

--------------------------------

### toStringMaxLength usage example

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Example usage of toStringMaxLength. The first call returns the string, the second throws an error because the input exceeds the maximum length.

```typescript
const toStr10 = toStringMaxLength(10);
toStr10("ok");        // "ok"
toStr10("12345678901"); // throws: String exceeds maximum length of 10
```

--------------------------------

### Basic call to cancelVerifactuInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Example of calling cancelVerifactuInvoice with a cancelInvoice object, a previousInvoice for chaining, and a software object. The result's qrcode is always null for cancellations.

```typescript
import { cancelVerifactuInvoice, CancelInvoice, Software, PreviousInvoiceId } from 'verifactu-node-lib';

const cancelInvoice: CancelInvoice = {
    issuer: { irsId: "99999990S", name: "Mi Empresa S.L." },
    id: { number: "FAC-100", issuedTime: new Date("2024-03-18T10:00:00.000Z") }
};

const previousInvoice: PreviousInvoiceId = {
    issuerIrsId: "99999990S",
    number: "FAC-099",
    issuedTime: new Date("2024-03-17T10:00:00.000Z"),
    hash: "abc123def456789..."
};

const result = await cancelVerifactuInvoice(cancelInvoice, software, previousInvoice);
console.log(result.qrcode);        // null (cancellations have no QR)
console.log(result.chainInfo);
console.log(result.verifactuXml);
```

--------------------------------

### GET /api/verifactu/health

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Health check endpoint for the example Express server. It is used to verify that the server is running.

```APIDOC
## GET /api/verifactu/health

### Description
Health check endpoint for the example Express server. It returns a simple response indicating the server is running.

### Method
GET

### Endpoint
/api/verifactu/health

### Parameters
No parameters are documented in the source.

### Request Example
No request body is documented in the source.

### Response
No response schema is documented in the source.
```

--------------------------------

### GET /api/verifactu/health

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Health check endpoint that returns service status, version, and software configuration. No request body required.

```APIDOC
## GET /api/verifactu/health

### Description
Health check endpoint. No request body.

### Method
GET

### Endpoint
/api/verifactu/health

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Status of the service.
- **service** (string) - Service name.
- **version** (string) - API version.
- **timestamp** (string) - ISO 8601 timestamp.
- **software** (object) - Software configuration.
  - **name** (string) - Software name.
  - **version** (string) - Software version.

#### Response Example
{
  "status": "ok",
  "service": "VeriFacTu API",
  "version": "1.0.0",
  "timestamp": "<ISO 8601>",
  "software": {
    "name": "<SOFTWARE_CONFIG.name>",
    "version": "<SOFTWARE_CONFIG.version>"
  }
}
```

--------------------------------

### VatLine interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Defines a VAT line with tax base, rate, and optional surcharge fields. `vatOperation` values starting with `S*` emit the full subject set; `E*`/`N*` omit rate/amount. `tax` defaults to `"01"`.

```typescript
export interface VatLine {
    base: number;
    rate: number;
    amount?: number;
    rate2?: number;
    amount2?: number;
    vatOperation: VatExemptReason | VatType | VatNotSubjectReason;
    vatKey: VatKey;
    tax?: TaxType;
    isUsingSimplifiedRegime?: boolean;
}
```

--------------------------------

### Remove elements with querySelectorAll and removeElement

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Example usage of `querySelectorAll` and `removeElement` to strip the `<Destinatarios>` block when there is no recipient.

```typescript
// Used internally to strip the <Destinatarios> block when there is no recipient
querySelectorAll(xml, 'RegistroAnterior').forEach(removeElement);
```

--------------------------------

### POST /api/verifactu/invoice/cancel

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Cancels a VeriFactu invoice via the example Express server. The endpoint is listed in the route table but no request/response details are provided in the source.

```APIDOC
## POST /api/verifactu/invoice/cancel

### Description
Cancels a VeriFactu invoice. The endpoint is part of the example Express server and is used to cancel an existing invoice. The request and response formats are JSON.

### Method
POST

### Endpoint
/api/verifactu/invoice/cancel

### Parameters
No parameters are documented in the source.

### Request Example
No request body is documented in the source.

### Response
No response schema is documented in the source.
```

--------------------------------

### Error handling with cancelVerifactuInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Example of calling cancelVerifactuInvoice inside a try-catch block to handle errors. The error message is logged using console.error.

```typescript
import { cancelVerifactuInvoice } from 'verifactu-node-lib';

try {
    const result = await cancelVerifactuInvoice(cancelInvoice, software);
    console.log('Factura anulada:', result.chainInfo);
} catch (error) {
    console.error('Error anulando factura:', error instanceof Error ? error.message : String(error));
}
```

--------------------------------

### Configure Software object for verifactu-node-lib

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/configuration.md

Defines the required Software configuration object for createInvoice and cancelInvoice. All 9 fields are required; validateSoftware throws 'Todos los datos del software son obligatorios' if any of the first six string fields is missing. Boolean fields map to 'S'/'N' via toBooleanString.

```typescript
import { Software } from 'verifactu-node-lib';

const software: Software = {
    developerName: "Mi Empresa Desarrolladora S.L.",
    developerIrsId: "B12345678",
    name: "Mi Software de Facturación",
    id: "SOFT_001",
    version: "1.0.0",
    number: "12345",
    useOnlyVerifactu: true,
    useMulti: true,
    useCurrentMulti: false
};
```

--------------------------------

### createInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Creates a Verifactu invoice by serializing the provided invoice data, generating a QR code, and returning the SOAP XML and chaining information. This is the primary function for creating invoices in the library.

```APIDOC
## createInvoice

### Description
Creates a Verifactu invoice by serializing the provided invoice data, generating a QR code, and returning the SOAP XML and chaining information.

### Signature
```ts
export async function createInvoice(
    invoice: Invoice,
    software: Software,
    previousId: PreviousInvoiceId | null = null,
    options: ToXmlOptions = {},
    isTesting = true
): Promise<VerifactuResult>
```

`createVerifactuInvoice` is an identical alias (`export const createVerifactuInvoice = createInvoice;`, `src/index.ts:8`).

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `invoice` | [`Invoice`](../types.md#invoice) | yes | — | The invoice data to serialize. |
| `software` | [`Software`](../types.md#software) | yes | — | Software identification block (`SistemaInformatico`). |
| `previousId` | [`PreviousInvoiceId`](../types.md#previousinvoiceid) \| `null` | no | `null` | Previous invoice for chaining. `null` produces a *first record* (removes `RegistroAnterior`, keeps `PrimerRegistro=S`). |
| `options` | [`ToXmlOptions`](../types.md#toxmloptions) | no | `{}` | Currently only an optional `deviceId`. Not consumed by the function body. |
| `isTesting` | `boolean` | no | `true` | When `true`, uses AEAT pre-production URLs for the QR code, WSDL, and endpoint. |

### Return type

Returns `Promise<VerifactuResult>` (`src/types.ts:137`):

| Field | Type | Meaning |
|-------|------|---------|
| `qrcode` | `string \| null` | QR code as a `data:` URL (from `qrcode.toDataURL`). Non-null for invoices. |
| `chainInfo` | `PreviousInvoiceId` | Chain info for the *next* invoice (hash of this record). |
| `verifactuXml` | `string` | The SOAP-wrapped invoice XML, base64-encoded. |
| `wsld` | `string` | URL of the WSDL service (note: field is misspelled "wsld" in source). |
| `endpoint` | `string` | URL of the SOAP endpoint. |
| `hash` | `string` | Uppercase hex SHA-256 hash of the record. |

### Behavior details

- The `chainInfo.hash` is the uppercase SHA-256 hex digest of:
  `IDEmisorFactura=...&NumSerieFactura=...&FechaExpedicionFactura=...&TipoFactura=...&CuotaTotal=...&ImporteTotal=...&Huella=<previousHash>&FechaHoraHusoGenRegistro=...` (`generateHash`, `src/verifactu.ts:230`).
- `TipoRectificativa` is set to `"I"` only when `invoice.type === "R1"`, otherwise empty and later removed.
- The `<Tercero>` block is removed when `(invoice.issuedBy || "N") === "N"`.
- `Subsanacion` is `"S"` when `invoice.id.replacement === true`, otherwise empty and removed.
- The `RetencionSoportada` element is removed when the (currently hardcoded to `0`) retention amount is not positive — the retention logic is commented out in this version.
- QR URL format: `https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=...&numserie=...&fecha=...&importe=...&hash=<last 6 chars>` (pre-production prefix is `https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR` when `isTesting` is `true`).

### Example — basic call

```typescript
import { createVerifactuInvoice, Invoice, Software, PreviousInvoiceId } from 'verifactu-node-lib';

const software: Software = {
    developerName: "Mi Empresa Desarrolladora S.L.",
    developerIrsId: "B12345678",
    name: "Mi Software de Facturación",
    id: "SOFT_001",
    version: "1.0.0",
    number: "12345",
    useOnlyVerifactu: true,
    useMulti: true,
    useCurrentMulti: false
};

const invoice: Invoice = {
    issuer: { irsId: "99999990S", name: "Mi Empresa S.L." },
    recipient: { irsId: "B87654321", name: "Cliente S.A.", country: "ES" },
    id: { number: "FAC-100", issuedTime: new Date("2024-03-18T10:00:00.000Z") },
    type: "F1",
    description: { text: "Servicios de consultoría" },
    vatLines: [{ vatOperation: "S1", base: 1000.00, rate: 21, amount: 210.00, vatKey: "01" }],
    total: 1210.00,
    amount: 210.00
};

const previousInvoice: PreviousInvoiceId = {
    issuerIrsId: "99999990S",
    number: "FAC-099",
    issuedTime: new Date("2024-03-17T10:00:00.000Z"),
    hash: "abc123def456789..."
};

const result = await createVerifactuInvoice(invoice, software, previousInvoice);
console.log(result.qrcode);        // data:image/png;base64,...
console.log(result.chainInfo);     // next chaining info (including new hash)
console.log(result.verifactuXml);  // base64 SOAP XML
```

### Example — error handling / first record

```typescript
import { createVerifactuInvoice, Invoice, Software } from 'verifactu-node-lib';

try {
    // Omit previousId -> first record in chain (RegistroAnterior removed)
    const result = await createVerifactuInvoice(invoice, software);
    // Decode the XML for inspection
    const xml = Buffer.from(result.verifactuXml, 'base64').toString('utf8');
    console.log(xml);
} catch (error) {
    console.error('Error creando factura:', error instanceof Error ? error.message : String(error));
}
```
```

--------------------------------

### VerifactuResult interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Returned by createInvoice and cancelInvoice. Contains QR as data URL or null for cancellations, chaining info, base64-encoded SOAP XML, WSDL URL (field name 'wsld' is a typo preserved from source), endpoint URL, and uppercase hex SHA-256 hash.

```ts
export interface VerifactuResult {
    qrcode: string | null; // XML codificado en base64
    chainInfo: PreviousInvoiceId;
    verifactuXml: string; // XML codificado en base64
    wsld: string; // URL del WSDL del servicio
    endpoint: string; // URL del endpoint del servicio
    hash: string; // Hash del XML
}
```

--------------------------------

### Import types from verifactu-node-lib

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Import the package's public types from the root entry point. All types are defined in src/types.ts and re-exported via export * from "./types";.

```ts
import { Invoice, Software, VerifactuResult, PreviousInvoiceId } from 'verifactu-node-lib';
```

--------------------------------

### Factura simplificada (F2) sin destinatario

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/README.md

Crea una factura simplificada (F2) que no requiere destinatario.

```typescript
const invoice: Invoice = {
    // ...otros campos
    type: "F2",
    // Sin campo recipient
    // ...
};
```

--------------------------------

### Software interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Software identification and usage flags, accepted by both createInvoice and cancelInvoice.

```ts
export interface Software {
    developerName: string;
    developerIrsId: string;
    name: string;
    id: string;
    version: string;
    number: string;
    useOnlyVerifactu: boolean;
    useMulti: boolean;
    useCurrentMulti: boolean;
}
```

--------------------------------

### toString(input: SimpleType): string

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Performs a plain string conversion using String(input). Returns an empty string for undefined or null, and never throws.

```APIDOC
## toString

### Description
Plain string conversion (`String(input)`); returns `""` for `undefined`/`null`. Never throws.

### Signature
```ts
export function toString(input: SimpleType): string
```

### Parameters
- **input** (SimpleType) - Required - The value to convert to string.

### Returns
- **string** - The string representation of the input, or `""` for `undefined`/`null`.

### Example
```typescript
toString(123); // "123"
toString(null); // ""
```
```

--------------------------------

### toDateString(input: SimpleType): string

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Formats a Date or date-like string as DD-MM-YYYY with zero-padded day and month. Returns an empty string for undefined or null, and throws an error for invalid dates.

```APIDOC
## toDateString

### Description
Formats a `Date` (or date-like string) as `DD-MM-YYYY` (zero-padded day/month, 4-digit year). Returns `""` for `undefined`/`null`.

### Signature
```ts
export function toDateString(input: SimpleType): string
```

### Parameters
- **input** (SimpleType) - Required - The date value to format.

### Returns
- **string** - The formatted date string, or `""` for `undefined`/`null`.

### Throws
- **Error** - `Invalid date: ${input}` when the parsed date is not valid.

### Example
```typescript
toDateString(new Date("2024-03-18T10:00:00Z")); // "18-03-2024"
toDateString("not a date");                      // throws: Invalid date
```
```

--------------------------------

### createInvoice function signature

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Shows the exported async function signature for createInvoice. Includes parameters: invoice (Invoice), software (Software), previousId (PreviousInvoiceId | null) with default null, options (ToXmlOptions) with default {}, and isTesting (boolean) with default true. The return type is Promise<VerifactuResult>.

```typescript
export async function createInvoice(
    invoice: Invoice,
    software: Software,
    previousId: PreviousInvoiceId | null = null,
    options: ToXmlOptions = {},
    isTesting = true
): Promise<VerifactuResult>
```

--------------------------------

### Pre-built formatters: toStr2...toStr500 and toNifStr

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Pre-built formatters from src/utils.ts:97-110. toStr2 through toStr500 call toStringMaxLength(n) for n = 2,20,30,50,60,64,100,120,500. toNifStr validates a Spanish NIF/CIF/NIE shape (X1234567X, 12345678X, or X12345678) and throws 'String does not match required pattern' otherwise.

```ts
export const toStr2 = toStringMaxLength(2);
export const toStr20 = toStringMaxLength(20);
export const toStr30 = toStringMaxLength(30);
export const toStr50 = toStringMaxLength(50);
export const toStr60 = toStringMaxLength(60);
export const toStr64 = toStringMaxLength(64);
export const toStr100 = toStringMaxLength(100);
export const toStr120 = toStringMaxLength(120);
export const toStr500 = toStringMaxLength(500);

export const toNifStr = toStringRegexp(
    /^(([a-z|A-Z]{1}\d{7}[a-z|A-Z]{1})|(\d{8}[a-z|A-Z]{1})|([a-z|A-Z]{1}\d{8}))$/
);
```

--------------------------------

### Factura completa (F1) con destinatario

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/README.md

Crea una factura completa (F1) que requiere un destinatario identificado con irsId, name y country.

```typescript
const invoice: Invoice = {
    // ...otros campos
    type: "F1",
    recipient: {
        irsId: "B87654321",
        name: "Cliente S.A.",
        country: "ES"
    }
    // ...
};
```

--------------------------------

### Catch validation errors from createVerifactuInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/errors.md

Shows how to catch validation errors from async functions. All public functions are async, so failures surface as Promise rejections caught via try/catch around await or .catch.

```typescript
import { createVerifactuInvoice, cancelVerifactuInvoice } from 'verifactu-node-lib';

try {
    const result = await createVerifactuInvoice(invoice, software);
} catch (error) {
    if (error instanceof Error) {
        console.error(error.message); // e.g. "El emisor es obligatorio y debe incluir NIF y nombre"
    } else {
        console.error(String(error));
    }
}
```

--------------------------------

### ToXmlOptions

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Options for XML generation, used as the options parameter for createInvoice and cancelInvoice.

```APIDOC
## ToXmlOptions

### Description
Options for XML generation, currently only accepts an optional device identifier. This interface is used as the `options` parameter for both `createInvoice` and `cancelInvoice`.

### Fields
- **deviceId** (`string`) - Optional - Optional device identifier. **Not consumed** by the current function bodies.

```

--------------------------------

### toString: plain string conversion

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

toString performs plain string conversion (String(input)); returns "" for undefined/null. Never throws.

```ts
export function toString(input: SimpleType): string
```

--------------------------------

### VerifactuResult

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Result object returned by createInvoice and cancelInvoice, containing the generated QR code, chaining info, XML, WSDL, endpoint, and hash.

```APIDOC
## VerifactuResult

### Description
Result object returned by `createInvoice` and `cancelInvoice`. Contains the generated QR code, chaining information, the SOAP-wrapped XML, WSDL and endpoint URLs, and the hash of the XML.

### Fields
- **qrcode** (`string | null`) - Required - QR as a `data:` URL (invoices), or `null` (cancellations).
- **chainInfo** (`PreviousInvoiceId`) - Required - Chaining info for the next record (includes the new `hash`).
- **verifactuXml** (`string`) - Required - SOAP-wrapped XML, base64-encoded.
- **wsld** (`string`) - Required - WSDL URL (field name "wsld" is a typo preserved from source).
- **endpoint** (`string`) - Required - SOAP endpoint URL.
- **hash** (`string`) - Required - Uppercase hex SHA-256 hash.

```

--------------------------------

### toBooleanString(input: SimpleType): string

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Returns 'S' for truthy values and 'N' for falsy values. Returns an empty string for undefined or null.

```APIDOC
## toBooleanString

### Description
Returns `"S"` for truthy values and `"N"` for falsy values; returns `""` for `undefined`/`null`.

### Signature
```ts
export function toBooleanString(input: SimpleType): string
```

### Parameters
- **input** (SimpleType) - Required - The value to convert to boolean string.

### Returns
- **string** - `"S"` for truthy, `"N"` for falsy, or `""` for `undefined`/`null`.

### Example
```typescript
toBooleanString(true);   // "S"
toBooleanString(false);  // "N"
```
```

--------------------------------

### ToXmlOptions interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Optional device identifier. Not consumed by the current function bodies. Accepted by the options parameter of both createInvoice and cancelInvoice.

```ts
export interface ToXmlOptions {
    deviceId?: string;
}
```

--------------------------------

### Factura rectificativa (R1) con nota de crédito

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/README.md

Crea una factura rectificativa (R1) con nota de crédito, estilo de sustitución (S), base y IVA.

```typescript
const invoice: Invoice = {
    // ...otros campos
    type: "R1",
    creditNote: {
        ids: [{
            number: "FAC-099",
            issuedTime: new Date("2024-03-17T10:00:00.000Z")
        }],
        style: "S", // Sustitución
        creditBase: 100.00,
        creditVat: 21.00
    }
    // ...
};
```

--------------------------------

### toStringRegexp function signature

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Returns a formatter that stringifies input and throws if the string does not match the provided regular expression. Throws Error with message 'String does not match required pattern: ${str}' when the pattern does not match.

```typescript
export function toStringRegexp(regexp: RegExp): FormatAndValidationFunction
```

--------------------------------

### POST /api/verifactu/invoice request body

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Request body for POST /api/verifactu/invoice. The invoice field is required; previousInvoice and testing are optional. testing defaults to false and is passed as the isTesting argument to createVerifactuInvoice.

```json
{
  "invoice": { ... },
  "previousInvoice": { ... },
  "testing": false
}
```

--------------------------------

### Config endpoint response

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Configuration endpoint response exposing non-sensitive software configuration.

```json
{
  "software": {
    "name": "<SOFTWARE_CONFIG.name>",
    "version": "<SOFTWARE_CONFIG.version>",
    "useOnlyVerifactu": true,
    "useMulti": true
  }
}
```

--------------------------------

### cancelInvoice

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Cancels an invoice by sending the cancellation data to the Verifactu service. Returns a VerifactuResult with chainInfo and XML, but qrcode is always null.

```APIDOC
## cancelInvoice

### Description
Cancels an invoice by sending the cancellation data to the Verifactu service. Returns a VerifactuResult with chainInfo and XML, but qrcode is always null.

### Signature
```ts
export async function cancelInvoice(
    cancelInvoice: CancelInvoice,
    software: Software,
    previousId: PreviousInvoiceId | null = null,
    options: ToXmlOptions = {},
    isTesting = true
): Promise<VerifactuResult>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `cancelInvoice` | [`CancelInvoice`](../types.md#cancelinvoice) | yes | — | Data identifying the invoice to cancel. |
| `software` | [`Software`](../types.md#software) | yes | — | Software identification block. |
| `previousId` | [`PreviousInvoiceId`](../types.md#previousinvoiceid) \| `null` | no | `null` | Previous invoice for chaining. |
| `options` | [`ToXmlOptions`](../types.md#toxmloptions) | no | `{}` | Not consumed by the function body. |
| `isTesting` | `boolean` | no | `true` | Uses AEAT pre-production URLs when `true`. |

### Return Type
Returns `Promise<VerifactuResult>` — the same shape as `createInvoice`, **except** `qrcode` is always `null` for cancellations ("Las anulaciones no generan QR", `src/verifactu.ts:664`).

### Behavior Details
- The hash for a cancellation is computed over:
  `IDEmisorFacturaAnulada=...&NumSerieFacturaAnulada=...&FechaExpedicionFacturaAnulada=...&Huella=<previousHash>&FechaHoraHusoGenRegistro=...` (`generateHash`).
- `chainInfo` is populated via `getCancelChainInfo`, which reads the `IDFactura>IDEmisorFacturaAnulada`, `NumSerieFacturaAnulada`, and `FechaExpedicionFacturaAnulada` elements (`src/verifactu.ts:355`).

### Example — Basic Call
```typescript
import { cancelVerifactuInvoice, CancelInvoice, Software, PreviousInvoiceId } from 'verifactu-node-lib';

const cancelInvoice: CancelInvoice = {
    issuer: { irsId: "99999990S", name: "Mi Empresa S.L." },
    id: { number: "FAC-100", issuedTime: new Date("2024-03-18T10:00:00.000Z") }
};

const previousInvoice: PreviousInvoiceId = {
    issuerIrsId: "99999990S",
    number: "FAC-099",
    issuedTime: new Date("2024-03-17T10:00:00.000Z"),
    hash: "abc123def456789..."
};

const result = await cancelVerifactuInvoice(cancelInvoice, software, previousInvoice);
console.log(result.qrcode);        // null (cancellations have no QR)
console.log(result.chainInfo);
console.log(result.verifactuXml);
```

### Example — Error Handling
```typescript
import { cancelVerifactuInvoice } from 'verifactu-node-lib';

try {
    const result = await cancelVerifactuInvoice(cancelInvoice, software);
    console.log('Factura anulada:', result.chainInfo);
} catch (error) {
    console.error('Error anulando factura:', error instanceof Error ? error.message : String(error));
}
```
```

--------------------------------

### POST /api/verifactu/invoice success response

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/endpoints.md

Success response (200) for POST /api/verifactu/invoice. The data field contains the full VerifactuResult object with qrcode, chainInfo, verifactuXml, wsld, endpoint, and hash.

```json
{
  "success": true,
  "data": { ... VerifactuResult ... }
}
```

--------------------------------

### Pre-built formatters: toStr2 ... toStr500, toNifStr

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Pre-built formatter constants that enforce maximum string lengths or validate Spanish NIF/CIF/NIE shape. These are exported constants that can be used directly.

```APIDOC
## Pre-built formatters

### Description
Pre-built formatter constants that enforce maximum string lengths or validate Spanish NIF/CIF/NIE shape. These are exported constants that can be used directly.

### Constants
- `toStr2` ... `toStr500` - `toStringMaxLength(n)` for `n = 2,20,30,50,60,64,100,120,500`. Truncates or validates string length.
- `toNifStr` - Validates a Spanish NIF/CIF/NIE shape: `X1234567X`, `12345678X`, or `X12345678`. Throws `String does not match required pattern` otherwise.

### Usage Example
```typescript
import { toStr20, toNifStr } from 'verifactu-node-lib';

const str = toStr20('some string');
const nif = toNifStr('12345678Z');
```
```

--------------------------------

### querySelector function signature

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Finds the first element matching a simple name or a `>`-separated path. For simple selectors (no `>`), recurses through the whole tree; for nested selectors it descends child-by-child (direct child first, then recursive fallback). Comparison ignores namespaces (`localName`, `tagName`, or `tagName.endsWith(':' + name)`). Returns `any` (the matched element) or `null`.

```typescript
export function querySelector(doc: any, selector: string): any
```

--------------------------------

### Invoice interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Main invoice structure accepted by createInvoice. Includes issuer, recipient, VAT lines, and optional credit note details.

```ts
export interface Invoice {
    issuer: Issuer;
    recipient?: Partner;
    id: InvoiceId;
    type: InvoiceType;
    replacedTicketIds?: InvoiceId[];
    creditNote?: CreditNote;
    description?: InvoiceDescription;
    vatLines: VatLine[];
    amount: number;
    total: number;
    issuedBy?: IssuedBy;
    isFix?: boolean;
    previousRejection?: boolean;
}
```

--------------------------------

### VatKey

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

VAT/regime key type used in invoice lines.

```APIDOC
## Type: VatKey

### Description
VAT/regime key (`ClaveRegimen`) as a string literal union type. Notable values: `"01"` general regime, `"02"` export, `"03"` used goods, `"04"` investment gold, `"05"` travel agencies, `"06"` group of entities in IGIC, `"07"` cash-basis criterion, `"08"` IPSI/IVA, `"09"` travel agency mediation, `"10"` collection for third parties, `"11"` lease of business premises, `"14"`/`"15"` IGIC pending accrual, `"17"` retail trader, `"18"` small business/professional, `"19"` exempt domestic operations (art. 25 Ley 19/1994).

### Type Definition
```ts
export type VatKey = "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "10" | "11" | "12" | "13" | "14" | "15" | "16" | "17" | "18" | "19" | "20" | "21" | "22" | "23" | "24" | "25" | "26" | "27" | "28" | "29" | "30" | "31" | "32" | "33" | "34" | "35" | "36" | "37" | "38" | "39" | "40" | "41" | "42" | "43" | "44" | "45" | "46" | "47" | "48" | "49" | "50" | "51" | "52";
```

### Usage
Used by [`VatLine.vatKey`](#vatline).
```

--------------------------------

### InvoiceDescription interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Describes an invoice operation. `text` maps to `DescripcionOperacion` and optional `operationDate` to `FechaOperacion`.

```typescript
export interface InvoiceDescription {
    text: string;
    operationDate?: Date;
}
```

--------------------------------

### InvoiceLine interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Defines an invoice line with base, quantity, unit price, and VAT lines. Note: not consumed by createInvoice in the current version.

```ts
export interface InvoiceLine {
  /** Base amount for the line */
  base: number;
  /** Description of the line item */
  description?: string;
  /** Quantity of items (if applicable) */
  quantity?: number;
  /** Unit of measure (if applicable) */
  unitMeasure?: string;
  /** Unit price */
  unitPrice: number;
  /** Total amount for the line (calculated as base * quantity) */
  totalAmount: number;
  /** VAT lines applicable to this invoice line */
  vatLines: VatLine[];
}
```

--------------------------------

### Export public API from src/index.ts

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/verifactu.md

Exports the library's public API from the top-level entry point. It re-exports all types and provides both original and aliased function names for invoice creation and cancellation.

```typescript
export * from "./types";
export const createVerifactuInvoice = createInvoice;
export const cancelVerifactuInvoice = cancelInvoice;
export { createInvoice, cancelInvoice } from "./verifactu";
```

--------------------------------

### CreditNoteType

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Credit-note style type.

```APIDOC
## Type: CreditNoteType

### Description
Credit-note style as a string literal union type: `"S"` substitution, `"I"` (direct).

### Type Definition
```ts
export type CreditNoteType = "S" | "I";
```

### Usage
Used by [`CreditNote.style`](#creditnote).
```

--------------------------------

### Línea de IVA exenta (E1)

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/README.md

Define una línea de IVA exenta (E1) con tipo 0 y clave de régimen 02.

```typescript
{
    vatOperation: "E1",
    base: 1000.00,
    rate: 0,
    amount: 0,
    vatKey: "02"
}
```

--------------------------------

### PartnerIrs interface

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/types.md

Represents a recipient that has an NIF. The `irsId` renders as `<NIF>`, `name` as `<NombreRazon>`, and optional `country` as the country code.

```typescript
export interface PartnerIrs {
    irsId: string;
    name: string;
    country?: CountryCode;
}
```

--------------------------------

### toDateString: format date as DD-MM-YYYY

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

toDateString formats a Date (or date-like string) as DD-MM-YYYY (zero-padded day/month, 4-digit year). Returns "" for undefined/null. Throws Error 'Invalid date: ${input}' when the parsed date is not valid.

```ts
export function toDateString(input: SimpleType): string
```

```typescript
toDateString(new Date("2024-03-18T10:00:00Z")); // "18-03-2024"
toDateString("not a date");                      // throws: Invalid date
```

--------------------------------

### round2ToString(input: SimpleType): string

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Converts a value to a number and formats it with 2 decimal places. Returns an empty string for undefined or null, and throws an error if the input cannot be converted to a number.

```APIDOC
## round2ToString

### Description
Converts the value to a number and formats it with 2 decimal places (`toFixed(2)`). Returns `""` for `undefined`/`null`.

### Signature
```ts
export function round2ToString(input: SimpleType): string
```

### Parameters
- **input** (SimpleType) - Required - The value to format.

### Returns
- **string** - The formatted number with 2 decimal places, or `""` for `undefined`/`null`.

### Throws
- **Error** - `Invalid number: ${input}` when `Number(input)` is `NaN`.

### Example
```typescript
round2ToString(21);      // "21.00"
round2ToString(210);     // "210.00"
round2ToString("abc");   // throws: Invalid number
```
```

--------------------------------

### toStringMaxLength function signature

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

Returns a formatter that stringifies input and throws if the resulting string is longer than maxLength. Throws Error with message 'String exceeds maximum length of ${maxLength}: ${str}' when the string exceeds maxLength.

```typescript
export function toStringMaxLength(maxLength: number): FormatAndValidationFunction
```

--------------------------------

### updateDocument function signature

Source: https://github.com/zarpilla/verifactu-node-lib/blob/main/_autodocs/api-reference/utils.md

For each `[selector, value, convert]` tuple: finds the node via `querySelector`. If the value is `undefined` and the node has a parent, the node is **removed**; otherwise its `textContent` is set to `convert(value)`.

```typescript
export function updateDocument(
    doc: any,
    selectorsToValues: Array<[string, SimpleType, FormatAndValidationFunction]>
): void
```
Tokens:
Raw