get_sales_participants

Instructions

Implementation Reference

• src/hotmart_mcp/tools/sales.py:141-203 (handler)

  The main handler function for the get_sales_participants tool. Calls the Hotmart API endpoint /payments/api/v1/sales/users with optional filter parameters and returns the JSON result.

  async def get_sales_participants(
      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,
      buyer_email: Optional[str] = None,
      sales_source: Optional[str] = None,
      buyer_name: Optional[str] = None,
      affiliate_name: Optional[str] = None,
      commission_as: Optional[str] = None,
      select: Optional[str] = None,
  ) -> str:
      """Sales Participants
      
      Retorna os participantes de uma venda (produtor, afiliado, coprodutor).
      
      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)
          buyer_email: E-mail do comprador
          sales_source: Origem da venda
          buyer_name: Nome do comprador
          affiliate_name: Nome do afiliado
          commission_as: Papel de comissão do usuário autenticado. Values: PRODUCER, COPRODUCER, AFFILIATE
          select: Seleção de campos customizados na resposta"""
      endpoint = "/payments/api/v1/sales/users"
      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 buyer_email is not None:
          params["buyer_email"] = buyer_email
      if sales_source is not None:
          params["sales_source"] = sales_source
      if buyer_name is not None:
          params["buyer_name"] = buyer_name
      if affiliate_name is not None:
          params["affiliate_name"] = affiliate_name
      if commission_as is not None:
          params["commission_as"] = commission_as
      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:141-155 (schema)

  The function signature defines the input schema (all optional parameters) and return type (str) for this tool.

  async def get_sales_participants(
      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,
      buyer_email: Optional[str] = None,
      sales_source: Optional[str] = None,
      buyer_name: Optional[str] = None,
      affiliate_name: Optional[str] = None,
      commission_as: Optional[str] = None,
      select: Optional[str] = None,
  ) -> str:

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

  Auto-discovers and registers all async functions from tools modules (including get_sales_participants) as MCP tools.

  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/tools/sales.py:8-9 (registration)

  Exports get_sales_participants from the sales module, making it importable for tool discovery.

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

• src/hotmart_mcp/_shared.py:10-14 (helper)

  Shared helper that provides the HotmartClient singleton used by get_sales_participants to make the API call.

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