GUIA API BTB 2clientes.b3.com.br/data/files/4D/61/61/C0...GUIA API BTB 2.1 8 INFORMAÇÃO PÚBLICA 3.3 Uso do GET 3.4 Endpoint URI base (todas as URIs iniciam com): /BTBWebApi/api/v1.0

GUIA API BTB 2.1

INFORMAÇÃO PÚBLICA

SUMÁRIO

1 HISTÓRICO DE VERSÕES .......................................................................... 5

2 INTRODUÇÃO .............................................................................................. 6

3 VISÃO GERAL ............................................................................................. 6

3.1 Verbos HTTP – API - BTB ........................................................................ 6

3.2 Uso do POST ............................................................................................ 7

3.3 Uso do GET .............................................................................................. 8

3.4 Endpoint ................................................................................................... 8

3.5 Restrições................................................................................................. 8

4 ENDEREÇOS DA API DO BTB ................................................................... 9

5 SWAGGER ................................................................................................... 9

6 APIS BTB ..................................................................................................... 9

6.1 Order ....................................................................................................... 10

6.1.1 Inclusão de ordem ................................................................................. 10

6.1.2 Fechamento Doador .............................................................................. 11

6.1.3 Fechamento Tomador ........................................................................... 13

6.1.4 Cancelar Ordem ..................................................................................... 14

6.1.5 Cancelar todas as ordens ..................................................................... 16

6.1.6 Consultar Ordem .................................................................................... 17

GUIA API BTB 2.1

3 INFORMAÇÃO PÚBLICA

6.1.7 Consultar Lista de Ordens .................................................................... 19

6.1.8 Consultar Situação da Ordem ............................................................... 21

6.2 Book ........................................................................................................ 22

6.2.1 Consultar Ofertas Disponíveis .............................................................. 22

6.2.2 Consultar Melhores Ofertas .................................................................. 24

6.2.3 Consultar Instrumentos ........................................................................ 26

6.3 Trade ....................................................................................................... 27

6.3.1 Consultar Negócios do Mercado .......................................................... 27

6.3.2 Consultar Negócio ................................................................................. 28

6.3.3 Consultar Lista de Negócios ................................................................. 31

6.3.4 Consultar Situação do Negócio ............................................................ 35

6.4 Event ....................................................................................................... 36

6.4.1 Consultar Eventos ................................................................................. 36

6.5 Ranking ................................................................................................... 37

6.5.1 Consultar Ranking de Ofertas .............................................................. 37

6.5.2 Consultar Ranking de Negócios ........................................................... 39

6.5.3 Consultar Ranking de Participantes - Ofertas ..................................... 40

6.5.4 Consultar Ranking de Participantes - Negócios ................................. 42

6.5.5 Consultar Ranking de Participantes – Volume Financeiro de Ofertas

................................................................................................................. 44

GUIA API BTB 2.1


6.5.6 Consultar Ranking de Participantes – Volume Financeiro de Negócios

................................................................................................................. 45

7 FLUXOS DE NEGÓCIO .............................................................................. 47

8 SEGURANÇA ............................................................................................. 47

8.1 Mutual SSL (Two Way SSL) ................................................................... 47

8.2 Pinagem de certificado .......................................................................... 48

8.3 Token JWT no padrão OAuth 2.0 .......................................................... 49

GUIA API BTB 2.1


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

Dezembro/2019 2.1 Atualização de métodos e definições de autenticação

GUIA API BTB 2.1


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


3.2 Uso do POST

GUIA API BTB 2.1


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-listados-cert.b3.com.br/BTBWebApi/api/v1.0/order/entry

3.5 Restrições

Cada cliente pode realizar até 3 solicitações por segundo à API BTB. Os

detalhes de cada método podem ser consultados no item 6. API’s BTB.

https://api-listados-cert.b3.com.br/

GUIA API BTB 2.1


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: https://api-listados-cert.b3.com.br/

• 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: POST

Método: order/entry

Descrição: 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)

GUIA API BTB 2.1


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

Verbo: POST

Método: order/hitLender

Descrição: Agride uma ordem doadora específica no livro de ofertas

1..1 Data de validade Offer/expirationDate Data de validade da ordem Sim date

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


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


6.1.3 Fechamento Tomador

Verbo: POST

