Enviando Ordem via HTTP

Guia para Envio de Ordens via HTTP

Este documento descreve o procedimento para envio de ordens através de um endpoint, incluindo os parâmetros necessários e a forma de obtenção do token de autenticação.

1. Autenticação

Para enviar uma ordem, é necessário obter um token de autenticação. Certifique-se de seguir os passos abaixo para obter o token:

Realize a autenticação no serviço apropriado para geração de token. Observe esse link Autenticação de usuários
Use as credenciais fornecidas pela equipe de suporte ou documentação interna.
Insira o token obtido no cabeçalho da requisição HTTP, conforme descrito na seção Requisição HTTP.

2. SubscribWebBroker

Após obter o token, é obrigatório chamar o método abaixo antes de enviar a ordem.

Ao se inscrever a API passara a enviar a evolução da execuções das ordens

Endpoint para SubscribWebBroker

POST https://webbrokerhml.plugntrade.com.br:10001/Integration/SubscribWebBroker

3. URL do Endpoint

URL do Endpoint

O endpoint para envio de ordens é:

https://webbrokerhml.plugntrade.com.br:10001/Integration/SendStrategyToRobot?requestId=876595464

Atenção: O requestId é um identificador obrigatório gerado pelo cliente. Ele deve ser único para cada requisição e, de preferência, um GUID.

Formato da Requisição HTTP

A requisição deve ser feita utilizando o método POST, com o payload no formato JSON.

Exemplo de Cabeçalho HTTP:

POST /Integration/SendStrategyToRobot?requestId=876595464 HTTP/1.1
Host: webbrokerhml.plugntrade.com.br:10001
Authorization: Bearer <TOKEN>
Content-Type: application/json

Corpo da Requisição:

Exemplo de uma ordem do tipo SpreadMaker:

{
  "Side": "C",
  "Symbol": "PETR4",
  "OrderQty": 30,
  "PriceLimit": 5,
  "StartTime": "2024-10-01T10:00:00",
  "EndTime": "2024-10-01T18:15:00",
  "IgnQtyBook": 500,
  "ChangeInterval": 5,
  "MaxPercent": 30,
  "PriceWould": 6.16,
  "AddDirects": true,
  "JumpLimPrices": true,
  "ParticipateOwnVolume": false,
  "AddSameBuySellPs": true,
  "TargetStrategy": "1015",
  "BVSPAccount": "357",
  "BMFAccount": "357",
  "AccountNumber": "357"
}

4. Parâmetros do Payload

Parâmetro	Tipo	Descrição

Parâmetro	Tipo	Descrição
`Side`	String	Indica o lado da ordem: `C` para compra ou `V` para venda.
`Symbol`	String	Identificação do ativo financeiro (e.g., `PETR4`).
`OrderQty`	Inteiro	Quantidade da ordem.
`PriceLimit`	Decimal	Preço limite para a ordem.
`StartTime`	DateTime	Hora de início da estratégia (formato ISO 8601).
`EndTime`	DateTime	Hora de término da estratégia (formato ISO 8601).
`IgnQtyBook`	Inteiro	Quantidade a ignorar no livro de ofertas.
`ChangeInterval`	Inteiro	Intervalo de mudança entre ordens (em segundos).
`MaxPercent`	Inteiro	Percentual máximo permitido.
`PriceWould`	Decimal	Preço hipotético utilizado na estratégia.
`AddDirects`	Booleano	Indica se devem ser adicionadas direções à ordem.
`JumpLimPrices`	Booleano	Define se preços-limite podem ser ultrapassados.
`ParticipateOwnVolume`	Booleano	Define participação no próprio volume.
`AddSameBuySellPs`	Booleano	Define se deve adicionar o mesmo PS para compra/venda.
`TargetStrategy`	String	Estratégia alvo.
`BVSPAccount`	String	Conta na BVSP.
`BMFAccount`	String	Conta na BMF.
`AccountNumber`	String	Número da conta vinculada.

5. Respostas do Endpoint

