guia api btb 2 - clientes.b3.com.brclientes.b3.com.br/data/files/ac/13/54/d7... · guia api btb 2.0...
Post on 27-Jul-2020
15 Views
Preview:
TRANSCRIPT
GUIA API BTB 2.0
05/04/2019 INFORMAÇÃO PÚBLICA
SUMÁRIO
1 HISTÓRICO DE VERSÕES .......................................................................... 4
2 INTRODUÇÃO .............................................................................................. 5
3 VISÃO GERAL ............................................................................................. 5
3.1 Verbos HTTP – API - BTB ........................................................................ 5
3.2 Uso do POST ............................................................................................ 6
3.3 Uso do GET .............................................................................................. 7
3.4 Endpoint ................................................................................................... 7
3.5 Restrições................................................................................................. 7
4 ENDEREÇOS DA API DO BTB ................................................................... 8
5 SWAGGER ................................................................................................... 8
6 APIS BTB ..................................................................................................... 8
6.1 Order ......................................................................................................... 9
6.1.1 Inclusão de ordem ................................................................................... 9
6.1.2 Fechamento Doador .............................................................................. 10
6.1.3 Fechamento Tomador ........................................................................... 12
6.1.4 Cancelar Ordem ..................................................................................... 13
6.1.5 Cancelar todas as ordens ..................................................................... 14
6.1.6 Consultar Ordem .................................................................................... 15
GUIA API BTB 2.0
3 INFORMAÇÃO PÚBLICA
6.1.7 Consultar Lista de Ordens .................................................................... 17
6.1.8 Consultar Situação da Ordem ............................................................... 20
6.2 Book ........................................................................................................ 21
6.2.1 Consultar Ofertas Disponíveis .............................................................. 21
6.2.2 Consultar Melhores Ofertas .................................................................. 23
6.2.1 Consultar Instrumentos ........................................................................ 24
6.3 Trade ....................................................................................................... 25
6.3.1 Consultar Negócios Realizados ........................................................... 25
6.3.2 Consultar Negócio ................................................................................. 27
6.3.3 Consultar Lista de Negócios ................................................................. 29
6.3.4 Consultar Situação do Negócio ............................................................ 32
6.4 Event ....................................................................................................... 33
6.4.1 Consultar Eventos ................................................................................. 33
7 FLUXOS DE NEGÓCIO .............................................................................. 35
8 SEGURANÇA ............................................................................................. 35
8.1 Mutual SSL (Two Way SSL) ................................................................... 35
8.2 Pinagem de certificado .......................................................................... 36
8.3 Token de assinatura AWS (Amazon Web Services) ........................... 37
GUIA API BTB 2.0
4 INFORMAÇÃO PÚBLICA
1 HISTÓRICO DE VERSÕES
Data Versão Descrição
Fevereiro/2019 1.0 Versão Inicial
Abril/2019 2.0 Formas de utilização, segurança e fluxo de negócios
GUIA API BTB 2.0
5 INFORMAÇÃO PÚBLICA
2 INTRODUÇÃO
A API do BTB 1.0 disponibiliza endpoints web, construídos no padrão REST
(Representational State Transfer), que viabilizam a realização de acesso e
operação no sistema BTB - Negociação Eletrônica de Empréstimo de Ativos,
desenvolvido pela [B]3, para consulta de cotações, envio, agressão de ordens, e
consulta de lista de ordens próprias.
As APIs (Application Programming Interface) WEB possibilitam aos participantes
do BTB que não possuem acesso direto às redes privadas da [B]3,
desenvolverem suas aplicações no padrão server-to-server, para
automatizarem seus processos de negociação de empréstimo de ativos.
3 VISÃO GERAL
3.1 Verbos HTTP – API - BTB
Para as APIs do BTB serão utilizados somente os verbos GET (para
recuperar mensagens) e POST (Para enviar mensagens). Os verbos HTTP
DELETE, PUT e HEAD não são suportados.
GUIA API BTB 2.0
6 INFORMAÇÃO PÚBLICA
3.2 Uso do POST
GUIA API BTB 2.0
7 INFORMAÇÃO PÚBLICA
3.3 Uso do GET
3.4 Endpoint
URI base (todas as URIs iniciam com): /BTBWebApi/api/v1.0/
Exemplo de uma URL completa, para o ambiente de produção, referente a mensagem “order/entry”:
https://api-btb.b3.com.br/BTBWebApi/api/v1.0/order/entry
3.5 Restrições
Estamos avaliando restrições para o uso de alguns dos métodos
disponibilizados e devemos informar maiores detalhes em momento
oportuno.
Os métodos em avaliação estão destacados no item “6 APIS BTB”.
GUIA API BTB 2.0
8 INFORMAÇÃO PÚBLICA
4 ENDEREÇOS DA API DO BTB
A B3 possui dois ambientes, um dedicado a certificação dos participantes e outro ambiente dedicado à produção. Seguem os endereços para conexão referente a cada ambiente:
• Certificação: Será divulgado assim que estiver disponível.
• Produção: Será divulgado assim que estiver disponível.
5 SWAGGER
A documentação técnica detalhada das APIs do BTB está disponível no Swagger em: http://clientes.b3.com.br/pt_br/produtos-e-servicos/sobre/negociacao-eletronica-de-emprestimo-de-ativos.htm
Aba: “Material de apoio” > Link: “REST API Swagger”
6 APIS BTB
Abaixo estão listadas as mensagens, com a estrutura dos atributos e domínios que podem ser utilizados no processo de negociação eletrônica de empréstimos. O arquivo Swagger, fornece estes mesmos métodos e parâmetros.
6.1 Order
6.1.1 Inclusão de ordem
Verbo Método Descrição
POST order/entry Inclusão de ordem – Inclui uma ordem no livro de ofertas
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante
1..1 Número identificação participante Party/code Número identificação participante Sim string 35
1..1 Investidor Party/Account/number Investidor do participante de negociação Sim string 35
2 Informações
do custodiante
0..1 Custodiante Custodian/code Agente de custódia Não string 35
0..1 Investidor custodiante Custodian/Account/number Investidor do agente de custódia Não string 35
3 Informações
do instrumento
1..1 Código de negociação Security/symbol Código de negociação Sim string 12
4 Informações
da ordem
1..1 Prazo de liquidação Offer/daysToSettlementIndicator Prazo de liquidação 0 - D+0 1 - D+1
Sim int 1
0..1 Indicador de ordem certificada Offer/certifiedOfferIndicator Indicador de ordem certificada True - Sim False - Não
Sim boolean 1
1..1 Quantidade Offer/quantity Quantidade de ativos para alugar Sim BigInt
1..1 Taxa Offer/rate Taxa Sim Decimal (11,5)
1..1 Data de validade Offer/expirationDate Data de validade da ordem Sim date
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Status
Requisição
0..1 Número da ordem Offer/code Número da ordem Não string 35
0..1 Situação da ordem Offer/offerStatus Situação da ordem
1 - Cancelada 9 - Fechada 11 - Disponível 32 - Aguardando Autorização Custodiante 34 - Rejeitada 60 - Aguardando Autorização Carrying 70 - Ordem em processamento pela clearing
Não int
0..1 Código de erro BusinessStatus/code Código de erro http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.2 Fechamento Doador
Verbo Método Descrição
POST order/hitLender Fechamento Doador – Agride uma ordem doadora específica no livro de ofertas
1..1 Tipo de ordem Offer/OfferType/code Tipo de ordem 1 - Doadora 2 - Tomadora
Sim string 1
0.1 Carteira Offer/Finality/code Carteira de origem/destino dos ativos Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante
1..1 Número identificação participante tomador
BorrowerParty/code Número identificação participante tomador
Sim string 35
1..1 Investidor tomador BorrowerParty/Account/number Investidor do participante de negociação tomador
Sim string 35
2 Informações
do custodiante
0..1 Custodiante tomador BorrowerCustodian/code Custodiante tomador Não string 35
0..1 Investidor do custodiante tomador BorrowerCustodian/Account/number
Investidor do custodiante tomador Não string 35
3 Informações
da ordem
1..1 Número da ordem doadora LenderOffer/code Número da ordem doadora Sim string 35
1.1 Quantidade LenderOffer/quantity Quantidade de ativos para tomar Sim BigInt
0.1 Carteira do tomador LenderOffer/BorrowerFinality/code Carteira de destino dos ativos no tomador
Não int
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações do Negócio
0..1 Número do negócio Trade/code Número do negócio Não string 35
0..1 Situação do negócio Trade/tradeStatus Situação do negócio
4 - Fechado 7 - Rejeitado 48 - Aguardando autorização 65 - Aguardando validação clearing 62 - Em processamento pela Clearing 71 - Cancelado
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
6.1.3 Fechamento Tomador
Verbo Método Descrição
POST order/hitBorrower Fechamento Tomador – Agride uma ordem tomadora específica no livro de ofertas
Requisição:
2 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante
1..1 Número identificação participante doador
LenderParty/code Número identificação participante doador
Sim string 35
1..1 Investidor doador LenderParty/Account/number Investidor do participante de negociação doador
Sim string 35
2 Informações
do custodiante
0..1 Custodiante doador LenderCustodian/code Custodiante doador Não string 35
0..1 Investidor do custodiante doador LenderCustodian/Account/number Investidor do custodiante doador Não string 35
3 Informações
da ordem
1..1 Número da ordem tomadora BorrowerOffer/code Número da ordem tomadora Sim string 35
1.1 Quantidade BorrowerOffer/quantity Quantidade de ativos para alugar Sim BigInt
1.1 Indicador de ordem certificada BorrowerOffer/certifiedOfferIndicator Indicador de ordem certificada True - Sim False - Não
Sim boolean 1
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações do Negócio
0..1 Número do negócio Trade/code Número do negócio Não string 35
0..1 Situação do negócio Trade/tradeStatus Situação do negócio
4 - Fechado 7 - Rejeitado 48 - Aguardando autorização 65 - Aguardando validação clearing 62 - Em processamento pela Clearing 71 - Cancelado
Não int
2 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.4 Cancelar Ordem
Verbo Método Descrição
POST order/cancel Cancelar Ordem - Cancela uma ordem específica no livro de ofertas
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações
da ordem 1..1 Número da ordem Offer/code Número da ordem a ser cancelada Sim string 35
0.1 Carteira do doador BorrowerOffer/LenderFinality/code Carteira de origem dos ativos no doador
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Status
Requisição
1..1 Número da ordem Offer/code Número da ordem Sim string 35
0..1 Situação da ordem Offer/offerStatus Situação da ordem
1 - Cancelada 9 - Fechada 11 - Disponível 32 - Aguardando Autorização Custodiante 34 - Rejeitada 60 - Aguardando Autorização Carrying 70 - Em processamento pela clearing
Não int
0..1 Código de erro BusinessStatus/code Código de erro http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.5 Cancelar todas as ordens
Verbo Método Descrição
POST order/cancel/all
Cancelar Todas as Ordens - Cancela todas as ordens de um participante específico disponíveis no livro de ofertas
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Participante 1..1 Número identificação participante Party/code Número identificação participante Sim string 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Status
Requisição
0..1 Situação da solicitação Offer/offerStatus Situação da solicitação 62 - Em processamento pela Clearing Não int
0..1 Código de Erro BusinessStatus/code Código de erro http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.6 Consultar Ordem
Verbo Método Descrição
GET order/{code} Consultar Ordem - Retorna uma ordem específica incluída pelo Buy-Side
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Bloco de Informação Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações da ordem 1..1 Número da ordem code Número da ordem Sim string 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante
0..1 Número identificação participante
Offer/Party/code Número identificação participante
Não string 35
0..1 Nome do participante Offer/Party/name Nome do participante Não string 60
0..1 Investidor Offer/Party/Account/number Investidor do participante de negociação
Não string 35
0..1 Nome do investidor Offer/Party/Account/name Nome do investidor Não string 60
2 Informações
do custodiante
0..1 Custodiante Offer/Custodian/code Agente de custódia Não string 35
0..1 Nome do custodiante Offer/Custodian/name Nome do custodiante Não string 60
0..1 Investidor custodiante Offer/Custodian/Account/ number
Investidor do agente de custódia
Não string 35
0..1 Nome do investidor custodiante
Offer/Custodian/Account/ name
Nome do investidor do agente de custodia
Não string 60
3 Informações
do instrumento
0..1 Código de negociação Offer/Security/symbol Código de negociação Não string 12
4 Informações
da ordem
0..1 Número da ordem Offer/code Número da ordem Não string 35
0..1 Prazo de liquidação Offer/ daysToSettlementIndicator
Prazo de liquidação 0 - D+0 1 - D+1
Não int 1
0..1 Indicador de ordem certificada
Offer/certifiedOfferIndicator Indicador de ordem certificada
True - Sim False - Não
Não boolean 1
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..1 Quantidade Original Offer/originalQuantity Quantidade original de ativos para alugar
Não BigInt
0..1 Quantidade Disponível Offer/quantity Quantidade disponível de ativos para alugar
Não BigInt
0..1 Taxa Offer/rate Taxa Não Decimal(1
1,5)
0..1 Data de Validade Offer/expirationDate Data de validade da ordem
Não date
0..1 Situação da ordem Offer/orferStatus Situação da ordem
1 - Cancelada 9 - Fechada 11 - Disponível 32 - Aguardando Autorização Custodiante 34 - Rejeitada 60 - Aguardando Autorização Carrying 70 - Em processamento pela clearing
Não int
0..1 Tipo de ordem Offer/OfferType/code Tipo de ordem 1 - Doadora 2 - Tomadora
Não string 1
0..1 Carteira Offer/Finality/code Carteira de origem/destino dos ativos
Não int
5 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.7 Consultar Lista de Ordens
Verbo Método Descrição
GET order/list?partyCode=&number=&symbol=
&daysToSettlementIndicator=&offerCode=&offerTypeCode=
Consultar Lista de Ordens - Retorna lista de ordens incluídas pelo Buy-Side. Restrição: Em avaliação
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Caso necessite obter informações atualizadas das ordens, recomendamos o uso do método “/event”
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do
Atributo Domínio Obrigatório?
Tipo de Dado
Tamanho Dado
1 Participante
0..1 Número identificação participante
partyCode Número identificação participante
Sim string 35
0..1 Investidor number Investidor do participante de negociação
Não string 35
2 Informações
do instrumento
0..1 Código de negociação symbol Código de negociação
Não string 12
3 Informações
da ordem
0..1 Número da ordem offerCode Número da ordem
Não string 35
0..1 Prazo de liquidação daysToSettlementIndicator Prazo de liquidação
0 - D+0 1 - D+1
Não int 1
0..1 Tipo de ordem offerTypeCode Tipo da ordem 1 - Doadora 2 - Tomadora
Não int 1
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante 0..*
Número identificação participante
OfferList/{0..*}/Party/code Número identificação participante
Não string 35
0..* Nome do participante
OfferList/{0..*}/Party/name Nome do participante Não string 60
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..* Investidor OfferList/{0..*}/Party/Account/ number
Investidor do participante de negociação
Não string 35
0..* Nome do investidor OfferList/{0..*}/Party/Account/name Nome do investidor Não string 60
2 Informações
do custodiante
0..* Custodiante OfferList/{0..*}/Custodian/code Agente de custódia Não string 35
0..* Nome do custodiante
OfferList/{0..*}/Custodian/name Nome do custodiante Não string 60
0..* Investidor custodiante
OfferList/{0..*}/Custodian/Account/number
Investidor do agente de custódia
Não string 35
0..* Nome do investidor custodiante
OfferList/{0..*}/Custodian/Account/name
Nome do investidor do agente de custodia
Não string 60
3 Informações
do instrumento
0..* Código de negociação
OfferList/{0..*}/Security/symbol Código de negociação Não string 12
4 Informações
da ordem
0..* Número da ordem OfferList/{0..*}/code Número da ordem Não string 35
0..* Prazo de liquidação OfferList/{0..*}/ daysToSettlementIndicator
Prazo de liquidação 0 - D+0 1 - D+1
Não int 1
0..* Indicador de ordem certificada
OfferList/{0..*}/ certifiedOfferIndicator
Indicador de ordem certificada
True - Sim False - Não
Não boolean 1
0..* Quantidade original OfferList/{0..*}/originalQuantity Quantidade original de ativos para alugar
Não BigInt
0..* Quantidade disponível
OfferList/{0..*}/quantity Quantidade disponível de ativos para alugar
Não BigInt
0..* Taxa OfferList/{0..*}/rate Taxa Não Decimal(
11,5)
0..* Data de validade OfferList/{0..*}/expirationDate Data de validade da ordem
Não date
0..* Situação da ordem OfferList/{0..*}/offerStatus Situação da ordem
1 - Cancelada 9 - Fechada 11 - Disponível 32 - Aguardando Autorização Custodiante 34 - Rejeitada 60 - Aguardando Autorização Carrying 70 - Em processamento pela clearing
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..* Tipo de ordem OfferList/{0..*}/OfferType/code Tipo de ordem 1 - Doadora 2 - Tomadora
Não string 1
0..* Carteira OfferList/{0..*}/Finality/code Carteira de origem/destino dos ativos
Não int
5 Status
Requisição
1..1 Quantidade total de registros da pesquisa
OfferList/{0..*}/TrafficInformation/ returnRecordQuantity
Quantidade total de registros da pesquisa
Sim int
0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.1.8 Consultar Situação da Ordem
Verbo Método Descrição
GET order/status/{code} Consultar Situação da Ordem – Retorna situação de uma ordem específica
Requisição:
Bloco de Informação Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações da ordem 1..1 Número da ordem code Número da ordem Sim string 35
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações
da ordem
0..1 Número da ordem Offer/code Número da ordem Não string 35
0..1 Situação da ordem Offer/offerStatus Situação da ordem
1 - Cancelada 9 - Fechada 11 - Disponível 32 - Aguardando Autorização Custodiante 34 - Rejeitada 60 - Aguardando Autorização Carrying 70 - Ordem em processamento pela clearing
Não int
2 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.2 Book
6.2.1 Consultar Ofertas Disponíveis
Verbo Método Descrição
GET book/list/{symbol}/{daysToSettlementIndicator}
Consultar Ofertas Disponíveis – Retorna as 100 melhores ofertas disponíveis de um determinado instrumento
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações
do instrumento
1..1 Código de negociação symbol Código de negociação Sim string 12
2 Informações
da ordem 1..1 Prazo de liquidação daysToSettlementIndicator Prazo de liquidação
0 - D+0 1 - D+1
Sim int 1
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do
Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações
do instrumento
0..1 Código de negociação
Security/symbol Código de negociação
Não string 12
2 Informações
da ordem Doadora
0..1 Número da ordem
Security/LenderOfferList/code Número da ordem Não string 35
0..1 Quantidade Security/LenderOfferList/quantity Quantidade de ativos para alugar
Não BigInt
0..1 Taxa Security/LenderOfferList/rate Taxa Não Decimal(11,5)
0..1 Número identificação participante
Security/LenderOfferList/Party/code Número identificação participante
Não string 35
3 Informações
da ordem Tomadora
0..1 Número da ordem
Security/BorrowerOfferList/code Número da ordem Não string 35
0..1 Quantidade Security/BorrowerOfferList/quantity Quantidade de ativos para alugar
Não BigInt
0..1 Taxa Security/BorrowerOfferList/rate Taxa Não Decimal(11,5)
0..1 Número identificação participante
Security/BorrowerOfferList/Party/code Número identificação participante
Não string 35
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
4 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.2.2 Consultar Melhores Ofertas
Verbo Método Descrição
GET book/top/{symbol}/{daysToSettlementIndicator}
Consultar Melhores Ofertas – Retorna a melhor oferta disponível para um ou mais instrumentos, limitado a 50 instrumentos
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações
do instrumento
1..* Código de negociação symbol Código de negociação Sim string 12
2 Informações
da ordem 1..1 Prazo de Liquidação daysToSettlementIndicator Prazo de liquidação
0 - D+0 1 - D+1
Sim int 1
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações
do instrumento
0..* Código de negociação SecurityList/symbol Código de negociação Não string 12
2 0..* Número da ordem SecurityList/LenderOffer/code Número da ordem Não string 35
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Informações da ordem Doadora
0..* Quantidade SecurityList/LenderOffer/quantity Quantidade de ativos para alugar
Não BigInt
0..* Taxa SecurityList/LenderOffer/rate Taxa Não Decimal(1
1,5)
0..* Número identificação participante
SecurityList/LenderOffer/Party/code Número identificação participante
Não string 35
3 Informações
da ordem Tomadora
0..* Número da ordem SecurityList/BorrowerOffer/code Número da ordem Não string 35
0..* Quantidade SecurityList/BorrowerOffer/quantity Quantidade de ativos para alugar
Não BigInt
0..* Taxa SecurityList/BorrowerOffer/rate Taxa Não Decimal(1
1,5)
0..* Número identificação participante
SecurityList/BorrowerOffer/Party/code Número identificação participante
Não string 35
4 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
6.2.1 Consultar Instrumentos
Verbo Método Descrição
GET
/v1.0/SecurityLending/List
Consultar Instrumentos – Retorna os instrumentos disponíveis para empréstimo. Restrição: Em avaliação
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Sem parâmetros
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações
do instrumento
0..*
Código de Negociação SecurityList/symbol Código de Negociação Não string 12
Descrição do código de negociação
SecurityList/Description Descrição do instrumento Não string 100
6.3 Trade
6.3.1 Consultar Negócios Realizados
Verbo Método Descrição
GET
trade/all/{symbol}/{daysToSettlementIndicator}
Consultar Negócios Realizados – Retorna lista de negócios realizados pelo mercado de um determinado instrumento Restrição: Em avaliação
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações
do instrumento
1..1 Código de negociação symbol Código de negociação Sim string 12
2 Informações
da ordem 1..1 Prazo de liquidação daysToSettlementIndicator Prazo de liquidação
0 - D+0 1 - D+1
Sim int 1
Retorno:
Bloco de Informação
Número de Ocorrência
s Nome Swagger Definição do Atributo Domínio Obrigatório?
Tipo de Dado
Tamanho Dado
1 Informaçõe
s do instrumento
0..1 Código de negociação Security/symbol Código de negociação Não string 12
2 Informações da ordem
0..1 Quantidade TradeList/quantity Quantidade de ativos negociados
Não BigInt
0..1 Taxa TradeList/rate Taxa Não Decimal (11,5)
0..1 Data e hora do negócio
TradeList/date Data e hora do negócio Não date
3 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
6.3.2 Consultar Negócio
Verbo Método Descrição
GET trade/{code} Consultar Negócio - Retorna um negócio específico
Requisição:
Bloco de Informação Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações do Negócio 1..1 Número do negócio code Número do negócio Sim string 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Participante
0..1 Número identificação participante
Trade/Party/party/code Número identificação participante
Não string 35
0..1 Nome do participante Trade/Party/party/name Nome do participante Não string 60
0..1 Investidor Trade/Party/party/Account/number Investidor do participante de negociação
Não string 35
0..1 Nome do investidor Trade/Party/party/Account/name Nome do investidor Não string 60
0..1 Número identificação participante contraparte
Trade/Party/CounterParty/code Número identificação participante contraparte
Não string 35
0..1 Nome do participante contraparte
Trade/Party/CounterParty/name Nome do participante contraparte
Não string 60
2 Informações
do custodiante
0..1 Custodiante Trade/Custodian/code Custodiante Não string 35
0..1 Nome do custodiante Trade/Custodian/name Nome do custodiante Não string 60
0..1 Investidor custodiante
Trade/Custodian/Account/number Investidor do custodiante Não string 35
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..1 Nome do investidor custodiante
Trade/Custodian/Account/name Nome do investidor do custodiante
Não string 60
3 Informações
do instrumento
0..1 Código de negociação Trade/Security/symbol Código de negociação Não string 12
4 Informações do Negócio
0..1 Número do negócio Trade/code Número do negócio Não string 35
0..1 Prazo de liquidação Trade/daysToSettlementIndicator Prazo de liquidação 0 - D+0 1 - D+1
Não int 1
0..1 Data de negociação Trade/date Data de negociação Não dateTime
0..1 Quantidade Trade/quantity Quantidade de ativos negociados
Não BigInt
0..1 Data de vencimento Trade/expirationDate Data de vencimento do negócio
Não date
0..1 Taxa Trade/rate Taxa Não Decimal (11,5)
0..1 Situação do negócio Trade/tradeStatus Situação do negócio
4 - Fechado 7 - Rejeitado 48 - Aguardando autorização 65 - Aguardando validação clearing 62 - Em processamento pela Clearing 71 - Cancelado
Não int
0..1 Tipo do negócio Trade/TradeType/code Tipo do negócio 1 - Doador 2 - Tomador
Não string 1
5 Informações
da Ordem
0..1 Número da ordem Trade/Offer/code Número da ordem Não string 35
0..1 Número da ordem contraparte
Trade/Offer/counterpartyOfferCode Número da ordem contraparte
Não string 35
0..1 Carteira Trade/Offer/Finality/code Carteira de origem/destino dos ativos
Não int
6 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
6.3.3 Consultar Lista de Negócios
Verbo Método Descrição
GET
trade/list/?partyCode=&number=&symbol=&daysToSettlementIndicator= &offerTypeCode=&date=lenderCode=&borrowerCode=&tradeCode=
Consultar Lista de Negócios - Retorna lista de negócios. Restrição: Em avaliação Caso necessite obter informações atualizadas dos negócios, recomendamos o uso do método “/event”
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Participante
0..1 Número identificação participante
partyCode Número identificação participante
Sim string 35
0..1 Investidor number Investidor do participante de negociação
Não string 35
2 Informaçõe
s do instrumento
0..1 Código de negociação symbol Código de negociação Não string 12
3 Informações da ordem
0..1 Prazo de liquidação daysToSettlementIndicator
Prazo de liquidação 0 - D+0 1 - D+1
Sim int 1
0..1 Tipo do negócio offerTypeCode Tipo do negócio 1 - Doador 2 - Tomador
Não string 1
0..1 Indicador Data de negociação date Indicador Data de negociação
0 - D+0 1 - D-1
Não int 1
0..1 Número da Ordem Doadora lenderCode Número da ordem Doadora
Não string 35
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..1 Número da Ordem Tomadora borrowerCode Número da Ordem Tomadora
Não string 35
4 Informaçõe
s do Negócio
0..1 Número do negócio tradeCode Número do negócio Não string 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do
Atributo Domínio Obrigatório?
Tipo de Dado
Tamanho Dado
1 Participante
0..* Número identificação participante
TradeList/{0..*}/Party/party/code Número identificação participante
Não string 35
0..* Nome do Participante
TradeList/{0..*}/Party/party/name Nome do participante Não string 60
0..* Investidor TradeList/{0..*}/Party/party/Account/number Investidor do participante de negociação
Não string 35
0..* Nome do investidor
TradeList/{0..*}/Party/party/Account/name Nome do investidor Não string 60
0..*
Número identificação participante contraparte
TradeList/{0..*}/Party/CounterParty/code Número identificação participante contraparte
Não string 35
0..* Nome do participante contraparte
TradeList/{0..*}/Party/CounterParty/name Nome do participante contraparte
Não string 60
2 Informações
do custodiante
0..* Custodiante TradeList/{0..*}/Custodian/code Custodiante Não string 35
0..* Nome do custodiante
TradeList/{0..*}/Custodian/name Nome do custodiante Não string 60
0..* Investidor custodiante
TradeList/{0..*}/Custodian/Account/number Investidor do custodiante
Não string 35
0..* Nome do investidor custodiante
TradeList/{0..*}/Custodian/Account/name Nome do investidor do custodiante
Não string 60
3 Informações
do instrumento
0..* Código de negociação
TradeList/{0..*}/ Security/symbol Código de negociação Não string 12
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
4 Informações do Negócio
0..* Número do negócio
TradeList/{0..*}/code Número do negócio Não string 35
0..* Data de negociação
TradeList/{0..*}/date Data de negociação Não dateTime
0..* Quantidade TradeList/{0..*}/quantity Quantidade de ativos negociados
Não BigInt
0..* Data de vencimento
TradeList/{0..*}/expirationDate Data de vencimento do negócio
Não date
0..* Taxa TradeList/{0..*}/rate Taxa Não Decimal (11,5)
0..* Situação do negócio
TradeList/{0..*}/tradeStatus Situação do negócio
4 - Fechado 7 - Rejeitado 48 - Aguardando autorização 65 - Aguardando validação clearing 62 - Em processamento pela Clearing 71 - Cancelado
Não int
0..* Tipo do negócio TradeList/{0..*}/TradeType/code Tipo do negócio 1 - Doador 2 - Tomador
Não string 1
5 Informações
da Ordem
0..* Número da Ordem
TradeList/{0..*}/ Offer/code Número da ordem Não string 35
0..* Número da Ordem Contraparte
TradeList/{0..*}/ Offer/counterpartyOfferCode Número da ordem contraparte
Não string 35
0..* Carteira TradeList/{0..*}/ Offer/Finality/code Carteira de origem/destino dos ativos
Não int
6 Status
Requisição
1..1 Quantidade total de registros da pesquisa
TradeList/{0..*}/ TrafficInformation/ returnRecordQuantity
Quantidade total de registros da pesquisa
Sim int
0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
6.3.4 Consultar Situação do Negócio
Verbo Método Descrição
GET trade/status/{code} Consultar Situação do Negócio - Retorna situação de um negócio específico
Requisição:
Bloco de Informação Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Informações do Negócio 1..1 Número do negócio code Número do negócio Sim string 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho
Dado
0..1 Situação do negócio Trade/tradeStatus Situação do negócio
4 - Fechado 7 - Rejeitado 48 - Aguardando autorização 65 - Aguardando validação clearing 62 - Em processamento pela Clearing 71 - Cancelado
Não int
2 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
6.4 Event
6.4.1 Consultar Eventos
Verbo Método Descrição
GET
event/{startDate}
Consultar Eventos - Retorna consulta de eventos relacionados às ofertas e negócios por intervalo de tempo. Restrição: Em avaliação
Requisição:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho Dado
1 Timestamp 1..1 Data hora evento inicio startDate Data hora inicial para consulta de eventos Sim dateTime 35
Retorno:
Bloco de Informação
Número de Ocorrências
Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado
Tamanho Dado
1 Informações
da oferta
0..* Data hora ordem OfferList/{0..*}/date Data hora da ordem Não dateTime 35
0..* Número da ordem OfferList/{0..*}/code Número da Ordem Não string 35
0..* Quantidade Original
OfferList/{0..*}/originalQuantity Quantidade original de ativos da ordem
Não bigint
0..* Quantidade Atual OfferList/{0..*}/quantity Quantidade atual de ativos da ordem
Não bigint
GUIA API BTB 2.0
INFORMAÇÃO PÚBLICA
0..* Situação da ordem OfferList/{0..*}/offerStatus Situação da ordem Não string 60
2 Informações do negócio
0..* Número do negócio OfferList/{0..*}/TradeList/{0..*}/code Número do negócio Não string 35
0..* Data hora negócio OfferList/{0..*}/TradeList/{0..*}/date Data hora do negócio Não dateTime 35
0..* Quantidade OfferList/{0..*}/TradeList/{0..*}/quantity Quantidade de ativos negociados
Não bigint
0..* Situação do negócio
OfferList/{0..*}/TradeList/{0..*}/tradeStatus Situação do negócio Não string 60
2 Status
Requisição 0..1 Código de erro BusinessStatus/code Código de erro
http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls - [Empréstimo de Ativo]
Não int
7 FLUXOS DE NEGÓCIO
As APIs podem ser consumidas em uma ordem específica para atender a um
fluxo de negócio. A indicação sobre a sequência de uso está disponível no link:
http://clientes.b3.com.br/pt_br/produtos-e-servicos/sobre/negociacao-eletronica-de-emprestimo-de-ativos.htm
Aba: “Material de apoio” > Link: “BTB – Fluxo de Negócios REST API”
8 SEGURANÇA
Neste capítulo temos as informações relacionadas à Segurança da Informação.
A B3 definiu como modelo de segurança para as APIs expostas o uso de Mutual
SSL (Two Way SSL) com pinagem de certificado e tokens de assinatura AWS
(Amazon Web Services) para as requisições enviadas.
8.1 Mutual SSL (Two Way SSL)
Para que o canal de comunicação entre cliente e servidor seja seguro, para todas as APIs do BTB, é utilizado protocolo HTTPS (Hyper Text Transfer Protocol
Secure), o que implica a apresentação de certificado pelo servidor para garantir sua autenticidade e criptografia dos dados trafegados. Com o uso do Mutual SSL (Two Way SSL) o cliente também deverá apresentar certificado ao servidor durante o handshake SSL, garantindo assim mútua autenticidade. O certificado de cliente será fornecido pela B3 juntamente com a senha utilizada para proteger a chave privada.
Abaixo exemplo se conexão utilizando mutual SSL com o comando curl
curl --cert ./client.cer:senhafornecidapelaB3 --key client.key \ --request GET https://api-btb-cert.b3.com.br/healthcheck
GUIA API BTB 2.0
36 INFORMAÇÃO PÚBLICA
8.2 Pinagem de certificado
Os clientes que irão consumir as APIs deverão implementar a pinagem do
certificado raiz do endereço de conexão. As imagens abaixo ilustram como obter
as informações para implementação da pinagem de certificado.
GUIA API BTB 2.0
37 INFORMAÇÃO PÚBLICA
8.3 Token de assinatura AWS (Amazon Web Services)
O token de assinatura padrão AWS aumenta a segurança na comunicação entre cliente e servidor prevenindo adulteração das requisições em ataques do tipo “man in the middle”. Para geração do token de assinatura os elementos que compõe a requisição são concatenados em uma única string e então realiza-se o cálculo do HMAC (Hash Message Authentication Code) conforme o padrão RFC 2104 HMAC-SHA1 utilizando uma palavra-chave (secret). A requisição então deverá vir acompanhada de header Authorization contendo a chave de identicação (Api Key) e o token separados por “:” conforme exemplo abaixo:
GUIA API BTB 2.0
38 INFORMAÇÃO PÚBLICA
Para este exemplo o secret utilizado foi: 7b9e79e5-b8fb-4f47-9c8e-1ccbba45006e. Utilize os dados da requisição acima para validar sua implementação. O API Key e Secret para assinatura das requisições nos ambientes de certificação e produção será fornecido pela B3. O endereço abaixo contém a especificação completa deste padrão:
https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html
top related