intifact 1.2.0 → 1.3.1
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 +134 -93
- package/dist/index.d.ts +399 -23
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +75 -8
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +333 -4
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,93 +1,134 @@
|
|
|
1
|
-
# intifact
|
|
2
|
-
|
|
3
|
-
SDK TypeScript para la API de Facturación Electrónica SUNAT de [Intifact](https://intifact.com).
|
|
4
|
-
|
|
5
|
-
Wrapper tipado sobre `openapi-fetch`: los tipos de request y response se generan
|
|
6
|
-
del OpenAPI de la API, así que el editor te avisa si
|
|
7
|
-
existe o te falta uno obligatorio.
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install intifact
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Uso
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { FacturacionClient } from "intifact";
|
|
17
|
-
|
|
18
|
-
const fact = new FacturacionClient({
|
|
19
|
-
baseUrl: "https://api-facturacion.intifact.com",
|
|
20
|
-
apiKey: "fact_live_...",
|
|
21
|
-
});
|
|
22
|
-
|
|
23
|
-
const { data, error } = await fact.sendInvoice({ /* ... */ });
|
|
24
|
-
if (error) throw new Error(error.message);
|
|
25
|
-
console.log("encolado:", data.data?.id);
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## El envío es asíncrono
|
|
29
|
-
|
|
30
|
-
Ningún `send*` devuelve el CDR. La API responde **202** con
|
|
31
|
-
`{ id, estado, hash, jobId }` y encola el documento; el resultado de SUNAT llega
|
|
32
|
-
después.
|
|
33
|
-
|
|
34
|
-
- **Webhook** (recomendado): `createWebhook()` y
|
|
35
|
-
`document.rejected`.
|
|
36
|
-
- **Polling**: `waitForDocument(id)` hace polling hasta un estado final
|
|
37
|
-
(`ACEPTADO`, `RECHAZADO`, `COLA_FALLIDA`, `ANULADO`) o timeout.
|
|
38
|
-
|
|
39
|
-
```ts
|
|
40
|
-
const { data } = await fact.sendInvoice(payload);
|
|
41
|
-
const doc = await fact.waitForDocument(data.data.id, { timeoutMs: 120_000 });
|
|
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
|
-
|
|
1
|
+
# intifact
|
|
2
|
+
|
|
3
|
+
SDK TypeScript para la API de Facturación Electrónica SUNAT de [Intifact](https://intifact.com).
|
|
4
|
+
|
|
5
|
+
Wrapper tipado sobre `openapi-fetch`: los tipos de request y response se generan
|
|
6
|
+
del OpenAPI de la API, así que el editor te avisa si envías un campo que no
|
|
7
|
+
existe o te falta uno obligatorio.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install intifact
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Uso
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { FacturacionClient } from "intifact";
|
|
17
|
+
|
|
18
|
+
const fact = new FacturacionClient({
|
|
19
|
+
baseUrl: "https://api-facturacion.intifact.com",
|
|
20
|
+
apiKey: "fact_live_...",
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const { data, error } = await fact.sendInvoice({ /* ... */ });
|
|
24
|
+
if (error) throw new Error(error.message);
|
|
25
|
+
console.log("encolado:", data.data?.id);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## El envío es asíncrono
|
|
29
|
+
|
|
30
|
+
Ningún `send*` devuelve el CDR. La API responde **202** con
|
|
31
|
+
`{ id, estado, hash, jobId }` y encola el documento; el resultado de SUNAT llega
|
|
32
|
+
después. Tienes dos formas de enterarte:
|
|
33
|
+
|
|
34
|
+
- **Webhook** (recomendado): `createWebhook()` y escuchas `document.accepted` /
|
|
35
|
+
`document.rejected`.
|
|
36
|
+
- **Polling**: `waitForDocument(id)` hace polling hasta un estado final
|
|
37
|
+
(`ACEPTADO`, `RECHAZADO`, `COLA_FALLIDA`, `ANULADO`) o timeout.
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
const { data } = await fact.sendInvoice(payload);
|
|
41
|
+
const doc = await fact.waitForDocument(data.data.id, { timeoutMs: 120_000 });
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Un webhook para todos tus RUC
|
|
45
|
+
|
|
46
|
+
Si facturas para terceros, no registres uno por empresa. Omitiendo `empresaRuc`
|
|
47
|
+
el webhook cubre **toda tu cuenta**, con un solo secret, e incluye los RUC que
|
|
48
|
+
des de alta después:
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
const { data } = await fact.createWebhook({
|
|
52
|
+
url: "https://miapp.com/hooks/sunat",
|
|
53
|
+
events: ["document.accepted", "document.rejected"],
|
|
54
|
+
});
|
|
55
|
+
// data.data.secret — se muestra UNA sola vez
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Cada payload trae `data.empresaRuc`, así que ruteas por ahí y verificas la firma
|
|
59
|
+
HMAC siempre con la misma clave. Pasa `empresaRuc` solo si quieres que los eventos
|
|
60
|
+
de una empresa puntual vayan a otra URL.
|
|
61
|
+
|
|
62
|
+
## Establecimientos (anexos)
|
|
63
|
+
|
|
64
|
+
Emitir sin `establecimientoCodigo` usa el matriz `"0000"`, así que esto solo hace
|
|
65
|
+
falta si facturas desde más de un punto de venta — la dirección del
|
|
66
|
+
establecimiento es la que sale impresa en el comprobante.
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
await fact.createBranch(companyId, {
|
|
70
|
+
codigo: "0001", // el que te asignó SUNAT en SOL
|
|
71
|
+
nombre: "Sucursal Miraflores",
|
|
72
|
+
direccion: "Av. Larco 1234",
|
|
73
|
+
ubigeo: "150122",
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
El `codigo` tiene que coincidir con el del portal SOL (Mis Trámites >
|
|
78
|
+
Establecimientos Anexos): si no calza, el comprobante sale con un punto de
|
|
79
|
+
emisión que SUNAT no reconoce. El matriz `"0000"` no se puede desactivar.
|
|
80
|
+
|
|
81
|
+
## Qué cubre
|
|
82
|
+
|
|
83
|
+
| Área | Métodos |
|
|
84
|
+
|---|---|
|
|
85
|
+
| Comprobantes | `sendInvoice`, `computeInvoice`, `sendNote`, `computeNote` |
|
|
86
|
+
| Guías | `sendDespatch`, `sendDespatchMulti`, `sendDespatchTransportista` |
|
|
87
|
+
| Anulaciones | `cancelInvoice`, `cancelBoleta`, `sendVoided`, `sendSummary` |
|
|
88
|
+
| Documentos | `listDocuments`, `getDocument`, `retryDocument`, `getNextCorrelativo`, `waitForDocument` |
|
|
89
|
+
| Archivos | `getInvoiceXml/Cdr/Pdf`, `getNoteXml/Pdf/Cdr`, `getDespatchXml/Cdr/Pdf` |
|
|
90
|
+
| CDR | `consultarCdr` |
|
|
91
|
+
| Empresas | `listCompanies`, `getCompany`, `createCompany`, `updateCompany`, `getCompanyLogo` |
|
|
92
|
+
| Establecimientos | `listBranches`, `createBranch`, `updateBranch`, `deleteBranch` |
|
|
93
|
+
| Webhooks | `createWebhook`, `listWebhooks`, `getWebhook`, `updateWebhook`, `deleteWebhook`, `listWebhookDeliveries`, `redeliverWebhook`, `testWebhook`, `rotateWebhookSecret` |
|
|
94
|
+
| Catálogos | `getCatalogs`, `getCatalog` |
|
|
95
|
+
| Consulta pública | `consultarComprobante`, `consultarComprobantePdf`, `consultarComprobanteXml` |
|
|
96
|
+
| Colas | `getQueueStats` |
|
|
97
|
+
| Tickets | `getTicketStatus` |
|
|
98
|
+
|
|
99
|
+
Las operaciones administrativas (subir certificado y logo, gestionar API keys,
|
|
100
|
+
tenants, auditoría, planes, reconciliación con SUNAT) requieren `MASTER_API_KEY`
|
|
101
|
+
y **no** se exponen aquí.
|
|
102
|
+
|
|
103
|
+
Reclamar un RUC que otra cuenta registró (`POST /companies/claim`) sí acepta tu
|
|
104
|
+
key, pero se hace desde el portal: recibe tu `.p12` con su contraseña, y eso no
|
|
105
|
+
debería vivir en el código de tu app.
|
|
106
|
+
|
|
107
|
+
## PDF de guías en ticket
|
|
108
|
+
|
|
109
|
+
`getDespatchPdf(id, format)` acepta `"a4"` (default), `"ticket80"` y
|
|
110
|
+
`"ticket58"`.
|
|
111
|
+
|
|
112
|
+
## Regenerar los tipos
|
|
113
|
+
|
|
114
|
+
Los tipos salen del OpenAPI de la API, no se escriben a mano:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npm run gen # baja el spec de localhost:3000
|
|
118
|
+
npm run build
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Si el server no está levantado, la API sabe volcar el spec sin HTTP:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
cd ../api-facturacion && npx tsx scripts/dump-openapi.ts spec.json
|
|
125
|
+
cd ../api-facturacion-sdk && SPEC_FILE=../api-facturacion/spec.json npm run gen
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Ojo:** con `SPEC_URL` el server tiene que estar corriendo con el código ya
|
|
129
|
+
mergeado. Si generas antes de tocar los schemas Zod, sale el spec viejo y los
|
|
130
|
+
campos nuevos no aparecen.
|
|
131
|
+
|
|
132
|
+
## Licencia
|
|
133
|
+
|
|
134
|
+
MIT
|