Tipos, paginación y archivos

Qué devuelve cada método

El SDK valida el envoltorio HTTP. Los métodos de clientes y facturas devuelven únicamente data; los listados de nómina devuelven { data, pagination }. No devuelve un objeto Response, el estado HTTP ni meta.requestId o meta.idempotencyKey.

Los ejemplos usan el cliente factucat de Instala y conecta e invoiceId, el ID de FactuCat de un documento guardado en tu sistema.

const clientes = await factucat.listCustomers({ limit: 50, offset: 0 })
console.log(clientes.length) // Es un arreglo, no clientes.data.

const factura = await factucat.getInvoice(invoiceId)
console.log(factura.status, factura.satUuid)

Los resúmenes de listados y los documentos completos son tipos diferentes. listDrafts() y listInvoices() no incluyen conceptos; getDraft() y getInvoice() sí. Los campos id son identificadores de FactuCat; satUuid es el UUID fiscal.

Las fechas son strings ISO 8601. Los importes de las respuestas son números, y las tasas son fracciones decimales, por ejemplo 0.16. El total que recibe cancelExternalInvoice() es una cadena. Los campos opcionales pueden estar ausentes, y null solo se admite cuando el tipo lo indica.

Los listados de nómina usan cursor y conservan pagination.nextCursor para continuar.

Tipos exportados

Además del cliente y las clases de error, puedes importar estos tipos desde @factucat/sdk:

Grupo	Tipos
Configuración	FactuCatSdkOptions
Clientes	CustomerCreateInput, CustomerListQuery, CustomerRecord
Borradores	DraftCreateInput, DraftListQuery, DraftListItem, DraftRecord
Edición	DraftSetReceiverInput, DraftSetMetaInput, DraftAddItemInput, DraftUpdateItemInput
Timbrado	DraftStampInput
Facturas	InvoiceListQuery, InvoiceListItem, InvoiceRecord
Nómina	EmployeeListQuery, PayrollEmployee, PayrollBatchListQuery, PayrollBatchListItem, PayrollBatchRecord, PayrollReceiptListQuery, PayrollReceiptRecord, PayrollDownload
Archivos	InvoiceXmlOutput, InvoicePdfOutput

Los tipos de entrada reflejan las firmas actuales de TypeScript. CustomerCreateInput requiere sendInvoices, invoiceLanguage y currency; DraftAddItemInput requiere quantity. Inclúyelos incluso si el validador HTTP tiene valores por defecto. Para códigos con ceros iniciales, usa strings como '03' y '06000'.

Los tipos de cuenta, cancelación y opciones por solicitud no se reexportan con nombre desde el SDK. Puedes derivarlos sin depender directamente del paquete de contratos:

import type { FactuCatSdk, InvoiceRecord } from '@factucat/sdk'

type Cuenta = Awaited<ReturnType<FactuCatSdk['getMe']>>
type Cancelacion = Parameters<FactuCatSdk['cancelInvoice']>[1]
type ResultadoCancelacion = Awaited<ReturnType<FactuCatSdk['cancelInvoice']>>

function estaEmitida(factura: InvoiceRecord) {
  return factura.status === 'issued' && Boolean(factura.satUuid)
}

evidence y el campo opcional invoice de una cancelación son unknown. El SDK no garantiza su estructura interna. El resultado estable que debes interpretar es status, con los valores cancelled y not_confirmed.

Recorre todas las páginas

Los listados de clientes, borradores y facturas aceptan limit (1–100; predeterminado 50) y offset (0–1,000,000; predeterminado 0). Como el SDK devuelve el arreglo sin hasMore, termina al recibir menos elementos que el límite. Una última página completa requiere consultar una página adicional vacía.

const limit = 100
for (let offset = 0; ; offset += limit) {
  if (offset > 1_000_000) {
    throw new Error(
      'Se alcanzó el límite de offset; reduce el conjunto con filtros.',
    )
  }
  const pagina = await factucat.listInvoices({
    status: 'issued',
    limit,
    offset,
  })
  for (const factura of pagina) {
    console.log(factura.id, factura.total)
  }
  if (pagina.length < limit) break
}

No hay paginación automática ni cursor en el SDK. Si se crean o eliminan registros durante el recorrido, las páginas pueden desplazarse: elimina duplicados por id y vuelve a conciliar el listado. Consulta también Errores y paginación HTTP.

Guarda XML y PDF

Los métodos de descarga devuelven { fileName, mimeType, base64 }. Decodifica base64 para obtener los bytes del archivo. Este ejemplo guarda nombres locales elegidos por tu aplicación:

import { writeFile } from 'node:fs/promises'

const xml = await factucat.downloadInvoiceXml(invoiceId)
await writeFile('factura.xml', Buffer.from(xml.base64, 'base64'))

const pdf = await factucat.downloadInvoicePdf(invoiceId)
await writeFile('factura.pdf', Buffer.from(pdf.base64, 'base64'))

El XML timbrado es el documento fiscal canónico; el PDF es su representación. El SDK no devuelve streams ni enlaces de descarga. Referencia de archivos.