Sobre a nossa API

Antes de falarmos das credenciais de acesso, é importante falar como a nossa API é estruturada.

Toda a comunicação com a nossa API é feita via HTTP através de requisições POST passando um objeto JSON estruturado no body da requisição. Esse objeto JSON tem o seguinte padrão.

avisoNote que nós não usamos o padrão REST, ao invés disso, nossa API é baseada em um conceito interno de eventos que são objetos trafegados no body das requisições.
COPIAR
{
"flowId": "a0c700c2-7055-11ea-bc55-0242ac130003",
"id": "a0c70306-7055-11ea-bc55-0242ac130003",
"name": "do:something",
"version": 1,
"payload": {
"param1": "someValue1",
"param2": "someValue2"
},
"identity": {
"clientId": "MY_ID"
},
"auth": {
"clientSecret": "MY_PASS"
},
"metadata": {}
}

O que são os campos flowId e id?

São identificadores UUID gerados de forma aleatória. O primeiro diz respeito a como o Guiabolso rastreia as requisições dentro da sua plataforma e o segundo é apenas um identificador que identifica esse evento específico. Você pode passar qualquer identificador aqui contanto que ele seja único.

O que são os campos name e version?

Dizem respeito ao nome e versão do evento exposto pela nossa API. No exemplo acima estamos chamando um evento chamado "do:something" na versão 1. O mesmo evento pode ter versões diferentes (note a diferença do padrão REST aqui).

O que é o campo payload?

O payload define os parâmetros a serem passados para a nossa API. No exemplo acima param1 e param2 são parâmetros passados para o evento "do:something"

O que são os campos identity e auth?

O campo identity define o ID da sua credencial enquanto o campo auth diz respeito a sua senha ou secret.

Respostas da API

As repostas feitas para nossa API, quer sejam bem sucedidas ou não, também estarão dentro deste padrão. Isso quer dizer que dentro da resposta HTTP haverá um body com o seguinte objeto JSON. Note que os valores de flowId e id são os mesmos passados na requisição anteriormente e que o nome do evento possui a palavra response atrelada a ele.

COPIAR
{
"flowId": "a0c700c2-7055-11ea-bc55-0242ac130003",
"id": "a0c70306-7055-11ea-bc55-0242ac130003",
"name": "do:something:response",
"version": 1,
"payload": {},
"auth": {},
"identity": {},
"metadata": {}
}

Tipos de Erros da API

Se um erro ocorrer na API, o erro será contextualizado no próprio nome do evento.

  • do:something:error - Erro genérico referente a um status code 500
  • do:something:notFound - Nome do evento ou parâmetro não encontrado na plataforma
  • do:something:badRequest - Erro na requisição (parâmetro faltante, etc.)
  • do:something:unauthorized - Acesso não concedido
  • do:something:forbidden - Requisitante não possui acesso aos recursos requisitados
  • do:something:userDenied - Usuário negou acesso do cliente OAuth em seu nome
  • do:something:resourceDenied - Usuário negou acesso a um recurso requisitado por cliente
  • do:something:expired - Token de acesso em nome de usuário via OAuth expirado
  • do:something:redirect - Deve ser feito um redirecionamento para a URL contida na resposta

Considerações Finais

Se você quiser saber mais sobre este padrão de comunicação na API do Guiabolso, a implementação está disponível em várias linguagens como Javascript, Python e Kotlin através da nossa página no github

Agora vamos falar das credencias de acesso da API para a integração com nosso produto.

Próximos passos

overview

Credenciais

Nós utilizamos o protocolo de autorização OAuth 2.0 para conceder autorização na nossa API, mais especificamente...

overview

Pré-requisitos

Para seguir com a integração você vai precisar das credenciais, isto é, as chaves fornecidas para ...

overview

Fluxo de Integração

A integração com o produto do Guiabolso Connect é feita por meio de um link de integração e ...

© GuiaBolso Finanças Correspondente Bancário e Serviços LTDA 2020