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

Ambiente de testes Banco do Brasil - Aplicação

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.

Layout de Registro de Cobrança

O Layout de Registro de cobrança é o Layout que fará uma requisição POST na API