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.
HEAD: Semelhante ao GET, mas solicita apenas os cabeçalhos da resposta, não o corpo. Isso é útil para verificar informações, como verificar se um recurso foi modificado recentemente.
OPTIONS: Solicita informações sobre as opções de comunicação disponíveis para um recurso, como quais métodos e cabeçalhos são suportados.
CONNECT: Usado para estabelecer uma conexão de rede com um recurso, geralmente para configurar túneis SSL/TLS (usados para segurança).
TRACE: Usado para depuração e diagnóstico, solicita que o servidor retorne uma mensagem de depuração que pode ser útil para rastrear problemas de comunicação.
CONNECT: Esse método foi originalmente definido para ser usado com um proxy que pode dinamicamente se tornar um túnel. No entanto, ele não é amplamente utilizado na prática.
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);
Criação dos Layouts
Logo abaixo você tem o passo a passo de como criar os layouts para que seja possível fazer as requisições, lembrando que os exemplos utilizados serão com o ambiente de homologação do Banco do Brasil, mas poderia ser com qualquer outro, a criação dos layouts se tornou algo genérico:
1° passo: Você deve entrar no portal do Banco do Brasil e fazer o login
2° passo: Com o login realizado, você deve ir até o ambiente de testes, basta clicar em SandBox
3° passo: No ambiente de teste do Banco do Brasil, vá até API's -> Cobrança
4° passo: Com a API de cobrança selecionada, basta clicar no menu boletos
Pronto, dessa forma já estamos preparados para começar a criação dos Layouts, mas antes é necessário que entenda como funciona o link que é enviado para a requisiçã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 mostra o método que está sendo enviado na requisição, POST, ou seja, essa é uma requisição de registro/inserção; A segunda linha mostra o link da requisição, esse link é divido da seguinte maneira:
https:/api.sandbox.bb.com.br/cobrancas/v2 - É o End-Point da requisição, esse link é padrão para todos os clientes
/boletos - É o serviço a ser utilizado, cada API possui o seu, por exemplo, uma instituição de ensino, ao clicar em fazer login para entrar na sua conta, o serviço a ser utilizado é /login. Uma API pode ter várias rotas (serviços).
?gw-dev-app-key=e85f6f4c289d565aeb9cewq9dd4777e - É a chave da aplicação, cada API tem uma chave que é necessária para poder ser autenticada no servidor
Para requisições com o método POST, as requisições geralmente possuem pouco conteúdo, os valores são concentrados no corpo, para requisições GET, o conteúdo geralmente são concentrados no próprio link, um exemplo: https:/api.sandbox.bb.com.br/cobrancas/v2/boletos?gw-dev-app-key=e85f6f4c238ad5255sdfdb9321213f39dd4777e &indicadorSituacao=A&agenciaBeneficiario=452&contaBeneficiario=123873
Após a chave do aplicativo (?gw-dev-app-key=e85f6f4c238ad5255sdfdb9321213f39dd4777e), você pode perceber que os outros valores são concatenados com o E comercial (&), esses valores são como filtros para a requisição, ou seja, eu vou querer buscar cobranças que possui o indicador de situação = A, as cobranças que estão na agencia = 452 e a cobranças que estejam na conta = 123873, esses valores são chamados de parâmetros;
A terceira linha mostra o tipo que a aplicação aceita de retorno, por exemplo, é o tipo de retorno que o ERP aceita para fazer suas tratativas;
A quarta linha mostra a Authorization, ela é necessária para fazer a autenticação sua no servidor, para que seja possível fazer as requisições, esse valor possui um tempo de expiração definido por cada API, no caso do banco do brasil a autorização dura em cerca de 10 minutos (mas não se preocupe, o ERP cuida dessa parte);
A quinta linha mostra o tipo de envio que a API vai receber, nesse caso você está dizendo para API que ela vai receber um arquivo do tipo JSON;
Para o restante das linhas você tem o corpo da requisição, ali é concentrado todo os dados que serão enviados para a requisição, o corpo é mais utilizado em requisições com o método POST, PATCH, DELETE, o GET não utiliza. O corpo contém os valores como o nosso número do boleto, data de vencimento, valor, valor do desconto e etc.
Layouts
Para a criação dos layouts de envio de requisição, você pode encontrar no ERP nas seguintes abas: Finanças->Contas a Receber->Cobrança Bancária->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 autorização que a API exige para realizar as requisições, ou seja, no caso do Banco do Brasil é preciso enviar o client-id e o client-secret em base64, então o primeiro valor se refere ao fazer o hash em base64 das credenciais ou não, devendo ser informado (True ou False), seguido de um ponto e vírgula, e o próximo valor é a chave do Header da requisição para a autorização (Authorization), seguido de um ponto e vírgula, e o próximo valor é o tipo do token (token type) Bearer.
Valor do campo Banco do Brasil: True;Authorization;Bearer
Valor do campo Itáu: False;Authorization;Bearer
Lembrando que esse é para a API do Banco do Brasil, podendo variar para os outros bancos;
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 marcar a coluna Campo Aninhado. Então, todos os valores que vierem dentro de desconto, como também o próprio campo desconto, deverá ser marcado como campo aninhado.
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 é semelhante a do corpo do layout de registro de cobrança, na coluna Descrição vai o nome do campo e na coluna Valor vai o valor que será atribuído no filtro (parâmetro), lembrando que alguns parâmetros são obrigatórios, porém é preciso ler a documentação para ver quais, pois cada API tem o seu. As linhas 11 e 12 são filtros opcionais, que serão utilizados em formulários que terá filtros de períodos, para utiliza-los basta colocar o valor dataini- (Para a data inicial que será filtrada) ou datafim- (Para a data final que será filtrada) + o valor do campo e na coluna Valor a máscara de data que a API aceita.
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->Contas a Receber->Cobrança Bancária->Layouts de Retorno Online.
Layout de Retorno de Consulta de Cobranças
Com 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, você deve informar os valores do retorno que serão coletados para uso no ERP. Então na coluna Descrição vai ser informado o campo da classe que recebera o valor e na coluna Valor o nome do campo que guarda esse valor.
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)
Ultima atualização em 19/01/2024