apiempresas 1.6.0 → 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.
- package/README.md +282 -280
- package/dist/ApiEmpresas.d.ts +1 -1
- package/dist/ApiEmpresas.js +1 -1
- package/dist/resources/Watchlist.d.ts +1 -1
- package/dist/resources/Watchlist.js +1 -1
- package/dist/types.d.ts +45 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,280 +1,282 @@
|
|
|
1
|
-
# APIEmpresas.es - Node.js SDK
|
|
2
|
-
|
|
3
|
-
SDK
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
console.
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
//
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
'
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
await api.watchlist.
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
res.sendStatus(
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
//
|
|
191
|
-
|
|
192
|
-
//
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
//
|
|
213
|
-
|
|
214
|
-
//
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
console.error(`
|
|
270
|
-
console.error(`
|
|
271
|
-
console.error(`
|
|
272
|
-
console.error(`
|
|
273
|
-
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
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/ApiEmpresas.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { Tenders } from './resources/Tenders';
|
|
|
6
6
|
import { Sanctions } from './resources/Sanctions';
|
|
7
7
|
import { verifyWebhookSignature, constructWebhookEvent } from './webhooks/signature';
|
|
8
8
|
/** Versión del SDK, enviada en el User-Agent. */
|
|
9
|
-
export declare const SDK_VERSION = "1.6.
|
|
9
|
+
export declare const SDK_VERSION = "1.6.1";
|
|
10
10
|
export declare class ApiEmpresas {
|
|
11
11
|
private apiKey;
|
|
12
12
|
private baseURL;
|
package/dist/ApiEmpresas.js
CHANGED
|
@@ -9,7 +9,7 @@ const Tenders_1 = require("./resources/Tenders");
|
|
|
9
9
|
const Sanctions_1 = require("./resources/Sanctions");
|
|
10
10
|
const signature_1 = require("./webhooks/signature");
|
|
11
11
|
/** Versión del SDK, enviada en el User-Agent. */
|
|
12
|
-
exports.SDK_VERSION = '1.6.
|
|
12
|
+
exports.SDK_VERSION = '1.6.1';
|
|
13
13
|
/**
|
|
14
14
|
* Mensaje legible del cuerpo de error. Según el error, la API lo pone en
|
|
15
15
|
* message, detail, error (texto) o messages (errores de validación).
|
|
@@ -29,7 +29,7 @@ export declare class Watchlist {
|
|
|
29
29
|
}>;
|
|
30
30
|
/**
|
|
31
31
|
* Cambios en las empresas vigiladas desde una fecha (borme_act, status_change,
|
|
32
|
-
* risk_level_change), de más antiguo a más reciente.
|
|
32
|
+
* risk_level_change e insolvency), de más antiguo a más reciente.
|
|
33
33
|
*/
|
|
34
34
|
events(options?: WatchlistEventsOptions): Promise<{
|
|
35
35
|
data: WatchlistEvent[];
|
|
@@ -41,7 +41,7 @@ class Watchlist {
|
|
|
41
41
|
}
|
|
42
42
|
/**
|
|
43
43
|
* Cambios en las empresas vigiladas desde una fecha (borme_act, status_change,
|
|
44
|
-
* risk_level_change), de más antiguo a más reciente.
|
|
44
|
+
* risk_level_change e insolvency), de más antiguo a más reciente.
|
|
45
45
|
*/
|
|
46
46
|
async events(options = {}) {
|
|
47
47
|
const params = new URLSearchParams();
|
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;
|
|
@@ -317,7 +348,10 @@ export interface SegmentMeta {
|
|
|
317
348
|
truncated: boolean;
|
|
318
349
|
filters: Record<string, any>;
|
|
319
350
|
}
|
|
320
|
-
|
|
351
|
+
/** insolvency desde 1.6.1 (anuncio concursal en el BORME). */
|
|
352
|
+
export type WatchlistEventType = 'borme_act' | 'status_change' | 'risk_level_change' | 'insolvency';
|
|
353
|
+
/** Fase del concurso en los eventos insolvency (data.stage). */
|
|
354
|
+
export type InsolvencyStage = 'filed' | 'declared' | 'restructuring' | 'agreement' | 'liquidation' | 'classification' | 'concluded' | 'reopened' | 'enforcement_insolvency' | 'other';
|
|
321
355
|
export interface WatchlistEvent {
|
|
322
356
|
/** Estable: úsalo para no procesar dos veces el mismo evento. */
|
|
323
357
|
id: string;
|
|
@@ -326,7 +360,8 @@ export interface WatchlistEvent {
|
|
|
326
360
|
company_name?: string | null;
|
|
327
361
|
date: string;
|
|
328
362
|
/** borme_act: act_types, description, url_pdf. status_change: status, status_code.
|
|
329
|
-
* risk_level_change: from, to, model_change (true/false, o null si no consta la versión del modelo).
|
|
363
|
+
* risk_level_change: from, to, model_change (true/false, o null si no consta la versión del modelo).
|
|
364
|
+
* insolvency (desde 1.6.1): stage (InsolvencyStage), status_code (estado actual), act_types, description, url_pdf. */
|
|
330
365
|
data: Record<string, any>;
|
|
331
366
|
}
|
|
332
367
|
export interface WatchlistAddResult {
|
|
@@ -351,7 +386,7 @@ export interface WatchlistEventsOptions {
|
|
|
351
386
|
page?: number;
|
|
352
387
|
limit?: number;
|
|
353
388
|
}
|
|
354
|
-
export type WebhookEvent = 'company.created' | 'company.borme_act' | 'company.status_changed' | 'company.risk_level_changed' | 'watchlist.*' | 'test.ping' | string;
|
|
389
|
+
export type WebhookEvent = 'company.created' | 'company.borme_act' | 'company.status_changed' | 'company.risk_level_changed' | 'company.insolvency' | 'watchlist.*' | 'test.ping' | string;
|
|
355
390
|
/** Filtros del evento company.created (desde 1.5.0). Sin filtros llegan todas las sociedades nuevas. */
|
|
356
391
|
export interface CompanyCreatedFilters {
|
|
357
392
|
/** Provincias del Registro Mercantil (hasta 10). Valores en catalog(). */
|
|
@@ -822,7 +857,8 @@ export interface VerifyBatchOptions {
|
|
|
822
857
|
export type InvoiceHint = 'ok' | 'revisar' | 'no_facturar';
|
|
823
858
|
export interface VerifyBatchFlag {
|
|
824
859
|
/** EXTINCT, MERGED, INSOLVENCY, DISSOLVED, IN_LIQUIDATION, REGISTRY_CLOSED, INACTIVE, STATUS_UNKNOWN,
|
|
825
|
-
* 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). */
|
|
826
862
|
code: string;
|
|
827
863
|
severity: 'info' | 'low' | 'medium' | 'high';
|
|
828
864
|
message: string;
|
|
@@ -849,6 +885,11 @@ export interface VerifyBatchRow {
|
|
|
849
885
|
/** ACTIVE, INSOLVENCY, DISSOLVED, IN_LIQUIDATION, EXTINCT, MERGED, REGISTRY_CLOSED, INACTIVE, UNKNOWN... */
|
|
850
886
|
status_code?: string;
|
|
851
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;
|
|
852
893
|
/** Solo si enviaste name: parecido 0-100 y si coincide (desde 80). */
|
|
853
894
|
name_check?: {
|
|
854
895
|
provided: string;
|