Cliente

createArcaClient() devuelve el cliente. Sus métodos son la API para emitir: reciben datos de tu negocio y devuelven el resultado fiscal ya normalizado.

Método	Qué hace	Guía
`issue()`	Emite una factura	Emitir facturas
`preview()`	Muestra lo que enviaría `issue()`, sin I/O	Emitir facturas
`issueCreditNote()`	Emite una nota de crédito	Notas de crédito
`issueDebitNote()`	Emite una nota de débito	Notas de crédito
`previewCreditNote()`	Muestra la nota de crédito, leyendo el original	Notas de crédito
`previewDebitNote()`	Muestra la nota de débito, leyendo el original	Notas de crédito
`recover()`	Concilia una reserva sin emitir	Evitar comprobantes duplicados
`lookup()`	Consulta un comprobante autorizado	Consultar un comprobante
`lastAuthorized()`	Lee el último número autorizado	Último número autorizado

client.wsfe, client.wsmtxca y client.padron son los módulos técnicos que el cliente usa por debajo. Están en Módulos de transporte, y el Padrón en Consultar contribuyentes.

`createArcaClient()`

function createArcaClient(config?: ArcaClientOptions): ArcaClient;

Completa los campos que faltan con las variables ARCA_* y valida la configuración al crear el cliente. Si falta el CUIT, un PEM o el entorno, lanza ArcaConfigurationError antes de cualquier llamada. client.config expone taxId y environment, de solo lectura. Las opciones están en Configuración.

`issue()`

issue(input: IssueInput, options?: IssueOptions): Promise<IssueOutcome>;

Deriva la clase, el tipo de comprobante, el IVA y el pedido para ARCA a partir de input, y autoriza el comprobante. Sin idempotencyKey, lee el próximo número, autoriza una vez y hace a lo sumo una consulta si la respuesta queda incierta. Con clave y store, reserva el número antes de escribir, y una repetición consulta la reserva en vez de emitir otra vez. Los errores de input y la falla al leer el próximo número se lanzan antes de autorizar. Todo lo que pasa después vuelve como uno de los cuatro resultados. Los campos de input están en Emitir facturas.

`preview()`

preview(
  input: IssueInput,
  options?: { representedTaxId?: number | string; service?: "wsfe" | "wsmtxca" },
): IssuePreview;

Sincrónico y sin I/O: no usa el store, WSAA ni SOAP, y no lee el próximo número. Lanza los mismos errores de input que issue() antes de su primera llamada. Devuelve:

Campo	Qué trae
`voucherClass`	`"A"`, `"B"` o `"C"`
`voucherType`	El código de ARCA, por ejemplo `6` para Factura B
`date`	La fecha del comprobante, `YYYY-MM-DD`. Es la misma que devuelve `issue()`, también cuando el input no trae `date`
`header`	La cabecera fiscal, la misma que trae un resultado autorizado
`amounts`	Los importes que se enviarían
`request`	El pedido para ARCA, sin el número de comprobante

`issueCreditNote()`

issueCreditNote(
  input: CreditNoteInput | PeriodNoteInput,
  options?: IssueOptions,
): Promise<IssueOutcome>;

for nombra el comprobante autorizado que corregís, o una lista de ellos. La nota acredita las líneas de items, un desglose amounts ya revisado, o el original entero con all: true. Uno de los tres es obligatorio. La clase, el receptor, la moneda, el concepto y las fechas de servicio salen del original. Con associatedPeriod: { from, to } en lugar de for, la nota ajusta un período y lleva su propio input de negocio. Devuelve los mismos resultados que issue().

`issueDebitNote()`

issueDebitNote(input: DebitNoteInput, options?: IssueOptions): Promise<IssueOutcome>;

El mismo contrato que issueCreditNote(), sin all: true: una nota de débito suma a la cuenta, así que sus líneas o importes siempre son explícitos. En WSFE también acepta notas de crédito ordinarias autorizadas (3, 8 y 13) en for y deriva la nota de débito de la misma clase (2, 7 y 12).

`previewCreditNote()` y `previewDebitNote()`

previewCreditNote(
  input: CreditNoteInput | PeriodNoteInput,
  options?: PreviewOptions,
): Promise<NotePreview>;

previewDebitNote(input: DebitNoteInput, options?: PreviewOptions): Promise<NotePreview>;

A diferencia de preview(), son asincrónicas: consultan cada original una vez, sin escribir y sin reservar número. Devuelven lo mismo que preview() más originals, los comprobantes consultados en el orden del input. Una nota por período no consulta nada y no trae originals. PreviewOptions acepta representedTaxId, service, forceRefresh y abortSignal.

`recover()`

recover(idempotencyKey: string, options?: RecoveryOptions): Promise<IssueOutcome>;

