intifact 1.3.1 → 1.3.3

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.
Files changed (2) hide show
  1. package/README.md +147 -45
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,47 +1,160 @@
1
1
  # intifact
2
2
 
3
- SDK TypeScript para la API de Facturación Electrónica SUNAT de [Intifact](https://intifact.com).
3
+ [![npm](https://img.shields.io/npm/v/intifact.svg)](https://www.npmjs.com/package/intifact)
4
+ [![types](https://img.shields.io/npm/types/intifact.svg)](https://www.npmjs.com/package/intifact)
4
5
 
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.
6
+ SDK oficial de TypeScript para emitir comprobantes electrónicos ante **SUNAT
7
+ (Perú)**: facturas, boletas, notas de crédito y débito, guías de remisión,
8
+ resúmenes diarios y comunicaciones de baja.
9
+
10
+ Tú mandas JSON. La API arma el XML UBL 2.1, lo firma con tu certificado, lo
11
+ envía a SUNAT, procesa el CDR y te devuelve el PDF con su QR. No necesitas saber
12
+ nada de UBL, XMLDSig ni SOAP.
13
+
14
+ Los tipos se generan del OpenAPI de la API, así que el editor te avisa del campo
15
+ que falta o del que escribiste mal **antes** de ejecutar nada.
8
16
 
9
17
  ```bash
10
18
  npm install intifact
11
19
  ```
12
20
 
13
- ## Uso
21
+ Requiere Node 18+ (usa `fetch` nativo). Funciona igual en Bun y Deno.
22
+
23
+ ## Empieza en pruebas
24
+
25
+ El ambiente **lo decide la key**, no un parámetro. Las creas tú desde el
26
+ [panel de Intifact](https://intifact.com).
27
+
28
+ | Prefijo | Destino | Validez fiscal | Consume tu plan | Certificado |
29
+ |---|---|---|---|---|
30
+ | `fact_test_` | SUNAT beta | Ninguna | No | Uno de prueba compartido |
31
+ | `fact_live_` | SUNAT producción | Real | Sí | El tuyo |
32
+
33
+ Integra entero con `fact_test_`. Cuando funcione, cambias la key por la de
34
+ producción — el código no cambia ni una línea.
35
+
36
+ > [!WARNING]
37
+ > Una key `fact_live_` emite comprobantes fiscales reales desde la primera
38
+ > request. Un error ahí no se borra: se anula con nota de crédito o
39
+ > comunicación de baja.
40
+
41
+ ## Tu primera factura
14
42
 
15
43
  ```ts
16
44
  import { FacturacionClient } from "intifact";
17
45
 
18
46
  const fact = new FacturacionClient({
19
47
  baseUrl: "https://api-facturacion.intifact.com",
20
- apiKey: "fact_live_...",
48
+ apiKey: process.env.INTIFACT_API_KEY, // fact_test_...
49
+ });
50
+
51
+ const { data, error } = await fact.sendInvoice({
52
+ empresaRuc: "20553510661",
53
+ tipoDoc: "01", // 01 factura · 03 boleta
54
+ serie: "F001",
55
+ correlativo: "1",
56
+ fechaEmision: "2026-01-15",
57
+ tipoMoneda: "PEN",
58
+ tipoOperacion: "0101", // venta interna
59
+
60
+ clienteTipoDoc: "6", // 6 RUC · 1 DNI
61
+ clienteNumDoc: "20000000001",
62
+ clienteRazonSocial: "EMPRESA CLIENTE SAC",
63
+
64
+ detalle: [{
65
+ unidad: "NIU",
66
+ cantidad: 2,
67
+ codProducto: "PROD001",
68
+ descripcion: "Producto de ejemplo",
69
+ montoValorUnitario: 100.0,
70
+ montoBaseIgv: 200.0,
71
+ porcentajeIgv: 18,
72
+ igv: 36.0,
73
+ tipAfeIgv: "10", // gravado, operación onerosa
74
+ totalImpuestos: 36.0,
75
+ montoPrecioUnitario: 118.0,
76
+ montoValorVenta: 200.0,
77
+ }],
78
+
79
+ montoIgv: 36.0,
80
+ totalImpuestos: 36.0,
81
+ valorVenta: 200.0,
82
+ subTotal: 236.0,
83
+ montoImpVenta: 236.0,
84
+ leyendas: [{ legendCode: "1000", legendValue: "DOSCIENTOS TREINTA Y SEIS CON 00/100 SOLES" }],
85
+ formaPago: [{ tipo: "Contado", monto: 236.0, fechaPago: "2026-01-15" }],
21
86
  });
22
87
 
23
- const { data, error } = await fact.sendInvoice({ /* ... */ });
24
88
  if (error) throw new Error(error.message);
25
- console.log("encolado:", data.data?.id);
89
+ console.log(data.data.id, data.data.estado); // → "550e8400-…" "ENCOLADO"
26
90
  ```
27
91
 
28
- ## El envío es asíncrono
92
+ ¿No quieres calcular los importes tú? `computeInvoice()` te los devuelve a
93
+ partir de cantidades y precios, sin emitir nada.
94
+
95
+ ## Errores
96
+
97
+ Ningún método lanza excepciones por respuestas de la API: devuelven
98
+ `{ data, error }`, igual que `openapi-fetch`. Un `throw` solo aparece si se cae
99
+ la red.
100
+
101
+ ```ts
102
+ const { data, error } = await fact.sendInvoice(payload);
103
+
104
+ if (error) {
105
+ console.error(error.message); // "Error de validación"
106
+ console.error(error.errors); // [{ path: "detalle.0.igv", message: "..." }]
107
+ return;
108
+ }
109
+ ```
110
+
111
+ Los errores de schema llegan **al instante**, con el campo exacto. Los rechazos
112
+ de SUNAT llegan después, en el estado del documento.
113
+
114
+ ## El resultado de SUNAT llega después
29
115
 
30
116
  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:
117
+ `{ id, estado: "ENCOLADO", hash }` y encola el documento: si SUNAT está caída,
118
+ reintenta sola con backoff en vez de fallarte la venta.
33
119
 
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.
120
+ Tienes dos formas de enterarte del desenlace:
38
121
 
39
122
  ```ts
40
- const { data } = await fact.sendInvoice(payload);
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)
41
130
  const doc = await fact.waitForDocument(data.data.id, { timeoutMs: 120_000 });
42
131
  ```
43
132
 
44
- ### Un webhook para todos tus RUC
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
45
158
 
46
159
  Si facturas para terceros, no registres uno por empresa. Omitiendo `empresaRuc`
47
160
  el webhook cubre **toda tu cuenta**, con un solo secret, e incluye los RUC que
@@ -56,13 +169,13 @@ const { data } = await fact.createWebhook({
56
169
  ```
57
170
 
58
171
  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.
172
+ HMAC siempre con la misma clave. Pasa `empresaRuc` solo si quieres que los
173
+ eventos de una empresa puntual vayan a otra URL.
61
174
 
62
175
  ## Establecimientos (anexos)
63
176
 
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
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
66
179
  establecimiento es la que sale impresa en el comprobante.
67
180
 
68
181
  ```ts
@@ -97,37 +210,26 @@ emisión que SUNAT no reconoce. El matriz `"0000"` no se puede desactivar.
97
210
  | Tickets | `getTicketStatus` |
98
211
 
99
212
  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í.
213
+ tenants, auditoría, planes, reconciliación con SUNAT) requieren la master key y
214
+ **no** se exponen aquí.
102
215
 
103
216
  Reclamar un RUC que otra cuenta registró (`POST /companies/claim`) sí acepta tu
104
217
  key, pero se hace desde el portal: recibe tu `.p12` con su contraseña, y eso no
105
218
  debería vivir en el código de tu app.
106
219
 
107
- ## PDF de guías en ticket
220
+ ## Documentación
108
221
 
109
- `getDespatchPdf(id, format)` acepta `"a4"` (default), `"ticket80"` y
110
- `"ticket58"`.
222
+ Documentación completa en **[docs.intifact.com](https://docs.intifact.com/docs)**.
111
223
 
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.
224
+ | | |
225
+ |---|---|
226
+ | [Quickstart](https://docs.intifact.com/docs/facturacion/quickstart) | Tu primera factura, con ejemplos en Node, PHP, Python, C# y cURL |
227
+ | [Autenticación](https://docs.intifact.com/docs/facturacion/authentication) | Ambientes `test`/`live`, alcance de las keys y rate limit |
228
+ | [Idempotencia](https://docs.intifact.com/docs/facturacion/documents#idempotencia) | Qué devuelve un reintento y cómo no duplicar comprobantes |
229
+ | [Webhooks](https://docs.intifact.com/docs/facturacion/webhooks) | Eventos, firma HMAC y verificación en 4 lenguajes |
230
+ | [Guías de remisión](https://docs.intifact.com/docs/facturacion/despatch) | Tipos 09 y 31, reparto a varios destinos |
231
+ | [Códigos de error](https://docs.intifact.com/docs/facturacion/error-codes) | HTTP, respuestas de SUNAT y cuáles se reintentan solos |
232
+ | [Catálogos SUNAT](https://docs.intifact.com/docs/facturacion/catalogs) | Tipos de documento, afectación IGV, unidades de medida |
131
233
 
132
234
  ## Licencia
133
235
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "intifact",
3
- "version": "1.3.1",
3
+ "version": "1.3.3",
4
4
  "description": "SDK TypeScript para la API de Facturación Electrónica SUNAT de Intifact",
5
5
  "homepage": "https://intifact.com",
6
6
  "type": "module",