Método: order/hitBorrower

Descrição: 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




GUIA API BTB 2.1


Retorno:




Tamanho Dado





Não int

2 Status



Não int

6.1.4 Cancelar Ordem

Verbo: POST

Método: order/cancel

Descrição: Cancela uma ordem específica no livro de ofertas

1.1 Indicador de ordem certificada BorrowerOffer/certifiedOfferIndicator Indicador de ordem certificada True - Sim False - Não

Sim boolean 1

0.1 Carteira do doador BorrowerOffer/LenderFinality/code Carteira de origem dos ativos no doador

Não int




GUIA API BTB 2.1


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

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


Não int




GUIA API BTB 2.1


6.1.5 Cancelar todas as ordens

Verbo: POST

Método: order/cancel/all

Descrição: Cancela todas as ordens de um participante específico disponíveis no livro de ofertas

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 70 - Em processamento pela Clearing Não int


Não int




GUIA API BTB 2.1


6.1.6 Consultar Ordem

Verbo: GET

Método: order/{code}

Descrição: Retorna uma ordem específica incluída pelo Buy-Side

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

GUIA API BTB 2.1


0..1 Nome do investidor custodiante

Offer/Custodian/Account/ name

Nome do investidor do agente de custódia

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

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




GUIA API BTB 2.1


6.1.7 Consultar Lista de Ordens

Verbo: GET

Método: order/list?partyCode=&number=&symbol=&daysToSettlementIndicator=&offerTypeCode=&lastItemIdentifier=

Descrição: Retorna lista de ordens incluídas pelo Buy-Side.

Premissas: Serão retornados 100 registos por requisição. Num retorno onde o campo returnRecordQuantity retorne valor maior que 100, para obter a próxima sequência de registros deverá ser informado o valor do campo OfferList/code do último registro recebido. Este valor deve ser informado no parâmetro de requisição lastItemIdentifier. 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 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

0..1 Número da ordem da última sequência

lastItemIdentifier Número da ordem da última sequência

Não string 35

Retorno:

GUIA API BTB 2.1





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

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

GUIA API BTB 2.1


0..* Situação da ordem OfferList/{0..*}/offerStatus Situação da ordem


Não int

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

Verbo: GET

Método: order/status/{code}

Descrição: Retorna situação de uma ordem específica




GUIA API BTB 2.1


Requisição:



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

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




GUIA API BTB 2.1


Verbo: GET

Método: book/list/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna as 100 melhores ofertas disponíveis de um determinado instrumento

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 Security/symbol Código de negociação Não string 12

2 Informações

da ordem Doadora

0..* Número da ordem Security/LenderOfferList/code Número da ordem Não string 35

0..* Quantidade Security/LenderOfferList/quantity Quantidade de ativos para alugar

Não BigInt

0..* Taxa Security/LenderOfferList/rate Taxa Não Decimal(1

1,5)


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

Não string 35

3 0..* Número da ordem Security/BorrowerOfferList/code Número da ordem Não string 35

GUIA API BTB 2.1


Informações da ordem Tomadora

0..* Quantidade Security/BorrowerOfferList/quantity Quantidade de ativos para alugar

Não BigInt

0..* Taxa Security/BorrowerOfferList/rate Taxa Não Decimal(1

1,5)


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

Não string 35

4 Status



Não int

6.2.2 Consultar Melhores Ofertas

Verbo: GET

Método: book/top/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna a melhor oferta disponível para um ou mais instrumentos, limitado a 50 instrumentos

Requisição:




1 Informações

do instrumento


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:




GUIA API BTB 2.1





1 Informações

do instrumento

0..* Código de negociação SecurityList/symbol Código de negociação Não string 12

2 Informações

da ordem doadora

0..* Número da ordem SecurityList/LenderOffer/code Número da ordem Não string 35

0..* Quantidade SecurityList/LenderOffer/quantity Quantidade de ativos para alugar

Não BigInt

0..* Taxa SecurityList/LenderOffer/rate Taxa Não Decimal(11,5)


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(11,5)


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

Não string 35

4 Informações

dos negócios

0..* Taxa último negócio do dia

SecurityList/TradeInformation/lastTradeRate

Taxa último negócio do dia

Não Decimal(11,5)

