Contas Bancárias

Abertura e gestão de contas bancárias digitais.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/accounts`	Criar conta bancária	`BAAS_ACCOUNTS_CREATE`
GET	`/baas/api/v1/accounts`	Listar contas	`BAAS_ACCOUNTS_READ`
GET	`/baas/api/v1/accounts/:id`	Obter conta por ID	`BAAS_ACCOUNTS_READ`
PATCH	`/baas/api/v1/accounts/:id`	Atualizar conta	`BAAS_ACCOUNTS_UPDATE`
POST	`/baas/api/v1/accounts/:id/close`	Encerrar conta	`BAAS_ACCOUNTS_CLOSE`
POST	`/baas/api/v1/accounts/:id/kyc`	Enviar documentos KYC	`BAAS_ACCOUNTS_KYC`
GET	`/baas/api/v1/accounts/:id/kyc`	Consultar status KYC	`BAAS_ACCOUNTS_KYC_READ`

Atributos

Campo	Tipo	Descrição
`providerId`	string (UUID)	ID do provedor bancário
`holderName`	string	Nome do titular
`holderDocument`	string	CPF/CNPJ do titular
`holderDocumentType`	enum	Tipo: `CPF`, `CNPJ`
`type`	enum	Tipo: `CHECKING`, `SAVINGS`, `PAYMENT`
`status`	enum	Status: `PENDING`, `ACTIVE`, `BLOCKED`, `CLOSED`
`branch`	string	Agência (atribuída pelo provedor)
`accountNumber`	string	Número da conta (atribuído pelo provedor)
`balance`	number	Saldo atual
`currency`	string	Moeda (ex: `BRL`)
`metadata`	object	Dados adicionais
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Criar Conta Bancária

POST /baas/api/v1/accounts

Abre uma nova conta bancária digital no provedor configurado.

Atributos

Campo	Tipo	Obrigatório	Descrição
`providerId`	string	Sim	ID do provedor bancário
`holderName`	string	Sim	Nome do titular
`holderDocument`	string	Sim	CPF/CNPJ do titular
`holderDocumentType`	enum	Sim	Tipo: `CPF` ou `CNPJ`
`type`	enum	Não	Tipo da conta (padrão: `CHECKING`)
`metadata`	object	Não	Dados adicionais

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/accounts' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "accounts",
      "attributes": {
        "providerId": "550e8400-e29b-41d4-a716-446655440001",
        "holderName": "Empresa ABC Ltda",
        "holderDocument": "12.345.678/0001-90",
        "holderDocumentType": "CNPJ",
        "type": "CHECKING"
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'accounts',
      attributes: {
        providerId: '550e8400-e29b-41d4-a716-446655440001',
        holderName: 'Empresa ABC Ltda',
        holderDocument: '12.345.678/0001-90',
        holderDocumentType: 'CNPJ',
        type: 'CHECKING',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Conta criada: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "accounts",
    "id": "550e8400-e29b-41d4-a716-446655440100",
    "links": {
      "self": "/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100"
    },
    "attributes": {
      "providerId": "550e8400-e29b-41d4-a716-446655440001",
      "holderName": "Empresa ABC Ltda",
      "holderDocument": "12.345.678/0001-90",
      "holderDocumentType": "CNPJ",
      "type": "CHECKING",
      "status": "PENDING",
      "branch": null,
      "accountNumber": null,
      "balance": 0,
      "currency": "BRL",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100"
  }
}

Listar Contas

GET /baas/api/v1/accounts

Lista todas as contas bancárias com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[status]`	enum	Filtrar por status
`filter[type]`	enum	Filtrar por tipo de conta
`filter[providerId]`	UUID	Filtrar por provedor

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/accounts?filter[status]=ACTIVE&page[size]=10' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[status]': 'ACTIVE',
  'page[size]': '10',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta, links } = await response.json();
console.log(`Total de contas: ${meta.totalItems}`);

Response (200 OK)

