fiscalapi 4.0.141 → 4.0.270

package/dist/types/models/download.d.ts

@@ -0,0 +1,432 @@
+import { DateTime } from 'luxon';
+import { BaseDto } from '../common/base-dto';
+import { CatalogDto } from '../common/catalog-dto';
+import { Person } from './person';
+/**
+ * Representa una plantilla para crear solicitudes de descarga de CFDI o metadatos.
+ */
+export interface DownloadRule extends BaseDto {
+    /** ID de la persona asociada a la regla de descarga */
+    personId?: string;
+    /** Información de la persona asociada */
+    person?: Person;
+    /** RFC (Tax Identification Number) del solicitante */
+    tin?: string;
+    /** Descripción de la regla de descarga */
+    description?: string;
+    /**
+     * Estado de la regla de descarga
+     * 1: Pendiente, 2: Aprobada, 3: Rechazada, 4: Abandonada
+     */
+    downloadRuleStatusId?: string;
+    /** Catálogo del estado de la regla de descarga */
+    downloadRuleStatus?: CatalogDto;
+    /**
+     * Tipo de consulta SAT
+     * CFDI, Metadata
+     */
+    satQueryTypeId?: string;
+    /** Catálogo del tipo de consulta SAT */
+    satQueryType?: CatalogDto;
+    /**
+     * Tipo de descarga
+     * Emitidos, Recibidos
+     */
+    downloadTypeId?: string;
+    /** Catálogo del tipo de descarga */
+    downloadType?: CatalogDto;
+    /**
+     * Estado de la factura SAT
+     * Vigente, Cancelado
+     */
+    satInvoiceStatusId?: string;
+    /** Catálogo del estado de la factura SAT */
+    satInvoiceStatus?: CatalogDto;
+}
+/**
+ * Representa una solicitud de descarga de CFDI o metadatos
+ */
+export interface DownloadRequest extends BaseDto {
+    /** Número consecutivo de la solicitud */
+    consecutive?: number;
+    /**
+     * ID de solicitud SAT utilizado para rastrear la solicitud en el sistema SAT
+     */
+    satRequestId?: string;
+    /**
+     * ID de la regla asociada con la solicitud
+     */
+    downloadRuleId?: string;
+    /** ID del tipo de descarga */
+    downloadTypeId?: string;
+    /** Catálogo del tipo de descarga */
+    downloadType?: CatalogDto;
+    /** ID del tipo de solicitud de descarga */
+    downloadRequestTypeId?: string;
+    /** Catálogo del tipo de solicitud de descarga */
+    downloadRequestType?: CatalogDto;
+    /**
+     * RFC Receptor
+     * CFDI específicos o metadatos del RFC receptor dado
+     */
+    recipientTin?: string;
+    /**
+     * RFC Emisor
+     * CFDI específicos o metadatos del RFC emisor dado
+     */
+    issuerTin?: string;
+    /**
+     * RFC Solicitante
+     * RFC quien está solicitando la consulta
+     */
+    requesterTin?: string;
+    /**
+     * Fecha inicial
+     * Fecha de inicio para la solicitud asociada
+     */
+    startDate: DateTime;
+    /**
+     * Fecha final
+     * Fecha de fin para la solicitud asociada
+     */
+    endDate: DateTime;
+    /**
+     * Tipo de solicitud
+     * Tipo de solicitud para la petición
+     * CFDI o Metadata
+     */
+    satQueryTypeId?: string;
+    /** Catálogo del tipo de consulta SAT */
+    satQueryType?: CatalogDto;
+    /**
+     * Tipo de comprobante
+     * Tipo específico de factura a solicitar
+     * Ingreso, Egreso, Traslado, Nómina, Pago, Todos
+     */
+    satInvoiceTypeId?: string;
+    /** Catálogo del tipo de factura SAT */
+    satInvoiceType?: CatalogDto;
+    /**
+     * Estado del comprobante
+     * Estado de los CFDI a solicitar
+     */
+    satInvoiceStatusId?: string;
+    /** Catálogo del estado de la factura SAT */
+    satInvoiceStatus?: CatalogDto;
+    /**
+     * Complemento
+     * Complementos CFDI para la solicitud
+     */
+    satInvoiceComplementId?: string;
+    /** Catálogo del complemento de factura SAT */
+    satInvoiceComplement?: CatalogDto;
+    /**
+     * Estado actual de la solicitud
+     * DESCONOCIDO, ACEPTADA, EN PROCESO, TERMINADA, ERROR, RECHAZADA, VENCIDA
+     */
+    satRequestStatusId?: string;
+    /** Catálogo del estado de la solicitud SAT */
+    satRequestStatus?: CatalogDto;
+    /**
+     * ID del estado de la solicitud en Fiscalapi
+     */
+    downloadRequestStatusId?: string;
+    /** Catálogo del estado de la solicitud de descarga */
+    downloadRequestStatus?: CatalogDto;
+    /**
+     * Fecha del último intento
+     * Fecha del último intento para la solicitud asociada
+     */
+    lastAttemptDate?: DateTime | string;
+    /**
+     * Fecha del siguiente intento
+     * Fecha del siguiente intento para la solicitud asociada
+     */
+    nextAttemptDate?: DateTime | string;
+    /**
+     * Número de CFDI encontrados para la solicitud cuando la solicitud está terminada
+     */
+    invoiceCount?: number;
+    /**
+     * Lista de IDs de paquetes disponibles para descarga cuando la solicitud está terminada
+     */
+    packageIds?: string[];
+    /**
+     * Indica si la solicitud está lista para descarga, se vuelve verdadero cuando la solicitud está terminada y los paquetes están disponibles
+     */
+    isReadyToDownload?: boolean;
+    /**
+     * Número total de reintentos intentados para esta solicitud a través de todas las re-submisiones
+     */
+    retriesCount?: number;
+}
+/**
+* Representa un elemento de metadatos de CFDI descargado desde el SAT
+*/
+export interface MetadataItem extends BaseDto {
+    /**
+     * Folio de la factura - UUID
+     */
+    invoiceUuid?: string;
+    /**
+     * RFC del emisor del comprobante - RfcEmisor
+     */
+    issuerTin?: string;
+    /**
+     * Nombre o razón social del emisor - NombreEmisor
+     */
+    issuerName?: string;
+    /**
+     * RFC del receptor del comprobante - RfcReceptor
+     */
+    recipientTin?: string;
+    /**
+     * Nombre o razón social del receptor - NombreReceptor
+     */
+    recipientName?: string;
+    /**
+     * RFC del Proveedor Autorizado de Certificación (PAC) - RfcPac
+     */
+    pacTin?: string;
+    /**
+     * Fecha y hora de emisión del comprobante - FechaEmision
+     */
+    invoiceDate: DateTime | string;
+    /**
+     * Fecha y hora de certificación por el SAT - FechaCertificacionSat
+     */
+    satCertificationDate: DateTime | string;
+    /**
+     * Monto total del comprobante - Monto
+     */
+    amount?: number;
+    /**
+     * Tipo de comprobante (I = Ingreso, E = Egreso, T = Traslado, N = Nómina, P = Pago) - EfectoComprobante
+     */
+    invoiceType?: string;
+    /**
+     * Estatus del comprobante (1 = Vigente, 0 = Cancelado) - Estatus
+     */
+    status?: number;
+    /**
+     * Fecha de cancelación del comprobante (si aplica) - FechaCancelacion
+     */
+    cancellationDate?: DateTime | string;
+    /** ID del paquete de descarga */
+    downloadPackageId?: string;
+    /** ID de la solicitud de descarga */
+    downloadRequestId?: string;
+}
+/**
+* Representa el XML de un CFDI (Comprobante Fiscal Digital por Internet) descargado desde el SAT
+*/
+export interface Xml extends BaseDto {
+    /** ID de la solicitud de descarga */
+    downloadRequestId?: string;
+    /** Versión del CFDI */
+    version?: string;
+    /** Serie */
+    series?: string;
+    /** Folio */
+    number?: string;
+    /** Fecha de emisión del CFDI */
+    date: DateTime | string;
+    /** Código de la forma de pago */
+    paymentForm?: string;
+    /** Código del método de pago */
+    paymentMethod?: string;
+    /** Número de certificado del emisor */
+    certificateNumber?: string;
+    /** Condiciones de pago */
+    paymentConditions?: string;
+    /** Subtotal del CFDI */
+    subTotal?: number;
+    /** Descuento aplicado al CFDI */
+    discount?: number;
+    /** Código de la moneda del CFDI */
+    currency?: string;
+    /** Tipo de cambio del CFDI (si aplica) */
+    exchangeRate?: number;
+    /** Total del CFDI */
+    total?: number;
+    /** Tipo de comprobante (I = Ingreso, E = Egreso, T = Traslado, N = Nómina, P = Pago) */
+    invoiceType?: string;
+    /** Código de exportación (si aplica) */
+    export?: string;
+    /** Lugar de expedición del CFDI */
+    expeditionZipCode?: string;
+    /** Confirmación si aplica */
+    confirmation?: string;
+    /** Total impuestos retenidos */
+    totalWithheldTaxes?: number;
+    /** Total impuestos trasladados */
+    totalTransferredTaxes?: number;
+    /** Información global del CFDI (para CFDI globales) */
+    xmlGlobalInformation?: XmlGlobalInformation;
+    /** Información de impuestos del CFDI */
+    taxes?: XmlTax[];
+    /** Información sobre facturas relacionadas del CFDI (CFDI relacionados) */
+    xmlRelated?: XmlRelated[];
+    /** Información del emisor del CFDI */
+    xmlIssuer?: XmlIssuer;
+    /** Información del receptor del CFDI */
+    xmlRecipient?: XmlRecipient;
+    /** Información de los conceptos del CFDI */
+    xmlItems?: XmlItem[];
+    /** Información de los complementos del CFDI */
+    xmlComplements?: XmlComplement[];
+    /** XML crudo en base64 */
+    base64Content?: string;
+}
+/**
+ * Información global del CFDI
+ */
+export interface XmlGlobalInformation extends BaseDto {
+    /** Periodicidad */
+    periodicity?: string;
+    /** Mes */
+    month?: string;
+    /** Año */
+    year?: number;
+}
+/**
+ * Información del emisor del CFDI
+ */
+export interface XmlIssuer extends BaseDto {
+    /** RFC del emisor */
+    tin?: string;
+    /** Razón social */
+    legalName?: string;
+    /** Régimen fiscal */
+    taxRegime?: string;
+}
+/**
+ * Información aduanera del concepto
+ */
+export interface XmlItemCustomsInformation extends BaseDto {
+    /** ID del concepto XML */
+    xmlItemId?: string;
+    /** Número de documento aduanero */
+    customsDocumentNumber?: string;
+}
+/**
+ * Concepto del CFDI
+ */
+export interface XmlItem extends BaseDto {
+    /** ID del XML */
+    xmlId?: string;
+    /** Código del concepto */
+    itemCode?: string;
+    /** SKU del concepto */
+    sku?: string;
+    /** Cantidad */
+    quantity?: number;
+    /** Unidad de medida */
+    unitMeasurement?: string;
+    /** Descripción */
+    description?: string;
+    /** Precio unitario */
+    unitPrice?: number;
+    /** Importe */
+    amount?: number;
+    /** Descuento */
+    discount?: number;
+    /** Objeto de impuesto */
+    taxObject?: string;
+    /** Cuenta de terceros */
+    thirdPartyAccount?: string;
+    /** Información aduanera del concepto */
+    xmlItemCustomsInformation?: XmlItemCustomsInformation[];
+    /** Cuentas prediales del concepto */
+    xmlItemPropertyAccounts?: XmlItemPropertyAccount[];
+    /** Impuestos del concepto */
+    taxes?: XmlItemTax[];
+}
+/**
+ * Cuenta predial del concepto
+ */
+export interface XmlItemPropertyAccount extends BaseDto {
+    /** ID del concepto XML */
+    xmlItemId?: string;
+    /** Número de cuenta predial */
+    propertyAccountNumber?: string;
+}
+/**
+ * Impuesto del concepto
+ */
+export interface XmlItemTax extends BaseDto {
+    /** Base del impuesto */
+    base?: number;
+    /** Código del impuesto */
+    tax?: string;
+    /** Tipo de impuesto */
+    taxType?: string;
+    /** Tasa o cuota */
+    rate?: number;
+    /** Importe del impuesto */
+    amount?: number;
+    /** Naturaleza del impuesto (T = Traslado, R = Retención) */
+    taxFlag?: string;
+    /** ID del concepto XML */
+    xmlItemId?: string;
+}
+/**
+ * Información del receptor del CFDI
+ */
+export interface XmlRecipient extends BaseDto {
+    /** RFC del receptor */
+    tin?: string;
+    /** Razón social */
+    legalName?: string;
+    /** Código postal */
+    zipCode?: string;
+    /** Régimen fiscal */
+    taxRegime?: string;
+    /** Uso del CFDI */
+    cfdiUse?: string;
+    /** ID fiscal extranjero */
+    foreignTaxId?: string;
+    /** Residencia fiscal */
+    fiscalResidence?: string;
+}
+/**
+ * CFDI relacionado
+ */
+export interface XmlRelated extends BaseDto {
+    /** ID del XML */
+    xmlId?: string;
+    /** Tipo de relación */
+    relationshipType?: string;
+    /** UUID del CFDI relacionado */
+    cfdiUuid?: string;
+}
+/**
+ * Impuesto del CFDI
+ */
+export interface XmlTax extends BaseDto {
+    /** Base del impuesto */
+    base?: number;
+    /** Código del impuesto */
+    tax?: string;
+    /** Tipo de impuesto */
+    taxType?: string;
+    /** Tasa o cuota */
+    rate?: number;
+    /** Importe del impuesto */
+    amount?: number;
+    /** Naturaleza del impuesto (T = Traslado, R = Retención) */
+    taxFlag?: string;
+    /** ID del XML */
+    xmlId?: string;
+}
+/**
+ * Complemento del CFDI
+ */
+export interface XmlComplement extends BaseDto {
+    /** Nombre del complemento */
+    complementName?: string;
+    /** Valor del complemento en base64 */
+    base64ComplementValue?: string;
+    /** ID del XML */
+    xmlId?: string;
+}

