@pimia/sdk 0.3.0 → 0.5.0

package/dist/api.d.ts

@@ -233,6 +233,21 @@ export interface paths {
         /**
          * Handle the incoming request
          * @description **No disponible para integradores.** Exige `settings:write`, que el Authorization Server de Pimia no emite: la acción la realiza el dueño desde su panel y un token de partner recibe `403`. Aparece en el contrato para que el hueco sea explícito, no para que se llame.
+         *
+         *     Asistente de arranque: fija el tipo de cambio de cada moneda en uso y
+         *     RECALCULA con él los importes base de todas las facturas, presupuestos y
+         *     pagos de esa moneda — documentos ya emitidos incluidos. Corre una sola vez
+         *     por empresa (mientras `bulk_exchange_rate_configured` sea 'NO').
+         *
+         *     Reescribir en masa los importes de documentos emitidos es configuración de
+         *     empresa, no una operación de uso diario: va con el mismo gate de owner que
+         *     el resto de lo que escribe en Settings. Hasta 2026-08-10 no tenía ninguno
+         *     —el FormRequest autoriza a todo el mundo— y para un token de API la única
+         *     barrera era que `settings:write` no esté en el catálogo OAuth.
+         *
+         *     OJO al frontend: el modal lo abre `LayoutBasic` en cuanto entra CUALQUIER
+         *     usuario con la marca a 'NO'. Sin la condición de owner que se añadió allí,
+         *     este gate deja a un empleado atrapado en un modal que no puede completar.
          */
         post: operations["general.bulkExchangeRate"];
         delete?: never;
@@ -384,7 +399,14 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Handle the incoming request */
+        /**
+         * Convertir un presupuesto en factura borrador
+         * @description Acepta `external_ref` para etiquetar la factura resultante **en el mismo
+         *     paso**. Etiquetarla después, con `PUT /invoices/{id}`, llega tarde:
+         *     `invoice.created` ya ha salido con la referencia nula, y entre las dos
+         *     llamadas hay una ventana en la que la factura existe y no la encuentras
+         *     por tu referencia.
+         */
         post: operations["estimate.convertEstimate"];
         delete?: never;
         options?: never;
@@ -881,6 +903,34 @@ export interface paths {
         /**
          * Toggle lock state for a quarter
          * @description **No disponible para integradores.** Exige `reports:write`, que el Authorization Server de Pimia no emite: la acción la realiza el dueño desde su panel y un token de partner recibe `403`. Aparece en el contrato para que el hueco sea explícito, no para que se llame.
+         *
+         *     Cerrar un trimestre corta el alta y la edición de facturas emitidas y
+         *     recibidas con fecha en ese periodo ({@see FiscalQuarter::isLocked}); esta
+         *     misma acción lo REABRE. Es cierre contable, así que va con el gate de
+         *     owner que ya gobierna la configuración sensible del tenant.
+         *
+         *     Hasta 2026-08-10 no tenía ninguno: el `index` y el `toggle` colgaban de la
+         *     ability de LECTURA de informes que gatea la pantalla (VIEW_FINANCIAL_REPORT
+         *     en el router del panel), de modo que cualquiera que pudiera ver el informe
+         *     contable podía reabrir un ejercicio cerrado. Para un token de API la única
+         *     barrera era que `reports:write` no esté en el catálogo OAuth — una ausencia
+         *     que protegía por accidente y que este gate deja de necesitar.
+         *
+         *     El `index` sigue sin gate a propósito: leer qué trimestres están cerrados
+         *     es lo que pinta el panel y no cambia nada.
+         *
+         *     `locked` (opcional) es el ESTADO DESEADO, y es lo que deberían mandar los
+         *     clientes: con él la operación es idempotente y dice lo que quiere en vez
+         *     de depender de lo que había. Sin él se conserva el alternado histórico.
+         *
+         *     El alternado ciego tiene una carrera que no es teórica: el cliente decide
+         *     qué va a pasar leyendo un estado que ya puede haber cambiado. El panel
+         *     pinta «Cerrar T1» porque lo leyó abierto, otro usuario lo cierra, y el
+         *     clic acaba REABRIENDO el trimestre que su botón prometía cerrar. Por la
+         *     vía del MCP era peor: `toggle_fiscal_quarter_lock` declaraba este mismo
+         *     parámetro y el servidor lo ignoraba, así que un agente que pidiera cerrar
+         *     un trimestre ya cerrado lo abría — en una operación que el propio MCP
+         *     anuncia como PELIGROSA.
          */
         post: operations["fiscalQuarter.toggle"];
         delete?: never;
@@ -2976,6 +3026,22 @@ export interface components {
             created_at: string;
             updated_at: string;
         };
+        /**
+         * ConvertEstimateRequest
+         * @description Cuerpo —opcional— de la conversión de un presupuesto en factura.
+         */
+        ConvertEstimateRequest: {
+            /**
+             * @description Referencia externa: TU identificador para la factura que sale de
+             *     esta conversión (el id del pedido o de la venta cerrada en tu
+             *     sistema). Sin él la factura nace sin etiquetar y los webhooks
+             *     `invoice.created` e `invoice.paid` llegan con `external_ref`
+             *     nulo. El alcance es tu client OAuth, igual que en el alta
+             *     directa de facturas. Duplicada dentro de tu namespace → 422 con
+             *     `existing_id`, y la conversión entera se deshace.
+             */
+            external_ref?: string | null;
+        };
         /** CountryResource */
         CountryResource: {
             id: number;
@@ -3081,6 +3147,17 @@ export interface components {
             prefix?: string | null;
             tax_id?: string | null;
             notes?: string | null;
+            /**
+             * @description Referencia externa: TU identificador para este cliente (el id
+             *     del deal, del contacto o del pedido en tu sistema). El alcance
+             *     es tu client OAuth, así que dos integradores pueden usar la
+             *     misma cadena sin pisarse y ninguno ve la del otro. Se consulta
+             *     con `GET /customers?external_ref=…`, vuelve en el recurso y
+             *     viaja en los webhooks `customer.*`. Si ya la lleva otro cliente
+             *     tuyo, la respuesta es un 422 con `existing_id` — que es el
+             *     find-or-create sin mantener mapeo local. `null` la desvincula.
+             */
+            external_ref?: string | null;
             currency_id?: string | null;
             payment_method_id?: number | null;
             billing?: {
@@ -3139,6 +3216,13 @@ export interface components {
             prefix: string;
             tax_id: string;
             notes: string;
+            /**
+             * @description Referencia externa DE QUIEN PREGUNTA: la resuelve el client OAuth
+             *     del token, así que dos integradores ven cada uno la suya y el
+             *     panel (sin client) ve la del namespace de la company. Siempre
+             *     presente aunque sea null, para que el tipo del SDK no alterne.
+             */
+            external_ref: string | null;
             iban: string;
             bic: string;
             sepa_mandate_id: string;
@@ -3280,6 +3364,12 @@ export interface components {
             template_name: string;
             customer_id: string;
             lead_id: string;
+            /**
+             * @description Referencia externa del client OAuth del token (null si no hay).
+             *     Es el asidero que `lead_id` no podía ser: aquel es un entero de
+             *     Pimia y no admite el cuid o el uuid de un CRM de fuera.
+             */
+            external_ref: string | null;
             exchange_rate: string;
             base_discount_val: string;
             base_sub_total: string;
@@ -3313,6 +3403,17 @@ export interface components {
             expiry_date?: string | null;
             customer_id?: number | null;
             lead_id?: number | null;
+            /**
+             * @description Referencia externa: TU identificador para este presupuesto (el
+             *     id de la oportunidad en tu CRM). Es el asidero que `lead_id` no
+             *     podía ser: aquel es un entero de Pimia y no admite un cuid ni un
+             *     uuid. El alcance es tu client OAuth. Se consulta con
+             *     `GET /estimates?external_ref=…` y viaja en el payload de
+             *     `estimate.accepted`, así que recuperas tu oportunidad en el
+             *     evento sin mantener ningún mapeo. Duplicada dentro de tu
+             *     namespace → 422 con `existing_id`. `null` la desvincula.
+             */
+            external_ref?: string | null;
             /**
              * @description Opcional en el alta: si no llega, lo genera el servidor con el mismo
              *     SerialNumberFormatter que alimenta a GET /next-number, que es de donde
@@ -3533,6 +3634,11 @@ export interface components {
             template_name: string;
             invoice_series_id: string;
             customer_id: string;
+            /**
+             * @description Referencia externa del client OAuth del token (null si no hay):
+             *     cada integrador ve la suya y solo la suya.
+             */
+            external_ref: string | null;
             payment_method_id: string;
             recurring_invoice_id: string;
             sequence_number: string;
@@ -3684,6 +3790,15 @@ export interface components {
             due_date?: string | null;
             customer_id: number;
             invoice_number?: string | null;
+            /**
+             * @description Referencia externa: TU identificador para esta factura (el id
+             *     del pedido o de la suscripción en tu sistema). El alcance es tu
+             *     client OAuth. Se consulta con `GET /invoices?external_ref=…` y
+             *     viaja en los payloads de `invoice.created` e `invoice.paid`.
+             *     Duplicada dentro de tu namespace → 422 con `existing_id`.
+             *     `null` la desvincula.
+             */
+            external_ref?: string | null;
             exchange_rate?: string | null;
             /**
              * @description Descuento global: opcional en el contrato y rellenado a 0 en
@@ -4720,31 +4835,31 @@ export interface components {
         };
     };
     responses: {
-        /** @description Validation error */
-        ValidationException: {
+        /** @description Authorization error */
+        AuthorizationException: {
             headers: {
                 [name: string]: unknown;
             };
             content: {
                 "application/json": {
-                    /** @description Errors overview. */
+                    /** @description Error overview. */
                     message: string;
-                    /** @description A detailed description of each field that failed validation. */
-                    errors: {
-                        [key: string]: string[];
-                    };
                 };
             };
         };
-        /** @description Authorization error */
-        AuthorizationException: {
+        /** @description Validation error */
+        ValidationException: {
             headers: {
                 [name: string]: unknown;
             };
             content: {
                 "application/json": {
-                    /** @description Error overview. */
+                    /** @description Errors overview. */
                     message: string;
+                    /** @description A detailed description of each field that failed validation. */
+                    errors: {
+                        [key: string]: string[];
+                    };
                 };
             };
         };
@@ -5436,6 +5551,7 @@ export interface operations {
                     "application/json": Record<string, never>;
                 };
             };
+            403: components["responses"]["AuthorizationException"];
             422: components["responses"]["ValidationException"];
         };
     };
@@ -5759,7 +5875,11 @@ export interface operations {
             };
             cookie?: never;
         };
-        requestBody?: never;
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ConvertEstimateRequest"];
+            };
+        };
         responses: {
             200: {
                 headers: {
@@ -5771,6 +5891,7 @@ export interface operations {
             };
             403: components["responses"]["AuthorizationException"];
             404: components["responses"]["ModelNotFoundException"];
+            422: components["responses"]["ValidationException"];
         };
     };
     "general.countries": {
@@ -6074,7 +6195,10 @@ export interface operations {
     };
     "customers.index": {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Devuelve solo el recurso que lleve esta referencia externa. El alcance es el client OAuth del token: cada integrador consulta las suyas y nunca ve las de otro. Combinado con la escritura de `external_ref`, es el find-or-create sin mantener ningún mapeo local. */
+                external_ref?: string;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -6632,7 +6756,10 @@ export interface operations {
     };
     "estimates.index": {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Devuelve solo el recurso que lleve esta referencia externa. El alcance es el client OAuth del token: cada integrador consulta las suyas y nunca ve las de otro. Combinado con la escritura de `external_ref`, es el find-or-create sin mantener ningún mapeo local. */
+                external_ref?: string;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -7094,6 +7221,7 @@ export interface operations {
                 "application/json": {
                     year: number;
                     quarter: number;
+                    locked?: boolean | null;
                 };
             };
         };
@@ -7115,6 +7243,7 @@ export interface operations {
                     };
                 };
             };
+            403: components["responses"]["AuthorizationException"];
             422: components["responses"]["ValidationException"];
         };
     };
@@ -8013,6 +8142,8 @@ export interface operations {
         parameters: {
             query?: {
                 limit?: string;
+                /** @description Devuelve solo el recurso que lleve esta referencia externa. El alcance es el client OAuth del token: cada integrador consulta las suyas y nunca ve las de otro. Combinado con la escritura de `external_ref`, es el find-or-create sin mantener ningún mapeo local. */
+                external_ref?: string;
             };
             header?: never;
             path?: never;

package/dist/client.d.ts

@@ -112,6 +112,19 @@ export interface ResponseWithMeta<T> {
 }
 /** Lo que se puede afinar en una escritura (`post`/`put`/`patch`). */
 export type WriteOptions = Pick<RequestOptions, 'headers' | 'query' | 'signal' | 'idempotencyKey'>;
+/**
+ * Lo que se puede afinar en una lectura (`get`/`delete` y los atajos de
+ * recurso).
+ *
+ * Sin `idempotencyKey`, que no significa nada en una lectura, y sin `query`,
+ * que en `get()` ya es un parámetro propio.
+ *
+ * Existe sobre todo por `signal`: hasta la 0.4 los atajos de lectura no
+ * aceptaban opciones, así que ponerle un timeout a un GET obligaba a bajar a
+ * `request()` — o a quedarse sin él, que es lo que pasa de verdad. Un cliente
+ * que sondea y se cuelga en una lectura deja de sondear sin dar un solo error.
+ */
+export type ReadOptions = Pick<RequestOptions, 'headers' | 'signal'>;
 export declare class PimiaClient {
     readonly oauth: OAuth;
     private readonly baseUrl;
@@ -128,13 +141,13 @@ export declare class PimiaClient {
     /** Cabeceras `X-RateLimit-*` de la última respuesta. */
     get rateLimit(): RateLimit;
     get invoices(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["InvoiceResource"][];
             meta: {
                 invoice_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["InvoiceResource"] & Record<string, never>;
         }>;
         /**
@@ -168,6 +181,7 @@ export declare class PimiaClient {
             template_name: string;
             invoice_series_id: string;
             customer_id: string;
+            external_ref: string | null;
             payment_method_id: string;
             recurring_invoice_id: string;
             sequence_number: string;
@@ -253,6 +267,7 @@ export declare class PimiaClient {
             template_name: string;
             invoice_series_id: string;
             customer_id: string;
+            external_ref: string | null;
             payment_method_id: string;
             recurring_invoice_id: string;
             sequence_number: string;
@@ -312,13 +327,13 @@ export declare class PimiaClient {
         }>>;
     };
     get customers(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["CustomerResource"][];
             meta: {
                 customer_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["CustomerResource"];
         }>;
         create: (body: CustomerRequest, options?: WriteOptions) => Promise<{
@@ -350,6 +365,7 @@ export declare class PimiaClient {
             prefix: string;
             tax_id: string;
             notes: string;
+            external_ref: string | null;
             iban: string;
             bic: string;
             sepa_mandate_id: string;
@@ -363,13 +379,13 @@ export declare class PimiaClient {
         }>>;
     };
     get estimates(): {
-        list: (query?: RequestOptions["query"]) => Promise<{
+        list: (query?: RequestOptions["query"], options?: ReadOptions) => Promise<{
             data: components["schemas"]["EstimateResource"][];
             meta: {
                 estimate_total_count: number;
             };
         }>;
-        get: (id: number | string) => Promise<{
+        get: (id: number | string, options?: ReadOptions) => Promise<{
             data: components["schemas"]["EstimateResource"];
         }>;
         create: (body: EstimatesRequest, options?: WriteOptions) => Promise<{
@@ -393,9 +409,24 @@ export declare class PimiaClient {
          * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
          * una segunda factura.
          *
+         * Y manda `externalRef` si la venta nació en tu sistema: es lo que hace
+         * que `invoice.created` e `invoice.paid` te lleguen con tu referencia en
+         * vez de con `null`. **Tiene que ir aquí, en la conversión**; etiquetar
+         * después con `PUT /invoices/{id}` llega tarde por dos motivos: para
+         * entonces `invoice.created` ya salió con la referencia nula, y entre las
+         * dos llamadas hay una ventana en la que la factura existe y no la
+         * encuentras por tu referencia.
+         *
+         * Va como opción y no como segundo parámetro para no romperle la llamada
+         * a quien ya hace `convertToInvoice(id, { idempotencyKey })`: el cuerpo lo
+         * monta el atajo, y `external_ref` es además el único campo que el
+         * endpoint acepta.
+         *
          * Exige `estimates:write` **e** `invoices:write`.
          */
-        convertToInvoice: (id: number | string, options?: WriteOptions) => Promise<ResourceEnvelope<{
+        convertToInvoice: (id: number | string, options?: WriteOptions & {
+            externalRef?: string | null;
+        }) => Promise<ResourceEnvelope<{
             id: string;
             invoice_date: string;
             due_date: string;
@@ -422,6 +453,7 @@ export declare class PimiaClient {
             template_name: string;
             invoice_series_id: string;
             customer_id: string;
+            external_ref: string | null;
             payment_method_id: string;
             recurring_invoice_id: string;
             sequence_number: string;
@@ -480,11 +512,11 @@ export declare class PimiaClient {
             currency?: components["schemas"]["CurrencyResource"];
         }>>;
     };
-    get<T = unknown>(path: string, query?: RequestOptions['query']): Promise<T>;
+    get<T = unknown>(path: string, query?: RequestOptions['query'], options?: ReadOptions): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
     put<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
     patch<T = unknown>(path: string, body?: unknown, options?: WriteOptions): Promise<T>;
-    delete<T = unknown>(path: string): Promise<T>;
+    delete<T = unknown>(path: string, options?: ReadOptions): Promise<T>;
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:
      * `/invoices` y `/api/v1/invoices` son lo mismo.

package/dist/client.js

@@ -44,8 +44,8 @@ export class PimiaClient {
     }
     get invoices() {
         return {
-            list: (query) => this.get('/invoices', query),
-            get: (id) => this.get(`/invoices/${id}`),
+            list: (query, options) => this.get('/invoices', query, options),
+            get: (id, options) => this.get(`/invoices/${id}`, undefined, options),
             /**
              * Devuelve `{ data: InvoiceResource }`. El tipo NO sale del spec: el
              * `200` de `invoices.store` está vacío ahí (ver {@link ResourceEnvelope}).
@@ -57,8 +57,8 @@ export class PimiaClient {
     }
     get customers() {
         return {
-            list: (query) => this.get('/customers', query),
-            get: (id) => this.get(`/customers/${id}`),
+            list: (query, options) => this.get('/customers', query, options),
+            get: (id, options) => this.get(`/customers/${id}`, undefined, options),
             create: (body, options) => this.post('/customers', body, options),
             /** El `200` de `customers.update` no está tipado en el spec. */
             update: (id, body, options) => this.put(`/customers/${id}`, body, options),
@@ -66,8 +66,8 @@ export class PimiaClient {
     }
     get estimates() {
         return {
-            list: (query) => this.get('/estimates', query),
-            get: (id) => this.get(`/estimates/${id}`),
+            list: (query, options) => this.get('/estimates', query, options),
+            get: (id, options) => this.get(`/estimates/${id}`, undefined, options),
             create: (body, options) => this.post('/estimates', body, options),
             /**
              * Convierte un presupuesto aceptado en factura.
@@ -87,13 +87,33 @@ export class PimiaClient {
              * `estimate:{id}:invoice`— y el reintento tras un timeout no te creará
              * una segunda factura.
              *
+             * Y manda `externalRef` si la venta nació en tu sistema: es lo que hace
+             * que `invoice.created` e `invoice.paid` te lleguen con tu referencia en
+             * vez de con `null`. **Tiene que ir aquí, en la conversión**; etiquetar
+             * después con `PUT /invoices/{id}` llega tarde por dos motivos: para
+             * entonces `invoice.created` ya salió con la referencia nula, y entre las
+             * dos llamadas hay una ventana en la que la factura existe y no la
+             * encuentras por tu referencia.
+             *
+             * Va como opción y no como segundo parámetro para no romperle la llamada
+             * a quien ya hace `convertToInvoice(id, { idempotencyKey })`: el cuerpo lo
+             * monta el atajo, y `external_ref` es además el único campo que el
+             * endpoint acepta.
+             *
              * Exige `estimates:write` **e** `invoices:write`.
              */
-            convertToInvoice: (id, options) => this.post(`/estimates/${id}/convert-to-invoice`, {}, options),
+            convertToInvoice: (id, options) => {
+                const { externalRef, ...resto } = options ?? {};
+                return this.post(`/estimates/${id}/convert-to-invoice`, 
+                // Cuerpo vacío si no se pide, y no `external_ref: null`: mandar el
+                // null explícito DESVINCULA la referencia, que no es lo mismo que no
+                // tocarla.
+                externalRef === undefined ? {} : { external_ref: externalRef }, resto);
+            },
         };
     }
-    get(path, query) {
-        return this.request(path, { method: 'GET', query });
+    get(path, query, options) {
+        return this.request(path, { ...options, method: 'GET', query });
     }
     post(path, body, options) {
         return this.request(path, { ...options, method: 'POST', body });
@@ -104,8 +124,8 @@ export class PimiaClient {
     patch(path, body, options) {
         return this.request(path, { ...options, method: 'PATCH', body });
     }
-    delete(path) {
-        return this.request(path, { method: 'DELETE' });
+    delete(path, options) {
+        return this.request(path, { ...options, method: 'DELETE' });
     }
     /**
      * Petición cruda contra `/api/v1`. `path` puede llevar el prefijo o no:

package/dist/errors.d.ts

@@ -38,6 +38,49 @@ export declare class NotFoundError extends PimiaApiError {
 export declare class ValidationError extends PimiaApiError {
     get errors(): Record<string, string[]>;
 }
+/**
+ * 422 `external_ref_already_used`: la referencia externa que intentaste colgar
+ * ya la lleva otro recurso del mismo tipo dentro de tu namespace (company +
+ * client OAuth).
+ *
+ * **Lo normal es que no sea un error tuyo, sino tu reintento**: «crea el cliente
+ * del deal 42» ejecutado dos veces porque el proceso se cayó entre el POST y el
+ * guardado de tu mapeo. Por eso el error trae {@link existingId}, el recurso que
+ * ya lleva esa referencia — que es lo que convierte el choque en un
+ * find-or-create sin mantener ningún mapeo local:
+ *
+ * ```ts
+ * async function clienteDelDeal(dealId: string, name: string): Promise<number> {
+ *   try {
+ *     const { id } = await crearCliente({ name, external_ref: `deal_${dealId}` })
+ *     return id
+ *   } catch (error) {
+ *     // Ya existía: el propio error dice cuál es.
+ *     if (error instanceof DuplicateExternalRefError) return error.existingId
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * Hereda de {@link ValidationError} a propósito: el cuerpo trae también el
+ * `errors` de siempre, así que el código que ya trataba los 422 por ese camino
+ * sigue funcionando sin ramas nuevas.
+ */
+export declare class DuplicateExternalRefError extends ValidationError {
+    /** Id del recurso que YA lleva esa referencia. Tu find-or-create acaba aquí. */
+    readonly existingId: number;
+    /** La referencia que chocó, tal y como la mandaste. */
+    readonly externalRef: string;
+    /** Tipo del recurso en el core (`customer`, `estimate`, `invoice`). */
+    readonly entityType: string;
+    constructor(
+    /** Id del recurso que YA lleva esa referencia. Tu find-or-create acaba aquí. */
+    existingId: number, 
+    /** La referencia que chocó, tal y como la mandaste. */
+    externalRef: string, 
+    /** Tipo del recurso en el core (`customer`, `estimate`, `invoice`). */
+    entityType: string, status: number, message: string, body: unknown, requestId?: string);
+}
 /** 429: pasado el rate limit. `retryAfter` en segundos si la API lo dijo. */
 export declare class RateLimitError extends PimiaApiError {
     readonly retryAfter: number | undefined;

package/dist/errors.js

@@ -30,8 +30,13 @@ export class PimiaApiError extends PimiaError {
                 return new MissingScopeError(scope, status, message, body, requestId);
             return new ForbiddenError(status, message, body, requestId);
         }
-        if (status === 422)
+        if (status === 422) {
+            const duplicate = duplicateExternalRefFrom(body);
+            if (duplicate) {
+                return new DuplicateExternalRefError(duplicate.existingId, duplicate.externalRef, duplicate.entityType, status, message, body, requestId);
+            }
             return new ValidationError(status, message, body, requestId);
+        }
         if (status === 404)
             return new NotFoundError(status, message, body, requestId);
         return new PimiaApiError(status, message, body, requestId);
@@ -67,6 +72,51 @@ export class ValidationError extends PimiaApiError {
         return body?.errors ?? {};
     }
 }
+/**
+ * 422 `external_ref_already_used`: la referencia externa que intentaste colgar
+ * ya la lleva otro recurso del mismo tipo dentro de tu namespace (company +
+ * client OAuth).
+ *
+ * **Lo normal es que no sea un error tuyo, sino tu reintento**: «crea el cliente
+ * del deal 42» ejecutado dos veces porque el proceso se cayó entre el POST y el
+ * guardado de tu mapeo. Por eso el error trae {@link existingId}, el recurso que
+ * ya lleva esa referencia — que es lo que convierte el choque en un
+ * find-or-create sin mantener ningún mapeo local:
+ *
+ * ```ts
+ * async function clienteDelDeal(dealId: string, name: string): Promise<number> {
+ *   try {
+ *     const { id } = await crearCliente({ name, external_ref: `deal_${dealId}` })
+ *     return id
+ *   } catch (error) {
+ *     // Ya existía: el propio error dice cuál es.
+ *     if (error instanceof DuplicateExternalRefError) return error.existingId
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * Hereda de {@link ValidationError} a propósito: el cuerpo trae también el
+ * `errors` de siempre, así que el código que ya trataba los 422 por ese camino
+ * sigue funcionando sin ramas nuevas.
+ */
+export class DuplicateExternalRefError extends ValidationError {
+    existingId;
+    externalRef;
+    entityType;
+    constructor(
+    /** Id del recurso que YA lleva esa referencia. Tu find-or-create acaba aquí. */
+    existingId, 
+    /** La referencia que chocó, tal y como la mandaste. */
+    externalRef, 
+    /** Tipo del recurso en el core (`customer`, `estimate`, `invoice`). */
+    entityType, status, message, body, requestId) {
+        super(status, message, body, requestId);
+        this.existingId = existingId;
+        this.externalRef = externalRef;
+        this.entityType = entityType;
+    }
+}
 /** 429: pasado el rate limit. `retryAfter` en segundos si la API lo dijo. */
 export class RateLimitError extends PimiaApiError {
     retryAfter;
@@ -103,6 +153,36 @@ function messageFrom(body) {
     }
     return undefined;
 }
+/**
+ * Reconoce el 422 de referencia duplicada por su campo `error`, no por la prosa
+ * del mensaje —que está en castellano y puede cambiar—. Sin `existing_id` usable
+ * no se promueve el error: sin ese id no hay find-or-create que hacer, y un
+ * {@link ValidationError} normal describe mejor lo que pasó.
+ */
+function duplicateExternalRefFrom(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const record = body;
+    if (record.error !== 'external_ref_already_used')
+        return undefined;
+    // El core lo manda como entero; se normaliza igualmente porque en este
+    // contrato hay enteros que llegan como cadena según el driver. Ojo con
+    // `Number(null)`, que es 0 y no NaN: sin descartar antes los no-numéricos, un
+    // `existing_id: null` se colaría como el id 0.
+    const raw = record.existing_id;
+    const existingId = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string' && raw.trim() !== ''
+            ? Number(raw)
+            : Number.NaN;
+    if (!Number.isInteger(existingId))
+        return undefined;
+    return {
+        existingId,
+        externalRef: typeof record.external_ref === 'string' ? record.external_ref : '',
+        entityType: typeof record.entity_type === 'string' ? record.entity_type : '',
+    };
+}
 /** «Token lacks the invoices:write scope» → `invoices:write`. */
 function scopeFrom(message) {
     return /Token lacks the (\S+) scope/.exec(message)?.[1];

package/dist/index.d.ts

@@ -6,14 +6,14 @@
  * salen los tipos de `./api`.
  */
 export { PimiaClient } from './client.js';
-export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WriteOptions, } from './client.js';
+export type { CustomerRequest, CustomerResource, EstimateResource, EstimatesRequest, InvoiceResource, InvoicesRequest, PimiaClientOptions, RateLimit, ReadOptions, RequestOptions, ResourceEnvelope, ResponseMeta, ResponseWithMeta, WriteOptions, } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export type { AuthorizationServerMetadata, AuthorizeUrlOptions, OAuthConfig, PkceChallenge, } from './oauth.js';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
 export type { TokenSet, TokenStore } from './tokens.js';
-export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { DuplicateExternalRefError, ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
 export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
-export type { ApprovalDecidedPayload, AppRevokedPayload, CustomerPayload, EstimateAcceptedPayload, InvoiceCreatedPayload, InvoicePaidPayload, InvoiceReceivedPayload, IsoDateTime, KnownWebhook, PimiaWebhook, SignWebhookOptions, UnknownWebhook, VerifyWebhookOptions, WebhookBodyInput, WebhookEvent, WebhookHeadersInput, WebhookPayloads, WebhookVerificationReason, } from './webhooks.js';
+export type { ApprovalDecidedPayload, AppRevokedPayload, CustomerPayload, EstimateAcceptedPayload, ExternalRef, InvoiceCreatedPayload, InvoicePaidPayload, InvoiceReceivedPayload, IsoDateTime, KnownWebhook, PimiaWebhook, SignWebhookOptions, UnknownWebhook, VerifyWebhookOptions, WebhookBodyInput, WebhookEvent, WebhookHeadersInput, WebhookPayloads, WebhookVerificationReason, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
 export declare const SCOPES: {
     readonly invoicesRead: "invoices:read";

package/dist/index.js

@@ -8,7 +8,7 @@
 export { PimiaClient } from './client.js';
 export { OAuth, createPkceChallenge, createState } from './oauth.js';
 export { MemoryTokenStore, isExpired, tokenSetFromResponse } from './tokens.js';
-export { ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
+export { DuplicateExternalRefError, ForbiddenError, MissingScopeError, NotAuthenticatedError, NotFoundError, OAuthError, PimiaApiError, PimiaError, RateLimitError, UnauthorizedError, ValidationError, } from './errors.js';
 export { WEBHOOK_DEFAULT_TOLERANCE_SECONDS, WEBHOOK_EVENTS, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_VERSION, WebhookVerificationError, isWebhookEvent, signWebhook, verifyWebhook, } from './webhooks.js';
 /** Scopes granulares del catálogo de Pimia (paso 4). Pide siempre lo mínimo. */
 export const SCOPES = {

package/dist/webhooks.d.ts

@@ -67,6 +67,26 @@ export declare function isWebhookEvent(value: string): value is WebhookEvent;
 export type IsoDateTime = string;
 /** Une un enum abierto: autocompleta los valores conocidos sin cerrar el tipo. */
 type OpenEnum<T extends string> = T | (string & {});
+/**
+ * Referencia externa **de quien recibe esta entrega**: la que TU app puso sobre
+ * el recurso del evento, nunca la de otro integrador.
+ *
+ * No se calcula una vez y se reparte. El core la resuelve endpoint por endpoint
+ * contra el `client_id` del destinatario, porque un mismo evento se entrega a
+ * todos los endpoints suscritos de la company y esos pueden pertenecer a
+ * integradores distintos: con un valor común en el payload, la referencia del
+ * integrador A habría llegado al endpoint de B. Una referencia escrita sin
+ * client OAuth (panel, token personal) no sale nunca por este canal.
+ *
+ * Es `string | null` y **no** opcional a propósito: la clave viaja siempre, con
+ * `null` cuando no hay referencia. Un payload cuya forma cambia según el dato es
+ * un payload que el receptor no puede tipar.
+ *
+ * Solo la llevan los cinco eventos de recurso (`customer.*`, `invoice.created`,
+ * `invoice.paid`, `estimate.accepted`). `approval.decided`, `invoice.received` y
+ * `app.revoked` no van sobre un recurso etiquetable y no la incluyen.
+ */
+export type ExternalRef = string | null;
 /**
  * Una decisión de aprobación delegada se resolvió.
  *
@@ -129,6 +149,8 @@ export interface CustomerPayload {
     company_id: number;
     created_at: IsoDateTime | null;
     updated_at: IsoDateTime | null;
+    /** Tu referencia para este cliente. Ver {@link ExternalRef}. */
+    external_ref: ExternalRef;
 }
 /** Alta de factura. Importes en céntimos. */
 export interface InvoiceCreatedPayload {
@@ -147,6 +169,14 @@ export interface InvoiceCreatedPayload {
     due_amount: number;
     currency_id: number | null;
     created_at: IsoDateTime | null;
+    /**
+     * Tu referencia para esta factura. Ver {@link ExternalRef}.
+     *
+     * Llega poblada también cuando la factura nace de
+     * `POST /estimates/{id}/convert-to-invoice` con `external_ref` en el cuerpo:
+     * sellar en la conversión existe justo para que este evento no salga nulo.
+     */
+    external_ref: ExternalRef;
 }
 /**
  * El CLIENTE FINAL aceptó el presupuesto. Es una transición, no un estado: solo
@@ -166,6 +196,14 @@ export interface EstimateAcceptedPayload {
     total: number;
     currency_id: number | null;
     accepted_at: IsoDateTime | null;
+    /**
+     * Tu referencia para este presupuesto. Ver {@link ExternalRef}.
+     *
+     * Es el asidero que `lead_id` no podía ser: aquel es un entero de Pimia y no
+     * admite el cuid ni el uuid de un CRM de fuera, así que recuperas tu
+     * oportunidad desde el propio evento sin mantener ninguna tabla de mapeo.
+     */
+    external_ref: ExternalRef;
 }
 /**
  * La factura quedó cobrada del todo. `PARTIALLY_PAID` no emite: es una
@@ -185,6 +223,8 @@ export interface InvoicePaidPayload {
     due_amount: number;
     currency_id: number | null;
     paid_at: IsoDateTime | null;
+    /** Tu referencia para esta factura. Ver {@link ExternalRef}. */
+    external_ref: ExternalRef;
 }
 /** Payload de cada evento del catálogo, por nombre. */
 export interface WebhookPayloads {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimia/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Cliente TypeScript de la API de Pimia para apps de partner: OAuth con PKCE, rotación de refresh persistida, reintentos de rate limit y tipos generados del OpenAPI.",
   "license": "MIT",
   "author": "Pimia (https://pimia.es)",