{
  "data": [
    {
      "type": "accounts",
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "links": {
        "self": "/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100"
      },
      "attributes": {
        "providerId": "550e8400-e29b-41d4-a716-446655440001",
        "holderName": "Empresa ABC Ltda",
        "holderDocument": "12.345.678/0001-90",
        "holderDocumentType": "CNPJ",
        "type": "CHECKING",
        "status": "ACTIVE",
        "branch": "0001",
        "accountNumber": "12345-6",
        "balance": 50000.00,
        "currency": "BRL",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-16T08:00:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 10
  },
  "links": {
    "self": "/baas/api/v1/accounts?page[number]=1&page[size]=10"
  }
}

Obter Conta por ID

GET /baas/api/v1/accounts/:id

Obtém os detalhes de uma conta bancária específica.

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100' \
  -H 'Authorization: Bearer SEU_TOKEN'

const accountId = '550e8400-e29b-41d4-a716-446655440100';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts/${accountId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Saldo: R$ ${data.attributes.balance.toFixed(2)}`);
console.log(`Agência: ${data.attributes.branch}`);
console.log(`Conta: ${data.attributes.accountNumber}`);

Atualizar Conta

PATCH /baas/api/v1/accounts/:id

Atualiza os dados de uma conta bancária.

Atributos Atualizáveis

Campo	Tipo	Descrição
`holderName`	string	Nome do titular
`metadata`	object	Dados adicionais

cURL
JavaScript

curl -X PATCH 'https://baas.stg.catalisa.app/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "accounts",
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "attributes": {
        "metadata": {
          "costCenter": "CC-001"
        }
      }
    }
  }'

const accountId = '550e8400-e29b-41d4-a716-446655440100';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts/${accountId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'accounts',
      id: accountId,
      attributes: {
        metadata: {
          costCenter: 'CC-001',
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Conta atualizada: ${data.id}`);

Encerrar Conta

POST /baas/api/v1/accounts/:id/close

Encerra uma conta bancária. A conta deve ter saldo zero e nenhuma operação pendente.

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100/close' \
  -H 'Authorization: Bearer SEU_TOKEN'

const accountId = '550e8400-e29b-41d4-a716-446655440100';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts/${accountId}/close`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // CLOSED

Response (200 OK)

{
  "data": {
    "type": "accounts",
    "id": "550e8400-e29b-41d4-a716-446655440100",
    "attributes": {
      "status": "CLOSED",
      "balance": 0,
      "updatedAt": "2024-01-20T15:00:00Z"
    }
  }
}

KYC (Know Your Customer)

Envio de documentos e consulta de status do processo de verificação de identidade (KYC) de uma conta bancária.

Status do KYC

Status	Descrição
`NOT_STARTED`	Nenhum documento enviado
`PENDING`	Documentos enviados, aguardando análise
`IN_PROGRESS`	Análise em andamento
`APPROVED`	Verificação aprovada
`REJECTED`	Verificação rejeitada
`REQUIRES_UPDATE`	Necessário atualizar/reenviar documentos

Tipos de Documento

Tipo	Descrição	Obrigatoriedade
`RG`	Registro Geral	Frente obrigatória, verso opcional
`CNH`	Carteira Nacional de Habilitação	Frente obrigatória, verso opcional
`PASSPORT`	Passaporte	Frente obrigatória, verso opcional
`RNE`	Registro Nacional de Estrangeiro	Frente obrigatória, verso opcional
`SELFIE`	Foto do titular (selfie)	Obrigatório
`PROOF_OF_ADDRESS`	Comprovante de endereço	Obrigatório
`PROOF_OF_INCOME`	Comprovante de renda	Opcional
`ARTICLES_OF_INCORPORATION`	Contrato social (para CNPJ)	Obrigatório para PJ

Enviar Documentos KYC

POST /baas/api/v1/accounts/:id/kyc

Envia documentos para o processo de verificação de identidade (KYC) de uma conta.

Atributos

Campo	Tipo	Obrigatório	Descrição
`documents`	array	Sim	Lista de documentos a enviar

Atributos de cada Documento

Campo	Tipo	Obrigatório	Descrição
`type`	enum	Sim	Tipo do documento (ver tabela acima)
`front`	string (base64)	Sim	Imagem frontal do documento
`back`	string (base64)	Não	Imagem do verso do documento

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100/kyc' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "kyc",
      "attributes": {
        "documents": [
          {
            "type": "RG",
            "front": "data:image/png;base64,iVBORw0KGgo...",
            "back": "data:image/png;base64,iVBORw0KGgo..."
          },
          {
            "type": "SELFIE",
            "front": "data:image/png;base64,iVBORw0KGgo..."
          },
          {
            "type": "PROOF_OF_ADDRESS",
            "front": "data:image/png;base64,iVBORw0KGgo..."
          }
        ]
      }
    }
  }'

const accountId = '550e8400-e29b-41d4-a716-446655440100';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts/${accountId}/kyc`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'kyc',
      attributes: {
        documents: [
          {
            type: 'RG',
            front: 'data:image/png;base64,iVBORw0KGgo...',
            back: 'data:image/png;base64,iVBORw0KGgo...',
          },
          {
            type: 'SELFIE',
            front: 'data:image/png;base64,iVBORw0KGgo...',
          },
          {
            type: 'PROOF_OF_ADDRESS',
            front: 'data:image/png;base64,iVBORw0KGgo...',
          },
        ],
      },
    },
  }),
});

