Referência MQL5Constantes, Enumeradores e EstruturasEstruturas de DadosEstrutura de uma Transação de Negociação

Estrutura de um Transação de Negociação (MqlTradeTransaction)

Ao realizar algumas ações específicas em uma conta de negociação, seu estado muda. Tais ações includem:

Envio de uma solicitação de negociação a partir de algum aplicativo MQL5 no terminal usando as funções OrderSend e OrderSendAsync e sua posterior execução.
Envio de uma solicitação de negociação por meio da interface gráfica do terminal e sua posterior execução.

Ativação de ordens pendentes e ordens de stop no servidor.
Realização de operações no lado de um servidor de negociação.

As seguintes transações de negociação são realizadas como resultado destas ações:

tratamento de uma solicitação de negociação
mudança de ordens de abertura
mudança de histórico de ordens
mudança de histórico de operações (deals)
mudança de posições

Por exemplo, ao enviar uma ordem de mercado para compra, ele é processado, para a conta cria-se a respetiva ordem para compra, a ordem é executada, excluída da lista de ordens abertas, adicionada ao histórico de ordens, a seguir, a transação respetiva é adicionada ao histórico e, finalmente, é criada uma nova posição. Todas estas ações são transações financeiras.

Para obter transações financeiras, aplicadas à conta, a MQL5 dispõe de um processador especial chamado de OnTradeTransaction (). Ao primeiro parâmetro deste processador é transferida a estrutura MqlTradeTransaction, que descreve a transação financeira.

struct MqlTradeTransaction
  {
   ulong                         deal;             // Bilhetagem da operação (deal)
   ulong                         order;            // Bilhetagem da ordem
   string                        symbol;           // Nome do ativo da negociação
   ENUM_TRADE_TRANSACTION_TYPE   type;             // Tipo de transação da negociação
   ENUM_ORDER_TYPE               order_type;       // Tipo de ordem
   ENUM_ORDER_STATE              order_state;      // Estado da ordem
   ENUM_DEAL_TYPE                deal_type;        // Tipo de operação (deal)
   ENUM_ORDER_TYPE_TIME          time_type;        // Tipo de ordem por período de ação
   datetime                      time_expiration;  // Hora de expiração da ordem
   double                        price;            // Preço
   double                        price_trigger;    // Preço de ativação de ordem tipo Stop limit
   double                        price_sl;         // Nível de Stop Loss
   double                        price_tp;         // Nível de Take Profit
   double                        volume;           // Volume em lotes
   ulong                         position;         // Position ticket
   ulong                         position_by;      // Ticket of an opposite position
  };

Descrição dos Campos

Campo	Descrição
deal	Bilhetagem (ticket) da operação.
order	Bilhetagem (ticket) da ordem.
symbol	O nome do ativo da negociação, para o qual a transação é realizada.
type	Tipo de transação de negociação. O valor pode ser um dos valores da enumeração ENUM_TRADE_TRANSACTION_TYPE.
order_type	Tipo de ordem de negociação. O valor pode ser um dos valores da enumeração ENUM_ORDER_TYPE.
order_state	Estado da ordem de negociação. O valor pode ser um dos valores da enumeração ENUM_ORDER_STATE.
deal_type	Tipo de operação. O valor pode ser um dos valores da enumeração ENUM_DEAL_TYPE.
time_type	Tipo de ordem quanto a expiração. O valor pode ser um dos valores da enumeração ENUM_ORDER_TYPE_TIME.
time_expiration	Período de expiração de uma ordem pendente (para ordens dos tipos ORDER_TIME_SPECIFIED e ORDER_TIME_SPECIFIED_DAY).
price	Preço. Dependendo do tipo de transação de negociação, ele pode ser um preço de uma ordem, de uma operação (deal), ou de uma posição.
price_trigger	Preço stop (de ativação) de uma ordem Stop Limit (ORDER_TYPE_BUY_STOP_LIMIT e ORDER_TYPE_SELL_STOP_LIMIT).
price_sl	Preço Stop Loss. Dependendo do tipo de transação de negociação, ele pode estar relacionado a uma ordem, a uma operação (deal) ou a uma posição.
price_tp	Preço Take Profit. Dependendo do tipo de transação de negociação, ele pode estar relacionado a uma ordem, a uma operação (deal) ou a uma posição.
volume	Volume em lotes. Dependendo do tipo de transação de negociação, ele pode indicar o valor corrente de uma ordem, de uma operação (deal), ou de uma posição.
position	Bilhete da posição que foi afetado pela transação.
position_by	Bilhete da posição oposta. Utiliza-se ao fechar uma posição usando outra oposta, se estiver aberta no mesmo instrumento, mas na direção oposta.