package/dist/types/services/download-catalog.service.d.ts

@@ -0,0 +1,29 @@
+import { CatalogDto } from '../common/catalog-dto';
+import { ApiResponse } from '../common/api-response';
+import { IFiscalapiHttpClient } from '../http/fiscalapi-http-client.interface';
+import { IDownloadCatalogService } from '../abstractions/download-catalog.inteface';
+/**
+ * Implementación del servicio de catálogos de descarga masiva
+ */
+export declare class DownloadCatalogService implements IDownloadCatalogService {
+    private readonly httpClient;
+    private readonly baseEndpoint;
+    private readonly apiVersion;
+    constructor(httpClient: IFiscalapiHttpClient, apiVersion?: string);
+    /**
+     * Construye el endpoint completo para las peticiones
+     * @param path - Ruta adicional opcional
+     * @returns URL completa del endpoint
+     */
+    private buildEndpoint;
+    /**
+     * GET /api/v4/download-catalogs
+     * Recupera todos los nombres de los catálogos de descarga masiva disponibles
+     */
+    getList(): Promise<ApiResponse<string[]>>;
+    /**
+     * GET /api/v4/download-catalogs/{catalogName}
+     * Lista todos los registros de un catálogo específico
+     */
+    listCatalog(catalogName: string): Promise<ApiResponse<CatalogDto[]>>;
+}

