factuplan 0.2.2 → 0.5.0

package/README.md

@@ -129,6 +129,27 @@ const { url } = await factuplan.invoices.downloadXml('invoice-id');
 const { url } = await factuplan.invoices.downloadPdf('invoice-id');
 ```
 
+### Importar factura ya autorizada por el SRI
+
+Si tienes una factura que ya fue autorizada directamente por el SRI (no a través de Factuplan), puedes importarla para almacenarla en tu cuenta y generar el PDF (RIDE):
+
+```typescript
+const result = await factuplan.invoices.importByAccessKey({
+  accessKey: '1512202501095019440700120010020000000116488711218',
+});
+
+console.log(result.id);         // ID interno del comprobante
+console.log(result.accessKey);  // Clave de acceso SRI
+console.log(result.sequential); // Número secuencial
+console.log(result.status);     // 'AUTHORIZED'
+console.log(result.total);      // Total del comprobante
+
+// El PDF se genera automáticamente. Descárgalo una vez listo:
+const { url } = await factuplan.invoices.downloadPdf(result.id);
+```
+
+> **Nota:** Este método no envía el comprobante al SRI ni envía correo al cliente. Solo importa y genera el PDF.
+
 ### Firmar y autorizar XML (Modo B)
 
 Si ya tienes tu XML generado (sin firmar), puedes enviarlo para que Factuplan lo firme con tu certificado y lo autorice ante el SRI:
@@ -152,6 +173,35 @@ const status = await factuplan.invoices.getStatus(result.id);
 const { url } = await factuplan.invoices.downloadXml(result.id);
 ```
 