Código HTTP	Descrição
200	Ordem enviada com sucesso.
400	Erro na validação dos parâmetros.
401	Token inválido ou expirado.
500	Erro interno no servidor.

6. Notificação de Evolução de Ordens

Importante: É imprescindível que o cliente tenha um webhook configurado para receber as notificações de evolução das ordens. Sem um webhook válido, as atualizações não poderão ser enviadas.

Após a subscrição e o envio de uma ordem, a API enviará atualizações sobre a evolução das ordens para o webhook cadastrado. Essas notificações incluirão informações detalhadas sobre o status e progresso da ordem.

Exemplo de notificações de uma ordem TWAP:

{
  "PercBook": null,
  "ChangeInterval": 5,
  "IgnQty": 0,
  "IgnQtyBook": 500,
  "ForceCompletion": true,
  "DifLast": null,
  "LastPriceMaxPercentVar": null,
  "MaxPercent": 0.0,
  "MinPercent": 0.0,
  "MaxReplacement": 1000,
  "PercFirstTrade": null,
  "PriceWould": null,
  "PriceAvgLimit": null,
  "Proclaim": true,
  "QtdIceberg": 0,
  "QtdOfferWould": 98.0,
  "QtdWould": 98.0,
  "ResetQtdStartSniper": true,
  "AddDirects": false,
  "ParticipateOwnVolume": false,
  "AddSameBuySellPs": false,
  "JumpLimPrices": false,
  "MarketAveragePrice": 0.0,
  "HedgeRatio": null,
  "SentAccumQty": null,
  "SentAveragePrice": null,
  "AccountNumber": "501",
  "BVSPAccounts": ["501"],
  "BMFAccounts": ["501"],
  "BrokerId": "PNT",
  "Coefficients": null,
  "CreateDate": "2024-12-23T14:10:30Z",
  "EndDate": "0001-01-01T00:00:00",
  "EndTime": "2024-10-11T19:00:00",
  "ErrorDescription": "Symbol TRPL4 not found.",
  "IsNewOrder": false,
  "Label": "",
  "StrategyLegs": [
    {
      "IsFinancialQty": false,
      "AvgFillPrice": 0.0,
      "CurrOpenQtyOnMkt": 0,
      "ErrorDescription": "",
      "ExchangeCode": "",
      "FilledQty": 0,
      "LastTimeExecReport": "0001-01-01T00:00:00",
      "OrderQty": 100.0,
      "PriceLimit": 33.54,
      "PriceStopLoss": 0.0,
      "Side": "C",
      "Symbol": "TRPL4",
      "ExecutionProgress": 0.0,
      "FinancialLim": 0.0,
      "Status": "",
      "MarketDif": null
    }
  ],
  "OnBehalfOfTraderId": "501",
  "OStatus": 1,
  "OStatus2": 0,
  "PriceLimits": [33.54],
  "PushId": "",
  "PushStatus": "",
  "PushValidity": "0001-01-01T00:00:00",
  "RobotId": "PNT",
  "StartTime": "2024-10-11T09:00:00",
  "StrategyId": "a84d7402-82fe-4c47-a3d3-27beebeadc52",
  "StrategyName": "TWAP",
  "StrategyStatus": "Error",
  "LastCoefficientUpdate": "2024-12-23T14:10:31.3323297+00:00",
  "SelCoeff": 0.0,
  "ExecCoeff": 0.0,
  "MarketCoeff": 0.0,
  "UsedCoeff": 0.0,
  "StrategyUniqueKey": null,
  "StratType": 1000,
  "TargetStrategy": "TWAP",
  "TraderID": "501",
  "UserId": "",
  "VirtualOrderId": 5122300002,
  "SendStrategyToClient": false,
  "ClOrdID": "72db5c73-0442-29e4-feb2-07bdefcb1f37"
}

7. Observações

Certifique-se de validar todos os parâmetros antes de enviar a requisição.
Tokens expiram após um período definido; renove o token quando necessário.
Guarde os logs das requisições para fins de auditoria.

WebBroker API