SDK para TypeScript

El SDK @factucat/sdk 0.4.1 incluye métodos tipados y validación de respuestas. Utilízalo desde tu servidor, donde la API key permanece privada.

Instala y conecta

npm install @factucat/[email protected]

yarn add @factucat/[email protected]

pnpm add @factucat/[email protected]

bun add @factucat/[email protected]

nub add @factucat/sdk

Solo necesitas la API key para conectar:

import { createFactuCatSdk } from '@factucat/sdk'

const factucat = createFactuCatSdk({
  apiKey: process.env.FACTUCAT_API_KEY!,
})

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

Los métodos devuelven directamente el contenido de data, sin el envoltorio HTTP.

El ambiente se elige con tu llave

Si omites baseUrl, el SDK selecciona el origen según el prefijo de la API key:

API key	Origen
`fc_test_...`	`https://sandbox.factucat.com`
`fc_live_...` y demás llaves	`https://factucat.com`

Puedes desarrollar tu integración en sandbox con una llave fc_test_.... Consulta Ambientes y pruebas para configurar tu cuenta y mantener separados los datos de pruebas y producción.

Para apuntar a tu entorno local u otro ambiente, indica una URL propia. baseUrl tiene prioridad sobre el prefijo de la llave:

const factucat = createFactuCatSdk({
  apiKey: process.env.FACTUCAT_API_KEY!,
  baseUrl: 'http://localhost:3000',
})

baseUrl es el origen: no agregues /api/v1, porque el SDK lo añade.

Idempotencia automática

Puedes omitir idempotencyKey: el SDK genera una clave UUID para cada mutación y la envía por ti.

const borrador = await factucat.createDraft()

Si ocurre un fallo de red o timeout, el SDK reintenta una sola vez con la misma clave y contenido. Los GET no generan claves, y los errores HTTP o de validación no se reintentan automáticamente.

Conserva la identidad de tu operación

Una llamada nueva genera otra clave. Para continuar la misma operación después de reiniciar tu servidor, guarda una clave propia antes de enviar la solicitud y pásala mediante idempotencyKey:

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

console.log(borrador.id)

El SDK respeta tu clave y la conserva en los reintentos. Las claves propias deben tener entre 1 y 255 caracteres después de quitar los espacios de los extremos; una clave vacía se rechaza antes de enviar la solicitud.

Fecha de emisión

createDraft, setDraftMeta y stampDraft aceptan issueDate opcional (YYYY-MM-DD o datetime ISO): hoy o hasta 72 horas antes del timbrado (máximo 3 días de calendario atrás), en la zona horaria del código postal de expedición, sin fechas futuras (regla 2.7.2.9 de la RMF). Fuera de rango, la API responde 400 con INVALID_ISSUE_DATE. Detalle en Timbrar un CFDI completo.

await factucat.stampDraft(draftId, { issueDate: '2026-10-28' })

Métodos del flujo de facturación

La referencia del SDK documenta los métodos de facturación con sus argumentos, campos obligatorios y opcionales, permisos, ejemplos y respuestas completas. Los métodos de empleados y nómina, incluidos crear y duplicar borradores, están en la guía de nómina.

Recurso	Qué puedes hacer
Cuenta	Consultar la identidad y los permisos de tu integración.
Clientes	Crear, buscar y consultar receptores.
Borradores y conceptos	Preparar el documento, editar receptor y pago, agregar o corregir conceptos.
Facturas	Timbrar, consultar y cancelar documentos, incluidos CFDI externos.
Archivos	Recuperar XML y PDF en base64.

Consulta también la configuración del cliente, los tipos y la paginación y el manejo de errores y reintentos.

Antes de automatizar stampDraft(), sigue Cómo timbrar un CFDI completo y revisa Idempotencia y reintentos.

Para otros lenguajes, utiliza los ejemplos HTTP de la referencia o genera tu cliente desde OpenAPI.