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 +167 -136
- package/dist/index.d.ts +839 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +78 -7
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +844 -53
- package/dist/types.d.ts.map +1 -1
- package/package.json +54 -47
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
|
|
94
|
-
- `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
+
- `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
|