get_sales_history

Instructions

Implementation Reference

• src/hotmart_mcp/tools/sales.py:11-77 (handler)

  The actual handler function for 'get_sales_history' tool. Calls the Hotmart API endpoint '/payments/api/v1/sales/history' with optional query parameters and returns the JSON result.

  async def get_sales_history(
      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,
      transaction: Optional[str] = None,
      select: Optional[str] = None,
      buyer_name: Optional[str] = None,
      buyer_email: Optional[str] = None,
      offer_code: Optional[str] = None,
      commission_as: Optional[str] = None,
      transaction_status: Optional[str] = None,
      payment_type: Optional[str] = None,
  ) -> str:
      """Sales History
      
      Retorna o histórico de vendas. Sem os filtros transaction ou transaction_status, apenas vendas com status APPROVED e COMPLETE são retornadas.
      
      Args:
          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
          transaction: Código da transação
          select: Seleção de campos customizados na resposta
          buyer_name: Nome do comprador
          buyer_email: E-mail do comprador
          offer_code: Código da oferta
          commission_as: Papel de comissão do usuário autenticado. Values: PRODUCER, COPRODUCER, AFFILIATE
          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
          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"""
      endpoint = "/payments/api/v1/sales/history"
      params = {}
      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 transaction is not None:
          params["transaction"] = transaction
      if select is not None:
          params["select"] = select
      if buyer_name is not None:
          params["buyer_name"] = buyer_name
      if buyer_email is not None:
          params["buyer_email"] = buyer_email
      if offer_code is not None:
          params["offer_code"] = offer_code
      if commission_as is not None:
          params["commission_as"] = commission_as
      if transaction_status is not None:
          params["transaction_status"] = transaction_status
      if payment_type is not None:
          params["payment_type"] = payment_type
      result = await get_client().get(endpoint, params=params)
      return json.dumps(result, indent=2)

• src/hotmart_mcp/tools/sales.py:11-25 (schema)

  Input parameters (schema) for get_sales_history: all optional, including max_results, page_token, product_id, date range, filters like buyer_name/email, sales_source, transaction, etc.

  async def get_sales_history(
      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,
      transaction: Optional[str] = None,
      select: Optional[str] = None,
      buyer_name: Optional[str] = None,
      buyer_email: Optional[str] = None,
      offer_code: Optional[str] = None,
      commission_as: Optional[str] = None,
      transaction_status: Optional[str] = None,
      payment_type: Optional[str] = None,

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

  Auto-discovery registration: server.py iterates all modules in hotmart_mcp.tools, finds each async function (including get_sales_history), and registers it via mcp.tool()(obj).

  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:1-14 (helper)

  Shared helper get_client() used by get_sales_history to obtain the HotmartClient singleton for making API calls.

  """Shared lazy singleton for the Hotmart API client."""
  
  from __future__ import annotations
  
  from hotmart_mcp.client import HotmartClient
  
  _client: HotmartClient | None = None
  
  
  def get_client() -> HotmartClient:
      global _client
      if _client is None:
          _client = HotmartClient()
      return _client

• src/hotmart_mcp/tools/sales.py:27-45 (schema)

  Documentation string describing the tool behavior and listing all possible enum values for transaction_status and payment_type.

  """Sales History
  
  Retorna o histórico de vendas. Sem os filtros transaction ou transaction_status, apenas vendas com status APPROVED e COMPLETE são retornadas.
  
  Args:
      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
      transaction: Código da transação
      select: Seleção de campos customizados na resposta
      buyer_name: Nome do comprador
      buyer_email: E-mail do comprador
      offer_code: Código da oferta
      commission_as: Papel de comissão do usuário autenticado. Values: PRODUCER, COPRODUCER, AFFILIATE
      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
      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"""