package/dist/types/services/download-request.service.d.ts

@@ -0,0 +1,60 @@
+import { DownloadRequest, Xml, MetadataItem } from '../models/download';
+import { IFiscalapiHttpClient } from '../http/fiscalapi-http-client.interface';
+import { BaseFiscalapiService } from './base-fiscalapi-service';
+import { IDownloadRequestService } from '../abstractions/download-request.service.interface';
+import { ApiResponse } from '../common/api-response';
+import { PagedList } from '../common/paged-list';
+import { FileResponse } from '../common/file-response';
+/**
+ * Implementación del servicio de solicitudes de descarga masiva
+ */
+export declare class DownloadRequestService extends BaseFiscalapiService<DownloadRequest> implements IDownloadRequestService {
+    /**
+     * Crea una nueva instancia del servicio de solicitudes de descarga masiva
+     * @param {IFiscalapiHttpClient} httpClient - Cliente HTTP
+     * @param {string} apiVersion - Versión de la API
+     */
+    constructor(httpClient: IFiscalapiHttpClient, apiVersion: string);
+    /**
+     * Lista los xmls descargados para un requestId.
+     *
+     * @param requestId - ID de la solicitud
+     * @returns Lista paginada de objetos Xml
+     */
+    getXmlsAsync(requestId: string): Promise<ApiResponse<PagedList<Xml>>>;
+    /**
+     * Lista los meta-items descargados para un requestId.
+     *
+     * @param requestId - ID de la solicitud
+     * @returns Lista paginada de objetos MetadataItem
+     */
+    getMetadataItemsAsync(requestId: string): Promise<ApiResponse<PagedList<MetadataItem>>>;
+    /**
+     * Downloads la lista de paquetes (archivos .zip) de un requestId.
+     *
+     * @param requestId - ID de la solicitud
+     * @returns Lista de FileResponses
+     */
+    downloadPackageAsync(requestId: string): Promise<ApiResponse<FileResponse[]>>;
+    /**
+     * Descarga el archivo crudo de solicitud SAT para un requestId.
+     *
+     * @param requestId - ID de la solicitud
+     * @returns Objeto de respuesta de archivo
+     */
+    downloadSatRequestAsync(requestId: string): Promise<ApiResponse<FileResponse>>;
+    /**
+     * Descarga la respuesta SAT para un requestId.
+     *
+     * @param requestId - ID de la solicitud
+     * @returns Objeto de respuesta de archivo
+     */
+    downloadSatResponseAsync(requestId: string): Promise<ApiResponse<FileResponse>>;
+    /**
+     * Busca solicitudes de descarga creadas en una fecha específica.
+     *
+     * @param createdAt - Fecha de creación
+     * @returns Lista de solicitudes de descarga
+     */
+    searchAsync(createdAt: Date): Promise<ApiResponse<DownloadRequest[]>>;
+}

