facturas Public API Reference

The facturas package exposes a small, stable public API covered by semantic versioning. Every method, type, and store constructor documented on this page will not change in a breaking way without a version bump. You can import from the package root facturas or from its named sub-paths — all of them are listed at the end of this page.

facturas is pre-1.0. Minor version bumps may include breaking changes. Pin an exact version in your package.json — for example "facturas": "0.11.0" — and review the changelog before upgrading.

`createArcaClient(options?)`

The main factory function. Call it once at startup and reuse the returned ArcaClient instance throughout your application.

import { createArcaClient } from "facturas";

const arca = createArcaClient({
  taxId: "20123456786",
  certificatePem: process.env.ARCA_CERTIFICATE_PEM!,
  privateKeyPem: process.env.ARCA_PRIVATE_KEY_PEM!,
  environment: "test",
});

All options fall back to the corresponding environment variable when omitted. Explicit values always win over environment variables. If a required field is missing from both the options object and the environment, createArcaClient throws ArcaConfigurationError immediately.

Options

string

required

Your 11-digit CUIT (tax ID). Falls back to the ARCA_TAX_ID environment variable.

string

required

PEM-encoded ARCA/AFIP certificate issued for your CUIT. Falls back to ARCA_CERTIFICATE_PEM. Treat this value as a secret.

string

required

PEM-encoded private key matching the certificate above. Falls back to ARCA_PRIVATE_KEY_PEM. Treat this value as a secret.

"test" | "production"

required

Target ARCA environment. Falls back to ARCA_ENVIRONMENT. There is no default — the client throws if this is absent from both sources.

number

default:"30000"

HTTP request timeout in milliseconds.

number

default:"0"

Number of additional transport-layer retry attempts. Retries apply only to ArcaTransportError (connection failures, timeouts, non-XML HTTP error responses). SOAP faults and service-level errors are never retried automatically.

number

default:"500"

Milliseconds to wait between transport retries.

ArcaLoggerConfig

Optional structured logger configuration. Pass { level: "debug" } to enable SOAP traces, WSAA login origin, and retry logs. Pass { disabled: true } to suppress all SDK output. Provide a custom sink via { level, log(level, message, ...args) { … } }. The default minimum level is warn. You can also set ARCA_LOG_LEVEL in the environment without touching code.

ArcaStore

A unified durable store for WSAA session tickets and invoice/credit-note idempotency reservations. Providing a store enables durability across process restarts and serverless cold starts. See Store Constructors below.

ArcaWsaaSessionStore

An optional separate store used only for WSAA login tickets. Takes priority over store for ticket management. Useful when you already have a shared cache and only want to persist auth tokens, not issuance reservations.

`ArcaClient` Methods

`issue(input, options?)`

Derives the ARCA request, reserves the next voucher number, sends the authorization, and returns the fiscal outcome. On an indeterminate result (timeout, connection loss, inconclusive response), issue automatically looks up the voucher at ARCA before returning — so you never need to check manually on a subsequent call.

import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
const outcome = await arca.issue({
  salesPoint: 1,
  receiverName: "Juan Pérez",
  receiverVatCondition: "consumidor_final",
  lines: [{ description: "Consultoría", quantity: 1, unitPrice: 10000 }],
});

if (outcome.kind === "authorized") {
  console.log(outcome.voucher.cae, outcome.voucher.caeExpiry);
}

Returns: Promise<IssueOutcome>

IssueInput

required

High-level invoice descriptor. See the Invoices guide for the full field list.

"wsfe" | "wsmtxca"

default:"\"wsfe\""

Target service. Pass "wsmtxca" to issue with full line-item detail via WSMTXCA.

number

An externally reserved voucher number. When supplied, issue skips the automatic getNextVoucherNumber call and uses this number instead.

string

An application-level key that ties the operation to your store reservation. Replaying the same key with the same input recovers the previous result; replaying with a different input throws ARCA_INPUT_IDEMPOTENCY_MISMATCH.

