Introdução

Nesta seção será explicado como fazer integração com o produto Monitoramento de Carteira. A aplicação utiliza um modelo de webhook para realizar as notificações sobre o status de sincronização, sucessos e falhas.


Pré requisitos

Para utilizar o monitoramento de carteiras, você precisar ter:


1. Chaves da API OBRIGATÓRIO

Possuir ativo ao seu clientId o produto monitoramento de carteira, com as URLs de sua preferência devidamente configuradas para o recebimento de eventos da sincronização de conta.

2. Integração com Guiabolso Connect OBRIGATÓRIO

Já tenha efetuado o passo anterior que explora o tópico como fazer integração com o Guiabolso Connect.


Solicitando sincronização


Para solicitar sincronização de contas, realize uma requisição HTTP POST no endereço https://kasbah.guiabolso.com.br/partner/events/ com os userTrackingIds que terão as contas sincronizadas. Veja um exemplo abaixo:

COPIAR
{
"name": "gbconnect:sync:accounts",
"version": 1,
"id": UUID,
"flowId": UUID,
"payload": {
"userTrackingIds": [
"6cdb191d-d821-42cc-9aef-6050352c96d4",
"ac315055-9e5c-4336-ba80-b2850f56108b",
"b8b9e3bf-860f-4c20-9ac0-04052138c5c8",
...
],
"producerTag": "DEFAULT"
},
"identity": {
"clientId": CLIENT_ID
},
"metadata": {},
"auth": {
"clientSecret": CLIENT_SECRET
}
}
avisoCada requisição possui limite de 5.000 `userTrackingIds`. Caso seja necessário sincronizar mais usuários que exceda esse limite, novas requisições devem ser realizadas.
CampoDescrição
userTrackingIdsLista de ID’s dos usuários que terão as contas sincronizadas.
producerTagPropriedade opcional, com valor padrão sendo DEFAULT, identifica um subgrupo que está atrelado ao clientId.
clientIdID da sua chave de API que fornecemos pra você.
clientSecretSecret da sua chave de API que fornecemos pra você.

Será retornada uma resposta contendo a propriedade synchronizationId, que poderá ser usada como referência ao pedido de sincronização de contas efetuado. Para manter o rastreio da sincronização de contas de cada usuário, poderá ser usada a combinação de chaves synchronizationId + userTrackingId para identificar seu usuário nos retornos enviados após a sincronização de conta na plataforma do Guiabolso. A chamada efetuada acima produzirá uma resposta como a exibida abaixo:

COPIAR
{
"name": "gbconnect:sync:accounts:response",
"version": 1,
"id": UUID,
"flowId": UUID,
"payload": {
"synchronizationId": "56223f5e-6196-4db8-a5f4-ff5317d39fdd"
},
"identity": {},
"auth": {},
"metadata": {}
}
CampoDescrição
synchronizationIdIdentificador único que representa o pedido de sincronização de contas.

Eventos gerados

Para cada userTrackingId passado na lista, enviaremos pelo menos uma requisição notificando sobre a sincronização de conta. Alguns dos eventos são opcionais enquanto outros são obrigatorios para o funcionamento. Os eventos disponíveis são:


gbconnect:user:sync:accounts:finished OBRIGATÓRIO

Este evento será enviado quando a sincronização de contas de um usuário for finalizada.

COPIAR
{
"name": "gbconnect:user:sync:accounts:finished",
"version": 1,
"id": UUID,
"flowId": UUID,
"payload": {
"synchronizationId": "56223f5e-6196-4db8-a5f4-ff5317d39fdd",
"producerTag": "DEFAULT",
"userTrackingId": "6cdb191d-d821-42cc-9aef-6050352c96d4",
"accounts": [
{
"accountId": 6460172,
"bacenCode": "001",
"result": {
"status": "SUCCESS"
}
},
...
]
},
"identity": {},
"auth": {},
"metadata": {}
}
CampoDescrição
synchronizationIdÉ um identificador único que representa o pedido de sincronização de conta à qual essa notificação foi originada.
producerTagIdentifica um subgrupo atrelado ao clientId, valor padrão DEFAULT.
userTrackingIdIdentificador do usuário.
accountsLista de contas que foram sincronizadas.
accountIdId da conta sincronizada.
bacenCodeO código de compensação fornecido pelo BACEN a instituição financeira.
statusResultado da sincronização de conta, SUCCESS ou ERROR.