package/dist/types/services/download-rule.service.d.ts

@@ -0,0 +1,22 @@
+import { DownloadRequest, DownloadRule } from '../models/download';
+import { IFiscalapiHttpClient } from '../http/fiscalapi-http-client.interface';
+import { BaseFiscalapiService } from './base-fiscalapi-service';
+import { IDownloadRuleService } from '../abstractions/download-rule.service.inteface';
+import { ApiResponse } from '../common/api-response';
+/**
+ * Implementación del servicio de reglas de descarga masiva
+ */
+export declare class DownloadRuleService extends BaseFiscalapiService<DownloadRule> implements IDownloadRuleService {
+    /**
+  * Crea una nueva instancia del servicio de reglas de descarga masiva
+     * @param {IFiscalapiHttpClient} httpClient - Cliente HTTP
+     * @param {string} apiVersion - Versión de la API
+     */
+    constructor(httpClient: IFiscalapiHttpClient, apiVersion: string);
+    /**
+     * Crea una regla y una solicitud de descarga masiva de prueba.
+     *
+     * @returns solicitud de descarga masiva de prueba
+     */
+    createTestRule(): Promise<ApiResponse<DownloadRequest>>;
+}

package/dist/types/services/fiscalapi-client.d.ts

@@ -1,5 +1,14 @@
-import { IFiscalapiClient, IInvoiceService, IProductService, IPersonService, IApiKeyService, ICatalogService, ITaxFileService } from '..';
+import { IFiscalapiClient } from '../abstractions/fiscalapi-client.interface';
+import { IInvoiceService } from '../abstractions/invoice-service.interface';
+import { IProductService } from '../abstractions/product-service.interface';
+import { IPersonService } from '../abstractions/person-service.interface';
+import { IApiKeyService } from '../abstractions/api-key-service.interface';
+import { ICatalogService } from '../abstractions/catalog-service.interface';
+import { ITaxFileService } from '../abstractions/tax-file-service.interface';
+import { IDownloadCatalogService } from '../abstractions/download-catalog.inteface';
 import { FiscalapiSettings } from '../common/fiscalapi-settings';
