Layout Requisição API

Página criada com o objetivo de auxiliar a criação dos layouts de requisições para as APIs.

O que é uma API?

Por exemplo, imagine que você está usando um aplicativo de previsão do tempo em seu celular. Esse aplicativo precisa obter informações atualizadas sobre o clima de uma fonte confiável, como um serviço meteorológico. Em vez de criar seu próprio sistema para coletar esses dados, o aplicativo utiliza uma API fornecida pelo serviço meteorológico. A API fornece métodos (ou opções) para solicitar informações específicas sobre o clima, como a temperatura atual, a previsão para os próximos dias, etc. O aplicativo utiliza esses métodos para obter os dados de que precisa, como se estivesse fazendo um pedido no cardápio, e depois exibe essas informações para você.

Em resumo, uma API é como um intermediário que permite que diferentes programas se comuniquem e compartilhem informações de maneira padronizada, tornando a integração entre sistemas mais fácil e eficiente. É como o cardápio que simplifica o processo de fazer pedidos em um restaurante.

Tipos de métodos das requisições

   GET: Solicita a recuperação de um recurso específico no servidor. É usado principalmente para recuperar informações, como visualizar uma página da web ou buscar dados.

   POST: Envia dados para o servidor para que ele processe ou armazene. Geralmente usado para enviar informações do usuário, como preenchimento de formulários online.

   PUT: Atualiza um recurso existente no servidor ou cria um novo se ele não existir. O conteúdo enviado no corpo da solicitação substitui completamente o recurso existente.

   PATCH: Similar ao PUT, mas usado para aplicar modificações parciais a um recurso. A solicitação contém apenas as alterações que devem ser aplicadas ao recurso existente.

   DELETE: Solicita a remoção de um recurso no servidor. Usado para excluir informações ou recursos específicos.

Dentre esses métodos para as requisições, os mais utilizados no ERP são o GET, POST, PATCH e DELETE.

Seções

O layouts das requisições contém 3 seções, sendo elas:

Cabeçalho: identifica a seção onde serão coletados os dados necessários para que a requisição seja feita (nomenclatura utilizada pelo layout dos bancos para definir a seção);

Cabeçalho Grupo: identifica a seção onde serão coletados os parâmetros necessários para que a requisição seja feita (nomenclatura utilizada pelo layout dos bancos para definir a seção);

Dados: identifica a seção onde serão coletados os dados necessários para o corpo da requisição (nomenclatura utilizada pelo layout dos bancos para definir a seção);

Entendendo a estrutura de envio da requisição

A estrutura de envio de requisições de uma API é chamada de CURL, sendo uma das mais utilizadas, sua estrutura é a seguinte:

A primeira linha indica o método utilizado na requisição, que neste caso é POST. Esse método é usado quando se deseja registrar ou inserir informações no servidor, ou seja, enviar novos dados.

A segunda linha mostra o endereço (URL) da requisição. Esse link é dividido da seguinte forma:

https://api.sandbox.bb.com.br/cobrancas/v2

/boletos → representa o serviço que está sendo utilizado. Cada API possui suas próprias rotas (ou serviços). Por exemplo, uma instituição de ensino, ao clicar em “fazer login”, utilizaria a rota /login. Uma mesma API pode conter várias rotas, cada uma com uma finalidade diferente.

?gw-dev-app-key=e85f6f4c238ad52eaeb9cf39dd4777e → é a chave da aplicação, usada para autenticar a requisição e identificar o sistema que está acessando a API.

Nas requisições do tipo POST, normalmente o conteúdo principal é enviado no corpo da requisição, e a URL costuma ser mais simples. Já em requisições do tipo GET, as informações são enviadas diretamente na URL.

Por exemplo: https://api.sandbox.bb.com.br/cobrancas/v2/boletos?gw-dev-app-key=e85f6f4c238ad52eaeb9cf39dd4777e&indicadorSituacao=A&agenciaBeneficiario=452&contaBeneficiario=123873