string | number

CUIT of the taxpayer on whose behalf you are issuing (for multi-tenant integrations).

boolean

Discard the cached WSAA ticket and obtain a fresh one before this call.

boolean

Include the raw ARCA SOAP response on the returned outcome.

boolean

Include the exact WsfeVoucherInput or WsmtxcaIssueRequest that was sent to ARCA on the returned outcome under sent.

`preview(input, options?)`

Derives the ARCA request object that issue would send, without making any network calls or reserving a number. Use this to inspect the fiscal amounts, derived voucher type, and service-level payload before committing.

import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
const preview = await arca.preview({
  salesPoint: 1,
  receiverName: "Empresa SRL",
  receiverVatCondition: "responsable_inscripto",
  receiverTaxId: "30999888777",
  lines: [{ description: "Software", quantity: 1, unitPrice: 50000 }],
});

console.log(preview.voucherClass); // "A"
console.log(preview.amounts.total);

Returns: IssuePreview

`recover(key)`

Looks up a previously stored idempotency reservation by its key. Returns the stored record if it exists, or undefined if no reservation was found under that key.

import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
const reservation = await arca.recover("invoice-order-42");
if (reservation) {
  console.log(reservation.coordinates, reservation.operation);
}

Returns: Promise<…reservation | undefined>

`issueCreditNote(input, options?)`

Issues a credit note against a previously authorized voucher. Accepts the same options as issue.

import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
const outcome = await arca.issueCreditNote({
  salesPoint: 1,
  associatedVoucher: {
    salesPoint: 1,
    voucherType: 6,
    number: 42,
    date: "2026-09-01",
    cuit: "20123456786",
  },
  lines: [{ description: "Devolución parcial", quantity: 1, unitPrice: 5000 }],
});

Returns: Promise<IssueOutcome>

`issueDebitNote(input, options?)`

Issues a debit note against a previously authorized voucher. Accepts the same options as issue. Returns: Promise<IssueOutcome>

`previewCreditNote(input, options?)`

Derives the ARCA request a credit note issuance would send, with no network calls. Returns: IssuePreview

`previewDebitNote(input, options?)`

Derives the ARCA request a debit note issuance would send, with no network calls. Returns: IssuePreview

`arca.wsfe`

The low-level WSFE service handle. Exposes raw ARCA methods including authorize, getNextVoucherNumber, getLastAuthorizedVoucher, lookupVoucher, and runtime catalog methods. See Exact Layer for the full surface.

`arca.wsmtxca`

The low-level WSMTXCA service handle. Same pattern as wsfe, adding full line-item encoding. See Exact Layer for details.

`arca.padron`

The Padrón service handle. Use it to look up taxpayer details or resolve a CUIT from a document number.

import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
const taxpayer = await arca.padron.getTaxpayerDetails("20123456786");
if (taxpayer) {
  console.log(taxpayer.name, taxpayer.personType);
}

const result = await arca.padron.getTaxIdByDocument("12345678");
if (result) {
  console.log(result.taxIds);
}

Padrón “not found” detection relies on SOAP fault message text from ARCA, which is less reliable than the code-based flows used by WSFE. Handle null returns defensively.

Store Constructors

All four store constructors are part of the public semver contract. Pass the result of any of them as the store option to createArcaClient. A single store covers both WSAA session tickets and issuance idempotency reservations.

Store reservation records contain fiscal and customer data. Restrict access to the underlying storage and protect backups accordingly. You cannot delete, expire, or overwrite reservation records — doing so can cause a retry to issue a duplicate invoice.

`createPostgresStore(options)`

Uses your application’s existing Postgres client. Compatible with Neon, Supabase Postgres, Vercel Postgres, pg, and postgres.