+import { IDownloadRuleService } from '../abstractions/download-rule.service.inteface';
+import { IDownloadRequestService } from '../abstractions/download-request.service.interface';
 /**
  * Cliente principal para FiscalAPI
  */
@@ -28,6 +37,18 @@ export declare class FiscalapiClient implements IFiscalapiClient {
      * Servicio de archivos fiscales
      */
     readonly taxFiles: ITaxFileService;
+    /**
+     * Servicio de catálogos de descarga masiva
+     */
+    readonly downloadCatalogs: IDownloadCatalogService;
+    /**
+     * Servicio de reglas de descarga masiva
+     */
+    readonly downloadRules: IDownloadRuleService;
+    /**
+     * Servicio de solicitudes de descarga masiva
+     */
+    readonly downloadRequests: IDownloadRequestService;
     /**
      * Crea una nueva instancia del cliente de FiscalAPI
      * @param {FiscalapiSettings} settings - Configuración

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "fiscalapi",
-  "version": "4.0.141",
-  "description": "SDK de Node.js para FiscalAPI",
+  "version": "4.0.270",
+  "description": "SDK de Node.js para Fiscalapi",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
   "files": [
     "dist/",
+    "README.md",
     "fiscalapi.ico",
     "fiscalapi.png",
     "LICENSE.txt"
@@ -59,6 +60,6 @@
     "@types/node": "^22.13.14",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   }
 }