@factucat/sdk

SDK 0.3.0, cliente oficial de FactuCat para TypeScript y Node.js. Incluye métodos tipados, validación de respuestas y autenticación mediante el header X-API-Key. Úsalo desde tu servidor para mantener privada la API key.

Consulta la referencia de los 20 métodos para ver parámetros, permisos, respuestas completas y ejemplos, junto con la configuración, los tipos y la paginación y el manejo de errores.

| Gestor | Instalación | | ------ | --------------------------- | | npm | npm install @factucat/sdk | | yarn | yarn add @factucat/sdk | | pnpm | pnpm add @factucat/sdk | | bun | bun add @factucat/sdk | | nub | nub add @factucat/sdk |

import { createFactuCatSdk } from '@factucat/sdk'

const apiKey = process.env.FACTUCAT_API_KEY
if (!apiKey) throw new Error('Falta FACTUCAT_API_KEY')

const factucat = createFactuCatSdk({ apiKey })

const cuenta = await factucat.getMe()
console.log(cuenta.scopes)

Los métodos devuelven directamente data, sin el envoltorio HTTP. El runtime debe ofrecer fetch, crypto.randomUUID y AbortSignal.any (por ejemplo, Node.js 22 o posterior).

Ambiente automático

baseUrl es opcional. Una llave con prefijo fc_test_ selecciona https://sandbox.factucat.com; las demás llaves usan https://factucat.com.

Para desarrollo local u otro ambiente, puedes indicar una baseUrl explícita. Esta opción tiene prioridad sobre el prefijo de la llave y debe ser el origen, sin /api/v1:

const factucat = createFactuCatSdk({
  apiKey,
  baseUrl: 'http://localhost:3000',
})

Prepara tu cuenta y tu llave de pruebas en sandbox.factucat.com. Si una solicitud falla, el SDK conserva el mismo ambiente al reintentar.

Idempotencia automática

Cuando omites idempotencyKey, cada llamada que modifica datos genera una clave UUID y la envía en Idempotency-Key. Si hay un error de red o timeout, el SDK reintenta una sola vez con la misma clave y contenido. Las consultas GET no generan claves.

// Una operación nueva: la clave se genera automáticamente.
const borrador = await factucat.createDraft()

Una llamada nueva genera otra clave. Para continuar la misma operación después de un reinicio o desde otro proceso, guarda tu propia clave antes de enviar la solicitud y reutilízala con el mismo método, ruta y contenido:

const borrador = await factucat.createDraft(
  {},
  {
    idempotencyKey: 'pedido-1001-crear-borrador',
  },
)

Las claves propias deben tener entre 1 y 255 caracteres; se eliminan los espacios al inicio y al final. No se aceptan claves vacías. Usa una clave distinta para el siguiente paso, por ejemplo pedido-1001-timbrar.

Errores y reintentos

• FactuCatApiError: respuesta HTTP de error, con status, code, requestId y retryable. El SDK la devuelve sin reintentar automáticamente, incluso cuando retryable es true.
• FactuCatNetworkError: fallo de transporte después del reintento, o cancelación mediante signal. timedOut indica si el error final fue un timeout.
• ZodError: solicitud o respuesta que no cumple el contrato. No se reintenta automáticamente.

El timeout predeterminado es de 30 segundos por intento y la espera entre intentos es de 250 ms. Puedes configurar timeoutMs al crear el cliente y pasar un signal en las opciones de cada operación.

La clave generada protege los reintentos internos de una llamada. Si se agotan durante el timbrado, consulta el borrador o documento original: un error de conexión no confirma que el CFDI no se haya emitido.