apiempresas 1.5.0 → 1.6.1

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
@@ -99,6 +99,21 @@ const { data, meta } = await api.companies.reconcile(['Mercadona', { name: 'Tall
99
99
  // data[i].status: match (con company.cif) | ambiguous (candidates) | no_match. Solo se cobran los match.
100
100
  ```
101
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
+
102
117
  ### Segmentos de empresas
103
118
 
104
119
  ```typescript
@@ -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.5.0";
9
+ export declare const SDK_VERSION = "1.6.1";
10
10
  export declare class ApiEmpresas {
11
11
  private apiKey;
12
12
  private baseURL;
@@ -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.5.0';
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).
@@ -1,5 +1,5 @@
1
1
  import { ApiEmpresas } from '../ApiEmpresas';
2
- import { Company, BatchRequest, BatchResponse, ScoreData, BormeData, SignalsData, VerifyOptions, VerifyResult, FilterOptions, SegmentRow, SegmentMeta, ReconcileItem, ReconcileResult, ReconcileMeta, SubsidiesOptions, SubsidiesResult, ChangesOptions, ChangesResult, CompanyChange } from '../types';
2
+ import { Company, BatchRequest, BatchResponse, ScoreData, BormeData, SignalsData, VerifyOptions, VerifyResult, FilterOptions, SegmentRow, SegmentMeta, ReconcileItem, ReconcileResult, ReconcileMeta, SubsidiesOptions, SubsidiesResult, ChangesOptions, ChangesResult, CompanyChange, VerifyBatchItem, VerifyBatchOptions, VerifyBatchRow, VerifyBatchMeta } from '../types';
3
3
  /** Opciones de get(): admin=true añade administradores y cargos (Pro/Business). */
4
4
  export interface GetOptions {
5
5
  admin?: boolean;
@@ -36,6 +36,19 @@ export declare class Companies {
36
36
  * alertas, con decision_hint pass / review / fail. Coste: 2 consultas.
37
37
  */
38
38
  verify(cif: string, options?: VerifyOptions): Promise<VerifyResult>;
39
+ /**
40
+ * (Pro, Business o saldo; desde 1.6.0) Valida en lote el NIF de los receptores de tus facturas
41
+ * (Verifactu, factura electrónica): hasta 1.000 por petición. Cada elemento puede ser un NIF o
42
+ * { cif, name?, ref? }: name es la razón social que tienes guardada y ref tu identificador (vuelve
43
+ * tal cual). Por cada NIF, en el mismo orden: valid_format, exists, legal_name, address,
44
+ * status_code, name_check e invoice_hint ('ok', 'revisar' o 'no_facturar') con sus motivos en flags.
45
+ * Cobro: 1 consulta por sociedad encontrada; NIF inválidos, de personas o que no constan, gratis.
46
+ * No sustituye la comprobación contra el censo de la AEAT.
47
+ */
48
+ verifyBatch(items: Array<string | VerifyBatchItem>, options?: VerifyBatchOptions): Promise<{
49
+ data: VerifyBatchRow[];
50
+ meta: VerifyBatchMeta;
51
+ }>;
39
52
  /**
40
53
  * (Pro) Nombre a CIF, hasta 100 por petición. 1 consulta por cada "match";
41
54
  * ambiguous y no_match no se cobran.
@@ -47,6 +47,27 @@ class Companies {
47
47
  const response = await this.client.request(`/companies/verify?${params.toString()}`);
48
48
  return response.data;
49
49
  }
50
+ /**
51
+ * (Pro, Business o saldo; desde 1.6.0) Valida en lote el NIF de los receptores de tus facturas
52
+ * (Verifactu, factura electrónica): hasta 1.000 por petición. Cada elemento puede ser un NIF o
53
+ * { cif, name?, ref? }: name es la razón social que tienes guardada y ref tu identificador (vuelve
54
+ * tal cual). Por cada NIF, en el mismo orden: valid_format, exists, legal_name, address,
55
+ * status_code, name_check e invoice_hint ('ok', 'revisar' o 'no_facturar') con sus motivos en flags.
56
+ * Cobro: 1 consulta por sociedad encontrada; NIF inválidos, de personas o que no constan, gratis.
57
+ * No sustituye la comprobación contra el censo de la AEAT.
58
+ */
59
+ async verifyBatch(items, options = {}) {
60
+ const body = {
61
+ items: items.map((i) => (typeof i === 'string' ? { cif: i } : i)),
62
+ };
63
+ if (options.vat)
64
+ body.vat = true;
65
+ const response = await this.client.request('/companies/verify/batch', {
66
+ method: 'POST',
67
+ body: JSON.stringify(body)
68
+ });
69
+ return { data: response.data, meta: response.meta };
70
+ }
50
71
  /**
51
72
  * (Pro) Nombre a CIF, hasta 100 por petición. 1 consulta por cada "match";
52
73
  * ambiguous y no_match no se cobran.
@@ -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
@@ -317,7 +317,10 @@ export interface SegmentMeta {
317
317
  truncated: boolean;
318
318
  filters: Record<string, any>;
319
319
  }
320
- export type WatchlistEventType = 'borme_act' | 'status_change' | 'risk_level_change';
320
+ /** insolvency desde 1.6.1 (anuncio concursal en el BORME). */
321
+ export type WatchlistEventType = 'borme_act' | 'status_change' | 'risk_level_change' | 'insolvency';
322
+ /** Fase del concurso en los eventos insolvency (data.stage). */
323
+ export type InsolvencyStage = 'filed' | 'declared' | 'restructuring' | 'agreement' | 'liquidation' | 'classification' | 'concluded' | 'reopened' | 'enforcement_insolvency' | 'other';
321
324
  export interface WatchlistEvent {
322
325
  /** Estable: úsalo para no procesar dos veces el mismo evento. */
323
326
  id: string;
@@ -326,7 +329,8 @@ export interface WatchlistEvent {
326
329
  company_name?: string | null;
327
330
  date: string;
328
331
  /** 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). */
332
+ * risk_level_change: from, to, model_change (true/false, o null si no consta la versión del modelo).
333
+ * insolvency (desde 1.6.1): stage (InsolvencyStage), status_code (estado actual), act_types, description, url_pdf. */
330
334
  data: Record<string, any>;
331
335
  }
332
336
  export interface WatchlistAddResult {
@@ -351,7 +355,7 @@ export interface WatchlistEventsOptions {
351
355
  page?: number;
352
356
  limit?: number;
353
357
  }
354
- export type WebhookEvent = 'company.created' | 'company.borme_act' | 'company.status_changed' | 'company.risk_level_changed' | 'watchlist.*' | 'test.ping' | string;
358
+ export type WebhookEvent = 'company.created' | 'company.borme_act' | 'company.status_changed' | 'company.risk_level_changed' | 'company.insolvency' | 'watchlist.*' | 'test.ping' | string;
355
359
  /** Filtros del evento company.created (desde 1.5.0). Sin filtros llegan todas las sociedades nuevas. */
356
360
  export interface CompanyCreatedFilters {
357
361
  /** Provincias del Registro Mercantil (hasta 10). Valores en catalog(). */
@@ -807,3 +811,79 @@ export interface StatsResult {
807
811
  notes: string;
808
812
  };
809
813
  }
814
+ export interface VerifyBatchItem {
815
+ /** NIF del cliente (CIF, DNI o NIE). */
816
+ cif: string;
817
+ /** Razón social que tienes guardada: se compara con la oficial (name_check). */
818
+ name?: string;
819
+ /** Tu identificador (id de cliente...): se devuelve tal cual. */
820
+ ref?: string;
821
+ }
822
+ export interface VerifyBatchOptions {
823
+ /** Comprobar también el NIF-IVA en VIES (solo lotes de hasta 20). */
824
+ vat?: boolean;
825
+ }
826
+ export type InvoiceHint = 'ok' | 'revisar' | 'no_facturar';
827
+ export interface VerifyBatchFlag {
828
+ /** 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. */
830
+ code: string;
831
+ severity: 'info' | 'low' | 'medium' | 'high';
832
+ message: string;
833
+ }
834
+ export interface VerifyBatchRow {
835
+ /** Lo que enviaste, sin tocar. */
836
+ input: string;
837
+ /** NIF normalizado (sin espacios, guiones ni prefijo ES); null si no se reconoce. */
838
+ cif: string | null;
839
+ ref?: string;
840
+ /** Dígito o letra de control correctos (CIF, DNI y NIE). */
841
+ valid_format: boolean;
842
+ /** false si no se ha comprobado por falta de cupo o saldo (flag NOT_PROCESSED_QUOTA; no se cobra). */
843
+ processed: boolean;
844
+ /** true/false si es una sociedad; null si es una persona física, el formato no es válido o no se ha procesado. */
845
+ exists: boolean | null;
846
+ legal_name?: string | null;
847
+ address?: {
848
+ street: string | null;
849
+ postal_code: string | null;
850
+ municipality: string | null;
851
+ province: string | null;
852
+ };
853
+ /** ACTIVE, INSOLVENCY, DISSOLVED, IN_LIQUIDATION, EXTINCT, MERGED, REGISTRY_CLOSED, INACTIVE, UNKNOWN... */
854
+ status_code?: string;
855
+ status_date?: string | null;
856
+ /** Solo si enviaste name: parecido 0-100 y si coincide (desde 80). */
857
+ name_check?: {
858
+ provided: string;
859
+ score: number;
860
+ match: boolean;
861
+ };
862
+ /** Solo con vat: true. */
863
+ vat?: {
864
+ vat_number: string;
865
+ checked: boolean;
866
+ valid: boolean | null;
867
+ [k: string]: any;
868
+ };
869
+ /** null si no se ha procesado. */
870
+ invoice_hint: InvoiceHint | null;
871
+ flags: VerifyBatchFlag[];
872
+ }
873
+ export interface VerifyBatchMeta {
874
+ requested: number;
875
+ /** Sociedades encontradas (cada NIF distinto cuenta una vez). */
876
+ found: number;
877
+ /** Consultas (o créditos) cobradas. */
878
+ cost: number;
879
+ /** true si no llegó el cupo para todas: las que faltan van con processed: false. */
880
+ truncated: boolean;
881
+ summary: {
882
+ ok: number;
883
+ revisar: number;
884
+ no_facturar: number;
885
+ not_processed: number;
886
+ };
887
+ checked_at: string;
888
+ note: string;
889
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "apiempresas",
3
- "version": "1.5.0",
3
+ "version": "1.6.1",
4
4
  "description": "SDK oficial de APIEmpresas.es para Node.js y TypeScript",
5
5
  "main": "dist/index.js",
6
6
  "files": [