O parâmetro essencial para análise de uma transação recebida é o seu tipo, especificado no campo type. Por exemplo, se uma transação é do tipo TRADE_TRANSACTION_REQUEST (um resultado de operar uma negociação requisitada pelo servidor foi recebido), a estrutura possui apenas um campo único que é completamente preenchido - type. Outros campos não são analisados. Neste caso, nós podemos analisar dois parâmetros adicionais, request e result, submetidos ao handler OnTradeTransaction(), como mostrado abaixo.

Tendo dados sobre um tipo de operação de negociação, você pode decidir sobre a análise do estado corrente de ordens, posições e operações (deals) em um conta de negociação. Lembre-se que uma solicitação de negociação enviada ao servidor a partir do terminal pode gerar várias novas transações. A prioridade de chegada delas no terminal não é garantida.

A estrutura MqlTradeTransaction é preenchida de diferentes maneiras dependendo do tipo de transação de negociação (ENUM_TRADE_TRANSACTION_TYPE):

TRADE_TRANSACTION_ORDER_* e TRADE_TRANSACTION_HISTORY_*

Os seguintes campos na estrutura MqlTradeTransaction são preenchidos para transações de negociação relacionados a manipulação de abertura de ordens (TRADE_TRANSACTION_ORDER_ADD, TRADE_TRANSACTION_ORDER_UPDATE e TRADE_TRANSACTION_ORDER_DELETE) e histórico de ordens (TRADE_TRANSACTION_HISTORY_ADD, TRADE_TRANSACTION_HISTORY_UPDATE, TRADE_TRANSACTION_HISTORY_DELETE):

order - bilhetagem da ordem;
symbol - nome do ativo da ordem;
type - tipo de transação de negociação;
order_type - tipo de ordem;
orders_state - estado corrente da ordem;
time_type - tipo de expiração da ordem;
time_expiration - hora de expiração da ordem (para ordens tendo tipos de expiração ORDER_TIME_SPECIFIED e ORDER_TIME_SPECIFIED_DAY);
price - preço da ordem especificado por um cliente;
price_trigger - preço de stop de ordem stop limit (somente para ORDER_TYPE_BUY_STOP_LIMIT e ORDER_TYPE_SELL_STOP_LIMIT);
price_sl - Preço de ordem Stop Loss (preenchido, se especificado na ordem);
price_tp - Preço de ordem Take Profit (preenchido, se especificado na ordem);
volume - volume corrente da ordem (não preenchida). Volume inicial da ordem pode ser encontra no histórico de ordens usando a função HistoryOrders*.
position - bilhete da posição, aberta, fechada ou modificada como resultado da execução da ordem. A preenchido apenas para ordens de mercado. Não é preenchido para TRADE_TRANSACTION_ORDER_ADD.
position_by - bilhete da posição oposta. Preenche-se apenas para ordens de fechamento da posição oposta (close by).

TRADE_TRANSACTION_DEAL_*

Os seguintes campos na estrutura MqlTradeTransaction são preenchidos para transações de negociação relacionados a manipulação de operações (TRADE_TRANSACTION_DEAL_ADD, TRADE_TRANSACTION_DEAL_UPDATE e TRADE_TRANSACTION_DEAL_DELETE):

deal - bilhetagem da operação (deal);
order - bilhetagem da ordem, baseado na qual uma operação (deal) foi realizada;
symbol - nome de ativo da operação (deal);
type - tipo de transação de negociação;
deal_type - tipo de operação (deal);
price - preço de operação (deal);
price_sl - preço de Stop Loss (preenchido, se especificado na ordem, baseado na qual uma operação foi realizada);
price_tp - preço de Take Profit (preenchido, se especificado na ordem, baseado na qual uma operação foi realizada);
volume - volume de operação em lotes.
position - bilhete da posição, aberta, fechada ou modificada como resultado da execução da transação.
position_by - bilhete da posição oposta. Preenche-se apenas para transações de fechamento da posição oposta (out by).

TRADE_TRANSACTION_POSITION

Os seguintes campos na estrutura MqlTradeTransaction são preenchidos para transações de negociação relacionado a mudança de posições não conectados com execução de operações (deals) (TRADE_TRANSACTION_POSITION):

symbol - nome de ativo da posição;
type - tipo de transação de negociação;
deal_type - tipo de posição (DEAL_TYPE_BUY ou DEAL_TYPE_SELL);
price - preço médio ponderado de abertura de posição;
price_sl - preço de Stop Loss;
price_tp - preço de Take Profit;
volume - volume de posição em lotes, se ele foi alterado.
position - bilhete de posição.

