Documentação Técnica Feed IMA ETF

ANBIMA Feed IMA-ETF

1. Sobre Nossa API

O ANBIMA Feed IMA-ETF é composto por APIs RESTFul baseadas no protocolo HTTP. Seu objetivo é disponibilizar dados às ETFs licenciadas pela ANBIMA cujo propósito é utilizar um índice pertencente à família IMA (Índice de Mercado ANBIMA). Os índices atualmente disponíveis são: IMA-B, IMA-B 5+, IMA-B 5 P2 e IRF-M P2.

Neste pacote, disponibilizamos as seguintes APIs: Prévia da Carteira Teórica, Carteira Teórica, Composição Diária, Negócios Extra, PU Intradiário, Resultado Diário e Resultado Intradiário.

Nossas APIs têm como padrão apresentar os resultados para todos os índices adquiridos da família IMA. Entretanto, é possível realizar consultas filtrando por um ou mais índices. Segue abaixo um de-para para auxiliar na consulta através das nossas URIs:

Índice Parâmetro para consulta
IMA-B IMA_B
IMA-B 5+ IMA_B5_MAIS
IMA-B 5 P2 IMA_B5_P2
IRF-M P2 IRF_M_P2

2. Primeiros passos

  • Conheça nossos ambientes

    Nossas APIs podem ser acessadas através de dois ambientes: Sandbox e Produção.

    O ambiente de Sandbox pode ser utilizado para testes gerais do serviço, tal como verificar o formato de resposta de um recurso específico da API. Neste momento os dados retornados serão fixos e fictícios.

    Já as informações oficiais poderão ser obtidas apenas através do ambiente de produção.

  • Como realizar chamadas aos recursos de nossa API?

    Na prática, uma chamada a nossas APIs considera sempre o modelo de URI abaixo: https://<ambiente>/<produto>/<versão>/<pacote>/<recursos>/<parâmetros>, sendo:

    • protocolo: https
    • ambiente: api.anbima.com.br (Produção) ou api-sandbox.anbima.com.br/mocks (Sandbox)
    • produto: feed/precos-indices
    • versão: v2
    • pacote: ima-etf

    Logo, a URI a ser utilizada para acesso a qualquer uma das APIs do ANBIMA Feed IMA-ETF seria https://<ambiente>/feed/precos-indices/v2/ima-etf.

    Lembrando que todos recursos desta API são privados e apenas podem ser acessados em ambientes de sandbox e produção através do padrão de autenticação O-Auth 2 (explicado em detalhes na seção Autenticação).

    Para maiores detalhes sobre os campos de cada API, por favor, consulte a nossa documentação funcional.

  • API 1: Prévia da Carteira Teórica:

    Nesta API é possível obter os dados referentes à prévia das composições das carteiras teóricas do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/previa-carteira-teorica.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/previa-carteira-teorica.

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes ao último período divulgado (mês/ano). Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/previa-carteira-teorica?ano=YYYY&mes=MM&etf=INDICE1,INDICE2
    ou
    GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/previa-carteira-teorica?ano=YYYY&mes=MM&etf=INDICE1&etf=INDICE2&
    etf=INDICE3

    onde:

    • ano: indica o ano da prévia da carteira teórica desejada;
    • mes: indica o mês da prévia da carteira teórica desejada;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira um valor superior ao mês/ano atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 2: Carteira Teórica:

    Nesta API é possível obter os dados referentes à carteira teórica do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/carteira-teorica.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/carteira-teorica.

    Nos resultados da consulta, por padrão são mostrados os resultados referentes ao último período divulgado (mês/ano). Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo, GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/carteira-teorica?ano=YYYY&mes=MM&etf=INDICE1:

    • ano: indica o ano da carteira teórica desejada;
    • mes: indica o mês da carteira teórica desejada;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira um valor superior ao mês/ano atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 3: Composição Diária:

    Nesta API é possível obter os dados diários dos componentes do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/composicao-diaria.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/composicao-diaria..

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes a última data divulgada. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/composicao-diaria?data=YYYY-MM-DD&etf=INDICE1,INDICE2
    ou
    GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/composicao-diaria?data=YYYY-MM-DD&etf=INDICE1&etf=INDICE2&
    etf=INDICE3

    onde:

    • data: indica a data da composição do índice;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira uma data superior a atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 4: Negócios Extra:

    Nesta API é possível obter os dados relativos aos volumes de negócios registrados no Selic com os componentes do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/negocios-extra.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/negocios-extra.

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes a última data divulgada. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/negocios-extra?data=YYYY-MM-DD&etf=INDICE1:

    • data: indica a data da negociação;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira uma data superior a atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 5: PU Intradiário:

    Nesta API é possível obter os dados de preços intradiários (12h) dos componentes do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/pu-intradiario.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/pu-intradiario.

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes a última data divulgada. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/pu-intradiario?data=YYYY-MM-DD&etf=INDICE1:

    • data: indica a data dos preços intradiários divulgados;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira uma data superior a atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 6: Resultado Diário:

    Nesta API é possível obter os dados de valores (resultados) diários do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/resultado-diario.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/resultado-diario.

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes a última data divulgada. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/resultado-diario?data=YYYY-MM-DD&etf=INDICE1:

    • data: indica a data dos preços intradiários divulgados;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira uma data superior a atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

  • API 7: Resultado Intradiário:

    Nesta API é possível obter os dados de valores (resultados) intradiários (12h) do índice licenciado.

    Para acessar esta API, deve-se utilizar a seguinte URI: https://<ambiente>/feed/precos-indices/v2/ima-etf/resultado-intradiario.

    O método utilizado para acesso aos recursos deve ser o GET, pois nossa API é exclusivamente utilizada para consultas a informações. Um exemplo de chamada real em ambiente de produção seria: GET https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/resultado-intradiario.

    Nos resultados da consulta, por padrão são mostrados os resultados de todos os índices disponíveis referentes a última data divulgada. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo: https://api.anbima.com.br/feed/precos-indices/v2/ima-etf/resultado-intradiario?data=YYYY-MM-DD&etf=INDICE1:

    • data: indica a data dos resultados intradiários divulgados;
    • etf: indica os índices que devem ser retornados na consulta.
    Caso o utilizador insira uma data superior a atual ou um índice não disponível/não existente, é retornado um erro ‘404 Not Found’.

    3. Requisições à API

    Para as requisições a estas APIs é necessária a combinação dos seguintes componentes: método (ou verbo) HTTP e URI do recurso. Todas as chamadas a recursos das APIs consideram a seguinte estrutura:

    GET https://<ambiente>/feed/precos-indices/v2/ima-etf/<recurso>/<parâmetros>, sendo que a lista de recursos disponíveis encontram-se disponíveis no seguinte Swagger (acesso restrito).

    Códigos de erro retornados pelo serviço RESTFul:

    Código HTTP Descrição
    400 Requisição malformada. Por favor, verifique a URL da requisição e os parâmetros informados
    401 Requisição não foi devidamente autenticada. Os valores informados de client_id e/ou access_token não são válidos.
    403 Credenciais informadas não possuem permissão de acesso ao recurso requisitado.
    404 Dados não existentes ou não disponíveis para a requisição e parâmetros
    5XX Erro interno inesperado no servidor

    Códigos de sucesso

    Código HTTP Descrição
    200 Consulta com sucesso. Dados disponíveis e informados no body da resposta.
    206 Conteúdo parcial. A resposta é incompleta, não existem dados disponíveis para completar toda a mensagem.
  • 4. Notificações via API

    O ANBIMA Feed possui recursos que permitem que os clientes sejam acionados com notificações em algumas situações, por exemplo quando existirem novas informações disponíveis em um determinado contexto, ou quando houver atraso para a disponibilização de determinadas informações. Para que este mecanismo funcione corretamente, é necessário que o cliente exponha uma API RESTFul para que o ANBIMA Feed possa fazer os respectivos acionamentos, e a API deverá ser implementada de acordo com a especificação abaixo:

    Método: POST
    URI: definida pelo cliente e informada à ANBIMA para cadastro (ex. https://endpoint-cliente.com/recurso-cliente/)
    Body:

    
    {
       "tipo_evento": "string",
       "nome_pacote": "string",
       "nome_item": "string",
       "descricao": "string",
       "data_referencia": "string",
    }
    
    

    Autenticação: É necessário que o tipo de autenticação seja a "Basic Authentication", conforme especificado em https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization

    A seguir, veja a descrição dos campos que seriam enviados no body da chamada:

    Nome campo Descrição
    tipo_evento Tipo do evento de notificação (ex. NOVO, ATRASO, ATUALIZACAO). Esta informação refere-se ao tipo do evento que gerou a notificação, por ex: novos dados de Pacote/Item disponibilizados pela API
    nome_pacote O nome do pacote para o qual foi gerada a notificação
    nome_item O nome do item do pacote para o qual foi gerada a notificação
    descricao Texto descritivo da notificação
    data_referencia A data de referência dos dados disponibilizados

    Intruções de como devem ser tratados os diferentes tipos de evento:

    • NOVO - Dados disponibilizados para o Pacote/Item e Data de Referência informados
      ATUALIZACAO - DDados corrigidos para o Pacote/Item e Data de Referência informados. Os dados que haviam sido armazenados anteriormente para este Pacote/Item e Data de Referência devem ser excluídos e substituídos pelos disponibilizados após a notificação deste tipo.
      ATRASO - Os dados de Pacote/Item e Data de Referência informados estão em atraso na sua geração.
  • Caminho das APIs

    Quando o ANBIMA Feed envia uma notificação, ele já possui novos dados para divulgar. Assim, logo após receber uma mensagem de notificação, seu sistema já poderá requisitar estes dados, invocando uma de nossas APIs.
    O quadro abaixo resume quais APIs devem ser chamadas para solicitar a atualização de dados para cada API do ANBIMA Feed:

    Pacote Item Caminho
    IMA_ETF RESULTADO_DIARIO ima-etf/resultado-diario
    IMA_ETF COMPOSICAO_DIARIA ima-etf/composicao-diaria
    IMA_ETF PU_INTRADIARIO ima-etf/pu-intradiario
    IMA_ETF NEGOCIOS_EXTRA ima-etf/negocios-extra
    IMA_ETF PREVIA_CARTEIRA_TEORICA_IMA ima-etf/previa-carteira-teorica
    IMA_ETF CARTEIRA_TEORICA_IMA ima-etf/carteira-teorica
    IMA_ETF RESULTADO_INTRADIARIO ima-etf/resultado-intradiario
    Códigos de resposta

    Códigos de erro esperado no serviço RESTFul

    Código HTTP Descrição
    400 Requisição mal formada. Por favor, verificar a url da requisição.
    401 Requisição requer autenticação. Provavelmente o "código base64" enviado pela ANBIMA pode ter sido criado com credenciais inválidas, ou pode estar ausente no header da chamada.
    405 Método não permitido. O método da chamada deve ser POST, por favor, verificar.
    406 Conteúdo ou Content-Type inválido. Por favor verificar o conteúdo enviado no Body da chamada (esperamos um json contendo os campos referentes à notificação ).
    5XX Erro interno inesperado no servidor

    Códigos de sucesso

    Código HTTP Descrição
    200 Notificação recebida com sucesso.