0..* Preço de referência SecurityList/TradeInformation/referencePrice

Preço de referência Não Decimal(11,5)

GUIA API BTB 2.1


0..* Taxa média dia anterior

SecurityList/TradeInformation/lastDayAverageRate

Taxa média dia anterior Não Decimal(11,5)

0..* Taxa mínima SecurityList/TradeInformation/minimumRate

Taxa mínima Não Decimal(11,5)

0..* Taxa máxima SecurityList/TradeInformation/maximumRate

Taxa máxima Não Decimal(11,5)

5 Status



Não int

6.2.3 Consultar Instrumentos

Verbo: GET

Método: SecurityLending/list

Descrição: Retorna os instrumentos disponíveis para empréstimo.

Requisição:

Sem parâmetros




GUIA API BTB 2.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

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

Verbo: GET

Método: trade/all/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna lista de negócios realizados pelo mercado de um determinado instrumento

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


0 - D+0 1 - D+1

Sim int 1

Retorno:

GUIA API BTB 2.1



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

6.3.2 Consultar Negócio

Verbo: GET

Método: trade/{code}

Descrição: 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




GUIA API BTB 2.1


Retorno:




Tamanho Dado

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

e

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/closedOfferingType Tipo do negócio 1 - Doador 2 - Tomador

Não string 1

3 Informações

da ordem doadora


Trade/Lender/Party/code Número identificação participante

Não string 35

0..1 Nome do participante Trade/Lender/Party/name Nome do participante Não string 60

0..1 Investidor Trade/Lender/Party/Account/number


Não string 35

0..1 Nome do investidor Trade/Lender/Party/Account/name Nome do investidor Não string 60

0..1 Número identificação participante contraparte

Trade/Lender/CounterParty/code Número identificação participante contraparte

Não string 35

0..1 Nome do participante contraparte

Trade/Lender/CounterParty/name Nome do participante contraparte

Não string 60

GUIA API BTB 2.1


0..1 Custodiante Trade/Lender/Custodian/code Custodiante Não string 35

0..1 Nome do custodiante Trade/Lender/Custodian/name Nome do custodiante Não string 60

0..1 Investidor custodiante

Trade/Lender/Custodian/Account/number

Investidor do custodiante Não string 35


Trade/Lender/Custodian/Account/name

Nome do investidor do custodiante

Não string 60

0..1 Número da ordem Trade/Lender/Offer/code Número da ordem Não string 35

0..1 Número da ordem contraparte

Trade/Lender/Offer/ counterpartyOfferCode

Número da ordem contraparte

Não string 35

0..1 Carteira Trade/Lender/Offer/Finality/code Carteira de origem/destino dos ativos

Não int

4 Informações

da ordem tomadora


Trade/Borrower/Party/code Número identificação participante

Não string 35

0..1 Nome do participante Trade/Borrower/Party/name Nome do participante Não string 60

0..1 Investidor Trade/Borrower/Party/Account/number


Não string 35

0..1 Nome do investidor Trade/Borrower/Party/Account/name

Nome do investidor Não string 60

0..1 Número identificação participante contraparte

Trade/Borrower/CounterParty/code Número identificação participante contraparte

Não string 35

0..1 Nome do participante contraparte

Trade/Borrower/CounterParty/name

Nome do participante contraparte

Não string 60

0..1 Custodiante Trade/Borrower/Custodian/code Custodiante Não string 35

0..1 Nome do custodiante Trade/Borrower/Custodian/name Nome do custodiante Não string 60

0..1 Investidor custodiante

Trade/Borrower/Custodian/Account/number

Investidor do custodiante Não string 35


Trade/Borrower/Custodian/Account/name

Nome do investidor do custodiante

Não string 60

0..1 Número da ordem Trade/Borrower/Offer/code Número da ordem Não string 35

0..1 Número da ordem contraparte

Trade/Borrower/Offer/ counterpartyOfferCode


Não string 35

0..1 Carteira Trade/Borrower/Offer/Finality/code Carteira de origem/destino dos ativos

Não int

5 Status



Não int




GUIA API BTB 2.1


6.3.3 Consultar Lista de Negócios

Verbo: GET

Método: trade/list/?partyCode=&number=&symbol=&daysToSettlementIndicator= &tradeDayIndicator&=lenderCode=&borrowerCode=

