get-upnify-sales-report

Instructions

Implementation Reference

• handlers/reports.ts:8-47 (handler)

  The main handler function that authenticates with Upnify, constructs the API query parameters, fetches the sales report from the Upnify API endpoint, and returns the formatted response.

  async getSalesReport(tkIntegracion: string, reportParams: ReportParams) {
      try {
          const { token, userInfo } = await this.auth.getTokenAndUserInfo(tkIntegracion);
  
          // Construir URL con parámetros de query
          const queryParams = new URLSearchParams({
              agrupacion: reportParams.agrupacion.toString(),
              periodicidad: reportParams.periodicidad.toString(),
              anio: reportParams.anio!.toString(),
              impuestos: reportParams.impuestos!.toString()
          });
  
          const response = await fetch(`${API_URLS.UPNIFY_BASE}${ENDPOINTS.REPORTS.SALES}?${queryParams}`, {
              method: 'GET',
              headers: {
                  'token': token,
                  'Content-Type': 'application/json',
              }
          });
  
          if (!response.ok) {
              const errorText = await response.text();
              console.error('Parámetros enviados:', reportParams);
              console.error('Token usado:', token);
              console.error('Respuesta del servidor:', errorText);
              throw new Error(`Error al obtener reporte de ventas: ${response.status} ${response.statusText}. ${errorText}`);
          }
  
          const result = await response.json();
          return {
              success: true,
              message: 'Reporte de ventas obtenido exitosamente',
              data: result,
              parameters: reportParams,
              tkEmpresa: userInfo.tkEmpresa
          };
      } catch (error) {
          throw new Error(`Error al obtener reporte de ventas de Upnify: ${error instanceof Error ? error.message : error}`);
      }
  }

• main.ts:127-156 (schema)

  MCP tool input schema defining parameters for grouping, periodicity, year, and taxes inclusion with enums, defaults, and required fields.

  inputSchema: {
      type: 'object',
      properties: {
          agrupacion: {
              type: 'integer',
              description: 'Group by: 1=Executive, 2=Group, 3=Line, 17=Industry, 4=Origin, 5=Country, 6=Region',
              enum: [1, 2, 3, 17, 4, 5, 6],
              default: 17
          },
          periodicidad: {
              type: 'integer',
              description: 'Period: 4=Monthly, 3=Bimonthly, 2=Quarterly, 1=Semiannual, 5=Biweekly, 6=Weekly',
              enum: [1, 2, 3, 4, 5, 6],
              default: 6
          },
          anio: {
              type: 'integer',
              description: 'Year (2009-2025)',
              minimum: 2009,
              maximum: 2025,
              default: 2025
          },
          impuestos: {
              type: 'integer',
              description: 'Taxes: 0=Exclude, 1=Include',
              enum: [0, 1],
              default: 0
          }
      },
      required: ['agrupacion', 'periodicidad', 'anio', 'impuestos']

• main.ts:327-348 (registration)

  Tool dispatch registration in the CallToolRequestSchema handler that validates parameters, calls the reportsHandler.getSalesReport, formats response, and handles errors.

  } else if (name === 'get-upnify-sales-report') {
      const reportParams = args as any;
      if (!validateReportParams(reportParams)) {
          return createErrorResponse(
              new Error('Se requieren todos los parámetros: agrupacion, periodicidad, anio, impuestos'),
              'Validación de parámetros'
          );
      }
  
      try {
          const result = await reportsHandler.getSalesReport(tkIntegracion, reportParams);
          const parametersDescription = formatReportParameters(reportParams);
  
          return createSuccessResponse({
              success: true,
              message: 'Reporte de ventas obtenido exitosamente',
              parameters: parametersDescription,
              data: result.data
          });
      } catch (error) {
          return createErrorResponse(error, 'Error al obtener reporte de ventas de Upnify');
      }

• types/interfaces.ts:37-42 (schema)

  TypeScript interface defining the shape of ReportParams used in the handler for type safety.

  export interface ReportParams {
      agrupacion: number;
      periodicidad: number;
      anio?: number;
      impuestos?: number;
  }

• utils/validators.ts:31-38 (helper)

  Validation function ensuring all required report parameters are present before calling the handler.

  export function validateReportParams(params: any): params is ReportParams {
      return (
          params.agrupacion !== undefined &&
          params.periodicidad !== undefined &&
          params.anio !== undefined &&
          params.impuestos !== undefined
      );
  }