intifact 1.1.2 → 1.3.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 CHANGED
@@ -1,107 +1,134 @@
1
1
  # intifact
2
2
 
3
- SDK TypeScript auto-generado para la **API de Facturación Electrónica SUNAT de Intifact** (Perú).
3
+ SDK TypeScript para la API de Facturación Electrónica SUNAT de [Intifact](https://intifact.com).
4
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
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
8
 
9
9
  ```bash
10
10
  npm install intifact
11
11
  ```
12
12
 
13
- ## Uso básico
13
+ ## Uso
14
14
 
15
15
  ```ts
16
16
  import { FacturacionClient } from "intifact";
17
17
 
18
18
  const fact = new FacturacionClient({
19
19
  baseUrl: "https://api-facturacion.intifact.com",
20
- apiKey: process.env.FACTURACION_API_KEY, // tu API key fact_live_/fact_test_
20
+ apiKey: "fact_live_...",
21
21
  });
22
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
- });
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:
31
33
 
32
- if (error) throw error;
33
- console.log("Encolada:", data.data.id);
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.
34
38
 
35
- // Esperar hasta que SUNAT responda
36
- const finalDoc = await fact.waitForDocument(data.data.id);
37
- console.log("Estado:", finalDoc.data.sunat.estado);
39
+ ```ts
40
+ const { data } = await fact.sendInvoice(payload);
41
+ const doc = await fact.waitForDocument(data.data.id, { timeoutMs: 120_000 });
38
42
  ```
39
43
 
40
- ## Métodos
44
+ ### Un webhook para todos tus RUC
41
45
 
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
46
+ Si facturás 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:
52
49
 
53
- ### Anulaciones
54
- - `cancelInvoice(body)` — anular factura
55
- - `cancelBoleta(body)` — anular boleta
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
+ ```
56
57
 
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
58
+ Cada payload trae `data.empresaRuc`, así que ruteás por ahí y verificás la firma
59
+ HMAC siempre con la misma clave. Pasá `empresaRuc` solo si querés que los eventos
60
+ de una empresa puntual vayan a otra URL.
62
61
 
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
62
+ ## Establecimientos (anexos)
67
63
 
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)`
64
+ Emitir sin `establecimientoCodigo` usa el matriz `"0000"`, así que esto solo hace
65
+ falta si facturás desde más de un punto de venta — la dirección del
66
+ establecimiento es la que sale impresa en el comprobante.
73
67
 
74
- ### Catálogos SUNAT
75
- - `getCatalogs()` / `getCatalog(key)`
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` |
76
98
 
77
- ### Consulta pública (sin auth — clientes finales)
78
- - `consultarComprobante(ruc, tipoDoc, serie, numero)`
79
- - `consultarComprobantePdf(...)` / `consultarComprobanteXml(...)` → ArrayBuffer
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 acá.
80
102
 
81
- ### Cola
82
- - `retryDocument(id)` — re-encolar documento fallido
83
- - `getQueueStats()` — estado de BullMQ
84
- - `waitForDocument(id, opts?)` — polling hasta estado final
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.
85
106
 
86
- ### Empresas (solo lectura)
87
- - `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
107
+ ## PDF de guías en ticket
88
108
 
89
- > Crear empresas, subir certificado/logo, gestionar API keys, tenants, audit y
90
- > planes son operaciones administrativas (requieren `MASTER_API_KEY`) y no se
91
- > exponen en el SDK — las gestiona el backend (ERP).
109
+ `getDespatchPdf(id, format)` acepta `"a4"` (default), `"ticket80"` y
110
+ `"ticket58"`.
92
111
 
93
- ## Regenerar tipos
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
+ ```
94
120
 
95
- Cada vez que la API agrega o cambia endpoints:
121
+ Si el server no está levantado, la API sabe volcar el spec sin HTTP:
96
122
 
97
123
  ```bash
98
- npm run gen # contra http://localhost:3000
99
- npm run gen -- --url=... # contra producción
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
100
126
  ```
101
127
 
102
- Esto descarga `openapi.json` y regenera `src/types.ts` con `openapi-typescript`.
128
+ **Ojo:** con `SPEC_URL` el server tiene que estar corriendo con el código ya
129
+ mergeado. Si generás antes de tocar los schemas Zod, sale el spec viejo y los
130
+ campos nuevos no aparecen.
103
131
 
104
- ## Stack
132
+ ## Licencia
105
133
 
106
- - `openapi-typescript` — genera tipos TS desde la spec
107
- - `openapi-fetch` — runtime client liviano (<6kB) con tipado completo
134
+ MIT