@pimia/sdk 0.3.0 → 0.4.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

@@ -168,6 +168,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 +254,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;
@@ -350,6 +352,7 @@ export declare class PimiaClient {
             prefix: string;
             tax_id: string;
             notes: string;
+            external_ref: string | null;
             iban: string;
             bic: string;
             sepa_mandate_id: string;
@@ -422,6 +425,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;

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

@@ -11,9 +11,9 @@ 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.4.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)",