const { data } = await response.json();
console.log(`KYC enviado: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (200 OK)

{
  "data": {
    "type": "kyc",
    "id": "550e8400-e29b-41d4-a716-446655440150",
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "status": "PENDING",
      "documents": [
        {
          "type": "RG",
          "status": "PENDING",
          "uploadedAt": "2024-01-15T10:30:00Z"
        },
        {
          "type": "SELFIE",
          "status": "PENDING",
          "uploadedAt": "2024-01-15T10:30:00Z"
        },
        {
          "type": "PROOF_OF_ADDRESS",
          "status": "PENDING",
          "uploadedAt": "2024-01-15T10:30:00Z"
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Consultar Status KYC

GET /baas/api/v1/accounts/:id/kyc

Consulta o status atual do processo de KYC de uma conta.

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/accounts/550e8400-e29b-41d4-a716-446655440100/kyc' \
  -H 'Authorization: Bearer SEU_TOKEN'

const accountId = '550e8400-e29b-41d4-a716-446655440100';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/accounts/${accountId}/kyc`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status KYC: ${data.attributes.status}`);
data.attributes.documents.forEach((doc) => {
  console.log(`${doc.type}: ${doc.status}`);
});

Response (200 OK)

{
  "data": {
    "type": "kyc",
    "id": "550e8400-e29b-41d4-a716-446655440150",
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "status": "APPROVED",
      "documents": [
        {
          "type": "RG",
          "status": "APPROVED",
          "uploadedAt": "2024-01-15T10:30:00Z",
          "reviewedAt": "2024-01-15T14:00:00Z"
        },
        {
          "type": "SELFIE",
          "status": "APPROVED",
          "uploadedAt": "2024-01-15T10:30:00Z",
          "reviewedAt": "2024-01-15T14:00:00Z"
        },
        {
          "type": "PROOF_OF_ADDRESS",
          "status": "APPROVED",
          "uploadedAt": "2024-01-15T10:30:00Z",
          "reviewedAt": "2024-01-15T14:00:00Z"
        }
      ],
      "reviewNote": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:00:00Z"
    }
  }
}

Dica

Quando o status é REQUIRES_UPDATE, o campo reviewNote conterá informações sobre quais documentos precisam ser reenviados e o motivo.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (documento, tipo, etc.)
404	`NOT_FOUND`	Conta ou provedor não encontrado
409	`CONFLICT`	Conta já existe para este documento no provedor
409	`CONFLICT`	Conta possui saldo ou operações pendentes (encerramento)
409	`CONFLICT`	KYC já aprovado (reenvio desnecessário)
422	`UNPROCESSABLE`	Provedor não suporta o tipo de conta solicitado
422	`UNPROCESSABLE`	Formato de imagem inválido ou tamanho excedido

Endpoints​

Atributos​

Criar Conta Bancária​

Atributos​

Response (201 Created)​

Listar Contas​

Query Parameters​

Response (200 OK)​

Obter Conta por ID​

Atualizar Conta​

Atributos Atualizáveis​

Encerrar Conta​

Response (200 OK)​

KYC (Know Your Customer)​

Status do KYC​

Tipos de Documento​

Enviar Documentos KYC​

Atributos​

Atributos de cada Documento​

Response (200 OK)​

Consultar Status KYC​

Response (200 OK)​

Erros Comuns​

Endpoints

Atributos

Criar Conta Bancária

Atributos

Response (201 Created)

Listar Contas

Query Parameters

Response (200 OK)

Obter Conta por ID

Atualizar Conta

Atributos Atualizáveis

Encerrar Conta

Response (200 OK)

KYC (Know Your Customer)

Status do KYC

Tipos de Documento

Enviar Documentos KYC

Atributos

Atributos de cada Documento

Response (200 OK)

Consultar Status KYC

Response (200 OK)

Erros Comuns