Após a chave do aplicativo (?gw-dev-app-key=...), os demais valores são separados pelo &. Esses valores funcionam como parâmetros ou filtros da requisição. No exemplo acima, estamos solicitando as cobranças com indicador de situação igual a A, pertencentes à agência 452 e conta 123873.

A terceira linha da requisição indica o tipo de retorno aceito pela aplicação, definido por meio do cabeçalho: -H 'accept: application/json' Isso informa à API que o sistema (ERP) espera receber os dados de resposta em formato JSON, para que possa tratá-los corretamente.

A quarta linha mostra o campo Authorization, que é responsável por autenticar o acesso ao servidor: -H 'Authorization: Bearer [token]' Esse token tem um tempo de validade limitado (no caso do Banco do Brasil, cerca de 10 minutos). Após esse tempo, é necessário gerar um novo token, mas o próprio ERP faz esse processo automaticamente.

A quinta linha define o tipo de conteúdo que está sendo enviado à API: -H 'Content-Type: application/json' Isso indica que os dados estão sendo enviados em formato JSON, o padrão mais utilizado para comunicação entre sistemas.

As demais linhas representam o corpo da requisição, que contém todas as informações a serem enviadas ao servidor. No caso da API de boletos, o corpo inclui dados como o número do convênio, número da carteira, data de emissão, data de vencimento, valores, descontos, entre outros campos obrigatórios exigidos pela API.

O corpo é utilizado principalmente em requisições do tipo POST, PATCH e DELETE. Já no método GET, as informações são enviadas apenas na URL, e não existe corpo na requisição.

Layouts

Para a criação dos layouts de envio de requisição, você pode encontrar no ERP nas seguintes abas: Finanças->Layouts de Envio Online

Os primeiros passos é criar a seção cabecalho. Ao adicionar a seção cabeçalho será adicionado os valores necessários para a requisição, basta preencher:

Os valores são preenchidos da seguinte maneira (Esses valores são essenciais para todos os layouts de envio):

End-Point - é o link em que a requisição será feita;

Requisição - é o serviço a ser utilizado;

Authorization – é o meio de autenticação exigido pela API para a realização das requisições. No caso do Banco do Brasil, é necessário enviar o client-id e o client-secret codificados em Base64.

O valor desse campo é composto por três partes, separadas por ponto e vírgula (;):

Primeiro valor: indica se as credenciais devem ser convertidas em Base64 (True ou False).

Segundo valor: representa a chave do cabeçalho (Header) utilizada na requisição, geralmente Authorization.

Terceiro valor: define o tipo do token (token type), normalmente Bearer.

Exemplos:

 Banco do Brasil: True;Authorization;Bearer

 Itaú: False;Authorization;Bearer

Url-OAuth - é o link em que a requisição será autenticada, ou seja, é o link em que será coletado um novo token (Authorization);

Client-Id e Client-Secret - São as chaves que são utilizadas para obter o token (Authorization) quando a API não fornece o token;

Scopos - É a identificação de quais serviços serão utilizados, esses valores são de uso interno da API;

Chave-Aplicativo - é a chave que será utilizada indicando qual o aplicativo que está fazendo a requisição;

Ident-Banco-Conta - é a identificação do código do banco do ERP + o número da conta, esse campo se faz necessário para a guarda das credenciais no XML de configuração.

Layout de Registro de Cobrança

Ao criar o layout de registro de cobranças, você vai precisar da seção Dados, que será utilizada para montar o corpo da requisição, ela é criada da seguinte maneira:

Para criar os elementos, você pode utilizar Textos, Formulas e Campos. Como comentando anteriormente a estrutura do envio da requisição da API é formada da seguinte maneira:

