Documentação Feed Fundos

ANBIMA Feed Fundos

1. Sobre Nossa API

O ANBIMA Feed Fundos é composto por APIs RESTFul baseadas no protocolo HTTP. Seu objetivo é disponibilizar dados referentes a fundos de investimentos. Disponibilizamos as seguintes APIs: Fundos Lista Completa, Fundos Detalhe e Fundos Série Histórica.

As informações são divididas em 6 contextos: Dados Cadastrais do Fundo, Prestadores de Serviço, Taxas de Administração, Movimentação de Cotas, Série Histórica e Documentos do Fundo.

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 nossas APIs?

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

    • protocolo: https
    • ambiente: api.anbima.com.br (Produção) ou api-sandbox.anbima.com.br/mocks (Sandbox)
    • produto: feed/fundos
    • versão: v1
    • pacote: fundos

    Logo, a URI a ser utilizada para acesso a qualquer recurso desta API seria https://ambiente/feed/fundos/v1/fundos

    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 e contextos de cada API, por favor, consulte a nossa documentação funcional.

  • API 1: Fundos Lista Completa:

    Nesta API é possível obter a lista completa de fundos de maneira paginada. Para acessá-la, deve-se utilizar a seguinte URI:https://<ambiente>/feed/fundos/v1/fundos

    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/fundos/v1/fundos

    Nos resultados da consulta, por padrão são mostrados os 1.000 primeiros fundos, ordenados pelo código do fundo, na página 0. Para alterar essa requisição, devem ser passados os parâmetros correspondentes na chamada, por exemplo, GET https://api.anbima.com.br/feed/fundos/v1/fundos?page=1&size=1000:

    • page: reflete a página dentro da lista de fundos apresentada. Por exemplo, se a lista contiver 16.000 fundos, listados 1.000 fundos por página, temos um total de 16 páginas. Caso o utilizador insira um valor superior ao limite de páginas, é retornado um erro ‘404 Not Found’.
    • size: limite de quantidade de fundos que aparecem por página. Para alterar a quantidade de registros na página deve ser utilizado este parâmetro, sendo que o mesmo possui um limite de 1.000 fundos. Caso seja inserido algum número superior, é adotado a quantia limite.

    Além da lista de fundos, o total de páginas e o total de registros (fundos) será retornado na página da consulta realizada.

    Contextos da API:

    Contexto no Feed Nome Contexto Descrição
    dados-cadastrais Dados Cadastrais do Fundo Informações referentes aos dados cadastrais de um fundo
  • API 2: Fundos Detalhe:

    Nesta API é possível obter as informações detalhadas de um fundo. Para acessá-la, deve-se utilizar a seguinte URI: https://<ambiente>/feed/fundos/v1/fundos/{codigoFundo}

    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/fundos/v1/fundos/{codigoFundo}

    Para realizar a consulta de detalhes de um fundo específico, o utilizador deve inserir no lugar do parâmetro {codigoFundo}, o código do fundo desejado. Dessa forma, resultará em uma informação mais completa, contendo todos os contextos para o fundo. Caso o fundo consultado possua informações de todos os contextos de informação, será retornado um código ‘200 OK’ e, caso haja algum dos contextos em falta, será retornado um código ‘206 Partial Content’.

    Contextos da API:

    Contexto no Feed Nome Contexto Descrição
    dados-cadastrais Dados Cadastrais do Fundo Informações referentes aos dados cadastrais de um fundo
    prestadores Prestadores de serviço Informações referentes aos prestadores de serviço de um fundo (administrador, gestor, custodiante, controlador de ativos e controlador de passivos)
    taxas Taxas de Administração Informações referentes às taxas aplicadas em um fundo
    movimentacao Movimentação de Cotas Informações de aportes, resgates e demais movimentações de cotas em um fundo
    serie_historica Série Histórica do Fundo Apresenta os dados periódicos de um fundo da última data disponível
    documentos Documentos do Fundo Apresenta a lista de documentos vinculados a um fundo
  • API 3: Fundos Série Histórica:

    Nesta API é possível obter todo o histórico (diário) de dados periódicos do fundo. Para acessá-la, deve-se utilizar a seguinte URI: https://<ambiente>/feed/fundos/v1/fundos/{codigoFundo}/serie-historica

    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 http://feed-vendor-api.apps.anbima.com.int/feed/v1/fundos/{codigoFundo}/serie-historica

    Para o retorno das informações de série histórica de um fundo específico, deve ser informado no campo {codigoFundo}, o código do fundo desejado. Esta consulta pode ser realizada por períodos de resultados, informando uma data início e uma data fim, por exemplo: GET https://api.anbima.com.br/feed/fundos/v1/fundos/{codigoFundo}/serie-historica?data-inicio=2019-11-19&data-fim=2020-11-14. Caso não seja passado nenhum parâmetro, é adotada como data final a mesma do dia da requisição e são retornados registros referentes ao período de 1 ano anterior à data final. Para alterar a consulta, são esses os seguintes parâmetros:

    • data-inicio: data inicial da consulta. Deve ser informada no formato “yyyy-MM-dd”.
    • data-fim: data final da consulta. Deve ser informada no formato “yyyy-MM-dd”.

    O range máximo de um período para consulta é 5 anos (60 meses) e, caso o período ultrapasse esse limite, será retornado o erro ‘400 Bad Request’. Se o utilizador inserir uma data inicial superior a data fim, é feita a substituição das mesmas e invertida a inicial pela final. Caso a data inicial esteja nula, será considerada a data referente a 1 ano anterior à data fim informada. Se por outro lado, for inserida a data inicial e a final estiver nula, esta última é considerada a data fim que compreende o período de 5 anos a partir da data informada. Os dados de série histórica são exibidos por ordem descendente da data de referência (do mais novo ao mais antigo registro). Se não for encontrado nenhum valor no período, é retornado um erro ‘404 Not Found’ e em caso de sucesso, o código ‘200 OK’ com a lista de séries históricas.

    Contextos da API:

    Contexto no Feed Nome Contexto Descrição
    serie_historica Série Histórica do Fundo Apresenta os dados periódicos de um fundo da última data disponível

    3. Requisições à API

    Para as requisições à esta API é necessário a combinação dos seguintes componentes: método (ou verbo) HTTP e URI do recurso. Todas as chamadas a recursos da API consideram a seguinte estrutura:

    GET https://<ambiente>/feed/fundos/v1/fundos/<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 recurso (pacote/item), 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 esta 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",
       "código_fundo”: ”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, 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
    codigo_fundo O código de referência do fundo.

    Instruçõ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 - Dados 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.
  • 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
    FUNDOS FUNDOS_LISTA_COMPLETA fundos
    FUNDOS FUNDOS_DETALHES fundos/{codigoFundo}
    FUNDOS FUNDOS_SERIE_HISTORICA fundos/{codigoFundo}/serie-historica
    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.

    Para acessar nossa documentação funcional, clique aqui.