get-upnify-pending-payments

Instructions

Implementation Reference

• handlers/reports.ts:49-88 (handler)

  Core handler function that authenticates, constructs the API URL with grouping and periodicity parameters, fetches the pending payments data from Upnify, and returns formatted response with total count.

  async getPendingPayments(tkIntegracion: string, reportParams: Pick<ReportParams, 'agrupacion' | 'periodicidad'>) {
      try {
          const { token, userInfo } = await this.auth.getTokenAndUserInfo(tkIntegracion);
  
          // Construir URL con parámetros de query para cobros pendientes
          const queryParams = new URLSearchParams({
              agrupacion: reportParams.agrupacion.toString(),
              periodicidad: reportParams.periodicidad.toString()
          });
  
          const response = await fetch(`${API_URLS.UPNIFY_BASE}${ENDPOINTS.REPORTS.PENDING_PAYMENTS}?${queryParams}`, {
              method: 'GET',
              headers: {
                  'token': token,
                  'Content-Type': 'application/json',
                  'User-Agent': 'UpnifyMCP/1.0'
              }
          });
  
          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 cobros pendientes: ${response.status} ${response.statusText}. ${errorText}`);
          }
  
          const result = await response.json();
          return {
              success: true,
              message: 'Cobros pendientes obtenidos exitosamente',
              data: result,
              parameters: reportParams,
              total: result.length || 0,
              tkEmpresa: userInfo.tkEmpresa
          };
      } catch (error) {
          throw new Error(`Error al obtener cobros pendientes de Upnify: ${error instanceof Error ? error.message : error}`);
      }
  }

• main.ts:159-180 (schema)

  Input schema definition specifying agrupacion and periodicidad parameters with enums, descriptions, defaults, and required fields for tool validation.

  {
      name: 'get-upnify-pending-payments',
      description: 'Get pending payments report from Upnify with customizable grouping and period options',
      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: 1
              },
              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: 4
              }
          },
          required: ['agrupacion', 'periodicidad']
      }
  },

• main.ts:350-372 (registration)

  Tool dispatch registration in CallToolRequestSchema handler that validates inputs, calls the reportsHandler.getPendingPayments, formats parameters, and constructs the MCP response.

  } else if (name === 'get-upnify-pending-payments') {
      const reportParams = args as any;
      if (!reportParams.agrupacion || !reportParams.periodicidad) {
          return createErrorResponse(
              new Error('Se requieren todos los parámetros: agrupacion, periodicidad'),
              'Validación de parámetros'
          );
      }
  
      try {
          const result = await reportsHandler.getPendingPayments(tkIntegracion, reportParams);
          const parametersDescription = formatPendingPaymentsParameters(reportParams);
  
          return createSuccessResponse({
              success: true,
              message: 'Cobros pendientes obtenidos exitosamente',
              parameters: parametersDescription,
              total: result.total,
              data: result.data
          });
      } catch (error) {
          return createErrorResponse(error, 'Error al obtener cobros pendientes de Upnify');
      }

• utils/validators.ts:65-70 (helper)

  Helper function to format agrupacion and periodicidad parameters into human-readable strings using predefined labels for display in responses.

  export function formatPendingPaymentsParameters(params: Pick<ReportParams, 'agrupacion' | 'periodicidad'>) {
      return {
          agrupacion: `${params.agrupacion} (${REPORT_LABELS.AGRUPACION[params.agrupacion as keyof typeof REPORT_LABELS.AGRUPACION] || 'Desconocido'})`,
          periodicidad: `${params.periodicidad} (${REPORT_LABELS.PERIODICIDAD[params.periodicidad as keyof typeof REPORT_LABELS.PERIODICIDAD] || 'Desconocido'})`
      };
  }