Ou seja, ao inserir os valores na seção dados, na coluna Descrição, vai ser informado, por exemplo, numeroTituloCliente e na coluna Valor vai ser informado o valor que vier depois dos dois pontos, no caso 00031285570000030000, o mesmo para mensagem de bloqueto, na coluna Descrição, vai ser informado mensagemBloquetoOcorrencia e na coluna Valor vai ser informado Outro Texto.

Já no caso do Desconto, pode-se perceber que ele possui valores filhos (tipo, dataExpiracao, porcentagem e valor). Eles são um caso especial, para ser criado o corpo do desconto, se utiliza a mesma maneira do exemplo anterior, porém, será necessário selecionar o Tipo dos Dados como Array ou Objeto.

Tipo Objeto:

 desconto {
   tipo: 1,
   dataExpiracao: "30.01.2024",
   porcentagem: 0,
   valor: 12.34
 }

Tipo Array

 desconto [
  {
   tipo: 1,
   dataExpiracao: "30.01.2024",
   porcentagem: 0,
   valor: 12.34
  },
  {
   tipo: 1,
   dataExpiracao: "30.01.2024",
   porcentagem: 0,
   valor: 12.34
  }
 ]

O tipo Array é um coleção, podendo ter muitos objetos dentro dele

Exemplo utilização campo pai:

 desconto {
   'valor':1.00, (Campo pai = desconto)
   'vencimento':01.01.0001 (Campo 
                              pai = desconto)
 }

Para as formatações de datas ou valores, basta utilizar as colunas Decimais e Mascara. Algo que vale ressaltar é que os campos e valores não precisam ser montados na sequência (exceto os campos que são aninhados, Ex: desconto), porém, o ideal é que seja em sequência, para evitar quaisquer transtornos.

Layout de Consulta de Cobranças

Como citado anteriormente, as consultas com o método GET, não possuem corpo, mas possuem parâmetros, e esses parâmetros são informados na seção cabecalhoGrupo:

A criação segue o mesmo padrão do corpo do layout de registro de cobrança. Na coluna “Descrição” deve ser informado o nome do campo, e na coluna “Valor” o valor que será atribuído ao filtro (parâmetro).

É importante observar que alguns parâmetros são obrigatórios, mas isso varia conforme a API utilizada — portanto, é necessário consultar a documentação oficial de cada API para verificar quais campos são exigidos.

As linhas 11 e 12 representam filtros opcionais, geralmente utilizados em formulários com filtros por período. Para utilizá-los, basta informar:

dataini- + nome do campo → indica a data inicial que será filtrada;

datafim- + nome do campo → indica a data final que será filtrada.

Na coluna “Valor”, deve ser informada a máscara de data aceita pela API.

Filtros como dataini- e datafim- são automaticamente substituídos pelas datas informadas no formulário durante a montagem da requisição. Esses indicadores também podem ser incluídos no JSON que fica na seção “Dados”.

Layouts de Retorno

Para qualquer tipo de API, toda requisição feita é obtido um retorno, seja com uma mensagem de sucesso, ou com uma estrutura parecida com a do CURL, cada API tem sua particularidade.

E para isso é preciso criar os layouts que receberão esse retorno. Esses layouts as vezes trabalharão em conjunto com os layouts de envio ou individualmente. Ao criar um layout do tipo retorno, será adicionado duas classes relacionadas, RetornoReqAPI e RetornoReqAPIItens. A montagem é semelhante a do arquivo, com a diferença de que no arquivo é preciso informar a posição do campo.

Para criar um layout de retorno você deve ir em Finanças->Layouts de Retorno Online.

Layout de Retorno de Consulta de Cobranças

Como citado alguns layouts trabalham em conjunto com os layouts de envio, no caso desse exemplo, irei utilizar um layout que trabalha em conjunto com o layout de consulta de diversas cobranças.

A estrutura desse tipo de layout é mais flexível, ou seja, ela não fica presa igual ao corpo que é preciso ser montado no registro da cobrança. Porém é preciso algumas configurações essências para o fluxo:

