intifact 1.3.3 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,236 +1,119 @@
1
1
  # intifact
2
2
 
3
- [![npm](https://img.shields.io/npm/v/intifact.svg)](https://www.npmjs.com/package/intifact)
4
- [![types](https://img.shields.io/npm/types/intifact.svg)](https://www.npmjs.com/package/intifact)
3
+ SDK TypeScript auto-generado para la **API de Facturación Electrónica SUNAT de Intifact** (Perú).
5
4
 
6
- SDK oficial de TypeScript para emitir comprobantes electrónicos ante **SUNAT
7
- (Perú)**: facturas, boletas, notas de crédito y débito, guías de remisión,
8
- resúmenes diarios y comunicaciones de baja.
5
+ Sigue siempre la versión más reciente de la API: los tipos se regeneran desde el `openapi.json` que la API expone en `/docs/json`.
9
6
 
10
- Tú mandas JSON. La API arma el XML UBL 2.1, lo firma con tu certificado, lo
11
- envía a SUNAT, procesa el CDR y te devuelve el PDF con su QR. No necesitas saber
12
- nada de UBL, XMLDSig ni SOAP.
13
-
14
- Los tipos se generan del OpenAPI de la API, así que el editor te avisa del campo
15
- que falta o del que escribiste mal **antes** de ejecutar nada.
7
+ ## Instalación
16
8
 
17
9
  ```bash
18
10
  npm install intifact
19
11
  ```
20
12
 
21
- Requiere Node 18+ (usa `fetch` nativo). Funciona igual en Bun y Deno.
22
-
23
- ## Empieza en pruebas
24
-
25
- El ambiente **lo decide la key**, no un parámetro. Las creas tú desde el
26
- [panel de Intifact](https://intifact.com).
27
-
28
- | Prefijo | Destino | Validez fiscal | Consume tu plan | Certificado |
29
- |---|---|---|---|---|
30
- | `fact_test_` | SUNAT beta | Ninguna | No | Uno de prueba compartido |
31
- | `fact_live_` | SUNAT producción | Real | Sí | El tuyo |
32
-
33
- Integra entero con `fact_test_`. Cuando funcione, cambias la key por la de
34
- producción — el código no cambia ni una línea.
35
-
36
- > [!WARNING]
37
- > Una key `fact_live_` emite comprobantes fiscales reales desde la primera
38
- > request. Un error ahí no se borra: se anula con nota de crédito o
39
- > comunicación de baja.
40
-
41
- ## Tu primera factura
13
+ ## Uso básico
42
14
 
43
15
  ```ts
44
16
  import { FacturacionClient } from "intifact";
45
17
 
46
18
  const fact = new FacturacionClient({
47
19
  baseUrl: "https://api-facturacion.intifact.com",
48
- apiKey: process.env.INTIFACT_API_KEY, // fact_test_...
20
+ apiKey: process.env.FACTURACION_API_KEY, // tu API key fact_live_/fact_test_
49
21
  });
50
22
 
23
+ // Enviar factura → 202 (encolada)
51
24
  const { data, error } = await fact.sendInvoice({
52
- empresaRuc: "20553510661",
53
- tipoDoc: "01", // 01 factura · 03 boleta
25
+ tipoDoc: "01",
54
26
  serie: "F001",
55
27
  correlativo: "1",
56
- fechaEmision: "2026-01-15",
57
- tipoMoneda: "PEN",
58
- tipoOperacion: "0101", // venta interna
59
-
60
- clienteTipoDoc: "6", // 6 RUC · 1 DNI
61
- clienteNumDoc: "20000000001",
62
- clienteRazonSocial: "EMPRESA CLIENTE SAC",
63
-
64
- detalle: [{
65
- unidad: "NIU",
66
- cantidad: 2,
67
- codProducto: "PROD001",
68
- descripcion: "Producto de ejemplo",
69
- montoValorUnitario: 100.0,
70
- montoBaseIgv: 200.0,
71
- porcentajeIgv: 18,
72
- igv: 36.0,
73
- tipAfeIgv: "10", // gravado, operación onerosa
74
- totalImpuestos: 36.0,
75
- montoPrecioUnitario: 118.0,
76
- montoValorVenta: 200.0,
77
- }],
78
-
79
- montoIgv: 36.0,
80
- totalImpuestos: 36.0,
81
- valorVenta: 200.0,
82
- subTotal: 236.0,
83
- montoImpVenta: 236.0,
84
- leyendas: [{ legendCode: "1000", legendValue: "DOSCIENTOS TREINTA Y SEIS CON 00/100 SOLES" }],
85
- formaPago: [{ tipo: "Contado", monto: 236.0, fechaPago: "2026-01-15" }],
86
- });
87
-
88
- if (error) throw new Error(error.message);
89
- console.log(data.data.id, data.data.estado); // → "550e8400-…" "ENCOLADO"
90
- ```
91
-
92
- ¿No quieres calcular los importes tú? `computeInvoice()` te los devuelve a
93
- partir de cantidades y precios, sin emitir nada.
94
-
95
- ## Errores
96
-
97
- Ningún método lanza excepciones por respuestas de la API: devuelven
98
- `{ data, error }`, igual que `openapi-fetch`. Un `throw` solo aparece si se cae
99
- la red.
100
-
101
- ```ts
102
- const { data, error } = await fact.sendInvoice(payload);
103
-
104
- if (error) {
105
- console.error(error.message); // "Error de validación"
106
- console.error(error.errors); // [{ path: "detalle.0.igv", message: "..." }]
107
- return;
108
- }
109
- ```
110
-
111
- Los errores de schema llegan **al instante**, con el campo exacto. Los rechazos
112
- de SUNAT llegan después, en el estado del documento.
113
-
114
- ## El resultado de SUNAT llega después
115
-
116
- Ningún `send*` devuelve el CDR. La API responde **202** con
117
- `{ id, estado: "ENCOLADO", hash }` y encola el documento: si SUNAT está caída,
118
- reintenta sola con backoff en vez de fallarte la venta.
119
-
120
- Tienes dos formas de enterarte del desenlace:
121
-
122
- ```ts
123
- // 1. Webhook (recomendado en producción)
124
- await fact.createWebhook({
125
- url: "https://miapp.com/hooks/sunat",
126
- events: ["document.accepted", "document.rejected"],
28
+ empresaRuc: "20553510661",
29
+ /* ...resto del payload */
127
30
  });
128
31
 
129
- // 2. Polling (cómodo en desarrollo)
130
- const doc = await fact.waitForDocument(data.data.id, { timeoutMs: 120_000 });
131
- ```
132
-
133
- `waitForDocument` consulta cada 2s hasta un estado final —`ACEPTADO`,
134
- `RECHAZADO`, `COLA_FALLIDA` o `ANULADO`— o hasta que expire el timeout.
32
+ if (error) throw error;
33
+ console.log("Encolada:", data.data.id);
135
34
 
136
- ### Reintentar es seguro
137
-
138
- La API es idempotente por `empresa + tipoDoc + serie + correlativo`. Si se te
139
- cae la conexión y no sabes si llegó, **repite el mismo POST con el mismo
140
- correlativo**: te devuelve el mismo `id` y el mismo `hash`, sin reenviar nada a
141
- SUNAT.
142
-
143
- Lo único que rompe esa garantía es pedir un correlativo nuevo en el reintento.
144
- Llama a `getNextCorrelativo()` **una vez**, guárdalo junto con la venta, y
145
- reutiliza ese.
146
-
147
- ## Descargar los archivos
148
-
149
- ```ts
150
- const pdf = await fact.getInvoicePdf(id); // ArrayBuffer
151
- const xml = await fact.getInvoiceXml(id); // XML firmado
152
- const cdr = await fact.getInvoiceCdr(id); // CDR de SUNAT (zip)
153
-
154
- await fact.getDespatchPdf(id, "ticket80"); // "a4" | "ticket80" | "ticket58"
35
+ // Esperar hasta que SUNAT responda
36
+ const finalDoc = await fact.waitForDocument(data.data.id);
37
+ console.log("Estado:", finalDoc.data.sunat.estado);
155
38
  ```
156
39
 
157
- ## Un webhook para todos tus RUC
158
-
159
- Si facturas para terceros, no registres uno por empresa. Omitiendo `empresaRuc`
160
- el webhook cubre **toda tu cuenta**, con un solo secret, e incluye los RUC que
161
- des de alta después:
40
+ ## Métodos
41
+
42
+ ### Emisión
43
+ - `sendInvoice(body)` — factura (01) o boleta (03)
44
+ - `computeInvoice(body)` — calcular importes (Modelo B) sin emitir
45
+ - `sendNote(body)` — nota crédito (07) o débito (08)
46
+ - `computeNote(body)` — calcular importes de nota sin emitir
47
+ - `sendDespatch(body)` — guía remisión remitente (09)
48
+ - `sendDespatchMulti(body)` — varias guías en un request
49
+ - `sendDespatchTransportista(body)` — guía remisión transportista (31)
50
+ - `sendSummary(body)` — resumen diario
51
+ - `sendVoided(body)` — comunicación de baja
52
+
53
+ ### Anulaciones
54
+ - `cancelInvoice(body)` — anular factura
55
+ - `cancelBoleta(body)` — anular boleta
56
+
57
+ ### Consultas
58
+ - `listDocuments(query?)` — listado paginado con filtros
59
+ - `getDocument(id)` — detalle completo
60
+ - `getNextCorrelativo(query)` — siguiente correlativo de una serie
61
+ - `getTicketStatus(ticket, ruc)` — estado de ticket asíncrono
62
+
63
+ ### Archivos (ArrayBuffer)
64
+ - `getInvoiceXml(id)` / `getInvoiceCdr(id)` / `getInvoicePdf(id)`
65
+ - `getNoteXml(id)` / `getNotePdf(id)`
66
+ - `getDespatchXml(id)` / `getDespatchPdf(id, format?)` — `format`: a4 | ticket80 | ticket58
67
+
68
+ ### Webhooks
69
+ - `createWebhook(body)` / `listWebhooks()` / `getWebhook(id)`
70
+ - `updateWebhook(id, body)` / `deleteWebhook(id)`
71
+ - `listWebhookDeliveries(id)` / `redeliverWebhook(id, deliveryId)`
72
+ - `testWebhook(id)` / `rotateWebhookSecret(id)`
73
+
74
+ ### Catálogos SUNAT
75
+ - `getCatalogs()` / `getCatalog(key)`
76
+
77
+ ### Código de Producto SUNAT (Catálogo 25 / UNSPSC)
78
+ El código que va en `detalle[].codProdSunat`. SUNAT lo exige desde el
79
+ **2027-01-01**: si falta o es inválido rechaza con error `3496`. Son 8 dígitos.
80
+ - `buscarProductoSunat(q, { nivel?, limit? })` — texto libre (ignora tildes,
81
+ exige todos los términos) o prefijo de código si `q` son dígitos. Devuelve
82
+ primero las `CLASE`: SUNAT pide llegar como mínimo a ese nivel.
83
+ - `getProductoSunat(codigo)` — un código puntual (404 si no existe).
84
+ - `exportarProductosSunat()` — el catálogo completo (52.840 códigos) si
85
+ prefieres tu propia copia local. Limitado a **5 req/min**: bájalo una vez.
86
+
87
+ ### Consulta pública (sin auth — clientes finales)
88
+ - `consultarComprobante(ruc, tipoDoc, serie, numero, filtro)`
89
+ - `consultarComprobantePdf(...)` / `consultarComprobanteXml(...)` → ArrayBuffer
90
+ - `filtro` es **obligatorio** (al menos uno de `total`, `fecha`, `receptor`) —
91
+ anti-scraping: sin esto la API responde 404 aunque el comprobante exista.
92
+
93
+ ### Cola
94
+ - `retryDocument(id)` — re-encolar documento fallido
95
+ - `getQueueStats()` — estado de BullMQ
96
+ - `waitForDocument(id, opts?)` — polling hasta estado final
97
+
98
+ ### Empresas (solo lectura)
99
+ - `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
100
+
101
+ > Crear empresas, subir certificado/logo, gestionar API keys, tenants, audit y
102
+ > planes son operaciones administrativas (requieren `MASTER_API_KEY`) y no se
103
+ > exponen en el SDK — las gestiona el backend (ERP).
104
+
105
+ ## Regenerar tipos
106
+
107
+ Cada vez que la API agrega o cambia endpoints:
162
108
 
163
- ```ts
164
- const { data } = await fact.createWebhook({
165
- url: "https://miapp.com/hooks/sunat",
166
- events: ["document.accepted", "document.rejected"],
167
- });
168
- // data.data.secret — se muestra UNA sola vez
109
+ ```bash
110
+ npm run gen # contra http://localhost:3000
111
+ npm run gen -- --url=... # contra producción
169
112
  ```
170
113
 
171
- Cada payload trae `data.empresaRuc`, así que ruteas por ahí y verificas la firma
172
- HMAC siempre con la misma clave. Pasa `empresaRuc` solo si quieres que los
173
- eventos de una empresa puntual vayan a otra URL.
114
+ Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
174
115
 
175
- ## Establecimientos (anexos)
176
-
177
- Emitir sin `establecimientoCodigo` usa el matriz `"0000"`, así que esto solo
178
- hace falta si facturas desde más de un punto de venta — la dirección del
179
- establecimiento es la que sale impresa en el comprobante.
180
-
181
- ```ts
182
- await fact.createBranch(companyId, {
183
- codigo: "0001", // el que te asignó SUNAT en SOL
184
- nombre: "Sucursal Miraflores",
185
- direccion: "Av. Larco 1234",
186
- ubigeo: "150122",
187
- });
188
- ```
116
+ ## Stack
189
117
 
190
- El `codigo` tiene que coincidir con el del portal SOL (Mis Trámites >
191
- Establecimientos Anexos): si no calza, el comprobante sale con un punto de
192
- emisión que SUNAT no reconoce. El matriz `"0000"` no se puede desactivar.
193
-
194
- ## Qué cubre
195
-
196
- | Área | Métodos |
197
- |---|---|
198
- | Comprobantes | `sendInvoice`, `computeInvoice`, `sendNote`, `computeNote` |
199
- | Guías | `sendDespatch`, `sendDespatchMulti`, `sendDespatchTransportista` |
200
- | Anulaciones | `cancelInvoice`, `cancelBoleta`, `sendVoided`, `sendSummary` |
201
- | Documentos | `listDocuments`, `getDocument`, `retryDocument`, `getNextCorrelativo`, `waitForDocument` |
202
- | Archivos | `getInvoiceXml/Cdr/Pdf`, `getNoteXml/Pdf/Cdr`, `getDespatchXml/Cdr/Pdf` |
203
- | CDR | `consultarCdr` |
204
- | Empresas | `listCompanies`, `getCompany`, `createCompany`, `updateCompany`, `getCompanyLogo` |
205
- | Establecimientos | `listBranches`, `createBranch`, `updateBranch`, `deleteBranch` |
206
- | Webhooks | `createWebhook`, `listWebhooks`, `getWebhook`, `updateWebhook`, `deleteWebhook`, `listWebhookDeliveries`, `redeliverWebhook`, `testWebhook`, `rotateWebhookSecret` |
207
- | Catálogos | `getCatalogs`, `getCatalog` |
208
- | Consulta pública | `consultarComprobante`, `consultarComprobantePdf`, `consultarComprobanteXml` |
209
- | Colas | `getQueueStats` |
210
- | Tickets | `getTicketStatus` |
211
-
212
- Las operaciones administrativas (subir certificado y logo, gestionar API keys,
213
- tenants, auditoría, planes, reconciliación con SUNAT) requieren la master key y
214
- **no** se exponen aquí.
215
-
216
- Reclamar un RUC que otra cuenta registró (`POST /companies/claim`) sí acepta tu
217
- key, pero se hace desde el portal: recibe tu `.p12` con su contraseña, y eso no
218
- debería vivir en el código de tu app.
219
-
220
- ## Documentación
221
-
222
- Documentación completa en **[docs.intifact.com](https://docs.intifact.com/docs)**.
223
-
224
- | | |
225
- |---|---|
226
- | [Quickstart](https://docs.intifact.com/docs/facturacion/quickstart) | Tu primera factura, con ejemplos en Node, PHP, Python, C# y cURL |
227
- | [Autenticación](https://docs.intifact.com/docs/facturacion/authentication) | Ambientes `test`/`live`, alcance de las keys y rate limit |
228
- | [Idempotencia](https://docs.intifact.com/docs/facturacion/documents#idempotencia) | Qué devuelve un reintento y cómo no duplicar comprobantes |
229
- | [Webhooks](https://docs.intifact.com/docs/facturacion/webhooks) | Eventos, firma HMAC y verificación en 4 lenguajes |
230
- | [Guías de remisión](https://docs.intifact.com/docs/facturacion/despatch) | Tipos 09 y 31, reparto a varios destinos |
231
- | [Códigos de error](https://docs.intifact.com/docs/facturacion/error-codes) | HTTP, respuestas de SUNAT y cuáles se reintentan solos |
232
- | [Catálogos SUNAT](https://docs.intifact.com/docs/facturacion/catalogs) | Tipos de documento, afectación IGV, unidades de medida |
233
-
234
- ## Licencia
235
-
236
- MIT
118
+ - `openapi-typescript` — genera tipos TS desde la spec
119
+ - `openapi-fetch` — runtime client liviano (<6kB) con tipado completo