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 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 mandás 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. Tenés dos formas de enterarte:
33
-
34
- - **Webhook** (recomendado): `createWebhook()` y escuchás `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
- ## Qué cubre
45
-
46
- | Área | Métodos |
47
- |---|---|
48
- | Comprobantes | `sendInvoice`, `computeInvoice`, `sendNote`, `computeNote` |
49
- | Guías | `sendDespatch`, `sendDespatchMulti`, `sendDespatchTransportista` |
50
- | Anulaciones | `cancelInvoice`, `cancelBoleta`, `sendVoided`, `sendSummary` |
51
- | Documentos | `listDocuments`, `getDocument`, `retryDocument`, `getNextCorrelativo`, `waitForDocument` |
52
- | Archivos | `getInvoiceXml/Cdr/Pdf`, `getNoteXml/Pdf/Cdr`, `getDespatchXml/Cdr/Pdf` |
53
- | CDR | `consultarCdr` |
54
- | Empresas | `listCompanies`, `getCompany`, `getCompanyLogo` |
55
- | Webhooks | `createWebhook`, `listWebhooks`, `getWebhook`, `updateWebhook`, `deleteWebhook`, `listWebhookDeliveries`, `redeliverWebhook`, `testWebhook`, `rotateWebhookSecret` |
56
- | Catálogos | `getCatalogs`, `getCatalog` |
57
- | Consulta pública | `consultarComprobante`, `consultarComprobantePdf`, `consultarComprobanteXml` |
58
- | Colas | `getQueueStats` |
59
- | Tickets | `getTicketStatus` |
60
-
61
- Las operaciones administrativas (crear empresas, subir certificado, gestionar
62
- API keys, tenants, auditoría, planes, reconciliación con SUNAT) requieren
63
- `MASTER_API_KEY` y **no** se exponen acá a propósito — las llama el backend
64
- directo.
65
-
66
- ## PDF de guías en ticket
67
-
68
- `getDespatchPdf(id, format)` acepta `"a4"` (default), `"ticket80"` y
69
- `"ticket58"`.
70
-
71
- ## Regenerar los tipos
72
-
73
- Los tipos salen del OpenAPI de la API, no se escriben a mano:
74
-
75
- ```bash
76
- npm run gen # baja el spec de localhost:3000
77
- npm run build
78
- ```
79
-
80
- Si el server no está levantado, la API sabe volcar el spec sin HTTP:
81
-
82
- ```bash
83
- cd ../api-facturacion && npx tsx scripts/dump-openapi.ts spec.json
84
- cd ../api-facturacion-sdk && SPEC_FILE=../api-facturacion/spec.json npm run gen
85
- ```
86
-
87
- **Ojo:** con `SPEC_URL` el server tiene que estar corriendo con el código ya
88
- mergeado. Si generás antes de tocar los schemas Zod, sale el spec viejo y los
89
- campos nuevos no aparecen.
90
-
91
- ## Licencia
92
-
93
- MIT
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