Fluxo básico de Baas

Este documento irá ajuda-lo a entender o fluxo básico de baas

pré requisitos

antes de começar a utilisar a api baas é nescessrio duas coisas:

• solicitar ativação das features: Bass e Criação de conta
• gerar uma chave de api master

A API precisa ser do tipo MASTER porquê ela precisa ser capaz de criar novas integrações. A conta bancária relacionada a essa API será utilizada no processo de criação das novas contas bancárias, elas usarão os dados desta para serem criadas.

Assim estamos prontos para iniciar a sequencia de integração

Sequência da integração

1. Registrando uma conta

• Utilise o endpoint de registro de conta para registrar uma nova conta
• Utilise a chave de api master para autenticar a requisição
• Faça a requisição

   curl -X POST "https://api.woovi.com/api/v1/account-register" \
     -H "Authorization: <apiMasterKey>" \
     -H "Content-Type: application/json" 
       --data-raw '
{
 "officialName": "<razão social>",
 "tradeName": "<nome fantasia>",
 "taxID": "<cnpj>",
 "billingAddress": {
   "zipcode": "<cpf>",
   "street": "<rua>",
   "number": "<numero>",
   "neighborhood": "<bairro>",
   "city": "<cidade>",
   "state": "<sigla estado>"
 },
 "documents": [
   {
     "url": "<url documento contrato social>",
     "type": "SOCIAL_CONTRACT"
   },
   {
     "url": "<url estatuto social>",
     "type": "BYLAWS"
   }
 ],
 "representatives": [
   {
     "name": "<nome socio 1>",
     "birthDate": "<nacimento>",
     "email": "<email>",
     "taxID": "<cnpj>",
     "phone": "<phone>",
     "address": {
       "zipcode": "<cep>",
       "street": "<rua>",
       "number": "<numero>",
       "neighborhood": "<bairro>",
       "city": "<cidade>",
       "state": "<sigla estado>",
       "taxID": "<cnpj>",
       "complement": "<complemento'>"
     },
     "documents": [
       {
         "url": "<url cnh>",
         "type": "CNH"
       },
       {
         "url": "<url foto de perfil>",
         "type": "PICTURE"
       }
     ],
     "type": "ADMIN"
   }
 ]
}'

• Caso tudo ocorra corretamente, um código 201 será retornado.
• No corpo da resposta terá:

  {
    "officialName": "minha compania LTDA",
    "tradeName": "nome fantasia da minha compania",
    "status": "IN_REVIEW",
    "taxID": {
        "taxID": "<cnpj>",
        "type": "BR:CNPJ"
    }
  }

2. Aguarde a aprovação da conta

• Cadastre um webhook ouvindo o seguinte evento: "ACCOUNT_REGISTER_APPROVED"
• Para cadastrar um webhook faça a seguinte request:

    curl --location --request POST 'https://api.woovi.com/api/openpix/v1/webhook' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: <apiMasterKey>' \
      --data-raw '{
        "webhook": {
        "name": "webhook via api",
        "event": "ACCOUNT_REGISTER_APPROVED",
        "url": "https://minhaurl.test/webhook",
        "authorization": "auth_key",
        "isActive": true
      }
    }'

• No corpo da resposta terá:

  {
    "webhook": {
      "id": "<idWebhook>",
      "name": "webhook via api",
      "event": "ACCOUNT_REGISTER_APPROVED",
      "url": "https://minhaurl.test/webhook",
      "authorization": "auth_key",
      "isActive": true,
      "hmacSecretKey": "<hmacSecretKey>",
      "createdAt": "2025-07-01T00:25:36.789Z",
      "updatedAt": "2025-07-01T00:25:36.789Z"
    }
  }

• quando a conta for aprova o webhook receberar os seguintes dados:

 {
   "event": "ACCOUNT_REGISTER_APPROVED",
   "accountRegister": {
     "officialName": "minha compania LTDA",
     "taxID": {
       "taxID": "<cnpj>",
       "type": "BR:CNPJ"
     },
     "status": "APPROVED"
   },
   "account": {
     "status": "OPEN",
     "accountId": "<accountId>",
     "account": "<accountNumber>",
     "branch": "<branch>"
   }
 }

3. Gere uma chave de api padrão

• Utilise o endpoint de application para gerar uma chave de api para a conta recen criada
• Utilise a chave de api master para autenticar a requisição
• Faça a requisição

   curl -X POST "https://api.woovi.com/api/v1/application" \
     -H "Authorization: <apiMasterKey>" \
     -H "Content-Type: application/json" 
     --data-raw '{
       "accountId": "<accountId>",
       "application": {
         "name": "Api account register",
         "type": "API"
       }
     }'

• Caso tudo ocorra corretamente, um código 201 será retornado.
• No corpo da resposta terá:

   {
     "application": {
         "name": "Api account register",
         "isActive": true,
         "type": "API",
         "clientId": "<clientId>",
         "clientSecret": "<clientSecret>",
         "appID": "<appID>"
     }
   }

4. Gere uma chave pix aleatoria

• Utilise o endpoint pix-keys para gerar uma chave para a conta
• Utilise o appId gerado no passo anterior para autenticar a requisição
• Faça a requisição:

   curl -X POST "https://api.woovi.com/api/v1/pix-keys" \
    -H "Authorization: <appId>" \
    -H "Content-Type: application/json" 
    --data-raw '{
      "key": "k1",
      "type": "EVP"
    }'

• Caso tudo ocorra corretamente, um código 200 será retornado.
• No corpo da resposta terá:

 {
   "pixKey": {
       "pixKey": "",
       "type": "EVP",
       "isDefault": false
   }
 }