Alteração de Posição (adição, alteração, encerramento), como resultado de uma execução de operação (deal), não leva a ocorrência de transação de TRADE_TRANSACTION_POSITION.

TRADE_TRANSACTION_REQUEST

Somente um campo na estrutura MqlTradeTransaction é preenchido para transações de negociação descrevendo o fato de que uma solicitação de negociação foi processada por um servidor e que o resultado do processamento foi recebido (TRADE_TRANSACTION_REQUEST):

type - tipo de transação de negociação;

Somente o campo type (tipo de transação de negociação) de ser analisado para tais transações. O segundo e terceiro parâmetros (request e result) da função OnTradeTransaction deve ser analisado para dados adicionais.

Exemplo:

input int MagicNumber=1234567;

//--- habilita a classe de negociação CTrade e declara a variável desta classe
#include <Trade\Trade.mqh>
CTrade trade;
//--- flags para instalação e exclusão de ordens pendentes
bool pending_done=false;
bool pending_deleted=false;
//--- bilhetagem da ordem pendente será armazenada aqui
ulong order_ticket;
//+------------------------------------------------------------------+
//| Função de inicialização do Expert                                |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- define o MagicNumber para marcar todas as nossas ordens
   trade.SetExpertMagicNumber(MagicNumber);
//--- solicitações de negociação serão enviadas em modo assíncrono usando a função OrderSendAsync()
   trade.SetAsyncMode(true);
//--- inicializa a variável em zero
   order_ticket=0;
//---
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Função tick (ponto) de um Expert                                 |
//+------------------------------------------------------------------+
void OnTick()
  {
//---instalando uma ordem pendente
   if(!pending_done)
     {
      double ask=SymbolInfoDouble(_Symbol,SYMBOL_ASK);
      double buy_stop_price=NormalizeDouble(ask+1000*_Point,(int)SymbolInfoInteger(_Symbol,SYMBOL_DIGITS));
      bool res=trade.BuyStop(0.1,buy_stop_price,_Symbol);
      //--- caso a função BuyStop() executou com sucesso
      if(res)
        {
         pending_done=true;
         //--- obtém um resultado da solicitação enviando para CTrade
         MqlTradeResult trade_result;
         trade.Result(trade_result);
         //--- obtém o request_id para a solicitações enviada
         uint request_id=trade_result.request_id;
         Print("Pedido foi enviado para definir uma ordem pendente. Request_ID=",request_id);
         //--- armazena a bilhetagem da ordem (será zero se usar o modo assíncrono de envio para CTrade)
         order_ticket=trade_result.order;
         //--- tudo está feito, saí cedo do handler OnTick()
         return;
        }
     }
//--- exclui a ordem pendente
   if(!pending_deleted)
      //--- verificação adicional
      if(pending_done && (order_ticket!=0))
        {
         //--- tenda excluir a ordem pendente
         bool res=trade.OrderDelete(order_ticket);
         Print("OrderDelete=",res);
         //--- quando solicitação de exclusão é enviada com sucesso
         if(res)
           {
            pending_deleted=true;
            //--- obtém o resultado da execução da solicitação
            MqlTradeResult trade_result;
            trade.Result(trade_result);
            //--- peque o ID da solicitação proveniente do resultado
            uint request_id=trade_result.request_id;
            //--- exibe no Diário
            Print("O pedido foi enviado para eliminar uma ordem pendente #",order_ticket,
                  ". Request_ID=",request_id,
                  "\r\n");
            //--- fixa a bilhetagem da ordem proveniente do resultado da solicitação
            order_ticket=trade_result.order;
           }
        }
//---
  }
//+------------------------------------------------------------------+
//| Função TradeTransaction                                          |
//+------------------------------------------------------------------+
void OnTradeTransaction(const MqlTradeTransaction &trans,
                        const MqlTradeRequest &request,
                        const MqlTradeResult &result)
  {
//--- obtém o tipo de transação como valor de enumeração
   ENUM_TRADE_TRANSACTION_TYPE type=(ENUM_TRADE_TRANSACTION_TYPE)trans.type;
//--- se a transação é a solicitação de manipulação do resultado, somente seu nome é exibido
   if(type==TRADE_TRANSACTION_REQUEST)
     {
      Print(EnumToString(type));
      //--- exibe o a string do nome da solicitação manipulada
      Print("------------RequestDescription\r\n",RequestDescription(request));
      //--- exibe a descrição do resultado da solicitação
      Print("------------ResultDescription\r\n",TradeResultDescription(result));
      //--- armazena a bilhetagem da ordem para sua exclusão na próxima manipulação em OnTick()
      if(result.order!=0)
        {
         //--- exclui esta ordem através de sua bilhetagem na próxima chamada de OnTick()
         order_ticket=result.order;
         Print(" Bilhetagem da ordem pendente ",order_ticket,"\r\n");
        }
     }
   else // exibe a descrição completa para transações de um outro tipo
//--- exibe a descriçaõ da transação recebida no Diário
      Print("------------TransactionDescription\r\n",TransactionDescription(trans));

//---
  }