Para cada userTrackingId, após todas as contas serem sincronizadas, será enviado uma requisição POST para a URL cadastrada. Para cada userTrackingId podem existir diversas contas cadastradas e todas serão sincronizadas, tendo o campo status para saber se a ação teve êxito ou não.


gbconnect:user:notFound OBRIGATÓRIO

Este evento será enviado quando o userTrackingId solicitado na importação de conta não foi encontrado. Esse evento é obrigatorio.

COPIAR
{
"name": "gbconnect:user:notFound",
"version": 1,
"id": UUID,
"flowId": UUID,
"payload": {
"userTrackingId": "ac315055-9e5c-4336-ba80-b2850f56108b",
"synchronizationId": "56223f5e-6196-4db8-a5f4-ff5317d39fdd",
"producerTag": "DEFAULT"
},
"identity": {},
"auth": {},
"metadata": {}
}
CampoDescrição
synchronizationIdÉ um identificador único que representa o pedido de sincronização de conta à qual essa notificação foi originada.
producerTagIdentifica um subgrupo atrelado ao clientId, valor padrão DEFAULT.
userTrackingIdIdentificador do usuário.
avisoLembrando que todas as requisições do eventos são do tipo `POST`, logo o endereço cadastrado deve suportar requisições desse tipo.

Validando assinatura da requisição

Como medida de segurança, é encorajado que seja feita a validação da assinatura da requisição recebida, para garantir que de fato é o Guiabolso que está enviando essa mensagem para sua infraestrutura. Em todas as mensagens que enviaremos, será usado o token atrelado ao webhook de callback previamente cadastrada, e será gerada uma assinatura do corpo da requisição. Se esse token ainda não foi cadastrado, sugerimos que entre em contato conosco e forneça um token de sua preferência.

Nos headers da requisição, enviaremos um header chamado HTTP_X_GBC_SIGNATURE_256, esse header conterá uma string com o formato t=timestamp,v1=signature, onde:

  • t é o timestamp de quando foi gerado a assinatura; ele é importante para se proteger contra replay attack.
  • v1 é a versão da assinatura; note que futuramente podermos ter múltiplas versões.

Como fazer a validação da assinatura?

Veremos a seguir um exemplo de como fazer essa validação usando Kotlin. Usamos o algoritmo HmacSHA256 para gerar o hash do timestamp.body da requisição recebida, por exemplo, vamos utilizar o t recebido no header da requisição concatenado com . e body, em seguida gerar o hash resultante dessa concatenação, veja a implementação de exemplo abaixo:

COPIAR
fun checkSignature(header: String, body: String, secret: String) {
val (timestamp, signature) = parse(header)
validateTimestamp(timestamp = timestamp)
validateSignature(payload = "$timestamp.$body", signature = signature, secret = secret)
}
private fun parse(header: String): Pair<String, String> {
val (time, v1) = header.split(",")
val timestamp = time.substringAfter("t=")
val signature = v1.substringAfter("v1=")
return Pair(timestamp, signature)
}
private fun validateTimestamp(timestamp: String) {
val requestTime =
Instant
.ofEpochMilli(timestamp.toLong())
.plusSeconds(YOUR_TIME_WINDOW_IN_SECONDS) // Defina quanto tempo é aceitável de atraso em segundos entre a geração e entrega da mesnagem no seu backend
if (requestTime.isBefore(Instant.now())) throw UnauthorizedException()
}
private fun validateSignature(payload: String, signature: String, secret: String) {
val keySpec = SecretKeySpec(secret.toByteArray(), "HmacSHA256")
val mac = Mac.getInstance("HmacSHA256").apply { init(keySpec) }
val generatedSignature = mac.doFinal(payload.toByteArray()).run {
BigInteger(this).toString(16)
}
if (!MessageDigest.isEqual(generatedSignature.toByteArray(), signature.toByteArray())) throw UnauthorizedException()
}

Buscando dados atualizados do seu usuário

Para buscar dados atualizados, basta seguir o passo-a-passo do fluxo normal do Guiabolso Connect, descrito aqui.

Próximos passos

overview

Nível de Segurança

O Guiabolso é uma empresa que utiliza protocolos de segurança de nível bancário

overview

Credenciais

As chaves de acesso para nossa API são definidas por dois identificadores únicos, um clientID e um clientSecret...

overview

Fluxo de Integração

A integração com o Guiabolso Connect se dá basicamente em 3 passos bem práticos. O primeiro deles...

© 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