get_sales_summary

Instructions

Implementation Reference

• src/hotmart_mcp/tools/sales.py:80-138 (handler)

  The main handler function for the get_sales_summary tool. Calls the Hotmart API endpoint /payments/api/v1/sales/summary with optional query parameters and returns JSON.

  async def get_sales_summary(
      transaction: Optional[str] = None,
      transaction_status: Optional[str] = None,
      max_results: Optional[int] = None,
      page_token: Optional[str] = None,
      product_id: Optional[int] = None,
      start_date: Optional[int] = None,
      end_date: Optional[int] = None,
      sales_source: Optional[str] = None,
      affiliate_name: Optional[str] = None,
      payment_type: Optional[str] = None,
      offer_code: Optional[str] = None,
      select: Optional[str] = None,
  ) -> str:
      """Sales Summary
      
      Retorna o resumo das vendas.
      
      Args:
          transaction: Código da transação
          transaction_status: Status da transação. Values: APPROVED, BLOCKED, CANCELLED, CHARGEBACK, COMPLETE, EXPIRED, NO_FUNDS, OVERDUE, PARTIALLY_REFUNDED, PRE_ORDER, PRINTED_BILLET, PROCESSING_TRANSACTION, PROTESTED, REFUNDED, STARTED, UNDER_ANALISYS, WAITING_PAYMENT
          max_results: Número máximo de resultados por página
          page_token: Token de paginação para a próxima página
          product_id: ID do produto
          start_date: Data inicial (timestamp em milissegundos desde epoch)
          end_date: Data final (timestamp em milissegundos desde epoch)
          sales_source: Origem da venda
          affiliate_name: Nome do afiliado
          payment_type: Tipo de pagamento. Values: BILLET, CASH_PAYMENT, CREDIT_CARD, DIRECT_BANK_TRANSFER, DIRECT_DEBIT, FINANCED_BILLET, FINANCED_INSTALLMENT, GOOGLE_PAY, HOTCARD, HYBRID, MANUAL_TRANSFER, PAYPAL, PAYPAL_INTERNACIONAL, PICPAY, PIX, SAMSUNG_PAY, WALLET
          offer_code: Código da oferta
          select: Seleção de campos customizados na resposta"""
      endpoint = "/payments/api/v1/sales/summary"
      params = {}
      if transaction is not None:
          params["transaction"] = transaction
      if transaction_status is not None:
          params["transaction_status"] = transaction_status
      if max_results is not None:
          params["max_results"] = max_results
      if page_token is not None:
          params["page_token"] = page_token
      if product_id is not None:
          params["product_id"] = product_id
      if start_date is not None:
          params["start_date"] = start_date
      if end_date is not None:
          params["end_date"] = end_date
      if sales_source is not None:
          params["sales_source"] = sales_source
      if affiliate_name is not None:
          params["affiliate_name"] = affiliate_name
      if payment_type is not None:
          params["payment_type"] = payment_type
      if offer_code is not None:
          params["offer_code"] = offer_code
      if select is not None:
          params["select"] = select
      result = await get_client().get(endpoint, params=params)
      return json.dumps(result, indent=2)

• src/hotmart_mcp/tools/sales.py:80-92 (schema)

  Input schema/type annotations for the get_sales_summary function — all parameters are Optional with str or int types, returning str.

  async def get_sales_summary(
      transaction: Optional[str] = None,
      transaction_status: Optional[str] = None,
      max_results: Optional[int] = None,
      page_token: Optional[str] = None,
      product_id: Optional[int] = None,
      start_date: Optional[int] = None,
      end_date: Optional[int] = None,
      sales_source: Optional[str] = None,
      affiliate_name: Optional[str] = None,
      payment_type: Optional[str] = None,
      offer_code: Optional[str] = None,
      select: Optional[str] = None,

• src/hotmart_mcp/server.py:21-37 (registration)

  Auto-discovery registration: iterates all tool modules and registers every async function (including get_sales_summary) via FastMCP's mcp.tool() decorator.

  def _discover_and_register_tools() -> int:
      """Import all modules under hotmart_mcp.tools and register async functions."""
      registered = 0
  
      for module_info in pkgutil.iter_modules(tools_pkg.__path__, prefix=f"{tools_pkg.__name__}."):
          if module_info.name.endswith("__init__"):
              continue
  
          module = importlib.import_module(module_info.name)
  
          for name, obj in inspect.getmembers(module, iscoroutinefunction):
              if name.startswith("_"):
                  continue
              mcp.tool()(obj)
              registered += 1
  
      return registered

• src/hotmart_mcp/_shared.py:7-15 (helper)

  Shared helper: get_client() returns a singleton HotmartClient instance used by get_sales_summary to make the API call.

  _client: HotmartClient | None = None
  
  
  def get_client() -> HotmartClient:
      global _client
      if _client is None:
          _client = HotmartClient()
      return _client

• src/hotmart_mcp/tools/sales.py:8-8 (registration)

  Module-level __all__ export listing get_sales_summary as a publicly exported tool function from the sales module.

  __all__ = ["get_sales_history", "get_sales_summary", "get_sales_participants", "get_sales_commissions", "get_sales_price_details", "refund_sale"]