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 +96 -69
- package/dist/index.d.ts +517 -19
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +103 -14
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +626 -10
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +0 -4
- package/dist/types.js.map +1 -1
- package/package.json +47 -47
package/README.md
CHANGED
|
@@ -1,107 +1,134 @@
|
|
|
1
1
|
# intifact
|
|
2
2
|
|
|
3
|
-
SDK TypeScript
|
|
3
|
+
SDK TypeScript para la API de Facturación Electrónica SUNAT de [Intifact](https://intifact.com).
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
|
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:
|
|
20
|
+
apiKey: "fact_live_...",
|
|
21
21
|
});
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
-
|
|
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.
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
const
|
|
37
|
-
|
|
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
|
-
|
|
44
|
+
### Un webhook para todos tus RUC
|
|
41
45
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
75
|
-
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
87
|
-
- `listCompanies()` / `getCompany(id)` / `getCompanyLogo(id)`
|
|
107
|
+
## PDF de guías en ticket
|
|
88
108
|
|
|
89
|
-
|
|
90
|
-
|
|
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
|
-
|
|
121
|
+
Si el server no está levantado, la API sabe volcar el spec sin HTTP:
|
|
96
122
|
|
|
97
123
|
```bash
|
|
98
|
-
|
|
99
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
132
|
+
## Licencia
|
|
105
133
|
|
|
106
|
-
|
|
107
|
-
- `openapi-fetch` — runtime client liviano (<6kB) con tipado completo
|
|
134
|
+
MIT
|