import { createPostgresStore, createArcaClient } from "facturas";
// ---cut---
// Create the table once:
// CREATE TABLE arca_store (
//   key text PRIMARY KEY,
//   value text NOT NULL,
//   updated_at timestamptz NOT NULL DEFAULT now()
// );

const store = createPostgresStore({
  query: (text, params) => pool.query(text, params),
  table: "arca_store", // optional, this is the default
});

(text: string, params: unknown[]) => Promise<…>

required

A parameterized query function. Results can be an array of rows or an object { rows }. For the postgres package, adapt with sql.unsafe(text, params).

string

default:"\"arca_store\""

Name of the table to use. Must be a simple SQL identifier (no schema prefix or quoting).

`createRedisStore(redis, options?)`

Wraps an ioredis or Upstash Redis client.

import { createRedisStore, createArcaClient } from "facturas";
declare const redis: any;
// ---cut---
const store = createRedisStore(redis);
// For Upstash:
// const store = createRedisStore(redis, { flavor: "upstash" });

Use a durable Redis instance with no eviction on reservation keys. Neither adapter sets a TTL on reservation records.

`createFileStore(directory)`

Persists keys as individual files under directory. Suitable for single-server deployments with a private, durable volume.

import { createFileStore } from "facturas";
// ---cut---
const store = createFileStore("/private/durable/arca");

Files are created with mode 0600; new directories are created with 0700. Keys are hashed to filenames. No process-level locking is provided.

`createMemoryStore()`

An in-process store for tests and examples. Does not survive process restarts and cannot coordinate across workers.

import { createMemoryStore } from "facturas";
// ---cut---
const store = createMemoryStore();

`createPadronService(options)`

Creates a Padrón service instance wired with the provided authentication and SOAP transport. In most applications you access Padrón directly via arca.padron, which is created automatically by createArcaClient. The standalone constructor is exported from facturas/padron for integration scenarios where you assemble the SDK’s internal modules yourself. Returns: PadronService with getTaxpayerDetails(taxId) and getTaxIdByDocument(documentNumber).

import { createArcaClient } from "facturas";
// ---cut---
// Standard usage: access padron through the client instance.
const arca = createArcaClient({
  taxId: "20123456786",
  certificatePem: process.env.ARCA_CERTIFICATE_PEM!,
  privateKeyPem: process.env.ARCA_PRIVATE_KEY_PEM!,
  environment: "test",
});

const taxpayer = await arca.padron.getTaxpayerDetails("20123456786");
if (taxpayer) {
  console.log(taxpayer.name, taxpayer.personType);
}

Error Classes

All SDK errors extend ArcaError and carry a stable code string. Import error classes from either facturas or facturas/errors.

import {
  ArcaError,
  ArcaConfigurationError,
  ArcaInputError,
  ArcaAuthenticationError,
  ArcaTransportError,
  ArcaSoapFaultError,
  ArcaServiceError,
  isArcaAuthenticationError,
  toArcaSafeErrorMetadata,
} from "facturas/errors";

Error class summary

Class	When thrown
`ArcaConfigurationError`	Invalid client configuration (missing credentials, bad environment, store failure)
`ArcaInputError`	Invalid caller input — for example, a malformed date or a negative amount
`ArcaAuthenticationError`	Explicit authentication rejection from ARCA; carries a typed `reason`, service, operation, and safe provider code
`ArcaTransportError`	HTTP or network failure; carries an optional `statusCode`
`ArcaSoapFaultError`	A SOAP fault returned by ARCA; carries `faultCode`
`ArcaServiceError`	Business-level service rejection (e.g., WSFE error codes); carries `serviceCode`

Use isArcaAuthenticationError(error) as a type-narrowing predicate when you cannot use instanceof (for example, across module boundaries). Use toArcaSafeErrorMetadata(error) to extract a structured, loggable error summary that never includes raw credentials or request bodies.