&closedOfferingType=&sideLenderBorrower=&lastItemIdentifier=

Descrição: Retorna um negócio específico

Premissas: Serão retornados 100 registos por requisição. Num retorno onde o campo returnRecordQuantity retorne valor maior que 100, para obter a próxima sequência de registros deverá ser informado o valor do campo TradeList/code do último registro recebido. Este valor deve ser informado no parâmetro de requisição lastItemIdentifier. Caso necessite obter informações atualizadas das ordens, recomendamos o uso do método “/event”.

Requisição:


Número de Ocorrência

s 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 Prazo de liquidação daysToSettlementIndicator


Sim int 1

0..1 Indicador Data de negociação tradeDayIndicator Indicador Data de negociação

T0 – Dia corrente T-1 – Dia anterior de negociação

Não int 1

GUIA API BTB 2.1


0..1 Número da Ordem Doadora lenderCode Número da ordem Doadora

Não string 35

0..1 Número da Ordem Tomadora borrowerCode Número da Ordem Tomadora

Não string 35

0..1 Tipo de Negócio closedOfferingType Tipo de Negócio 1 – Doador 2 – Tomador

Não string 1

0..1 Lado do negócio sideLenderBorrower Lado do negócio 1 - Doador 2 – Tomador

Não string 1


0..1 Número do negócio da última sequência

lastItemIdentifier Número do negócio da última sequência

Não string 35

Retorno:



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

TradeList/{0..*}/Security/symbol Código de negociação Não string 12


0..* Número do negócio

TradeList/{0..*}/code Número do negócio Não string 35

0..* Prazo de liquidação

TradeList/{0..*}/daysToSettlementIndicator Prazo de liquidação 0 - D+0 1 - D+1

Não int 1

0..* Data de negociação

TradeList/{0..*}/date Data de negociação Não dateTim

e

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)

GUIA API BTB 2.1


0..* Situação do negócio

TradeList/{0..*}/tradeStatus Situação do negócio


Não int

0..* Tipo do negócio

TradeList/{0..*}/closedOfferingType Tipo do negócio 1 - Doador 2 - Tomador

Não string 1

3 Informações

da ordem doadora


TradeList/{0..*}/Lender/Party/code Número identificação participante

Não string 35

0..* Nome do Participante

TradeList/{0..*}/Lender/Party/name Nome do participante

Não string 60

0..* Investidor TradeList/{0..*}/Lender/Party/Account/number Investidor do participante de negociação

Não string 35

0..* Nome do investidor

TradeList/{0..*}/Lender/Party/Account/name Nome do investidor Não string 60

0..*

Número identificação participante contraparte

TradeList/{0..*}/Lender/CounterParty/code Número identificação participante contraparte

Não string 35

0..* Nome do participante contraparte

TradeList/{0..*}/Lender/CounterParty/name Nome do participante contraparte

Não string 60

0..* Custodiante TradeList/{0..*}/Lender/Custodian/code Custodiante Não string 35


TradeList/{0..*}/Lender/Custodian/name Nome do custodiante Não string 60


TradeList/{0..*}/Lender/Custodian/Account/number Investidor do custodiante

Não string 35


TradeList/{0..*}/Lender/Custodian/Account/name Nome do investidor do custodiante

Não string 60

0..* Número da Ordem

TradeList/{0..*}/Lender/Offer/code Número da ordem Não string 35

0..* Número da Ordem Contraparte

TradeList/{0..*}/Lender/Offer/counterpartyOfferCode Número da ordem contraparte

Não string 35

0..* Carteira TradeList/{0..*}/Lender/Offer/Finality/code Carteira de origem/destino dos ativos

Não int

GUIA API BTB 2.1


4 Informações

da ordem tomadora


TradeList/{0..*}/Borrower/Party/code Número identificação participante

Não string 35

0..* Nome do Participante

TradeList/{0..*}/Borrower/Party/name Nome do participante

Não string 60

0..* Investidor TradeList/{0..*}/Borrower/Party/Account/number Investidor do participante de negociação

Não string 35

0..* Nome do investidor

TradeList/{0..*}/Borrower/Party/Account/name Nome do investidor Não string 60

0..*

Número identificação participante contraparte