Para que o fluxo funcione corretamente em alguns casos, como nesse layout exemplo ele trabalha em conjunto com a consulta de diversas cobranças, é preciso informar o proximoIndice da pesquisa, no caso do banco do brasil para cada consulta é coletado 300 cobranças, então é preciso guardar o esse valor para que a próxima consulta seja a partir do index 300. Então na coluna Valor você deverá informar o nome do campo que guarda esse valor no retorno.

Na segunda seção vai o nó (campo) que contém as cobranças, você não precisa criar uma nova seção, poderia ser no mesmo lugar, mas eu criei por questões de organização. Então, nessa segunda seção vai o nó (campo) que contém as cobranças, Ex:

Na coluna Valor você deve informar o nome do campo.

Na seção “Dados”, devem ser informados os valores de retorno que serão coletados para uso dentro do ERP. Na coluna “Descrição”, deve ser indicado o campo da classe que receberá o valor, e na coluna “Valor”, o nome do campo retornado pela API que contém esse dado.

Para permitir o reaproveitamento do layout de retorno, há situações em que o mesmo layout é utilizado em diferentes cenários. Nesses casos, alguns campos podem se repetir, conforme o exemplo abaixo:

O campo RetornoReqAPIItens->CodEstadoTituloCobranca pode, em uma requisição, receber o valor retornado pela API como codigoEstadoTituloCobranca, enquanto em outro recurso a API pode retornar codEstadoCobranca.

Quando isso ocorre, o layout mantém o primeiro valor encontrado. Ou seja, se o campo codigoEstadoTituloCobranca for retornado e preencher o campo correspondente no ERP, e em seguida a API também retornar codEstadoCobranca, o layout não substituirá o valor já atribuído.

Layout de Retorno para Tratamento de Erros

O layout de tratamento de erro é essencial quando o assunto é retorno da requisição, pois como citado anteriormente eles podem trabalhar em conjunto com os layouts de envio, como também individual, e muita das vezes esses retorno são de erros, e erros de API's são muitos genéricos, Exemplo:

Requisições HTTPs, sejam elas de envio ou os próprios retorno, retornam um código:

Códigos com o valor >= 200 dizem que a requisição foi um sucesso

Códigos com o valor >= 300 dizem que a requisição foi redirecionada para outro lugar, ou seja, suponhamos que eu faça a requisição no end-point https:/api.sandbox.bb.com.br/cobrancas/v2, e esse end-point não existe mais, a aplicação automaticamente me encaminhara para outro end-point configurado no servidor da API

Códigos com o valor >= 400 dizem que a requisição obteve um erro, porém esse erro foi do lado de quem solicitou, seja por um campo informado incorretamente.

Códigos com o valor >= 500 dizem que houve um erro na requisição, mas do lado do servidor, seja por estar fora do ar, ou algum evento não tratado pela própria API.

E então esse layout de tratamento de erro, ficará encarregado de tratar esse retorno, no caso do registro da cobrança o ERP primeiro faz uma consulta na API com o nosso número do boleto, e como a cobrança ainda não existe no servidor do banco do brasil, é retornado um erro, dizendo que o nosso número da cobrança foi informado incorretamente, e de fato esse erro faz sentido, pois como eu estou tentando registrar uma cobrança ela ainda não existe, mas essa consulta também é essencial pois ela busca primeiro se a cobrança existe para não ocorrer o caso de duplicidade. E esse erro retornado é o código 400, pode ser que o usuário deixou de informar também o valor da cobrança, isso resultaria em um erro de código 400, então pra isso foi preciso criar os layouts de tratamento de erro.

Na primeira seção (cabecalho) vai ser informado o nó (campo) pai do retorno, Ex:

Porém, esses nós (campos) pai retornado nem sempre tem o mesmo nome, no caso é erros, mas alguns erros também retornam errors, erro no singular, então é preciso que no cabeçalho seja colocado todas as variações separadas por virgula, exemplo: erros,errors,erro

