apiempresas 1.6.1 → 1.8.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.
Files changed (3) hide show
  1. package/README.md +282 -280
  2. package/dist/types.d.ts +38 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,280 +1,282 @@
1
- # APIEmpresas.es - Node.js SDK
2
-
3
- SDK oficial para interactuar con la API de [APIEmpresas.es](https://apiempresas.es) desde Node.js utilizando TypeScript o JavaScript.
4
-
5
- ## Instalación
6
-
7
- ```bash
8
- npm install apiempresas
9
- ```
10
-
11
- ## Inicialización
12
-
13
- ```typescript
14
- import { ApiEmpresas } from 'apiempresas';
15
-
16
- const api = new ApiEmpresas({
17
- apiKey: 'TU_API_KEY', // Obligatorio
18
- });
19
- ```
20
-
21
- ## Uso Básico
22
-
23
- ### 1. Obtener datos de una empresa
24
-
25
- ```typescript
26
- async function fetchCompany() {
27
- try {
28
- const company = await api.companies.get('A15075062');
29
- console.log(company.name);
30
- } catch (error) {
31
- console.error('Error fetching company:', error.message);
32
- }
33
- }
34
- ```
35
-
36
- ### 2. Historial de Actos del BORME
37
-
38
- ```typescript
39
- async function fetchBorme() {
40
- const bormeData = await api.companies.borme('A15075062');
41
- console.log(bormeData.events);
42
- }
43
- ```
44
-
45
- ### 3. Consulta Múltiple (Batch)
46
-
47
- ```typescript
48
- async function fetchBatch() {
49
- const response = await api.companies.batch({
50
- cifs: ['A15075062', 'A46103834']
51
- });
52
- console.log('Resultados:', response.data);
53
- console.log('Coste:', response.meta.cost);
54
- }
55
- ```
56
-
57
- ### 4. Administradores, búsqueda con varios resultados, Match y Radar
58
-
59
- ```typescript
60
- // Administradores y cargos (Pro/Business)
61
- const conAdmins = await api.companies.get('A15075062', { admin: true });
62
-
63
- // Varias empresas por nombre, con paginación
64
- let pagina = await api.companies.searchMultiple('software', { limit: 20 });
65
- while (pagina.meta.next_cursor) {
66
- pagina = await api.companies.searchMultiple('software', { cursor: pagina.meta.next_cursor });
67
- }
68
-
69
- // Match (Business): el sector del vendedor es obligatorio
70
- const match = await api.companies.match('A15075062', 'software');
71
-
72
- // Radar de empresas nuevas (todos los planes: 10 resultados en Free con nombre y CIF ocultos, 100 en Pro, 1.000 en Business). range: 'hoy' (por defecto) o días atrás ('7', '30')
73
- const nuevas = await api.companies.radar({ province: 'Madrid', range: '7' });
74
- // Filtros añadidos en 1.2.0: cnae, min_score, main_act_type, has_phone
75
- const software = await api.companies.radar({ cnae: '62', min_score: 70, has_phone: true });
76
- ```
77
-
78
- Requiere Node.js 18 o superior (usa `fetch` nativo).
79
-
80
- ### 5. Verificación KYB (Pro) — 2 consultas
81
-
82
- ```typescript
83
- const v = await api.companies.verify('A46103834', {
84
- name: 'Mercadona SA', // se compara con la razón social
85
- person: 'Juan Roig Alfonso', // ¿es administrador vigente?
86
- vat: true, // NIF-IVA en VIES
87
- iban: 'ES9121000418450200051332' // (1.5.0) ¿está bien formado? No dice de quién es la cuenta
88
- });
89
- console.log(v.decision_hint); // 'pass' | 'review' | 'fail'
90
- console.log(v.flags); // alertas con code, severity y message
91
- ```
92
-
93
- Cada empresa trae además `status_code` (ACTIVE, INSOLVENCY, EXTINCT...), `status_source`, `status_date` y, en Pro/Business, `financials` (tramo de tamaño y último año de cuentas). Los administradores traen `since`. Desde la 1.3.0 la respuesta lleva también `identifiers` (código LEI) y `legal_form` (forma jurídica con su código ISO 20275) en todos los planes, y en Pro/Business `group` (matriz directa y última según GLEIF) y `ownership` (socio único según el BORME). En `verify`, con `person`, `checks.person.is_sole_shareholder` dice si quien firma es el socio único. Desde la 1.5.0, en Pro/Business, `size` (tramo de empleados con su fuente: Kit Digital, TED o PLACSP; null si no consta) y `address_density` (cuántas sociedades activas comparten la dirección exacta), y en `verify` con `iban`, `checks.iban` (si no es válido, alerta `IBAN_INVALID` y `decision_hint` review). `filter()` admite `size_category` (micro, small, medium, large).
94
-
95
- ### Nombre a CIF (Pro)
96
-
97
- ```typescript
98
- const { data, meta } = await api.companies.reconcile(['Mercadona', { name: 'Talleres Pérez', province: 'Madrid' }]);
99
- // data[i].status: match (con company.cif) | ambiguous (candidates) | no_match. Solo se cobran los match.
100
- ```
101
-
102
- ### Validar el NIF de tus clientes antes de facturar (Pro, Business o saldo; desde 1.6.0)
103
-
104
- ```typescript
105
- const { data, meta } = await api.companies.verifyBatch([
106
- { cif: 'A46103834', name: 'Mercadona', ref: 'cliente-0001' }, // name: la razón social que tienes guardada
107
- { cif: 'A15075062', name: 'Inditex', ref: 'cliente-0002' }, // ref: tu identificador, vuelve tal cual
108
- 'B12345674', // o el NIF suelto
109
- ]);
110
- data.forEach((fila) => console.log(fila.input, fila.invoice_hint)); // 'ok' | 'revisar' | 'no_facturar'
111
- // await api.companies.verifyBatch(['A46103834'], { vat: true }); // también VIES
112
- ```
113
-
114
- Por cada NIF, en el mismo orden: `valid_format`, `exists`, `legal_name`, `address`, `status_code`, `name_check` (si das `name`) e `invoice_hint` (`ok`, `revisar` o `no_facturar`) con sus motivos en `flags`. `meta` trae `requested`, `found`, `cost`, `truncated` y `summary`. Hasta 1.000 NIF por llamada; con `vat` (lotes de hasta 20) comprueba también el NIF-IVA en VIES. Cobra 1 consulta por sociedad encontrada: los NIF inválidos, de personas o que no constan no se cobran; si no te llega el saldo, las filas que no caben vuelven con `processed: false`. No sustituye la comprobación contra el censo de la AEAT.
115
- Los tipos `VerifyBatchItem`, `VerifyBatchRow` y `VerifyBatchMeta` se exportan desde el paquete.
116
-
117
- ### Segmentos de empresas
118
-
119
- ```typescript
120
- const total = await api.companies.count({ cnae: ['62'], province: 'MADRID', has_phone: true }); // gratis
121
- const { data, meta } = await api.companies.filter({ cnae: ['62'], province: 'MADRID', limit: 100 }); // Business: 5 consultas por fila
122
- // Siguiente página: api.companies.filter({ ...mismosFiltros, cursor: meta.next_cursor })
123
- ```
124
-
125
- ### 6. Vigilancia de empresas (Pro: 100, Business: 1.000) — sin coste
126
-
127
- ```typescript
128
- await api.watchlist.add(['A46103834', 'A28015865']);
129
- const { data: vigiladas, meta } = await api.watchlist.list(); // meta.watch_limit
130
- const { data: cambios } = await api.watchlist.events({ since: '2026-09-01', types: ['borme_act', 'status_change'] });
131
- await api.watchlist.remove('A28015865');
132
- ```
133
-
134
- ### 7. Webhooks (Business)
135
-
136
- ```typescript
137
- const hook = await api.webhooks.create({ url: 'https://tu-servidor.com/apiempresas', event: 'watchlist.*' });
138
-
139
- // (1.5.0) Sociedades nuevas del BORME del día, con filtros opcionales
140
- const nuevas = await api.webhooks.create({
141
- url: 'https://tu-servidor.com/nuevas',
142
- event: 'company.created',
143
- filters: { province: ['MADRID', 'BARCELONA'], keywords: ['software', 'informática'], min_capital: 3000 }
144
- });
145
- // Guarda hook.secret: con él se comprueba la firma.
146
- await api.webhooks.test(hook.id); // envía un test.ping y devuelve lo que respondió tu servidor
147
-
148
- // Historial de entregas (lo más reciente primero): estado, intentos, código HTTP y error
149
- const { data, meta } = await api.webhooks.deliveries(hook.id, { status: 'dead', limit: 20 });
150
- ```
151
-
152
- En tu servidor, comprueba la firma con el cuerpo **en bruto** (no el JSON ya parseado):
153
-
154
- ```typescript
155
- import express from 'express';
156
- import { constructWebhookEvent } from 'apiempresas';
157
-
158
- app.post('/apiempresas', express.raw({ type: 'application/json' }), (req, res) => {
159
- try {
160
- const evento = constructWebhookEvent(req.body, req.header('X-ApiEmpresas-Signature'), process.env.APIEMPRESAS_WEBHOOK_SECRET!);
161
- // evento.event: company.created | company.borme_act | company.status_changed | company.risk_level_changed | test.ping
162
- // Usa evento.id (o la cabecera X-ApiEmpresas-Delivery) para no procesar dos veces el mismo envío.
163
- res.sendStatus(200);
164
- } catch {
165
- res.sendStatus(400);
166
- }
167
- });
168
- ```
169
-
170
- Si tu servidor no responde 2xx, se reintenta a los 1 min, 5 min, 30 min, 2 h y 6 h.
171
-
172
- ### 8. Licitaciones públicas abiertas (Business) — 1 consulta
173
-
174
- ```typescript
175
- // Concursos en plazo: Plataforma de Contratación del Sector Público y plataformas autonómicas
176
- const { tenders, pagination } = await api.tenders.list({ q: 'limpieza', province: 'Madrid', type: 'services' });
177
- console.log(pagination.total, tenders[0].title, tenders[0].deadline, tenders[0].url);
178
-
179
- // Las parecidas a los contratos que una empresa ya ha ganado (ordenadas por match_score)
180
- const forCompany = await api.tenders.forCompany('A82018474');
181
- ```
182
-
183
- ### 9. Listas de sanciones (Business) — 1 consulta
184
-
185
- ```typescript
186
- // Una empresa y sus administradores vigentes, en las listas de la UE, la ONU y OFAC
187
- const r = await api.sanctions.screen({ cif: 'A46103834' });
188
- console.log(r.summary.result); // 'clear' | 'possible_match' | 'match'
189
-
190
- // Un nombre suelto
191
- const p = await api.sanctions.screen({ name: 'Vladimir Putin', type: 'person' });
192
- // Cada coincidencia trae level (strong | possible), list, programs, countries y birth_dates para confirmarla
193
- ```
194
-
195
- En `companies.verify()` con Business, el resultado incluye `checks.sanctions`.
196
-
197
- ### 10. Subvenciones y ayudas públicas (Business, desde 1.5.0) — 1 consulta
198
-
199
- ```typescript
200
- // Concesiones de la BDNS desde 2022 (Kit Digital incluido)
201
- const s = await api.companies.subsidies('B12345678', { year: 2025, limit: 50 });
202
- console.log(s.summary.total_grants, s.summary.total_amount); // importes en texto con dos decimales
203
- console.log(s.summary.by_year, s.summary.top_calls);
204
- for (const g of s.grants) console.log(g.grant_date, g.amount, g.call);
205
- ```
206
-
207
- ### 11. Feed de cambios (Business, desde 1.5.0) — 1 consulta por página
208
-
209
- ```typescript
210
- // Todas las sociedades con un acto en el BORME desde una fecha (hasta 30 días atrás)
211
- const { data, meta } = await api.companies.changes({ since: '2026-10-19', types: ['address', 'officers'], province: 'MADRID' });
212
- // Siguiente página: api.companies.changes({ ...mismosFiltros, cursor: meta.next_cursor })
213
-
214
- // O recorre todas las páginas
215
- for await (const c of api.companies.iterateChanges({ since: '2026-10-19' })) {
216
- console.log(c.id, c.cif, c.change_types, c.status_code); // usa c.id para no procesar dos veces el mismo cambio
217
- }
218
- ```
219
-
220
- Solo salen sociedades con CIF: las recién constituidas todavía no lo tienen y llegan por el webhook `company.created`. Los tipos de cambio están en `catalog().change_types`.
221
-
222
- ### 12. Estadísticas del BORME (todos los planes, desde 1.5.0) — 1 consulta
223
-
224
- ```typescript
225
- const st = await api.stats({ metrics: ['incorporations', 'dissolutions'], province: 'MADRID', from: '2025-01', to: '2025-12' });
226
- console.log(st.totals.incorporations);
227
- for (const fila of st.series) console.log(fila.period, fila.incorporations);
228
- // Por años: api.stats({ group: 'year', from: '2015', to: '2025' })
229
- ```
230
-
231
- ## Entorno de Pruebas (Sandbox)
232
-
233
- Para probar la integración sin consumir saldo, apunta a la URL del Sandbox con tu misma API Key. Devuelve datos simulados: `A15075062` (empresa encontrada) y `B00000000` (no encontrada). Tiene también `subsidies()` y `changes()`; `stats()` y `usage()` no.
234
-
235
- ```typescript
236
- const api = new ApiEmpresas({
237
- apiKey: 'TU_API_KEY',
238
- baseURL: 'https://apiempresas.es/api/sandbox/v1'
239
- });
240
- ```
241
-
242
- ## Consumo
243
-
244
- ```typescript
245
- const u = await api.usage(); // no gasta consultas; no está en el Sandbox
246
- console.log(u.stats.remaining_calls, u.stats.wallet_balance, u.stats.quota_resets_at);
247
- ```
248
-
249
- ## Valores de los filtros
250
-
251
- ```typescript
252
- const cat = await api.catalog(); // no gasta consultas; también en el Sandbox
253
- console.log(cat.province, cat.size_band, cat.radar.priority, cat.webhook_events, cat.change_types);
254
- ```
255
-
256
- ## Manejo de Errores
257
-
258
- El SDK arrojará un `ApiError` detallado si ocurre algún problema (ej. Plan Insuficiente, CIF inválido).
259
-
260
- ```typescript
261
- import { ApiError } from 'apiempresas';
262
-
263
- try {
264
- await api.companies.score('B00000000');
265
- } catch (error) {
266
- if (error instanceof ApiError) {
267
- console.error(`Status: ${error.status}`);
268
- console.error(`Message: ${error.message}`);
269
- console.error(`Code: ${error.code}`); // p. ej. QUOTA_EXCEEDED, TOO_MANY_REQUESTS, API_KEY_INVALID
270
- console.error(`Request: ${error.requestId}`); // dáselo a soporte
271
- console.error(`Retry after: ${error.retryAfter}`); // segundos, en los 429 por velocidad
272
- console.error(`Plan: ${error.requiredPlan} ${error.checkoutUrl}`); // en los 403 de plan
273
- }
274
- }
275
- ```
276
-
277
- Un `429` con `code: 'TOO_MANY_REQUESTS'` se resuelve esperando y reintentando; con `code: 'QUOTA_EXCEEDED'` no: hay que recargar saldo o cambiar de plan. `errorCode` sigue devolviendo el campo `error` de la respuesta, como en versiones anteriores.
278
-
279
- ## Licencia
280
- MIT
1
+ # APIEmpresas.es - Node.js SDK
2
+
3
+ > **English:** official Node.js/TypeScript SDK for the Spanish company data API (CIF lookup, KYB, directors, BORME filings). English documentation and free API key (100 requests, no card) at [spaincompanyapi.com](https://spaincompanyapi.com/docs).
4
+
5
+ SDK oficial para interactuar con la API de [APIEmpresas.es](https://apiempresas.es) desde Node.js utilizando TypeScript o JavaScript.
6
+
7
+ ## Instalación
8
+
9
+ ```bash
10
+ npm install apiempresas
11
+ ```
12
+
13
+ ## Inicialización
14
+
15
+ ```typescript
16
+ import { ApiEmpresas } from 'apiempresas';
17
+
18
+ const api = new ApiEmpresas({
19
+ apiKey: 'TU_API_KEY', // Obligatorio
20
+ });
21
+ ```
22
+
23
+ ## Uso Básico
24
+
25
+ ### 1. Obtener datos de una empresa
26
+
27
+ ```typescript
28
+ async function fetchCompany() {
29
+ try {
30
+ const company = await api.companies.get('A15075062');
31
+ console.log(company.name);
32
+ } catch (error) {
33
+ console.error('Error fetching company:', error.message);
34
+ }
35
+ }
36
+ ```
37
+
38
+ ### 2. Historial de Actos del BORME
39
+
40
+ ```typescript
41
+ async function fetchBorme() {
42
+ const bormeData = await api.companies.borme('A15075062');
43
+ console.log(bormeData.events);
44
+ }
45
+ ```
46
+
47
+ ### 3. Consulta Múltiple (Batch)
48
+
49
+ ```typescript
50
+ async function fetchBatch() {
51
+ const response = await api.companies.batch({
52
+ cifs: ['A15075062', 'A46103834']
53
+ });
54
+ console.log('Resultados:', response.data);
55
+ console.log('Coste:', response.meta.cost);
56
+ }
57
+ ```
58
+
59
+ ### 4. Administradores, búsqueda con varios resultados, Match y Radar
60
+
61
+ ```typescript
62
+ // Administradores y cargos (Pro/Business)
63
+ const conAdmins = await api.companies.get('A15075062', { admin: true });
64
+
65
+ // Varias empresas por nombre, con paginación
66
+ let pagina = await api.companies.searchMultiple('software', { limit: 20 });
67
+ while (pagina.meta.next_cursor) {
68
+ pagina = await api.companies.searchMultiple('software', { cursor: pagina.meta.next_cursor });
69
+ }
70
+
71
+ // Match (Business): el sector del vendedor es obligatorio
72
+ const match = await api.companies.match('A15075062', 'software');
73
+
74
+ // Radar de empresas nuevas (todos los planes: 10 resultados en Free con nombre y CIF ocultos, 100 en Pro, 1.000 en Business). range: 'hoy' (por defecto) o días atrás ('7', '30')
75
+ const nuevas = await api.companies.radar({ province: 'Madrid', range: '7' });
76
+ // Filtros añadidos en 1.2.0: cnae, min_score, main_act_type, has_phone
77
+ const software = await api.companies.radar({ cnae: '62', min_score: 70, has_phone: true });
78
+ ```
79
+
80
+ Requiere Node.js 18 o superior (usa `fetch` nativo).
81
+
82
+ ### 5. Verificación KYB (Pro) — 2 consultas
83
+
84
+ ```typescript
85
+ const v = await api.companies.verify('A46103834', {
86
+ name: 'Mercadona SA', // se compara con la razón social
87
+ person: 'Juan Roig Alfonso', // ¿es administrador vigente?
88
+ vat: true, // NIF-IVA en VIES
89
+ iban: 'ES9121000418450200051332' // (1.5.0) ¿está bien formado? No dice de quién es la cuenta
90
+ });
91
+ console.log(v.decision_hint); // 'pass' | 'review' | 'fail'
92
+ console.log(v.flags); // alertas con code, severity y message
93
+ ```
94
+
95
+ Cada empresa trae además `status_code` (ACTIVE, INSOLVENCY, EXTINCT...), `status_source`, `status_date` y, en Pro/Business, `financials` (tramo de tamaño y último año de cuentas). Los administradores traen `since`. Desde la 1.3.0 la respuesta lleva también `identifiers` (código LEI) y `legal_form` (forma jurídica con su código ISO 20275) en todos los planes, y en Pro/Business `group` (matriz directa y última según GLEIF) y `ownership` (socio único según el BORME). En `verify`, con `person`, `checks.person.is_sole_shareholder` dice si quien firma es el socio único. Desde la 1.5.0, en Pro/Business, `size` (tramo de empleados con su fuente: Kit Digital, TED o PLACSP; null si no consta) y `address_density` (cuántas sociedades activas comparten la dirección exacta), y en `verify` con `iban`, `checks.iban` (si no es válido, alerta `IBAN_INVALID` y `decision_hint` review). `filter()` admite `size_category` (micro, small, medium, large). Desde la 1.7.0 (tipos), en todos los planes, `status_confidence` (`high`, `medium` o `low`; null si UNKNOWN) y `status_confidence_reasons`: cuánto fiarse de `status_code` y por qué. También en `verify` y en `verifyBatch`; no cambian `decision_hint` ni `invoice_hint`. Desde la 1.8.0 (tipos), en todos los planes, `tax_id_revocation` (tipo `TaxIdRevocation`): si la Agencia Tributaria ha revocado (`REVOKED`) o rehabilitado (`REHABILITATED`) el NIF según el BOE, con fecha y enlace; null si nunca se ha publicado. Un NIF revocado da la alerta `TAX_ID_REVOKED` y `decision_hint: fail` en `verify`, e `invoice_hint: no_facturar` en `verifyBatch`.
96
+
97
+ ### Nombre a CIF (Pro)
98
+
99
+ ```typescript
100
+ const { data, meta } = await api.companies.reconcile(['Mercadona', { name: 'Talleres Pérez', province: 'Madrid' }]);
101
+ // data[i].status: match (con company.cif) | ambiguous (candidates) | no_match. Solo se cobran los match.
102
+ ```
103
+
104
+ ### Validar el NIF de tus clientes antes de facturar (Pro, Business o saldo; desde 1.6.0)
105
+
106
+ ```typescript
107
+ const { data, meta } = await api.companies.verifyBatch([
108
+ { cif: 'A46103834', name: 'Mercadona', ref: 'cliente-0001' }, // name: la razón social que tienes guardada
109
+ { cif: 'A15075062', name: 'Inditex', ref: 'cliente-0002' }, // ref: tu identificador, vuelve tal cual
110
+ 'B12345674', // o el NIF suelto
111
+ ]);
112
+ data.forEach((fila) => console.log(fila.input, fila.invoice_hint)); // 'ok' | 'revisar' | 'no_facturar'
113
+ // await api.companies.verifyBatch(['A46103834'], { vat: true }); // también VIES
114
+ ```
115
+
116
+ Por cada NIF, en el mismo orden: `valid_format`, `exists`, `legal_name`, `address`, `status_code`, `name_check` (si das `name`) e `invoice_hint` (`ok`, `revisar` o `no_facturar`) con sus motivos en `flags`. `meta` trae `requested`, `found`, `cost`, `truncated` y `summary`. Hasta 1.000 NIF por llamada; con `vat` (lotes de hasta 20) comprueba también el NIF-IVA en VIES. Cobra 1 consulta por sociedad encontrada: los NIF inválidos, de personas o que no constan no se cobran; si no te llega el saldo, las filas que no caben vuelven con `processed: false`. No sustituye la comprobación contra el censo de la AEAT.
117
+ Los tipos `VerifyBatchItem`, `VerifyBatchRow` y `VerifyBatchMeta` se exportan desde el paquete.
118
+
119
+ ### Segmentos de empresas
120
+
121
+ ```typescript
122
+ const total = await api.companies.count({ cnae: ['62'], province: 'MADRID', has_phone: true }); // gratis
123
+ const { data, meta } = await api.companies.filter({ cnae: ['62'], province: 'MADRID', limit: 100 }); // Business: 5 consultas por fila
124
+ // Siguiente página: api.companies.filter({ ...mismosFiltros, cursor: meta.next_cursor })
125
+ ```
126
+
127
+ ### 6. Vigilancia de empresas (Pro: 100, Business: 1.000) — sin coste
128
+
129
+ ```typescript
130
+ await api.watchlist.add(['A46103834', 'A28015865']);
131
+ const { data: vigiladas, meta } = await api.watchlist.list(); // meta.watch_limit
132
+ const { data: cambios } = await api.watchlist.events({ since: '2026-09-01', types: ['borme_act', 'status_change'] });
133
+ await api.watchlist.remove('A28015865');
134
+ ```
135
+
136
+ ### 7. Webhooks (Business)
137
+
138
+ ```typescript
139
+ const hook = await api.webhooks.create({ url: 'https://tu-servidor.com/apiempresas', event: 'watchlist.*' });
140
+
141
+ // (1.5.0) Sociedades nuevas del BORME del día, con filtros opcionales
142
+ const nuevas = await api.webhooks.create({
143
+ url: 'https://tu-servidor.com/nuevas',
144
+ event: 'company.created',
145
+ filters: { province: ['MADRID', 'BARCELONA'], keywords: ['software', 'informática'], min_capital: 3000 }
146
+ });
147
+ // Guarda hook.secret: con él se comprueba la firma.
148
+ await api.webhooks.test(hook.id); // envía un test.ping y devuelve lo que respondió tu servidor
149
+
150
+ // Historial de entregas (lo más reciente primero): estado, intentos, código HTTP y error
151
+ const { data, meta } = await api.webhooks.deliveries(hook.id, { status: 'dead', limit: 20 });
152
+ ```
153
+
154
+ En tu servidor, comprueba la firma con el cuerpo **en bruto** (no el JSON ya parseado):
155
+
156
+ ```typescript
157
+ import express from 'express';
158
+ import { constructWebhookEvent } from 'apiempresas';
159
+
160
+ app.post('/apiempresas', express.raw({ type: 'application/json' }), (req, res) => {
161
+ try {
162
+ const evento = constructWebhookEvent(req.body, req.header('X-ApiEmpresas-Signature'), process.env.APIEMPRESAS_WEBHOOK_SECRET!);
163
+ // evento.event: company.created | company.borme_act | company.status_changed | company.risk_level_changed | test.ping
164
+ // Usa evento.id (o la cabecera X-ApiEmpresas-Delivery) para no procesar dos veces el mismo envío.
165
+ res.sendStatus(200);
166
+ } catch {
167
+ res.sendStatus(400);
168
+ }
169
+ });
170
+ ```
171
+
172
+ Si tu servidor no responde 2xx, se reintenta a los 1 min, 5 min, 30 min, 2 h y 6 h.
173
+
174
+ ### 8. Licitaciones públicas abiertas (Business) — 1 consulta
175
+
176
+ ```typescript
177
+ // Concursos en plazo: Plataforma de Contratación del Sector Público y plataformas autonómicas
178
+ const { tenders, pagination } = await api.tenders.list({ q: 'limpieza', province: 'Madrid', type: 'services' });
179
+ console.log(pagination.total, tenders[0].title, tenders[0].deadline, tenders[0].url);
180
+
181
+ // Las parecidas a los contratos que una empresa ya ha ganado (ordenadas por match_score)
182
+ const forCompany = await api.tenders.forCompany('A82018474');
183
+ ```
184
+
185
+ ### 9. Listas de sanciones (Business) — 1 consulta
186
+
187
+ ```typescript
188
+ // Una empresa y sus administradores vigentes, en las listas de la UE, la ONU y OFAC
189
+ const r = await api.sanctions.screen({ cif: 'A46103834' });
190
+ console.log(r.summary.result); // 'clear' | 'possible_match' | 'match'
191
+
192
+ // Un nombre suelto
193
+ const p = await api.sanctions.screen({ name: 'Vladimir Putin', type: 'person' });
194
+ // Cada coincidencia trae level (strong | possible), list, programs, countries y birth_dates para confirmarla
195
+ ```
196
+
197
+ En `companies.verify()` con Business, el resultado incluye `checks.sanctions`.
198
+
199
+ ### 10. Subvenciones y ayudas públicas (Business, desde 1.5.0) — 1 consulta
200
+
201
+ ```typescript
202
+ // Concesiones de la BDNS desde 2022 (Kit Digital incluido)
203
+ const s = await api.companies.subsidies('B12345678', { year: 2025, limit: 50 });
204
+ console.log(s.summary.total_grants, s.summary.total_amount); // importes en texto con dos decimales
205
+ console.log(s.summary.by_year, s.summary.top_calls);
206
+ for (const g of s.grants) console.log(g.grant_date, g.amount, g.call);
207
+ ```
208
+
209
+ ### 11. Feed de cambios (Business, desde 1.5.0) — 1 consulta por página
210
+
211
+ ```typescript
212
+ // Todas las sociedades con un acto en el BORME desde una fecha (hasta 30 días atrás)
213
+ const { data, meta } = await api.companies.changes({ since: '2026-10-19', types: ['address', 'officers'], province: 'MADRID' });
214
+ // Siguiente página: api.companies.changes({ ...mismosFiltros, cursor: meta.next_cursor })
215
+
216
+ // O recorre todas las páginas
217
+ for await (const c of api.companies.iterateChanges({ since: '2026-10-19' })) {
218
+ console.log(c.id, c.cif, c.change_types, c.status_code); // usa c.id para no procesar dos veces el mismo cambio
219
+ }
220
+ ```
221
+
222
+ Solo salen sociedades con CIF: las recién constituidas todavía no lo tienen y llegan por el webhook `company.created`. Los tipos de cambio están en `catalog().change_types`.
223
+
224
+ ### 12. Estadísticas del BORME (todos los planes, desde 1.5.0) — 1 consulta
225
+
226
+ ```typescript
227
+ const st = await api.stats({ metrics: ['incorporations', 'dissolutions'], province: 'MADRID', from: '2025-01', to: '2025-12' });
228
+ console.log(st.totals.incorporations);
229
+ for (const fila of st.series) console.log(fila.period, fila.incorporations);
230
+ // Por años: api.stats({ group: 'year', from: '2015', to: '2025' })
231
+ ```
232
+
233
+ ## Entorno de Pruebas (Sandbox)
234
+
235
+ Para probar la integración sin consumir saldo, apunta a la URL del Sandbox con tu misma API Key. Devuelve datos simulados: `A15075062` (empresa encontrada) y `B00000000` (no encontrada). Tiene también `subsidies()` y `changes()`; `stats()` y `usage()` no.
236
+
237
+ ```typescript
238
+ const api = new ApiEmpresas({
239
+ apiKey: 'TU_API_KEY',
240
+ baseURL: 'https://apiempresas.es/api/sandbox/v1'
241
+ });
242
+ ```
243
+
244
+ ## Consumo
245
+
246
+ ```typescript
247
+ const u = await api.usage(); // no gasta consultas; no está en el Sandbox
248
+ console.log(u.stats.remaining_calls, u.stats.wallet_balance, u.stats.quota_resets_at);
249
+ ```
250
+
251
+ ## Valores de los filtros
252
+
253
+ ```typescript
254
+ const cat = await api.catalog(); // no gasta consultas; también en el Sandbox
255
+ console.log(cat.province, cat.size_band, cat.radar.priority, cat.webhook_events, cat.change_types);
256
+ ```
257
+
258
+ ## Manejo de Errores
259
+
260
+ El SDK arrojará un `ApiError` detallado si ocurre algún problema (ej. Plan Insuficiente, CIF inválido).
261
+
262
+ ```typescript
263
+ import { ApiError } from 'apiempresas';
264
+
265
+ try {
266
+ await api.companies.score('B00000000');
267
+ } catch (error) {
268
+ if (error instanceof ApiError) {
269
+ console.error(`Status: ${error.status}`);
270
+ console.error(`Message: ${error.message}`);
271
+ console.error(`Code: ${error.code}`); // p. ej. QUOTA_EXCEEDED, TOO_MANY_REQUESTS, API_KEY_INVALID
272
+ console.error(`Request: ${error.requestId}`); // dáselo a soporte
273
+ console.error(`Retry after: ${error.retryAfter}`); // segundos, en los 429 por velocidad
274
+ console.error(`Plan: ${error.requiredPlan} ${error.checkoutUrl}`); // en los 403 de plan
275
+ }
276
+ }
277
+ ```
278
+
279
+ Un `429` con `code: 'TOO_MANY_REQUESTS'` se resuelve esperando y reintentando; con `code: 'QUOTA_EXCEEDED'` no: hay que recargar saldo o cambiar de plan. `errorCode` sigue devolviendo el campo `error` de la respuesta, como en versiones anteriores.
280
+
281
+ ## Licencia
282
+ MIT
package/dist/types.d.ts CHANGED
@@ -46,6 +46,16 @@ export interface Company {
46
46
  status_source?: string | null;
47
47
  /** Fecha del hecho que fija el estado (YYYY-MM-DD). */
48
48
  status_date?: string | null;
49
+ /** Todos los planes (desde 1.7.0): cuánto fiarse de status_code. null si UNKNOWN. No cambia el estado. */
50
+ status_confidence?: StatusConfidence | null;
51
+ /** Motivos de status_confidence (RECENT_REGISTRY_ACT, OLD_INSOLVENCY, ACTIVITY_AFTER_STATUS...). */
52
+ status_confidence_reasons?: StatusConfidenceReason[];
53
+ /**
54
+ * Todos los planes (desde 1.8.0): revocación o rehabilitación del NIF por la Agencia Tributaria publicada
55
+ * en el BOE. null si el BOE nunca ha publicado nada de ese NIF. Con status REVOKED el NIF no vale ante
56
+ * Hacienda y los bancos no pueden hacerle cobros ni pagos.
57
+ */
58
+ tax_id_revocation?: TaxIdRevocation | null;
49
59
  /** Pro/Business: tramo de tamaño y año de las últimas cuentas vistas. */
50
60
  financials?: CompanyFinancials | null;
51
61
  /** Todos los planes (desde 1.3.0): código LEI de GLEIF. */
@@ -77,6 +87,22 @@ export interface Company {
77
87
  };
78
88
  }
79
89
  export type StatusCode = 'ACTIVE' | 'PRESUMED_ACTIVE' | 'INSOLVENCY' | 'IN_LIQUIDATION' | 'DISSOLVED' | 'REGISTRY_CLOSED' | 'MERGED' | 'INACTIVE' | 'EXTINCT' | 'UNKNOWN';
90
+ /** (desde 1.7.0) */
91
+ export type StatusConfidence = 'high' | 'medium' | 'low';
92
+ /** (desde 1.7.0) Motivos de status_confidence. Pueden aparecer otros nuevos: trátalo como string. */
93
+ export type StatusConfidenceReason = 'RECENT_REGISTRY_ACT' | 'NO_RECENT_REGISTRY_ACT' | 'DATED_REGISTRY_EVENT' | 'NO_STATUS_DATE' | 'OLD_INSOLVENCY' | 'ACTIVITY_AFTER_STATUS' | 'REVERSIBLE_STATUS' | 'PRESUMED_STATUS' | 'NOT_FROM_COMMERCIAL_REGISTRY' | (string & {});
94
+ /** (desde 1.8.0) NIF revocado o rehabilitado por la Agencia Tributaria (BOE). */
95
+ export interface TaxIdRevocation {
96
+ /** REVOKED: revocado. REHABILITATED: revocado y después rehabilitado. */
97
+ status: 'REVOKED' | 'REHABILITATED';
98
+ /** Fecha del BOE (YYYY-MM-DD). */
99
+ date: string | null;
100
+ /** Identificador del anuncio, p. ej. BOE-A-2026-12345. */
101
+ boe_id: string | null;
102
+ /** Enlace al anuncio en boe.es. */
103
+ boe_url: string | null;
104
+ source: 'boe';
105
+ }
80
106
  export interface CompanyIdentifiers {
81
107
  lei: string | null;
82
108
  /** Estado del LEI en GLEIF: ISSUED, LAPSED, RETIRED... */
@@ -180,6 +206,11 @@ export interface VerifyResult {
180
206
  status_code: StatusCode | null;
181
207
  status_source: string | null;
182
208
  status_date: string | null;
209
+ /** (desde 1.7.0) Igual que en Company. Informativo: no cambia decision_hint. */
210
+ status_confidence?: StatusConfidence | null;
211
+ status_confidence_reasons?: StatusConfidenceReason[];
212
+ /** (desde 1.8.0) Igual que en Company. Con REVOKED: alerta TAX_ID_REVOKED (critical) y decision_hint fail. */
213
+ tax_id_revocation?: TaxIdRevocation | null;
183
214
  identifiers?: CompanyIdentifiers;
184
215
  legal_form?: CompanyLegalForm;
185
216
  group?: CompanyGroup | null;
@@ -826,7 +857,8 @@ export interface VerifyBatchOptions {
826
857
  export type InvoiceHint = 'ok' | 'revisar' | 'no_facturar';
827
858
  export interface VerifyBatchFlag {
828
859
  /** EXTINCT, MERGED, INSOLVENCY, DISSOLVED, IN_LIQUIDATION, REGISTRY_CLOSED, INACTIVE, STATUS_UNKNOWN,
829
- * NAME_MISMATCH, VAT_NOT_IN_VIES, PERSON_NIF, FAKE_CIF, NOT_FOUND, INVALID_FORMAT, NOT_PROCESSED_QUOTA. */
860
+ * NAME_MISMATCH, VAT_NOT_IN_VIES, PERSON_NIF, FAKE_CIF, NOT_FOUND, INVALID_FORMAT, NOT_PROCESSED_QUOTA,
861
+ * TAX_ID_REVOKED (desde 1.8.0). */
830
862
  code: string;
831
863
  severity: 'info' | 'low' | 'medium' | 'high';
832
864
  message: string;
@@ -853,6 +885,11 @@ export interface VerifyBatchRow {
853
885
  /** ACTIVE, INSOLVENCY, DISSOLVED, IN_LIQUIDATION, EXTINCT, MERGED, REGISTRY_CLOSED, INACTIVE, UNKNOWN... */
854
886
  status_code?: string;
855
887
  status_date?: string | null;
888
+ /** (desde 1.7.0) Igual que en Company. Informativo: no cambia invoice_hint. */
889
+ status_confidence?: StatusConfidence | null;
890
+ status_confidence_reasons?: StatusConfidenceReason[];
891
+ /** (desde 1.8.0) Igual que en Company. Con REVOKED: alerta TAX_ID_REVOKED e invoice_hint no_facturar. */
892
+ tax_id_revocation?: TaxIdRevocation | null;
856
893
  /** Solo si enviaste name: parecido 0-100 y si coincide (desde 80). */
857
894
  name_check?: {
858
895
  provided: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apiempresas",
3
- "version": "1.6.1",
3
+ "version": "1.8.0",
4
4
  "description": "SDK oficial de APIEmpresas.es para Node.js y TypeScript",
5
5
  "main": "dist/index.js",
6
6
  "files": [