intifact 1.3.2 → 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 +119 -227
- package/dist/index.d.ts +1773 -574
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +59 -108
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +5985 -2840
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +4 -0
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,227 +1,119 @@
|
|
|
1
|
-
# intifact
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
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"],
|
|
127
|
-
});
|
|
128
|
-
|
|
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.
|
|
135
|
-
|
|
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"
|
|
155
|
-
```
|
|
156
|
-
|
|
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:
|
|
162
|
-
|
|
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
|
|
169
|
-
```
|
|
170
|
-
|
|
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.
|
|
174
|
-
|
|
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
|
-
```
|
|
189
|
-
|
|
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
|
-
Guías completas, referencia de endpoints, catálogos SUNAT y códigos de error en
|
|
223
|
-
[intifact.com](https://intifact.com).
|
|
224
|
-
|
|
225
|
-
## Licencia
|
|
226
|
-
|
|
227
|
-
MIT
|
|
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
|
+
> 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:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
npm run gen # contra http://localhost:3000
|
|
111
|
+
npm run gen -- --url=... # contra producción
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
|
|
115
|
+
|
|
116
|
+
## Stack
|
|
117
|
+
|
|
118
|
+
- `openapi-typescript` — genera tipos TS desde la spec
|
|
119
|
+
- `openapi-fetch` — runtime client liviano (<6kB) con tipado completo
|