+### Solo firmar XML (Modo C)
+
+Firma el XML con tu certificado sin enviarlo al SRI:
+
+```typescript
+const { signedXml } = await factuplan.invoices.signOnly({ xml });
+```
+
+### Validar XML
+
+Valida la estructura de un XML sin procesarlo:
+
+```typescript
+const { valid, errors } = await factuplan.invoices.validateXml({ xml });
+if (!valid) {
+  console.log('Errores:', errors);
+}
+```
+
+### Verificar autorizacion
+
+Consulta el estado de autorizacion de un comprobante por su clave de acceso:
+
+```typescript
+const result = await factuplan.invoices.verify('0104202601099337815000110010010000000011234567890');
+console.log(result.authorized);           // true/false
+console.log(result.authorizationNumber);   // Numero de autorizacion
+```
+
 ### Uso y certificado
 
 ```typescript

package/dist/index.d.mts

@@ -115,6 +115,10 @@ interface CreateInvoiceInput {
     paymentMethod?: string;
     additionalInfo?: Record<string, string>;
 }
+interface ImportByAccessKeyInput {
+    /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
+    accessKey: string;
+}
 interface Invoice {
     id: string;
     accessKey: string;
@@ -142,6 +146,30 @@ interface SignAndAuthorizeResponse {
     accessKey: string;
     status: string;
 }
+interface SignOnlyInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignOnlyResponse {
+    signedXml: string;
+}
+interface ValidateXmlInput {
+    /** XML string to validate */
+    xml: string;
+}
+interface ValidateXmlResponse {
+    valid: boolean;
+    errors: string[];
+}
+interface VerifyResponse {
+    authorized: boolean;
+    authorizationNumber?: string;
+    authorizationDate?: string;
+    messages?: Array<{
+        code?: string;
+        message?: string;
+    }>;
+}
 interface UsageResponse {
     apiKeyId: string;
     month: string;
@@ -158,6 +186,24 @@ interface CertificateStatus {
     legalName?: string;
     expiresAt?: string;
 }
+interface WebhookEvent {
+    id: string;
+    event: string;
+    timestamp: string;
+    data: WebhookReceiptData;
+    webhookId: string;
+    attempt: number;
+}
+interface WebhookReceiptData {
+    receiptId: string;
+    type: string;
+    accessKey: string;
+    authorizationNumber: string;
+    documentNumber: string;
+    total: string;
+    customerName: string;
+    customerIdentification: string;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api.factuplan.com/api/v1) */
     baseUrl?: string;
@@ -165,10 +211,10 @@ interface FactuplanOptions {
     timeout?: number;
 }
 
-type Requester$2 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
-    constructor(request: Requester$2);
+    constructor(request: Requester$3);
     create(input: CreateCustomerInput): Promise<Customer>;
     list(params?: CustomerListParams): Promise<PaginatedResponse<Customer>>;
     get(id: string): Promise<Customer>;
@@ -176,22 +222,26 @@ declare class CustomersResource {
     delete(id: string): Promise<void>;
 }
 
-type Requester$1 = (method: string, path: string, body?: unknown) => Promise<unknown>;
+type Requester$2 = (method: string, path: string, body?: unknown) => Promise<unknown>;
 declare class InvoicesResource {
     private request;
-    constructor(request: Requester$1);
+    constructor(request: Requester$2);
     create(input: CreateInvoiceInput): Promise<Invoice>;
     signAndAuthorize(input: SignAndAuthorizeInput): Promise<SignAndAuthorizeResponse>;
+    signOnly(input: SignOnlyInput): Promise<SignOnlyResponse>;
+    validateXml(input: ValidateXmlInput): Promise<ValidateXmlResponse>;
+    verify(accessKey: string): Promise<VerifyResponse>;
     get(id: string): Promise<Record<string, unknown>>;
     getStatus(id: string): Promise<InvoiceStatus>;
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
+    importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
 }
 
-type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class ProductsResource {
     private request;
-    constructor(request: Requester);
+    constructor(request: Requester$1);
     create(input: CreateProductInput): Promise<Product>;
     list(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
     get(id: string): Promise<Product>;
@@ -199,6 +249,20 @@ declare class ProductsResource {
     delete(id: string): Promise<void>;
 }
 
+type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class WebhooksResource {
+    private readonly request;
+    constructor(requester: Requester);
+    /**
+     * Verify that a receipt (document) exists in the API.
+     * This is a second layer of verification beyond signature checking.
+     *
+     * @param receiptId - The receipt ID from the webhook payload
+     * @returns The receipt object if it exists, or `null` if not found
+     */
+    verifyReceipt(receiptId: string): Promise<Record<string, unknown> | null>;
+}
+
 declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
@@ -206,6 +270,8 @@ declare class Factuplan {
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
+    readonly webhooks: WebhooksResource;
+    static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
     certificateStatus(): Promise<CertificateStatus>;
@@ -225,4 +291,4 @@ declare class RateLimitError extends FactuplanError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse };
+export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type WebhookEvent, type WebhookReceiptData };

package/dist/index.d.ts

@@ -115,6 +115,10 @@ interface CreateInvoiceInput {
     paymentMethod?: string;
     additionalInfo?: Record<string, string>;
 }
+interface ImportByAccessKeyInput {
+    /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
+    accessKey: string;
+}
 interface Invoice {
     id: string;
     accessKey: string;
@@ -142,6 +146,30 @@ interface SignAndAuthorizeResponse {
     accessKey: string;
     status: string;
 }
+interface SignOnlyInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignOnlyResponse {
+    signedXml: string;
+}
+interface ValidateXmlInput {
+    /** XML string to validate */
+    xml: string;
+}
+interface ValidateXmlResponse {
+    valid: boolean;
+    errors: string[];
+}
+interface VerifyResponse {
+    authorized: boolean;
+    authorizationNumber?: string;
+    authorizationDate?: string;
+    messages?: Array<{
+        code?: string;
+        message?: string;
+    }>;
+}
 interface UsageResponse {
     apiKeyId: string;
     month: string;
@@ -158,6 +186,24 @@ interface CertificateStatus {
     legalName?: string;
     expiresAt?: string;
 }
+interface WebhookEvent {
+    id: string;
+    event: string;
+    timestamp: string;
+    data: WebhookReceiptData;
+    webhookId: string;
+    attempt: number;
+}
+interface WebhookReceiptData {
+    receiptId: string;
+    type: string;
+    accessKey: string;
+    authorizationNumber: string;
+    documentNumber: string;
+    total: string;
+    customerName: string;
+    customerIdentification: string;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api.factuplan.com/api/v1) */
     baseUrl?: string;
@@ -165,10 +211,10 @@ interface FactuplanOptions {
     timeout?: number;
 }
 
-type Requester$2 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
-    constructor(request: Requester$2);
+    constructor(request: Requester$3);
     create(input: CreateCustomerInput): Promise<Customer>;
     list(params?: CustomerListParams): Promise<PaginatedResponse<Customer>>;
     get(id: string): Promise<Customer>;
@@ -176,22 +222,26 @@ declare class CustomersResource {
     delete(id: string): Promise<void>;
 }
 
-type Requester$1 = (method: string, path: string, body?: unknown) => Promise<unknown>;
+type Requester$2 = (method: string, path: string, body?: unknown) => Promise<unknown>;
 declare class InvoicesResource {
     private request;
-    constructor(request: Requester$1);
+    constructor(request: Requester$2);
     create(input: CreateInvoiceInput): Promise<Invoice>;
     signAndAuthorize(input: SignAndAuthorizeInput): Promise<SignAndAuthorizeResponse>;
+    signOnly(input: SignOnlyInput): Promise<SignOnlyResponse>;
+    validateXml(input: ValidateXmlInput): Promise<ValidateXmlResponse>;
+    verify(accessKey: string): Promise<VerifyResponse>;
     get(id: string): Promise<Record<string, unknown>>;
     getStatus(id: string): Promise<InvoiceStatus>;
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
+    importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
 }
 
-type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class ProductsResource {
     private request;
-    constructor(request: Requester);
+    constructor(request: Requester$1);
     create(input: CreateProductInput): Promise<Product>;
     list(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
     get(id: string): Promise<Product>;
@@ -199,6 +249,20 @@ declare class ProductsResource {
     delete(id: string): Promise<void>;
 }
 
+type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class WebhooksResource {
+    private readonly request;
+    constructor(requester: Requester);
+    /**
+     * Verify that a receipt (document) exists in the API.
+     * This is a second layer of verification beyond signature checking.
+     *
+     * @param receiptId - The receipt ID from the webhook payload
+     * @returns The receipt object if it exists, or `null` if not found
+     */
+    verifyReceipt(receiptId: string): Promise<Record<string, unknown> | null>;
+}
+
 declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
@@ -206,6 +270,8 @@ declare class Factuplan {
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
+    readonly webhooks: WebhooksResource;
+    static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
     certificateStatus(): Promise<CertificateStatus>;
@@ -225,4 +291,4 @@ declare class RateLimitError extends FactuplanError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse };
+export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type WebhookEvent, type WebhookReceiptData };

package/dist/index.js

@@ -83,6 +83,15 @@ var InvoicesResource = class {
   async signAndAuthorize(input) {
     return this.request("POST", "/developer/sign-and-authorize", input);
   }
+  async signOnly(input) {
+    return this.request("POST", "/developer/sign", input);
+  }
+  async validateXml(input) {
+    return this.request("POST", "/developer/validate-xml", input);
+  }
+  async verify(accessKey) {
+    return this.request("GET", `/developer/verify/${accessKey}`);
+  }
   async get(id) {
     return this.request("GET", `/developer/receipts/${id}`);
   }
@@ -95,6 +104,9 @@ var InvoicesResource = class {
   async downloadPdf(id) {
     return this.request("GET", `/developer/receipts/${id}/pdf`);
   }
+  async importByAccessKey(input) {
+    return this.request("POST", "/developer/invoices/import", input);
+  }
 };
 
 // src/resources/products.ts
@@ -119,6 +131,28 @@ var ProductsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(requester) {
+    this.request = requester;
+  }
+  /**
+   * Verify that a receipt (document) exists in the API.
+   * This is a second layer of verification beyond signature checking.
+   *
+   * @param receiptId - The receipt ID from the webhook payload
+   * @returns The receipt object if it exists, or `null` if not found
+   */
+  async verifyReceipt(receiptId) {
+    try {
+      const result = await this.request("GET", `/developer/receipts/${receiptId}`);
+      return result ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-rest.factuplan.com.ec/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
@@ -132,6 +166,7 @@ var Factuplan = class {
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
+    this.webhooks = new WebhooksResource(requester);
   }
   async usage() {
     return this.request("GET", "/developer/usage");
@@ -185,6 +220,7 @@ var Factuplan = class {
     return json;
   }
 };
+Factuplan.webhooks = WebhooksResource;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,

package/dist/index.mjs

@@ -54,6 +54,15 @@ var InvoicesResource = class {
   async signAndAuthorize(input) {
     return this.request("POST", "/developer/sign-and-authorize", input);
   }
+  async signOnly(input) {
+    return this.request("POST", "/developer/sign", input);
+  }
+  async validateXml(input) {
+    return this.request("POST", "/developer/validate-xml", input);
+  }
+  async verify(accessKey) {
+    return this.request("GET", `/developer/verify/${accessKey}`);
+  }
   async get(id) {
     return this.request("GET", `/developer/receipts/${id}`);
   }
@@ -66,6 +75,9 @@ var InvoicesResource = class {
   async downloadPdf(id) {
     return this.request("GET", `/developer/receipts/${id}/pdf`);
   }
+  async importByAccessKey(input) {
+    return this.request("POST", "/developer/invoices/import", input);
+  }
 };
 
 // src/resources/products.ts
@@ -90,6 +102,28 @@ var ProductsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(requester) {
+    this.request = requester;
+  }
+  /**
+   * Verify that a receipt (document) exists in the API.
+   * This is a second layer of verification beyond signature checking.
+   *
+   * @param receiptId - The receipt ID from the webhook payload
+   * @returns The receipt object if it exists, or `null` if not found
+   */
+  async verifyReceipt(receiptId) {
+    try {
+      const result = await this.request("GET", `/developer/receipts/${receiptId}`);
+      return result ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-rest.factuplan.com.ec/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
@@ -103,6 +137,7 @@ var Factuplan = class {
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
+    this.webhooks = new WebhooksResource(requester);
   }
   async usage() {
     return this.request("GET", "/developer/usage");
@@ -156,6 +191,7 @@ var Factuplan = class {
     return json;
   }
 };
+Factuplan.webhooks = WebhooksResource;
 export {
   AuthenticationError,
   Factuplan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factuplan",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "Official Factuplan SDK for JavaScript & TypeScript — Create electronic invoices for Ecuador (SRI)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,6 +16,7 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0"
   },