Consulta la reserva guardada para esa clave, con el servicio y el número que quedaron registrados. Nunca autoriza ni reserva un número nuevo. Si ARCA confirma que el número está vacío, devuelve indeterminate con lookup.kind === "not_found": para emitir, llamá otra vez al método original con la misma clave. Con un store que provee withLock, espera a que termine una emisión en curso en esa secuencia, para no consultar una reserva que otra llamada con la misma clave está cambiando. Si tu abortSignal vence mientras espera, o el lock sigue tomado, lanza ArcaLockTimeoutError sin consultar a ARCA. Sin withLock, un conflicto en el número de una clave rechazada se informa pero no queda guardado: otra llamada con la misma clave puede haberlo escrito, así que la próxima consulta lo vuelve a revisar. Si no hay reserva para esa clave, lanza ArcaInputError con code === "ARCA_INPUT_RESERVATION_NOT_FOUND". RecoveryOptions acepta representedTaxId, forceRefresh, include y abortSignal.

`lookup()`

lookup(
  voucher: { salesPoint: number; voucherType: number; number: number },
  options?: PreviewOptions,
): Promise<VoucherSummary | null>;

Consulta un comprobante autorizado por sus coordenadas, las mismas que recibe for en una nota de crédito. Solo lee: no usa el store ni reserva número. Devuelve null si ARCA no tiene ese comprobante y lanza ante cualquier otro error del proveedor. Con service: "wsmtxca" consulta WSMTXCA. El resultado es un VoucherSummary, el mismo que traen originals y un conflict: importes en centavos, fechas YYYY-MM-DD, y sin la respuesta cruda. Un campo que ARCA omite no aparece.

const comprobante = await arca.lookup({
  salesPoint: 3,
  voucherType: 6,
  number: 41,
});
if (comprobante) {
  console.log(comprobante.date, comprobante.totalAmount, comprobante.cae);
}

`lastAuthorized()`

lastAuthorized(
  sequence: { salesPoint: number; voucherType: number },
  options?: PreviewOptions,
): Promise<number>;

Devuelve el número del último comprobante que ARCA autorizó para ese punto de venta y tipo, o 0 si nunca autorizó ninguno. Solo lee: no usa el store ni reserva número. Con service: "wsmtxca" consulta WSMTXCA, y la respuesta es la misma en los dos servicios.

const ultimo = await arca.lastAuthorized({ salesPoint: 3, voucherType: 6 });

Opciones de emisión

issue(), issueCreditNote() e issueDebitNote() aceptan IssueOptions como segundo argumento. Todas son opcionales.

Opción	Tipo	Qué hace
`idempotencyKey`	`string`	Liga la llamada a una reserva en el `store`. De 1 a 255 caracteres, estable por operación de negocio. Sin `store`, lanza antes de cualquier I/O
`abortSignal`	`AbortSignal`	Límite de tiempo para el login WSAA, la escritura y las consultas de la llamada. Un corte después del envío devuelve `indeterminate` con `lookup.kind === "aborted"`. Un corte mientras espera el lock de la secuencia lanza `ArcaLockTimeoutError` sin reservar ni enviar nada
`include`	`{ request?: boolean, rawResponse?: boolean }`	Agrega el request fiscal y la respuesta cruda de ARCA a cualquiera de los cuatro resultados
`service`	`"wsfe" \| "wsmtxca"`	El servicio de ARCA. Por defecto, WSFE. Pasá `"wsmtxca"` solo cuando el contribuyente o el punto de venta lo requiere
`number`	`number`	Un número reservado por fuera. La llamada no lee el próximo número
`representedTaxId`	`number \| string`	El CUIT por el que emitís cuando operás para un tercero. Sin la opción, es el `taxId` del cliente. Forma parte de la identidad de la clave
`forceRefresh`	`boolean`	Descarta el ticket WSAA guardado y pide uno nuevo. Con esta opción no hay segundo intento después de un rechazo del ticket

Resultados

Los cuatro métodos que emiten, y recover(), devuelven un IssueOutcome. Los resultados fiscales se devuelven, no se lanzan, y kind los distingue:

`kind`	Campos
`authorized`	`voucher`, `recoveredByMatch`, y `authorization` o, cuando `recoveredByMatch` es `true`, `attempt` y `lookup`
`rejected`	`attempted`, `issues` con los errores de ARCA, `authorization`
`indeterminate`	`attempted`, `attempt`, `lookup`
`conflict`	`attempted`, `attempt`, `found`, `reason`

attempted son las coordenadas del intento: salesPoint, voucherType y number. En indeterminate, lookup.kind dice por qué quedó abierto:

