Códigos de Retorno da API

Formato das Requisições

Toda a comunicação com a nossa API é feita via HTTPS através de requisições POST. Nós não usamos o padrão REST, ao invés disso, nossa API é baseada em um conceito interno de eventos que nada mais são que objetos JSON trafegados no body das requisições.

A seguir um exemplo deste tipo de evento sendo enviado para nossa API.

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": "CLIENT_ID"
},
"auth": {
"clientSecret": "CLIENT_SECRET"
},
"metadata": {}
}

Glossário de Campos


TermoDescrição
flowIdÉ um identificador único, pode ser um UUID gerado de forma aleatória. Diz respeito a como o Guiabolso rastreia as requisições dentro da sua plataforma, você pode passar qualquer identificador aqui contanto que ele seja único e não seja sensível.
idÉ um identificador único, pode ser um UUID gerado de forma aleatória, que identifica esse evento específico. Você pode passar qualquer identificador aqui contanto que ele seja único e não seja sensível.
nameÉ o nome do evento exposto pela nossa API, note que o mesmo evento pode ter uma versão diferente na nossa API.
versionÉ a versão exposta para um determinado evento da nossa API, valor numérico maior que zero.
payloadO 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"
identityO campo identity define o CLIENT_ID do seu acesso.
authO campo auth diz respeito ao seu CLIENT_SECRET

Formato das Respostas

As repostas da API quer sejam bem sucedidas ou não também estarão dentro do padrão de eventos, isso quer dizer que dentro da resposta HTTP haverá um body com um evento dentro. Note que os valores de flowId e id são os mesmos passados na requisição anteriormente.

A API por definição retornará sempre um HTTP status code de 200, você saberá se ocorreu um erro apenas dentro da resposta. Se a resposta for bem sucedida, o nome do evento terá a palavra response atrelada a ele, como no exemplo abaixo.

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

Se a resposta estiver com erro, o código do erro estará dentro do campo "payload" como mostra o exemplo abaixo, a requisição obteve um erro de PARTNER_NOT_FOUND.

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

Glossário de Códigos de Erros


Nome do erroDescrição
errorErro genérico referente a um status code 500.
notFoundNome do evento ou parâmetro não encontrado na plataforma.
badRequestErro na requisição (parâmetro faltante, etc.)
unauthorizedAcesso não concedido
forbiddenRequisitante não possui acesso aos recursos requisitados
userDeniedUsuário negou acesso do cliente OAuth em seu nome
resourceDeniedUsuário negou acesso a um recurso requisitado por cliente
expiredToken de acesso em nome de usuário via OAuth expirado
redirectDeve ser feito um redirecionamento para a URL contida na resposta

Próximos passos

connector

O que é o Connector

Uma aplicação kotlin criada pelo Guiabolso e distribuída sob a licença Apache 2.0 que provê uma ...

connector

Pré-requisitos

Para instalar o nosso Middleware na sua infraestrutura Cloud (AWS ou GCP) você vai...

connector

Como rodar local?

Descompacte o arquivo .zip em uma pasta de sua preferência e execute o seguinte comando....

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

O Guiabolso Connect utiliza cookies e tecnologias similares, como pixels e tags, para oferecer a melhor experiência para o usuário. Ao utilizar nossos serviços, você concorda com essa utilização. Mais detalhes no item 5 da nossa Política de Privacidade