factuplan 0.6.0 → 0.8.0

package/dist/index.d.mts

@@ -103,6 +103,13 @@ interface InvoiceItem {
     /** Tax rate override for IVA_RATE. Valid: 0, 5, 8, 12, 14, 15. Default: 15 */
     tax?: number;
 }
+type PaymentTimeUnit = 'dias' | 'meses' | 'anios';
+interface InvoicePayment {
+    method: string;
+    amount: number;
+    term?: number;
+    timeUnit?: PaymentTimeUnit;
+}
 interface CreateInvoiceInput {
     /** UUID of the emission point. Optional if using establishment + emissionPoint codes, or if the taxpayer has a single active emission point. */
     emissionPointId?: string;
@@ -112,8 +119,14 @@ interface CreateInvoiceInput {
     emissionPoint?: string;
     customer: InvoiceCustomer;
     items: InvoiceItem[];
-    paymentMethod?: string;
+    /** List of payment methods for multi-payment support. */
+    payments?: InvoicePayment[];
     additionalInfo?: Record<string, string>;
+    /**
+     * Whether to send the authorized invoice by email to the customer.
+     * @default true
+     */
+    sendEmail?: boolean;
 }
 interface ImportByAccessKeyInput {
     /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
@@ -214,6 +227,36 @@ interface FactuplanOptions {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Default taxpayer RUC sent as `x-taxpayer-ruc` header in every request.
+     * Required for most operations (emit, sign, customers, products, etc.).
+     * Not required for `queryExternalByAccessKey`.
+     */
+    ruc?: string;
+}
+interface QueryExternalByAccessKeyInput {
+    /** Clave de acceso de 49 dígitos del comprobante en el SRI */
+    accessKey: string;
+    /**
+     * Si es true (por defecto), guarda el contribuyente, documento, XML y PDF.
+     * Si es false, solo verifica el comprobante y descuenta el contador sin guardar registros.
+     * @default true
+     */
+    save?: boolean;
+}
+interface QueryExternalByAccessKeyResponse {
+    /** ID del comprobante guardado en Factuplan; null cuando save=false */
+    id: string | null;
+    /** Clave de acceso de 49 dígitos */
+    accessKey: string;
+    /** Número secuencial del comprobante (ej: '000000001') */
+    sequential: string;
+    /** Estado del comprobante ('AUTHORIZED') */
+    status: string;
+    /** Total del comprobante */
+    total: number;
+    /** XML completo autorizado del SRI (envelope <autorizacion>) en base64 */
+    xmlBase64: string;
 }
 
 type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -241,6 +284,7 @@ declare class InvoicesResource {
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
     importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
+    queryExternalByAccessKey(input: QueryExternalByAccessKeyInput): Promise<QueryExternalByAccessKeyResponse>;
 }
 
 type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -272,6 +316,7 @@ declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly options;
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;

package/dist/index.d.ts

@@ -103,6 +103,13 @@ interface InvoiceItem {
     /** Tax rate override for IVA_RATE. Valid: 0, 5, 8, 12, 14, 15. Default: 15 */
     tax?: number;
 }
+type PaymentTimeUnit = 'dias' | 'meses' | 'anios';
+interface InvoicePayment {
+    method: string;
+    amount: number;
+    term?: number;
+    timeUnit?: PaymentTimeUnit;
+}
 interface CreateInvoiceInput {
     /** UUID of the emission point. Optional if using establishment + emissionPoint codes, or if the taxpayer has a single active emission point. */
     emissionPointId?: string;
@@ -112,8 +119,14 @@ interface CreateInvoiceInput {
     emissionPoint?: string;
     customer: InvoiceCustomer;
     items: InvoiceItem[];
-    paymentMethod?: string;
+    /** List of payment methods for multi-payment support. */
+    payments?: InvoicePayment[];
     additionalInfo?: Record<string, string>;
+    /**
+     * Whether to send the authorized invoice by email to the customer.
+     * @default true
+     */
+    sendEmail?: boolean;
 }
 interface ImportByAccessKeyInput {
     /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
@@ -214,6 +227,36 @@ interface FactuplanOptions {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Default taxpayer RUC sent as `x-taxpayer-ruc` header in every request.
+     * Required for most operations (emit, sign, customers, products, etc.).
+     * Not required for `queryExternalByAccessKey`.
+     */
+    ruc?: string;
+}
+interface QueryExternalByAccessKeyInput {
+    /** Clave de acceso de 49 dígitos del comprobante en el SRI */
+    accessKey: string;
+    /**
+     * Si es true (por defecto), guarda el contribuyente, documento, XML y PDF.
+     * Si es false, solo verifica el comprobante y descuenta el contador sin guardar registros.
+     * @default true
+     */
+    save?: boolean;
+}
+interface QueryExternalByAccessKeyResponse {
+    /** ID del comprobante guardado en Factuplan; null cuando save=false */
+    id: string | null;
+    /** Clave de acceso de 49 dígitos */
+    accessKey: string;
+    /** Número secuencial del comprobante (ej: '000000001') */
+    sequential: string;
+    /** Estado del comprobante ('AUTHORIZED') */
+    status: string;
+    /** Total del comprobante */
+    total: number;
+    /** XML completo autorizado del SRI (envelope <autorizacion>) en base64 */
+    xmlBase64: string;
 }
 
 type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -241,6 +284,7 @@ declare class InvoicesResource {
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
     importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
+    queryExternalByAccessKey(input: QueryExternalByAccessKeyInput): Promise<QueryExternalByAccessKeyResponse>;
 }
 
 type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -272,6 +316,7 @@ declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly options;
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;

package/dist/index.js

@@ -107,6 +107,13 @@ var InvoicesResource = class {
   async importByAccessKey(input) {
     return this.request("POST", "/developer/invoices/import", input);
   }
+  async queryExternalByAccessKey(input) {
+    return this.request(
+      "POST",
+      "/developer/receipts/query",
+      input
+    );
+  }
 };
 
 // src/resources/products.ts
@@ -160,6 +167,7 @@ var Factuplan = class {
   constructor(apiKey, options) {
     if (!apiKey) throw new Error("API key is required");
     this.apiKey = apiKey;
+    this.options = options;
     this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
     const requester = this.request.bind(this);
@@ -190,6 +198,9 @@ var Factuplan = class {
       "x-api-key": this.apiKey,
       Accept: "application/json"
     };
+    if (this.options?.ruc) {
+      headers["x-taxpayer-ruc"] = this.options.ruc;
+    }
     if (body !== void 0) {
       headers["Content-Type"] = "application/json";
     }

package/dist/index.mjs

@@ -78,6 +78,13 @@ var InvoicesResource = class {
   async importByAccessKey(input) {
     return this.request("POST", "/developer/invoices/import", input);
   }
+  async queryExternalByAccessKey(input) {
+    return this.request(
+      "POST",
+      "/developer/receipts/query",
+      input
+    );
+  }
 };
 
 // src/resources/products.ts
@@ -131,6 +138,7 @@ var Factuplan = class {
   constructor(apiKey, options) {
     if (!apiKey) throw new Error("API key is required");
     this.apiKey = apiKey;
+    this.options = options;
     this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
     const requester = this.request.bind(this);
@@ -161,6 +169,9 @@ var Factuplan = class {
       "x-api-key": this.apiKey,
       Accept: "application/json"
     };
+    if (this.options?.ruc) {
+      headers["x-taxpayer-ruc"] = this.options.ruc;
+    }
     if (body !== void 0) {
       headers["Content-Type"] = "application/json";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factuplan",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Official Factuplan SDK for JavaScript & TypeScript — Create electronic invoices for Ecuador (SRI)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",