No cabecalhoGrupo é preciso informar o código do erro, como citado anteriormente os erros são muitos genéricos, mas para que os erros sejam identificados, cada um tem um código, no caso da consulta da cobrança antes de registrar ela, é consulta e o erro retornado é o código 4678420.1, nota-se que esse código está sendo informado no cabecalhoGrupo, ou seja, quando o retorno da requisição conter esse código no erro, a aplicação não será parada, por que esse retorno era o esperado, para encontrar esses código de erros na documentação do banco do brasil:

Na imagem acima é possível visualizar todos os códigos de erros que podem acontecer, então todos os código que serão previstos, devem ser adicionados no cabecalhoGrupo.

Na seção Dados, é preciso informar os nome dos campos que contém o código do erro e a mensagem, isso é essencial para erros que não são previstos, e segue a mesma lógica do cabecalho, como o retorno é genérico, pode ser retornado o nó (campo) pai com os nomes erros,errors,erro e a mensagem como mensagem,message.

Informar Layouts na Conta

Para informar os layouts criados, é preciso entrar no cadastro das contas na aba Cobrança API, ali você pode informar todos os layouts.

Valores de Acoplamento

Para poder informar os valores de acoplamentos corretamente, aqui está alguns exemplos:

Como citado anteriormente, caso a API forneça uma Authorization deve ser informada, já para as linha Client-Id e Client-Secret você deve informar os valores que a API fornece, para a chave do aplicativo já é um pouco diferente, pois para o banco do brasil em especifico, eles pedem que seja informado o valor gw-dev-app-key=sua_chave, e como cada API tem seu estilo de nomeclatura, é necessário informar antes do gw-dev-app-key= o sinal de "?", mas isso pode ser preciso somente para a API do banco do brasil, talvez outras API's tratam isso de uma forma diferente.

Parametrização das Ocorrência Bancária

Para parametrizar as ocorrências bancárias referentes as requisições por meio da API, segue a imagem abaixo:

A nova coluna Cod.Api indica uma relação do código de retorno por arquivo com o retorno da API

O tipo de ação de envio de cobrança por API permanece sendo o Envio_Cobranca_Api, aonde por sua vez pode ser parametrizado com qualquer código, o motivo de ter essa ação é pelo fato de que no modo convencional de gerar as cobranças pela remessa de arquivo não criava o Nosso Número, e sim somente na impressão do boleto. Como para registro de cobranças por meio da API é obrigatório o envio do Nosso Número ele é gerado assim que é gravada a remessa online, como o tipo de ação Envio_Cobranca_Api.

Formulas

No caso do Banco do Brasil é preciso que o nosso número contenha 20 caracteres no total, sendo 7 deles o número do convênio e 10 de controle (que seria o nosso número da cobrança no ERP) e zeros a esquerda para preencher os 20 caracteres, ficando assim: 00031285570001798547, aqui está uma formula que monta esse valor.

Nosso Número Banco do Brasil: NrParaTexto([[ConcatenarValores([numeroConvenio], , [[NrParaTexto({Cobranca.NossoNumero}, 10, False, 0, False)]], , , , )]], 20, False, 0, False)

Filtros Adicionais

Cabeçalhos adicionais podem ser incluídos adicionando novos elementos na seção de cabeçalho. Devem ser adicionais de acordo com as exigências da API.

Nome Tag deve ser usada quando houver tags com o mesmo nome sendo do tipo VrAcopl, por exemplo desconto e juros que possuem uma tag filha chamada 'tipo'. Se não preenchida, será usada a coluna de identificação/descrição.

Filtro de Datas

  dataini-nome_do_campo
  datafim-nome_do_campo
  periodo-nome_do_campo

Filtro de consulta

  pagina-nome_do_campo
  situacao-nome_do_campo

Ultima atualização em 10/11/2025