Configuración del SDK

createFactuCatSdk(options) devuelve una instancia de FactuCatSdk. También puedes usar new FactuCatSdk(options); ambas formas aceptan las mismas opciones.

Crea el cliente

import { createFactuCatSdk } from '@factucat/sdk'
import type { FactuCatSdkOptions } from '@factucat/sdk'

const configuracion: FactuCatSdkOptions = {
  apiKey: process.env.FACTUCAT_API_KEY!,
  timeoutMs: 30_000,
  userAgent: 'mi-integracion/1.0',
}

const factucat = createFactuCatSdk(configuracion)

La API key se envía mediante X-API-Key. Mantén el cliente en tu servidor; no distribuyas la llave dentro de una aplicación de navegador.

FactuCatSdkOptions

Opción	Tipo	Obligatoria	Valor predeterminado y uso
apiKey	string	Sí	Llave de la integración con los permisos necesarios.
baseUrl	string	No	https://sandbox.factucat.com si la llave comienza con fc_test_; https://factucat.com en los demás casos. Una URL explícita tiene prioridad.
timeoutMs	number	No	30000 milisegundos por intento. Utiliza un valor positivo.
userAgent	string	No	Sin header personalizado. Si se proporciona, se envía en User-Agent.
fetch	typeof globalThis.fetch	No	El fetch global del runtime. Permite instrumentar el transporte o simularlo en pruebas.

baseUrl debe ser el origen, sin /api/v1: el SDK añade ese prefijo. Se eliminan las diagonales finales. El SDK no cambia de ambiente si falla una solicitud y no lee automáticamente FACTUCAT_API_URL; esa variable pertenece a los ejemplos HTTP de las guías.

El runtime necesita fetch, crypto.randomUUID y AbortSignal.any. Node.js 22 o posterior ofrece estas APIs. Para preparar tu cuenta y tus llaves, consulta Ambientes y pruebas.

Opciones por solicitud

Todos los métodos aceptan un último argumento options. En métodos con un input opcional, pasa {} como primer argumento si solo quieres indicar opciones.

Opción	Tipo	Obligatoria	Comportamiento
idempotencyKey	string	No	Se genera un UUID por mutación al omitirla. Una clave propia se recorta en los extremos y debe contener entre 1 y 255 caracteres.
signal	AbortSignal	No	Cancela la espera de la solicitud. Se combina con el timeout interno de cada intento.

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

const cuenta = await factucat.getMe({
  signal: AbortSignal.timeout(5_000),
})

El SDK conserva la misma clave en su reintento de transporte, pero genera otra en una llamada nueva. Persiste una clave propia para continuar la operación después de reiniciar tu aplicación. Idempotencia y reintentos.

RequestOptions describe estas opciones, pero no se exporta como tipo con ese nombre. Puedes obtener el tipo desde un método:

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

type OpcionesSolicitud = NonNullable<Parameters<FactuCatSdk['getMe']>[0]>
const opciones: OpcionesSolicitud = { idempotencyKey: 'pedido-1001-timbrar' }

Instrumenta el transporte

Si necesitas el requestId de una respuesta exitosa, puedes leer X-Request-Id desde un fetch personalizado. Devuelve la respuesta original para que el SDK valide y lea su cuerpo.

const instrumentado = createFactuCatSdk({
  apiKey: process.env.FACTUCAT_API_KEY!,
  fetch: async (url, init) => {
    const respuesta = await globalThis.fetch(url, init)
    console.info({
      estado: respuesta.status,
      requestId: respuesta.headers.get('x-request-id'),
    })
    return respuesta
  },
})

No registres la API key, los headers de autenticación ni el XML completo. Para inspeccionar también un cuerpo sin consumir el que leerá el SDK, utiliza respuesta.clone().