TradeList/{0..*}/Borrower/CounterParty/code Número identificação participante contraparte

Não string 35

0..* Nome do participante contraparte

TradeList/{0..*}/Borrower/CounterParty/name Nome do participante contraparte

Não string 60

0..* Custodiante TradeList/{0..*}/Borrower/Custodian/code Custodiante Não string 35


TradeList/{0..*}/Borrower/Custodian/name Nome do custodiante Não string 60


TradeList/{0..*}/Borrower/Custodian/Account/number

Investidor do custodiante

Não string 35


TradeList/{0..*}/Borrower/Custodian/Account/name Nome do investidor do custodiante

Não string 60

0..* Número da Ordem

TradeList/{0..*}/Borrower/Offer/code Número da ordem Não string 35

0..* Número da Ordem Contraparte

TradeList/{0..*}/Borrower/Offer/counterpartyOfferCode


Não string 35

0..* Carteira TradeList/{0..*}/Borrower/Offer/Finality/code Carteira de origem/destino dos ativos

Não int

5 Status

requisição

1..1

Quantidade total de registros da pesquisa 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.1


6.3.4 Consultar Situação do Negócio

Verbo: GET

Método: trade/status/{code}

Descrição: 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.1


6.4 Event

6.4.1 Consultar Eventos

Verbo: GET

Método: event/{startDate}

Descrição: Retorna consulta de eventos relacionados às ofertas e negócios por intervalo de tempo.

Requisição:




1 Timestamp 1..1 Data hora evento inicio startDate Data hora inicial para consulta de eventos yyyy-MM-ddTHH:mm:ss 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.1


0..* Situação da ordem OfferList/{0..*}/offerStatus Situação da ordem Não string 60


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

6.5 Ranking

6.5.1 Consultar Ranking de Ofertas

Verbo: GET

Método: ranking/order/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna a soma de ofertas e quantidades de um ou mais instrumentos, limitado a 50 instrumentos




GUIA API BTB 2.1


Requisição:




Tamanho Dado

1 Informações

do Instrumento


2 Informações


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 Informações das ofertas Doadoras

0..* Número de ofertas securityList/LenderOffer/totalOffers Número total de ofertas Não int

0..* Quantidades ofertadas securityList/LenderOffer/totalQuantityOffered

Total de quantidades ofertadas

Não int

3 Informações das ofertas Tomadoras

0..* Número de ofertas securityList/BorrowerOffer/totalOffers Número total de ofertas Não int

0..* Quantidades ofertadas securityList/BorrowerOffer/totalQuantityOffered

Total de quantidades ofertadas

Não int

4 Status



Não int




GUIA API BTB 2.1


6.5.2 Consultar Ranking de Negócios

Verbo: GET

Método: ranking/trade/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna a soma de negócios e quantidades de um ou mais instrumentos, limitado a 50 instrumentos

Requisição:




Tamanho Dado

1 Informações

do instrumento


2 Informações


0 - D+0 1 - D+1

Sim string 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 Informações

dos negócios

0..* Número de negócios securityList/Trade/totalTrades Número total de negócios

Não

int

GUIA API BTB 2.1


0..* Quantidades negociada securityList/Trade/totalQuantityTraded Total de quantidades negociadas

Não int

5 Status



Não int

6.5.3 Consultar Ranking de Participantes - Ofertas

Verbo: GET

Método: ranking/partyOrder/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna a lista de participantes que possuem o maior número de ofertas e quantidades de determinado instrumento

Requisição:




Tamanho Dado

1 Informações

do instrumento


2 Informações


0 - D+0 1 - D+1

Sim int 1




GUIA API BTB 2.1


Retorno:




Tamanho Dado

c Informações

do instrumento


2 Informações das ofertas doadoras


Security/lenderOfferList/partyCode Número identificação participante

Não string

0..* Número de ofertas Security/lenderOfferList/totalOffers Número de total ofertas do participante

Não int

0..* Quantidades ofertadas Security/lenderOfferList/totalQuantityOffered

Total de quantidades ofertadas pelo participante

Não int

3 Informações das ofertas tomadoras


Security/borrowerOfferList/partyCode Número identificação participante

Não string

0..* Número de ofertas Security/borrowerOfferList/totalOffers Número de total ofertas do participante

Não int