import { ArcaAuthenticationError, ArcaServiceError, ArcaSoapFaultError, ArcaTransportError } from "facturas/errors";
import { createArcaClient } from "facturas";
const arca = createArcaClient({ taxId: "20123456786", certificatePem: "", privateKeyPem: "", environment: "test" });
// ---cut---
try {
  await arca.wsfe.getNextVoucherNumber({ salesPoint: 1, voucherType: 6 });
} catch (error) {
  if (error instanceof ArcaAuthenticationError) {
    console.error(error.reason, error.service, error.operation, error.providerCode);
  } else if (error instanceof ArcaServiceError) {
    console.error(error.serviceCode, error.message);
  } else if (error instanceof ArcaSoapFaultError) {
    console.error(error.faultCode, error.message);
  } else if (error instanceof ArcaTransportError) {
    console.error(error.statusCode, error.message);
  }
  throw error;
}

Package Exports

The facturas package exposes the following named sub-paths. All of them are stable and covered by semver.

facturas

Main entry point. createArcaClient, builder functions, error classes, store constructors, and all public types.

facturas/errors

All error classes and predicate helpers in isolation. Useful for libraries that handle errors without importing the full client.

facturas/constants

ARCA reference data: voucher type codes, VAT rates, document types, currencies, and receiver conditions. See Constants.

facturas/types

All public TypeScript types without runtime code.

facturas/wsfe

createWsfeService and all WSFE-specific types. See Exact Layer.

facturas/wsmtxca

createWsmtxcaService and all WSMTXCA-specific types. See Exact Layer.

facturas/padron

createPadronService and Padrón result types.

import { createWsfeService } from "facturas/wsfe";
import { ARCA_VOUCHER_TYPES } from "facturas/constants";
import { ArcaServiceError } from "facturas/errors";

Internal SOAP, HTTP, and WSAA modules are not part of the semver contract and should not be imported directly. Stick to the sub-paths listed above.

Get Started

Core Concepts

Guides

CLI

Reference

facturas Public API Reference

`createArcaClient(options?)`

Options

`ArcaClient` Methods

`issue(input, options?)`

`preview(input, options?)`

`recover(key)`

`issueCreditNote(input, options?)`

`issueDebitNote(input, options?)`

`previewCreditNote(input, options?)`

`previewDebitNote(input, options?)`

`arca.wsfe`

`arca.wsmtxca`

`arca.padron`

Store Constructors

`createPostgresStore(options)`

`createRedisStore(redis, options?)`

`createFileStore(directory)`

`createMemoryStore()`

`createPadronService(options)`

Error Classes

Package Exports

facturas

facturas/errors

facturas/constants

facturas/types

facturas/wsfe

facturas/wsmtxca

facturas/padron

​createArcaClient(options?)

​Options

​ArcaClient Methods

​issue(input, options?)

​preview(input, options?)

​recover(key)

​issueCreditNote(input, options?)

​issueDebitNote(input, options?)

​previewCreditNote(input, options?)

​previewDebitNote(input, options?)

​arca.wsfe

​arca.wsmtxca

​arca.padron

​Store Constructors

​createPostgresStore(options)

​createRedisStore(redis, options?)

​createFileStore(directory)

​createMemoryStore()

​createPadronService(options)

​Error Classes

​Package Exports

facturas

facturas/errors

facturas/constants

facturas/types

facturas/wsfe

facturas/wsmtxca

facturas/padron

`createArcaClient(options?)`

Options

`ArcaClient` Methods

`issue(input, options?)`

`preview(input, options?)`

`recover(key)`

`issueCreditNote(input, options?)`

`issueDebitNote(input, options?)`

`previewCreditNote(input, options?)`

`previewDebitNote(input, options?)`

`arca.wsfe`

`arca.wsmtxca`

`arca.padron`

Store Constructors

`createPostgresStore(options)`

`createRedisStore(redis, options?)`

`createFileStore(directory)`

`createMemoryStore()`

`createPadronService(options)`

Error Classes

Package Exports