intifact 2.0.0 → 2.1.2

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,136 +1,167 @@
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
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
94
+ - `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
95
+
96
+ **Autogestión** (desde la 2.1; key **live de cuenta** en un **plan pago**):
97
+ - `registerCompany(body)` — alta con el certificado `.p12` (base64) del **mismo
98
+ RUC**; si no abre, está vencido o es de otro RUC, responde `400` y no guarda
99
+ nada. Repetirla con un RUC que ya está en tu cuenta devuelve `creada: false`.
100
+ - `updateCompany(id, body)` — datos de la empresa (no sus credenciales)
101
+ - `uploadCompanyCertificate(id, body)` — renovar el certificado (mismo RUC)
102
+ - `uploadCompanyLogo(id, blob, nombre?)` / `deleteCompanyLogo(id)` — PNG o JPG,
103
+ hasta 200 KB y 2500 px por lado
104
+
105
+ ```ts
106
+ import { readFile } from "node:fs/promises";
107
+
108
+ const { data, error } = await fact.registerCompany({
109
+ ruc: "20553510661",
110
+ razonSocial: "ACME S.A.C.",
111
+ direccion: "AV. AREQUIPA 1234",
112
+ ubigeo: "150122",
113
+ certificado: {
114
+ content: (await readFile("acme.p12")).toString("base64"),
115
+ password: process.env.CERT_PASSWORD!,
116
+ },
117
+ });
118
+ ```
119
+
120
+ ### Establecimientos
121
+ El `codigo` (4 dígitos) va al XML como `cbc:AddressTypeCode` y decide qué
122
+ dirección sale impresa en el comprobante.
123
+ - `listBranches(companyId)` — para saber qué `establecimientoCodigo` mandar
124
+ - `createBranch(companyId, body)` / `updateBranch(companyId, branchId, body)` /
125
+ `deactivateBranch(companyId, branchId)` — autogestión (plan pago)
126
+
127
+ ### Consumo del plan
128
+ - `getUsage()` — comprobantes emitidos en el periodo y el límite de tu plan
129
+
130
+ > Alcance: una key con `tenantId` solo ve las empresas de su cuenta; con
131
+ > `companyId`, solo esa. Una empresa ajena responde **404**, no 403.
132
+
133
+ > Siguen en el panel de Intifact: las credenciales SOL/GRE/SIRE de una empresa
134
+ > ya creada, los **webhooks** y el reclamo de un RUC. Sin plan pago, con una key
135
+ > de prueba o con una key de empresa, la gestión responde `403`
136
+ > (`AUTOGESTION_NO_DISPONIBLE`). Detalle en
137
+ > https://docs.intifact.com/docs/facturacion/autogestion
138
+
139
+ ## Migrar de 1.x a 2.0
140
+
141
+ La 2.0 quita los métodos que la API ya no acepta con una API key:
142
+
143
+ - Webhooks: `createWebhook`, `listWebhooks`, `getWebhook`, `updateWebhook`,
144
+ `deleteWebhook`, `listWebhookDeliveries`, `redeliverWebhook`, `testWebhook`,
145
+ `rotateWebhookSecret` y los tipos `CreateWebhookInput` / `UpdateWebhookInput`.
146
+ - Establecimientos: `createBranch`, `updateBranch`, `deactivateBranch` y los
147
+ tipos `CreateBranchInput` / `UpdateBranchInput` (`listBranches` se queda).
148
+
149
+ Todo eso se hace desde el portal de Intifact. (Desde la 2.1, los métodos de
150
+ establecimientos vuelven para las cuentas con plan pago; los webhooks no.) Del lado de tu código, los
151
+ webhooks solo se reciben y se verifica su firma con el secret que da el portal.
152
+
153
+ ## Regenerar tipos
154
+
155
+ Cada vez que la API agrega o cambia endpoints:
156
+
157
+ ```bash
158
+ npm run gen # contra http://localhost:3000
159
+ npm run gen -- --url=... # contra producción
160
+ ```
161
+
162
+ Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
163
+
164
+ ## Stack
165
+
166
+ - `openapi-typescript` — genera tipos TS desde la spec
167
+ - `openapi-fetch` — runtime client liviano (<6kB) con tipado completo