@quo-digital/multipac-sdk

SDK oficial de Node/TypeScript para consumir la API CFDI de Multipac (/api/v1/cfdi/*).

Maneja autenticación (obtención y renovación de token de forma transparente), reintentos ante fallos transitorios del PAC o del rate limit, y validación/tipado en runtime de cada respuesta — para que no tengas que hablar HTTP a mano.

Instalación

npm install @quo-digital/multipac-sdk

Requiere Node.js 18 o superior (usa fetch nativo, sin dependencias de cliente HTTP).

Uso rápido

import { MultipacClient } from '@quo-digital/multipac-sdk';

const client = new MultipacClient({
	baseUrl: 'https://sandbox-multipac.quo.solutions',
	clientKey: process.env.MULTIPAC_CLIENT_KEY!,
	clientSecret: process.env.MULTIPAC_CLIENT_SECRET!,
});

const { uuidCfdi, xmlTimbrado } = await client.timbrar({ xmlCfdi });

El cliente obtiene y renueva el token internamente en la primera llamada — no necesitas manejarlo.

API

| Método | Descripción | | ---------------------------------------------- | -------------------------------------------------------------------------- | | client.timbrar(input) | Timbra un CFDI 4.0 | | client.cancelar(uuidCfdi, input) | Cancela un CFDI timbrado | | client.consultarEstado(uuidCfdi, params) | Consulta el estado de un CFDI ante el PAC | | client.recuperarXml(uuidCfdi, params?) | Recupera el XML timbrado | | client.consultarOperacion(operacionId) | Consulta el estado de una operación (útil en modo asíncrono) | | esperarOperacion(client, operacionId, opts?) | Hace polling de una operación asíncrona hasta que llegue a un estado final |

Manejo de errores

Cada operación puede lanzar una subclase de MultipacError. Los errores de negocio del catálogo de Multipac (XmlInvalidoError, CsdNoVigenteError, CreditosAgotadosError, etc.) exponen un codigo estable:

import { CreditosAgotadosError, MultipacError } from '@quo-digital/multipac-sdk';

try {
	await client.timbrar({ xmlCfdi });
} catch (err) {
	if (err instanceof CreditosAgotadosError) {
		// manejar saldo agotado
	} else if (err instanceof MultipacError) {
		// cualquier otro error del SDK
	}
}

Reintentos

429/502 se reintentan automáticamente (con backoff) tanto en GET como en POST, porque son respuestas del servidor que confirman que la operación no se completó. Un fallo de red puro (timeout, conexión perdida) solo se reintenta en operaciones de lectura (consultarEstado, recuperarXml, consultarOperacion). timbrar/cancelar nunca reintentan un fallo de red: si la respuesta se pierde, no hay forma de saber si el servidor ya procesó la operación, y reintentar podría timbrar el mismo CFDI dos veces o duplicar una cancelación. Ante un MultipacNetworkError de timbrar/cancelar, verifica el estado real con client.consultarOperacion() antes de reintentar manualmente.

Desarrollo

npm test
npm run build

Releases

El versionado y el publish a npm son automáticos vía CI, gatillados por changeset:

1. En tu PR, si el cambio debe reflejarse en una nueva versión, corre npx changeset — te pregunta el tipo de bump (patch/minor/major) y una descripción; esto crea un archivo en .changeset/. Cambios internos que no afectan al consumidor (CI, tests, docs) no necesitan uno.
2. Al mergear a main, el job version consume los changesets pendientes, bumpea package.json, actualiza CHANGELOG.md, y commitea ese cambio de vuelta a main.
3. Ese commit dispara un nuevo pipeline: el job publish detecta la versión nueva (aún no está en el registro) y la publica. Un push sin changesets pendientes no genera versión nueva — el pipeline queda verde sin publicar nada.

Licencia

MIT