0..* Quantidades ofertadas Security/borrowerOfferList/totalQuantityOffered

Total de quantidades ofertadas pelo participante

Não int

5 Status



Não int




GUIA API BTB 2.1


6.5.4 Consultar Ranking de Participantes - Negócios

Verbo: GET

Método: ranking/partyTrade/{symbol}/{daysToSettlementIndicator}

Descrição: Retorna a lista de participantes que possuem o maior número de ofertas e quantidades de determinado instrumento

Requisição:




Tamanho Dado

1 Informações

do instrumento


2 Informações


0 - D+0 1 - D+1

Sim int 1

GUIA API BTB 2.1


Retorno:




Tamanho Dado

1 Informações

do instrumento


2

Informações dos

negócios Doadores


Security/lenderTradeList/partyCode Número identificação participante

Não string

0..* Número de negócios Security/lenderTradeList/totalTrades Número de total negócios do participante

Não int

0..* Quantidades ofertadas Security/lenderTradeList/totalQuantityTraded

Total de quantidades negociadas pelo participante

Não int

3

Informações dos

negócios Tomadores


Security/borrowerTradeList/partyCode Número identificação participante

Não string

0..* Número de ofertas Security/borrowerTradeList/totalTrades Número de total negócios do participante

Não int

0..* Quantidades ofertadas Security/borrowerTradeList/totalQuantityTraded

Total de quantidades negociadas pelo participante

Não int

4 Status

Requisição 0..1 Código de erro BusinessStatus/code Código de erro


Não int




GUIA API BTB 2.1


6.5.5 Consultar Ranking de Participantes – Volume Financeiro de Ofertas

Verbo: GET

Método: ranking/partyFinancialVolumeOrder/{daysToSettlementIndicator}

Descrição: Retorna a lista de participantes que possuem o maior volume financeiro de ofertas

Requisição:




Tamanho Dado

1 Informações


0 - D+0 1 - D+1

Sim int 1

Retorno:




Tamanho Dado

1 Informações das ofertas doadoras


OfferInformation/lenderOfferList/partyCode

Número identificação participante

Não string 35

0..* Volume Financeiro OfferInformation/lenderOfferList/totalFinancialVolume

Soma do volume financeiro de todas ofertas doadoras de todos instrumentos do participante

Não Decimal(1

5,2)

2 0..* Número identificação participante

OfferInformation/borrowerOfferList/partyCode


Não string 35

GUIA API BTB 2.1


Informações das ofertas tomadoras

0..* Volume Financeiro OfferInformation/borrowerOfferList/totalFinancialVolume

Soma do volume financeiro de todas ofertas tomadoras de todos instrumentos do participante

Não

Decimal(1

5,2)

3 Status



Não int

6.5.6 Consultar Ranking de Participantes – Volume Financeiro de Negócios

Verbo: GET

Método: ranking/partyFinancialVolumeTrade/{daysToSettlementIndicator}

Descrição: Retorna a lista de participantes que possuem o maior volume financeiro de negócios

Requisição:




Tamanho Dado

1 Informações


0 - D+0 1 - D+1

Sim string 1




GUIA API BTB 2.1


Retorno:




Tamanho Dado

1

Informações dos

negócios doadores


tradeInformation/lenderTradeList/partyCode


Não string 35

0..* Volume Financeiro tradeInformation/lenderTradeList/totalFinancialVolume

Soma do volume financeiro de todos negócios doadores de todos instrumentos do participante

Não Decimal(1

5,2)

2

Informações dos

negócios tomadores


tradeInformation/borrowerTradeList/partyCode


Não string 35

0..* Volume Financeiro tradeInformation/borrowerTradeList/totalFinancialVolume

Soma do volume financeiro de todos negócios tomadores de todos instrumentos do participante

Não Decimal(1

5,2)

3 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 JWT obtidos com padrão

OAuth 2.0.

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


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


8.3 Token JWT no padrão OAuth 2.0

Para consumir a API, o usuário deverá realizar uma requisição de um token JWT

- ele garante que o usuário está autorizado a seguir. Ele precisará informar as

seguintes informações na requisição do token JWT no padrão OAuth 2.0:

GUIA API BTB 2.1


HTTP POST

HOST https://api-btb-exemplo.b3.com.br

Caminho /api/oauth/token

