Documentação da API

A documentação da API está estruturada na plataforma Swagger no seguinte endereço:

De forma interativa, é possível navegar por todos os endpoints. Sua estrutura é composta por:

  • Título: No topo pode ser encontrado o nome da aplicação;
  • Versão: Junto ao nome também está a versão a que se refere a definição visualizada;
  • Descrição: Abaixo do título está uma breve descrição sobre a aplicação;

  • Endpoints: Após a descrição da aplicação, serão listados todos os endpoints, ou funcionalidades, que compões a API. São URL de acesso ao que se deseja acionar e podem estar organizados por assunto. Cada endpoint é uma seção retrátil que contém:

    • Uma breve descrição sobre o endpoint;
    • Os parâmetros de requisição: listagem com os detalhes dos dados que devem ser enviados para que a API possa executar a ação desejada. Nesta seção estão o nome, a descrição, o tamanho, o tipo e o domínio dos campos, bem como um exemplo de preenchimento. Também constam exemplos de requisições e a linguagem utilizada.
    • Os parâmetros de resposta: listagem com os detalhes dos dados que são enviados da aplicação para o requisitante. Nesta seção estão os possíveis códigos de resposta da aplicação com suas respectivas descrições, seguidos dos possíveis dados que a aplicação pode retornar ao requisitante, quando for o caso. Também constam exemplos de respostas e a linguagem utilizada.

Política de atualização da API

A seguir estão listadas as regras que definem as atualizações da API do Pre-matching:

  • Será trocada a versão de toda a API, mesmo que somente um endpoint tenha sido modificado de tal forma a produzir um menor impacto aos consumidores da API e a gestão destes sobre inúmeras versões.
  • Mudanças que serão consideradas para uma troca de versão:
    • Mudança de atributo na requisição e resposta (nome modificado, exclusão do atributo, tipo de dado).
    • Mudança de domínio do atributo na requisição ou resposta. Ex: Atributo com domínio definido de opções A, B e C e que uma delas deixe de existir
  • As inclusões de novos atributos nos DTOs de resposta da API não serão consideradas quebra de contrato e nesse caso, não será gerada uma nova versão do endpoint.

Versões da API

A seguir estão listadas as versões da API que estão disponíveis para integração. As versões estão em diferentes situações:

  • Versão atual – versão mais recente que está sendo mantida e evoluída e só será modificado caso se tenha quebra de contrato.
  • Versão em descontinuação – versão que será mantida durante um período e depois será extinta. O período será definido de acordo com a necessidade e complexidade de atualização de cada versão.
  • Versão descontinuada – após o período definido para a migração de uma versão, ela será descontinuada e não será mais possível consumi-la.
Versão da API Situação Data da remoção
2.0 Versão atual --
1.0 Versão descontinuada 18/11/2022

Release notes API versão atual

