intifact 1.6.0 → 2.0.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,131 +1,136 @@
1
- # intifact
2
-
3
- SDK TypeScript auto-generado para la **API de Facturación Electrónica SUNAT de Intifact** (Perú).
4
-
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`.
6
-
7
- ## Instalación
8
-
9
- ```bash
10
- npm install intifact
11
- ```
12
-
13
- ## Uso básico
14
-
15
- ```ts
16
- import { FacturacionClient } from "intifact";
17
-
18
- const fact = new FacturacionClient({
19
- baseUrl: "https://api-facturacion.intifact.com",
20
- apiKey: process.env.FACTURACION_API_KEY, // tu API key fact_live_/fact_test_
21
- });
22
-
23
- // Enviar factura → 202 (encolada)
24
- const { data, error } = await fact.sendInvoice({
25
- tipoDoc: "01",
26
- serie: "F001",
27
- correlativo: "1",
28
- empresaRuc: "20553510661",
29
- /* ...resto del payload */
30
- });
31
-
32
- if (error) throw error;
33
- console.log("Encolada:", data.data.id);
34
-
35
- // Esperar hasta que SUNAT responda
36
- const finalDoc = await fact.waitForDocument(data.data.id);
37
- console.log("Estado:", finalDoc.data.sunat.estado);
38
- ```
39
-
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
- ### Establecimientos (sucursales)
102
- El `codigo` (4 dígitos) va al XML como `cbc:AddressTypeCode` y decide qué
103
- dirección sale impresa en el comprobante. Debe coincidir con el que SUNAT
104
- asignó en el portal SOL (Mis Trámites > Establecimientos Anexos).
105
- - `listBranches(companyId)` / `createBranch(companyId, body)`
106
- - `updateBranch(companyId, branchId, body)` — el `codigo` no se cambia
107
- - `deactivateBranch(companyId, branchId)` — soft-delete; el matriz `"0000"` no
108
- se puede desactivar (409)
109
-
110
- > Alcance: una key con `tenantId` solo opera las empresas de su cuenta; con
111
- > `companyId`, solo esa. Una empresa ajena responde **404**, no 403.
112
-
113
- > Crear empresas, subir certificado/logo, gestionar API keys, tenants, audit y
114
- > planes son operaciones administrativas (requieren `MASTER_API_KEY`) y no se
115
- > exponen en el SDK — las gestiona el backend (ERP).
116
-
117
- ## Regenerar tipos
118
-
119
- Cada vez que la API agrega o cambia endpoints:
120
-
121
- ```bash
122
- npm run gen # contra http://localhost:3000
123
- npm run gen -- --url=... # contra producción
124
- ```
125
-
126
- Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
127
-
128
- ## Stack
129
-
130
- - `openapi-typescript` — genera tipos TS desde la spec
131
- - `openapi-fetch` — runtime client liviano (<6kB) con tipado completo
1
+ # intifact
2
+
3
+ SDK TypeScript auto-generado para la **API de Facturación Electrónica SUNAT de Intifact** (Perú).
4
+
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`.
6
+
7
+ ## Instalación
8
+
9
+ ```bash
10
+ npm install intifact
11
+ ```
12
+
13
+ ## Uso básico
14
+
15
+ ```ts
16
+ import { FacturacionClient } from "intifact";
17
+
18
+ const fact = new FacturacionClient({
19
+ baseUrl: "https://api-facturacion.intifact.com",
20
+ apiKey: process.env.FACTURACION_API_KEY, // tu API key fact_live_/fact_test_
21
+ });
22
+
23
+ // Enviar factura → 202 (encolada)
24
+ const { data, error } = await fact.sendInvoice({
25
+ tipoDoc: "01",
26
+ serie: "F001",
27
+ correlativo: "1",
28
+ empresaRuc: "20553510661",
29
+ /* ...resto del payload */
30
+ });
31
+
32
+ if (error) throw error;
33
+ console.log("Encolada:", data.data.id);
34
+
35
+ // Esperar hasta que SUNAT responda
36
+ const finalDoc = await fact.waitForDocument(data.data.id);
37
+ console.log("Estado:", finalDoc.data.sunat.estado);
38
+ ```
39
+
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
+ - `getSummary(id)` — estado de un envío RC/RA (el `id` que devuelven `sendSummary`, `sendVoided`, `cancelInvoice` y `cancelBoleta`)
62
+ - `getTicketStatus(ticket, ruc)` — estado de ticket asíncrono
63
+
64
+ ### Archivos (ArrayBuffer)
65
+ - `getInvoiceXml(id)` / `getInvoiceCdr(id)` / `getInvoicePdf(id)`
66
+ - `getNoteXml(id)` / `getNotePdf(id)`
67
+ - `getDespatchXml(id)` / `getDespatchPdf(id, format?)` — `format`: a4 | ticket80 | ticket58
68
+
69
+ ### Catálogos SUNAT
70
+ - `getCatalogs()` / `getCatalog(key)`
71
+
72
+ ### Código de Producto SUNAT (Catálogo 25 / UNSPSC)
73
+ El código que va en `detalle[].codProdSunat`. SUNAT lo exige desde el
74
+ **2027-01-01**: si falta o es inválido rechaza con error `3496`. Son 8 dígitos.
75
+ - `buscarProductoSunat(q, { nivel?, limit? })` — texto libre (ignora tildes,
76
+ exige todos los términos) o prefijo de código si `q` son dígitos. Devuelve
77
+ primero las `CLASE`: SUNAT pide llegar como mínimo a ese nivel.
78
+ - `getProductoSunat(codigo)` — un código puntual (404 si no existe).
79
+ - `exportarProductosSunat()` — el catálogo completo (52.840 códigos) si
80
+ prefieres tu propia copia local. Limitado a **5 req/min**: bájalo una vez.
81
+
82
+ ### Consulta pública (sin auth — clientes finales)
83
+ - `consultarComprobante(ruc, tipoDoc, serie, numero, filtro)`
84
+ - `consultarComprobantePdf(...)` / `consultarComprobanteXml(...)` → ArrayBuffer
85
+ - `filtro` es **obligatorio** (al menos uno de `total`, `fecha`, `receptor`) —
86
+ anti-scraping: sin esto la API responde 404 aunque el comprobante exista.
87
+
88
+ ### Cola
89
+ - `retryDocument(id)` — re-encolar documento fallido
90
+ - `getQueueStats()` — estado de BullMQ
91
+ - `waitForDocument(id, opts?)` — polling hasta estado final
92
+
93
+ ### Empresas (solo lectura)
94
+ - `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
95
+
96
+ ### Establecimientos (solo lectura)
97
+ El `codigo` (4 dígitos) va al XML como `cbc:AddressTypeCode` y decide qué
98
+ dirección sale impresa en el comprobante.
99
+ - `listBranches(companyId)` — para saber qué `establecimientoCodigo` mandar
100
+
101
+ > Alcance: una key con `tenantId` solo ve las empresas de su cuenta; con
102
+ > `companyId`, solo esa. Una empresa ajena responde **404**, no 403.
103
+
104
+ > La administración de la cuenta —crear o editar empresas, credenciales SOL/GRE,
105
+ > certificado, logo, registrar establecimientos y **webhooks**— se hace desde el
106
+ > panel de Intifact, no con la API key (la API responde `403`). Así una key
107
+ > filtrada solo puede emitir y consultar.
108
+
109
+ ## Migrar de 1.x a 2.0
110
+
111
+ La 2.0 quita los métodos que la API ya no acepta con una API key:
112
+
113
+ - Webhooks: `createWebhook`, `listWebhooks`, `getWebhook`, `updateWebhook`,
114
+ `deleteWebhook`, `listWebhookDeliveries`, `redeliverWebhook`, `testWebhook`,
115
+ `rotateWebhookSecret` y los tipos `CreateWebhookInput` / `UpdateWebhookInput`.
116
+ - Establecimientos: `createBranch`, `updateBranch`, `deactivateBranch` y los
117
+ tipos `CreateBranchInput` / `UpdateBranchInput` (`listBranches` se queda).
118
+
119
+ Todo eso se hace ahora desde el portal de Intifact. Del lado de tu código, los
120
+ webhooks solo se reciben y se verifica su firma con el secret que da el portal.
121
+
122
+ ## Regenerar tipos
123
+
124
+ Cada vez que la API agrega o cambia endpoints:
125
+
126
+ ```bash
127
+ npm run gen # contra http://localhost:3000
128
+ npm run gen -- --url=... # contra producción
129
+ ```
130
+
131
+ Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
132
+
133
+ ## Stack
134
+
135
+ - `openapi-typescript` — genera tipos TS desde la spec
136
+ - `openapi-fetch` — runtime client liviano (<6kB) con tipado completo