GUIA API BTB 2 - clientes.b3.com.brclientes.b3.com.br/data/files/AC/13/54/D7... · GUIA API BTB 2.0 7 INFORMAÇÃO PÚBLICA 3.3 Uso do GET 3.4 Endpoint URI base (todas as URIs iniciam

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


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


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


3.2 Uso do POST

GUIA API BTB 2.0


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”.

https://api-btb.b3.com.br/BTBWebApi/api/v1.0/order/entry

GUIA API BTB 2.0


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.

http://clientes.b3.com.br/pt_br/produtos-e-servicos/sobre/negociacao-eletronica-de-emprestimo-de-ativos.htm


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:




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


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

http://www.bvmfnet.com.br/pt-br/manuais/download/CodigosErros-Mensageria-Maio-2018.xls



GUIA API BTB 2.0


Requisição:




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:




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


6.1.3 Fechamento Tomador


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




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


Retorno:




Tamanho Dado





Não int

2 Status



Não int

6.1.4 Cancelar Ordem


POST order/cancel Cancelar Ordem - Cancela uma ordem específica no livro de ofertas

Requisição:



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


Retorno:




Tamanho Dado

1 Status

Requisição

1..1 Número da ordem Offer/code Número da ordem Sim string 35


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


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


Requisição:




1 Participante 1..1 Número identificação participante Party/code Número identificação participante Sim string 35

Retorno:




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


GET order/{code} Consultar Ordem - Retorna uma ordem específica incluída pelo Buy-Side




GUIA API BTB 2.0


Requisição:

Bloco de Informação Número de Ocorrências


1 Informações da ordem 1..1 Número da ordem code Número da ordem Sim string 35

Retorno:




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 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


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


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



Não int

6.1.7 Consultar Lista de Ordens


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


Caso necessite obter informações atualizadas das ordens, recomendamos o uso do método “/event”

Requisição:



Nome Swagger Definição do

Atributo Domínio Obrigatório?

Tipo de Dado

Tamanho Dado

1 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:




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


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


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


Não int

GUIA API BTB 2.0


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


Não int

6.1.8 Consultar Situação da Ordem


GET order/status/{code} Consultar Situação da Ordem – Retorna situação de uma ordem específica

Requisição:



1 Informações da ordem 1..1 Número da ordem code Número da ordem Sim string 35




GUIA API BTB 2.0


Retorno:




Tamanho Dado

1 Informações

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



Não int

6.2 Book

6.2.1 Consultar Ofertas Disponíveis


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


Requisição:




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:




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)


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)


Security/BorrowerOfferList/Party/code Número identificação participante

Não string 35

GUIA API BTB 2.0


4 Status



Não int

6.2.2 Consultar Melhores Ofertas


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:




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:




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çõ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)


SecurityList/BorrowerOffer/Party/code Número identificação participante

Não string 35

4 Status



Não int

6.2.1 Consultar Instrumentos


GET

/v1.0/SecurityLending/List

Consultar Instrumentos – Retorna os instrumentos disponíveis para empréstimo. Restrição: Em avaliação




http://localhost:9000/2046429309#/operations/Book/SecurityLendingListget

GUIA API BTB 2.0


Requisição:

Sem parâmetros

Retorno:




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


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


Requisição:




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:


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



Não int




GUIA API BTB 2.0


6.3.2 Consultar Negócio


GET trade/{code} Consultar Negócio - Retorna um negócio específico

Requisição:



1 Informações do Negócio 1..1 Número do negócio code Número do negócio Sim string 35

Retorno:




Tamanho Dado

1 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


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



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)



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



Não int




GUIA API BTB 2.0


6.3.3 Consultar Lista de Negócios


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:




1 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


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


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:




Atributo Domínio Obrigatório?

Tipo de Dado

Tamanho Dado

1 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



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


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


Não int




GUIA API BTB 2.0


6.3.4 Consultar Situação do Negócio


GET trade/status/{code} Consultar Situação do Negócio - Retorna situação de um negócio específico

Requisição:



1 Informações do Negócio 1..1 Número do negócio code Número do negócio Sim string 35

Retorno:



Nome Swagger Definição do Atributo Domínio Obrigatório? Tipo de Dado Tamanho

Dado



Não int

2 Status



Não int




GUIA API BTB 2.0


6.4 Event

6.4.1 Consultar Eventos


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:




1 Timestamp 1..1 Data hora evento inicio startDate Data hora inicial para consulta de eventos Sim dateTime 35

Retorno:




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


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



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:


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



https://api-btb-cert.b3.com.br/healthcheck

GUIA API BTB 2.0


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


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


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

https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html

Documents

GUIA API BTB 2 - clientes.b3.com.brclientes.b3.com.br/data/files/AC/13/54/D7... · GUIA API BTB 2.0 7 INFORMAÇÃO PÚBLICA 3.3 Uso do GET 3.4 Endpoint URI base (todas as URIs iniciam