Endpoint Situação Impactos
POST /api/v2/negocios Alteração
  • Incluído o atributo dataLiquidação.
  • Alteração no código de retorno para 201.
    		•
    GET /api/v2/negocios Alteração
  • Incluídos os atributos transmissorComandosCedente, transmissorComandosCessionario e dataLiquidação.
  • Incluído também o atributo permiteIntermediacaoSemAssociacao que só é exibido para o intermediador.
    		•
    GET /api/v2/negocios/{id} Alteração
  • Incluídos os atributos transmissorComandosCedente, transmissorComandosCessionario e dataLiquidação.
  • Incluído também o atributo permiteIntermediacaoSemAssociacao que só é exibido para o intermediador.
    		•
    GET /api/v2/especificacoes/requisicoes/minhas Inclusão
  • Incluído para substituir o endpoint GET /api/v1/especificacoes/requisicoes.
  • Retorna somente as requisições do requisitante.
  • Incluído o atributo dataLiquidação.
    		•
    GET /api/v2/especificacoes/requisicoes Alteração
  • Passou a retornar as requisições já realizadas pela contraparte desde que o requisitante tenha lançado o negócio. Retorna também as requisições relacionadas (quebra de lote compromissada).
  • Alteração do parâmetro idNegocio para obrigatório.
  • Inclusão de novos atributos requisicoesRelacionadas e dataLiquidação.
    		•
    GET /api/v2/especificacoes/requisicoes/{id} Alteração
  • Passou a retornar uma requisição da contraparte desde que o requisitante já tenha lançado o negócio. Retorna também as requisições relacionadas (quebra de lote compromissada).
  • Inclusão de novos atributos requisicoesRelacionadas e dataLiquidação.
    		•
    POST /api/v2/especificacoes/requisicoes Alteração
  • Passou a receber e retornar uma lista para processamento de múltiplas requisições de uma mesma parte.
  • Inclusão do atributo idRequisicaoContraparte que será utilizado pelo cessionário para quebra de lote de compromissada.
  • Inclusão do atributo dataLiquidação. Para que seja identificada a resposta corretamente, deve ser enviada uma lista ordenada de requisições.
  • Alteração no código de retorno para 201.
    		•
    PUT /api/v2/especificacoes/{id} Alteração
  • Não houve alteração de contrato, entretanto em compromissadas com quebra de lote pelo cessionário, não é mais possível alterar a quantidade de títulos por este endpoint.
    		•
    PUT /api/v2/especificacoes/quebra-lote-lastro Inclusão
  • Incluído para permitir a alteração na quantidade de títulos quando há quebra de lote na compromissada pelo cessionário.
    		•
    GET /api/v2/evento Alteração
  • Incluído o evento requisição_especificacao_lancada.
    		•
    GET /api/v2/especificacoes Alteração
  • Incluídos os atributos quebraLoteLastro e dataLiquidação.
    		•
    GET /api/v2/especificacoes/{id} Alteração
  • Incluídos os atributos quebraLoteLastro e dataLiquidação.
    		•
    PUT /api/v2/negocios/{id}/permitir-intermediacao-sem-associacao Inclusão
  • Incluído para permitir intermediação sem associação.
    		•

    Observação: todos os endpoints que possuem os atributos de retorno valorFinanceiro, valorFinanceiroRetorno, precoUnitario, precoUnitarioRetorno e taxa terão seu tipo de dado alterado para texto.

    As operações à termo (3052 e 4052) só estão disponibilizadas na versão v2 da API.

    Eventos

    Esta funcionalidade foi criada para atender exclusivamente a API e possibilitar que o participante busque todos os eventos gerados pela plataforma em um único lugar. Na consulta, deve obrigatoriamente ser informada a data de movimento do dia e opcionalmente a data e hora a partir do qual o sistema deseja que sejam retornados os eventos.

    Os seguintes eventos serão gerados:

    Entidade Evento Quando o evento é gerado Para quem o evento é gerado
    Negócio negocio_registrado Quando as duas partes enviam o negócio e ele fica com o status Registrado
    • Participante transmissor de comandos do cedente momento do lançamento do negócio.
    • Participante transmissor de comandos do cessionário momento do lançamento do negócio
    Negócio negocio_lancado Quando a primeira ponta lança o negócio. Status: Aguardando lançamento da contraparte
    • Transmissor de comandos da contraparte.
    Requisição especificação requisicao_especificacao_lan cada Quando uma requisição é lançada e a contraparte já registrou o negócio
    • Transmissor de comandos da contraparte no momento do lançamento do negócio.
    Requisição especificação requisicao_especificacao_lan cada Quando um negócio é lançado e já existe requisição de especificação lançada
    • Participante que esta realizando o lançamento.
    Especificação especificacao_criada Quando a especificação é gerada
    • Participante que realizou a requisição da especificação pelo cedente
    • Participante que realizou a requisição da especificação pelo cessionário
    Especificação especificacao_alterada Quando uma especificação é alterada
    • Participante que realizou a requisição da especificação pela contraparte
    Especificação especificacao_ag_confirmaca o_cedente Quando uma especificação é confirmada pelo cessionário e ainda não foi confirmada pelo cedente
    • Participante que realizou a requisição da especificação pelo cedente
    • Participante que realizou a requisição da especificação pelo cessionário
    Especificação especificacao_ag_confirmaca o_cessionario Quando uma especificação é confirmada pelo cedente e ainda não foi confirmada pelo cessionário
    • Participante que realizou a requisição da especificação pelo cedente
    • Participante que realizou a requisição da especificação pelo cessionário
    Especificação especificacao_confirmada Quando a ambas as partes confirmam a especificação
    • Participante que realizou a requisição da especificação pelo cedente
    • Participante que realizou a requisição da especificação pelo cessionário
    Comando comando_gerado_credito quando o comando do tipo crédito de uma especificação é gerado
    • participante que realizou a requisição da especificação pelo cessionário
    Comando comando_gerado_debito quando o comando do tipo débito de uma especificação é gerado
    • participante que realizou a requisição da especificação pelo cedente

    Os demais eventos serão descritos posteriormente conforme a evolução da plataforma.

    Códigos de Erro do Pre-matching

    Versão da API Situação
    001 Informação obrigatória ausente.
    002 Formatação inválida.
    003 Código de operação inválido.
    004 ISelic inválido.
    005 Participante não tem permissão para fazer requisição pela parte informada.
    006 Título vencimento inválido.
    007 Código ISIN incompatível com título vencimento.
    008 Data de movimento inválida.
    009 Atributo não compatível com o tipo de operação.
    010 A quebra de lote só pode ser realizada por uma das partes.
    011 Participante não tem permissão para executar a ação.
    012 O negócio não pode ser cancelado pois já houve lançamento pela contraparte.
    013 A ação não pode ser realizada, negócio cancelado.
    014 A ação não pode ser realizada, negócio concluído.
    015 Informação incompatível com o negócio.
    016 Conta inválida para o negócio
    017 O identificador fiscal não pertence ao dono da conta.
    018 Quebra de lote já realizada pela contraparte.
    019 A quantidade informada somada a outras especificações ultrapassa a quantidade do negócio.
    020 A data de movimento do negócio não é a data atual do Selic.
    021 A requisição de especificação não pode ser cancelada pois possui uma especificação associada.
    022 A especificação não pode ser confirmada.
    023 Negócio inválido.
    024 Especificação não confirmada. A versão informada não é a versão atual da especificação.
    025 A ação não pode ser realizada. Especificação confirmada.
    026 Especificação inválida.
    027 A data de retorno não pode ser anterior à data do negócio.
    028 Número de comando indisponível para geração automática.
    029 Atributo não permitido para a requisição.
    030 Requisição já realizada pela parte.
    032 A ação não pode ser realizada, requisição cancelada.
    033 O negócio só pode ser concluído se seu status for Registrado.
    034 O negócio não pode ser concluído, existem especificações não confirmadas.
    035 Ocorreu um erro: fora do horário da grade.
    036 O participante da intermediação deve ser cedente em um negócio e cessionário no outro.
    037 Título incompatível entre os negócios.
    038 Quantidade de título incompatível entre os negócios e/ou outras associações.
    039 Um dos negócios não permite outra associação.
    040 A conta do intermediador deve ser do tipo conta de corretagem em todas as especificações.
    041 A conta do participante intermediador deve ser a mesma em todas as especificações dos negócios.
    042 A quebra de lote só pode ser realizada pelo negócio de menor quantidade de títulos.
    043 A associação não pode ser removida. Já foram gerados comandos para os negócios.
    044 A especificação não pode ter conta do tipo corretagem para as duas partes.
    045 O negócio não pode ser cancelado pois está associado a outro negócio.
    046 Ação não permitida para a operação.
    047 A associação só permite quebra de lote em um dos negócios.
    048 Um dos negócios já possui associação em outra posição (compra/venda)
    049 Departamento não permitido.
    050 Indique um departamento para o negócio.
    051 Conta inválida para o departamento do negócio.
    052 A ação não pode ser realizada. A parte possui requisição de especificação ativa.
    053 A associação só pode ser realizada entre negócios do mesmo departamento do intermediador.
    054 A ação não pode ser realizada, o negócio possui associação.
    055 Requisição inválida.
    056 Só é possível quebrar lote de compromissada em operações em que o Bacen é o cedente.
    057 A soma da quantidade de títulos das requisições deve ser igual a quantidade do lastro.
    058 As requisições devem ser referentes ao mesmo negócio e à mesma parte.
    059 O lastro não pode ser alterado pois já foi quebrado pela contraparte.
    060 Somente o cessionário pode realizar quebra de lote de compromissada.
    061 As especificações alteradas devem ser de uma mesma requisição do cedente.
    062 As quantidades de todas as especificações do lastro devem ser informadas.
    063 Ação não permitida para requisições sem quebra de lote.
    064 Data de liquidação inválida.
    065 Somente o cedente pode informar número de comando.
    066 A associação só pode ser realizada entre negócios da mesma operação.
    067 A associação só pode ser realizada entre negócios que possuem a mesma data de liquidação.
    068 Negócio deve possuir pelo menos uma especificação confirmada com conta de corretagem.
    069 Ação não permitida para o status do negócio.
    070 A ação não pode ser realizada. Em um dos negócios foi indicado que ele não será associado.
    071 Ação já realizada pela parte.
    999 Erro no processamento.

    Histórico de versões do manual

    Data Descrição
    24/07/2020 Versão inicial do documento.
    16/09/2020 Atualização do documento com o endpoint de buscar eventos.
    26/11/2020 Atualização do documento com a descrição restante do fluxo de definitivas simplificadas.
    21/01/2021 Atualização do documento com ajustes nos códigos de erros, funcionalidade concluir negócio e descrição do fluxo de compromissada.
    27/04/2021 Atualização do documento com inclusão de chinese wall e intermediação em lote. Inclusão de novos códigos de erro em função das novas funcionalidades.
    13/07/2021 Atualização do documento com inclusão de quebra de lote de um lastro de compromissada. Atualização do buscar que requisições que permitem que sejam vistas pela contraparte. Inclusão de novos eventos. Inclusão de novos códigos de erro em função das novas funcionalidades. Alteração da versão mais atual da API para 2.0
    29/11/2021 Atualização do documento com ajuste de lançamento único do negócio quando o Bacen é a primeira ponta a realizar o lançamento. Neste caso, a contraparte não precisará efetuar o lançamento. Incluir da informação de transmissor de comandos das partes no buscar negócio. Manual referente à versão em homologação. A data de entrada em ambiente de produção dessa funcionalidade será divulgada oportunamente.
    22/03/2022 Atualização do documento com passo a passo dos fluxos da interface Web. Inclusão das operações definitivas a termo, 3052 e 4052.
    08/04/2022 Atualização do documento com inclusão da regra de número de comando na especificação e novos códigos de erro.
    21/06/2022 Atualização do documento com ajustes na denominação das operações 3052 e 4052.
    14/11/2022 Atualização do documento com inclusão da intermediação sem associação na plataforma.
    20/12/2022 Atualização do documento com inclusão da funcionalidade de upload de arquivo.
    Voltar para Pre-matching
    Undefined