Cabeçalho Content-Type: application/x-www-form-urlencoded

CATEGORY_ID:39 (Código da categoria da instituição)

Parâmetros do Corpo

grant_type = client_credentials (Esse valor é fixo - igual para todas as

requisições)

client_id = c96rr10-dcf5-4231-ertert-cf886b8318fa (Aqui vai o client id que o

usuário recebeu no pacote de acesso)

client_secret = wertwert-68cf-4a59-b51b-67ee6f820a77 (Aqui vai o client secret

que o usuário recebeu no pacote de acesso)

O usuário deverá informar o certificado digital que recebeu no pacote de acesso,

utilizando a técnica de Mutual SSL. Abaixo veja um exemplo de requisição

completa de token JWT com Mutual SSL utilizando CURL – entretanto, a

requisição pode ser implementada em outra linguagem desejada:

curl --cert ./certificado.cer:senhadocertificado --key chave.key \

--insecure --header "Content-Type: application/x-www-form-urlencoded" \

--header " CATEGORY_ID: 39" \

-d "grant_type=client_credentials&client_id=dc96rr10-dcf5-4231-ertert-

cf886b8318fa&client_secret=wertwert-68cf-4a59-b51b-67ee6f820a77" \

-X POST https://api-btb-exemplo.b3.com.br/api/oauth/token \

A resposta da requisição será:

{

"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI5OTkiLCAiZXhwIjoiMTU

2MDAwNzgyOSIsICJpc3MiOiJDTj1JbnRlcm1lZCBDZXJ0aWZpY2F0ZSAtIEp

https://api-btb-exemplo.b3.com.br/api/oauth/token

GUIA API BTB 2.1


XVCxPVT1HQ01DLE89QjMgU0EsTD1TYW8gUGF1bG8sUz1TUCxDPUJSIn

0.JSWxLOVX6xWmeLAhwdTP2xKt2eK3JAJ2oB6lYn06PROQdpaCk8E_CaS

-xGc2xz9iBEnLTxZTrfdhyYstkBv90fLXVQnhEVFhfXLq2Ov-

xWAO_DFPeGLXzy5_7WOpbZ3oKbjJ1XVxbCZnoDIt3VRZGNHAyiS8dZJzx

V0n9D8qa_HhtZhOJNbH0ynhPyoE8qMULvgJQ5DzjXIvk2mP-

KWIfhoY9CQnGseqTjrqWOj2kmYsQ9yCgAW6DRxB7LvTOavUk/vjOga7hme

Xk9-

kunaqcu5EMpWzHeiFNGFhY1U4XhFtPZSIWzu23d6wDq5U0ZAWoV3Sw39

6d-hA3_cah9_hKQw",

"token_type": "Bearer",

"expires_in": "8640",

"scope": "resource.WRITE resource.READ"

}

Os campos são:

access_token: é o token JWT. Ele deverá ser informado no cabeçalho das

requisições às APIs.

expires_in: a validade do token é de 120 minutos. Após esse tempo, o token

JWT não será mais válido, e o usuário deverá requisitar um novo token para

consumir as APIs.

token_type: especifica o authentication schema utilizado pela API, por exemplo,

Basic, Bearer, AWS, entre outros. Para as APIs de ofertas e negócios, será

utilizado sempre o schema Bearer, conforme RFC:

https://tools.ietf.org/html/rfc6750

Exemplo requisição para BTB utilizando o token:

HTTP: GET /BTBWebApi/api/v1.0/book/top/PETR4/0

HOST: https://api-listados-cert.b3.com.br

Content-Type: application/json

https://tools.ietf.org/html/rfc6750


GUIA API BTB 2.1


Authorization: Bearer

eyJhbGc4OiJSUzI1Nie2.ZSAtIEpXVCxPVT1HQ01DLE89QjMgU0UGF1bG8s

Uz1TUCxDPUJSIn0.JSWxLOVX6xSw396d-hA3_cah9_hKQw

Documents

GUIA API BTB 2clientes.b3.com.br/data/files/4D/61/61/C0...GUIA API BTB 2.1 8 INFORMAÇÃO PÚBLICA 3.3 Uso do GET 3.4 Endpoint URI base (todas as URIs iniciam com): /BTBWebApi/api/v1.0