@chaski-ec/sdk
v0.2.1
Published
SDK oficial de Chaski: facturación electrónica del SRI (Ecuador) por API.
Maintainers
Readme
@chaski-ec/sdk
SDK oficial de Chaski para emitir comprobantes electrónicos del SRI (Ecuador) desde JavaScript o TypeScript. No tiene dependencias y funciona en Node 20+, Bun, Deno y en runtimes edge.
npm install @chaski-ec/sdkEmitir una factura
import { Chaski } from '@chaski-ec/sdk';
const chaski = new Chaski(process.env.CHASKI_API_KEY!); // sk_test_… o sk_live_…
const invoice = await chaski.invoices.create(
{
issuer: 'iss_…',
emission_point: '001-001',
buyer: { id_type: 'cedula', id: '1710034065', name: 'Ana Pérez', email: '[email protected]' },
items: [
{
description: 'Plan Pro - noviembre 2026',
quantity: '1',
unit_price: '29.00',
taxes: [{ type: 'iva', rate: '15' }],
},
],
payments: [{ method: 'credit_card' }],
},
{ idempotencyKey: 'pedido-1234' }, // opcional: el SDK genera una si no la pasas
);
// invoice.status === 'pending': el resultado del SRI llega por webhook (invoice.authorized, …).Los montos van como texto ("29.00") para no perder precisión.
Webhooks
import { verifyWebhook } from '@chaski-ec/sdk';
// Con el cuerpo crudo, tal como llegó (sin JSON.parse antes).
const event = await verifyWebhook(rawBody, request.headers.get('chaski-signature'), process.env.CHASKI_WEBHOOK_SECRET!);
if (event.type === 'invoice.authorized') {
// …
}Errores
Todo error de la API es un ChaskiError con status, code (estable, por ejemplo quota_exceeded o plan_limit_reached), message, field y raw (el cuerpo completo, con datos como limit o addon_offer).
import { ChaskiError } from '@chaski-ec/sdk';
try {
await chaski.invoices.create(body);
} catch (error) {
if (error instanceof ChaskiError && error.code === 'quota_exceeded') {
// Compra un paquete de comprobantes o mejora el plan.
}
}Reintentos
Los errores de red, los 429 y los 5xx se reintentan dos veces (configurable con maxRetries), respetando Retry-After. Al crear comprobantes, cada reintento usa la misma clave de idempotencia, así que nunca se emite dos veces. Un POST sin clave, como reenviar un correo, no se reintenta.
Recursos
| Recurso | Métodos |
|---|---|
| invoices | create, get, list, listAll, xml, pdf, void, resend, emails |
| creditNotes | create, get, list, listAll, xml, pdf, resend, emails |
| debitNotes | create, get, list, listAll, xml, pdf, resend, emails |
| withholdings | create, get, list, listAll, xml, pdf, resend, emails |
| deliveryGuides | create, get, list, listAll, xml, pdf, resend, emails |
| purchaseSettlements | create, get, list, listAll, xml, pdf, resend, emails |
| issuers | create, get, list, update, createEmissionPoint, updateEmissionPoint |
| certificates | upload, list |
| brandingProfiles | create, get, list, update, delete, logo |
| emailDomains | create, get, list, verify, delete |
| exports | create, get, list, download |
| webhookEndpoints | create, list, delete, deliveries |
| events | list, listAll |
| usage | get |
Los tipos salen del contrato OpenAPI de la API (Invoice, CreditNote, CreateInvoiceRequest, …).
