get_sales_price_details

Instructions

Implementation Reference

• src/hotmart_mcp/tools/sales.py:255-301 (handler)

  The core handler function for the 'get_sales_price_details' tool. It accepts optional filter parameters (transaction, transaction_status, max_results, page_token, product_id, start_date, end_date, payment_type, select), builds query params, calls the GET /payments/api/v1/sales/price/details endpoint via the shared HTTP client, and returns the JSON response as a string.

  async def get_sales_price_details(
      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,
      payment_type: Optional[str] = None,
      select: Optional[str] = None,
  ) -> str:
      """Sales Price Details
      
      Retorna os detalhes de preço das vendas. Sem os filtros transaction ou transaction_status, apenas vendas com status APPROVED e COMPLETE são retornadas.
      
      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)
          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
          select: Seleção de campos customizados na resposta"""
      endpoint = "/payments/api/v1/sales/price/details"
      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 payment_type is not None:
          params["payment_type"] = payment_type
      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:8-8 (registration)

  The tool function is explicitly listed in the __all__ export list, making it importable from the sales module.

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

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

  Generic dynamic tool registration: all async functions (not starting with '_') from every module under tools_pkg are discovered via pkgutil and registered as FastMCP tools via mcp.tool(). This is where get_sales_price_details gets registered as an MCP tool.

  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/__init__.py:7-7 (registration)

  Re-exports all definitions from sales.py (including get_sales_price_details) via wildcard import.

  from .sales import *  # noqa: F401,F403

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

  Shared helper that provides the HTTP client instance used by the handler to make the API call.

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