//+------------------------------------------------------------------+
//| Retorna a descrição textual da transação                         |
//+------------------------------------------------------------------+
string TransactionDescription(const MqlTradeTransaction &trans)
  {
//---
   string desc=EnumToString(trans.type)+"\r\n";
   desc+="Ativo: "+trans.symbol+"\r\n";
   desc+="Bilhetagem (ticket) da operação: "+(string)trans.deal+"\r\n";
   desc+="Tipo de operação: "+EnumToString(trans.deal_type)+"\r\n";
   desc+="Bilhetagem (ticket) da ordem: "+(string)trans.order+"\r\n";
   desc+="Tipo de ordem: "+EnumToString(trans.order_type)+"\r\n";
   desc+="Estado da ordem: "+EnumToString(trans.order_state)+"\r\n";
   desc+="Ordem do tipo time: "+EnumToString(trans.time_type)+"\r\n";
   desc+="Expiração da ordem: "+TimeToString(trans.time_expiration)+"\r\n";
   desc+="Preço: "+StringFormat("%G",trans.price)+"\r\n";
   desc+="Gatilho do preço: "+StringFormat("%G",trans.price_trigger)+"\r\n";
   desc+="Stop Loss: "+StringFormat("%G",trans.price_sl)+"\r\n";
   desc+="Take Profit: "+StringFormat("%G",trans.price_tp)+"\r\n";
   desc+="Volume: "+StringFormat("%G",trans.volume)+"\r\n";
//--- retorna a string obtida
   return desc;
  }
//+------------------------------------------------------------------+
//| Retorna a descrição textual da solicitação de negociação         |
//+------------------------------------------------------------------+
string RequestDescription(const MqlTradeRequest &request)
  {
//---
   string desc=EnumToString(request.action)+"\r\n";
   desc+="Ativo: "+request.symbol+"\r\n";
   desc+="Número mágico: "+StringFormat("%d",request.magic)+"\r\n";
   desc+="Bilhetagem (ticket) da ordem: "+(string)request.order+"\r\n";
   desc+="Tipo de ordem: "+EnumToString(request.type)+"\r\n";
   desc+="Preenchimento da ordem: "+EnumToString(request.type_filling)+"\r\n";
   desc+="Ordem do tipo time: "+EnumToString(request.type_time)+"\r\n";
   desc+="Expiração da ordem: "+TimeToString(request.expiration)+"\r\n";
   desc+="Preço: "+StringFormat("%G",request.price)+"\r\n";
   desc+="Pontos de desvio: "+StringFormat("%G",request.deviation)+"\r\n";
   desc+="Stop Loss: "+StringFormat("%G",request.sl)+"\r\n";
   desc+="Take Profit: "+StringFormat("%G",request.tp)+"\r\n";
   desc+="Stop Limit: "+StringFormat("%G",request.stoplimit)+"\r\n";
   desc+="Volume: "+StringFormat("%G",request.volume)+"\r\n";
   desc+="Comentário: "+request.comment+"\r\n";
//--- retorna a string obtida
   return desc;
  }
//+------------------------------------------------------------------+
//| Retorna a desc. textual do resultado da manipulação da solic.    |
//+------------------------------------------------------------------+
string TradeResultDescription(const MqlTradeResult &result)
  {
//---
   string desc="Retcode "+(string)result.retcode+"\r\n";
   desc+="ID da solicitação: "+StringFormat("%d",result.request_id)+"\r\n";
   desc+="Bilhetagem (ticket) da ordem: "+(string)result.order+"\r\n";
   desc+="Bilhetagem (ticket) da operação: "+(string)result.deal+"\r\n";
   desc+="Volume: "+StringFormat("%G",result.volume)+"\r\n";
   desc+="Preço: "+StringFormat("%G",result.price)+"\r\n";
   desc+="Compra: "+StringFormat("%G",result.ask)+"\r\n";
   desc+="Venda: "+StringFormat("%G",result.bid)+"\r\n";
   desc+="Comentário: "+result.comment+"\r\n";
//--- retorna a string obtida
   return desc;
  }

Também Veja

Tipos de Transação de Negociação, OnTradeTransaction()

Estrutura de Resultado de Solicitação de uma Negociação (Trade)

Estrutura para Preços Correntes