`lookup.kind`	Qué significa
`not_found`	ARCA confirmó que el número está vacío
`incomplete`	ARCA tiene un comprobante en el número reservado, pero la consulta no trae los datos para probar que es este. `reason` dice por qué
`failed`	La consulta falló. `error` trae el mensaje seguro y el código
`aborted`	Venció tu `abortSignal`. La reserva queda para `recover()`
`blocked`	Otra reserva sin resolver frena la secuencia. Conciliá la clave `by`, reservada por el emisor `byTaxId`, y repetí
`superseded`	La secuencia siguió sin esta clave, que ya no va a escribir. `by` tomó el número desde el emisor `byTaxId`. Emití con una clave nueva

Qué hacer con cada uno está en Emitir facturas.

`IssuedVoucher`

voucher, en un resultado autorizado, habla en las unidades del input: fechas YYYY-MM-DD e importes en centavos.

Campo	Qué trae
`salesPoint`, `voucherType`, `number`	Las coordenadas del comprobante
`voucherClass`	`"A"`, `"B"` o `"C"`
`date`	La fecha del comprobante
`header`	La cabecera fiscal
`cae`	El CAE
`caeExpiry`	El vencimiento del CAE
`amounts`	Los importes emitidos
`qr`	La URL que codifica el QR del comprobante impreso. Falta solo si ARCA devolvió un CAE que la especificación no puede codificar
`qrPayload`	El JSON que `qr` lleva en base64, como `ArcaQrPayload`. Está siempre que está `qr`

`FiscalHeader`

header es la misma en preview() y en voucher, tanto en una autorización directa como en una recuperada.

Campo	Qué trae
`concept`	`1` productos, `2` servicios, `3` productos y servicios
`documentType`	El tipo de documento del receptor, por ejemplo `80` para CUIT
`documentNumber`	El número de documento del receptor, como string
`receiverVatConditionId`	La condición de IVA del receptor, con el código de ARCA
`currencyId`	El código de moneda de ARCA, por ejemplo `PES`
`exchangeRate`	El tipo de cambio, como string decimal exacto
`serviceStartDate`, `serviceEndDate`	Las fechas de servicio. Faltan en un comprobante de productos
`paymentDueDate`	El vencimiento de pago. Falta cuando el comprobante no tiene vencimiento fiscal

Importes

amounts trae tres enteros en centavos:

Campo	Qué trae
`computedTotal`	El total que calculó el SDK a partir de los ítems
`sentTotal`	El total enviado a ARCA. Es el `total` que pasaste, o `computedTotal` si no pasaste ninguno
`vatAdjustment`	La diferencia entre los dos, absorbida en el IVA de cabecera. A lo sumo un centavo por alícuota

QR de un comprobante guardado

voucher.qr ya trae la URL. Para reimprimir un comprobante guardado sin volver a emitir, arcaQrUrl() la arma con los mismos datos, sin I/O:

import { arcaQrUrl } from "facturas";

const url = arcaQrUrl({
  taxId: "20123456786",
  salesPoint: guardado.salesPoint,
  voucherType: guardado.voucherType,
  number: guardado.number,
  date: guardado.date,
  total: guardado.amounts.sentTotal,
  currency: guardado.header.currencyId,
  exchangeRate: guardado.header.exchangeRate,
  cae: guardado.cae,
  document: {
    type: guardado.header.documentType,
    number: guardado.header.documentNumber,
  },
});

arcaQrPayload() devuelve el JSON que va codificado en esa URL, y ARCA_QR_URL es la base. El QR lleva el documento del receptor tal como se mandó a ARCA, también el tipo 99 con número 0 de un consumidor final sin identificar: sin esos campos, la página de constatación de ARCA deja el receptor vacío y hay que cargarlo a mano.

Empezar

Guías

Referencia

`createArcaClient()`

`issue()`

`preview()`

`issueCreditNote()`

`issueDebitNote()`

`previewCreditNote()` y `previewDebitNote()`

`recover()`

`lookup()`

`lastAuthorized()`

Opciones de emisión

Resultados

`IssuedVoucher`

`FiscalHeader`

Importes

QR de un comprobante guardado

​createArcaClient()

​issue()

​preview()

​issueCreditNote()

​issueDebitNote()

​previewCreditNote() y previewDebitNote()

​recover()

​lookup()

​lastAuthorized()

​Opciones de emisión

​Resultados

​IssuedVoucher

​FiscalHeader

​Importes

​QR de un comprobante guardado

`createArcaClient()`

`issue()`

`preview()`

`issueCreditNote()`

`issueDebitNote()`

`previewCreditNote()` y `previewDebitNote()`

`recover()`

`lookup()`

`lastAuthorized()`

Opciones de emisión

Resultados

`IssuedVoucher`

`FiscalHeader`

Importes

QR de un comprobante guardado