Provedores Bancários

Configuração e gestão de provedores bancários integrados à plataforma.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/providers`	Criar provedor	`BAAS_PROVIDERS_CREATE`
GET	`/baas/api/v1/providers`	Listar provedores	`BAAS_PROVIDERS_READ`
GET	`/baas/api/v1/providers/:id`	Obter provedor por ID	`BAAS_PROVIDERS_READ`
PATCH	`/baas/api/v1/providers/:id`	Atualizar provedor	`BAAS_PROVIDERS_UPDATE`
DELETE	`/baas/api/v1/providers/:id`	Excluir provedor	`BAAS_PROVIDERS_DELETE`
POST	`/baas/api/v1/provider-configs/:id/test`	Testar conexão com provedor	`BAAS_PROVIDERS_UPDATE`
POST	`/baas/api/v1/provider-configs/:id/set-default`	Definir provedor padrão	`BAAS_PROVIDERS_UPDATE`

Atributos

Campo	Tipo	Descrição
`name`	string	Nome do provedor
`code`	string	Código identificador único
`type`	enum	Tipo: `BANKING`, `PIX`, `BOLETO`, `FULL`
`status`	enum	Status: `ACTIVE`, `INACTIVE`, `SUSPENDED`
`credentials`	object	Credenciais de acesso ao provedor
`settings`	object	Configurações específicas do provedor
`supportedFeatures`	array	Funcionalidades suportadas
`metadata`	object	Dados adicionais
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Estrutura de Credenciais (credentials)

Campo	Tipo	Descrição
`clientId`	string	ID do cliente no provedor
`clientSecret`	string	Secret do cliente (write-only)
`apiKey`	string	Chave de API (alternativa)
`certificate`	string	Certificado digital (base64)
`environment`	enum	`sandbox` ou `production`

Tipos de Provedor

Tipo	Descrição
`BANKING`	Contas e transferências
`PIX`	Apenas Pix
`BOLETO`	Apenas boletos
`FULL`	Todos os serviços

Criar Provedor

POST /baas/api/v1/providers

Configura um novo provedor bancário na organização.

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do provedor
`code`	string	Sim	Código identificador
`type`	enum	Sim	Tipo do provedor
`credentials`	object	Sim	Credenciais de acesso
`settings`	object	Não	Configurações adicionais
`metadata`	object	Não	Dados adicionais

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/providers' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "providers",
      "attributes": {
        "name": "Banco Principal",
        "code": "BANK_001",
        "type": "FULL",
        "credentials": {
          "clientId": "seu-client-id",
          "clientSecret": "seu-client-secret",
          "environment": "sandbox"
        },
        "settings": {
          "webhookUrl": "https://api.exemplo.com/webhooks/bank",
          "autoReconciliation": true,
          "defaultBranch": "0001"
        }
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/providers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'providers',
      attributes: {
        name: 'Banco Principal',
        code: 'BANK_001',
        type: 'FULL',
        credentials: {
          clientId: 'seu-client-id',
          clientSecret: 'seu-client-secret',
          environment: 'sandbox',
        },
        settings: {
          webhookUrl: 'https://api.exemplo.com/webhooks/bank',
          autoReconciliation: true,
          defaultBranch: '0001',
        },
      },
    },
  }),
});

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

Response (201 Created)

{
  "data": {
    "type": "providers",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "links": {
      "self": "/baas/api/v1/providers/550e8400-e29b-41d4-a716-446655440001"
    },
    "attributes": {
      "name": "Banco Principal",
      "code": "BANK_001",
      "type": "FULL",
      "status": "ACTIVE",
      "credentials": {
        "clientId": "seu-client-id",
        "clientSecret": "********",
        "environment": "sandbox"
      },
      "settings": {
        "webhookUrl": "https://api.exemplo.com/webhooks/bank",
        "autoReconciliation": true,
        "defaultBranch": "0001"
      },
      "supportedFeatures": [
        "ACCOUNTS",
        "TRANSFERS",
        "PIX",
        "BOLETO",
        "STATEMENTS",
        "RECONCILIATION"
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/providers/550e8400-e29b-41d4-a716-446655440001"
  }
}

Listar Provedores

GET /baas/api/v1/providers

Lista provedores bancários configurados na organização.

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

cURL
JavaScript

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

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

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

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

data.forEach((provider) => {
  console.log(`${provider.attributes.name} (${provider.attributes.type}) - ${provider.attributes.status}`);
});

Obter Provedor por ID

GET /baas/api/v1/providers/:id

Obtém os detalhes de um provedor específico.

cURL
JavaScript

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

const providerId = '550e8400-e29b-41d4-a716-446655440001';

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

const { data } = await response.json();
console.log(`Nome: ${data.attributes.name}`);
console.log(`Tipo: ${data.attributes.type}`);
console.log(`Features: ${data.attributes.supportedFeatures.join(', ')}`);

Atualizar Provedor

PATCH /baas/api/v1/providers/:id

Atualiza a configuração de um provedor bancário.

Atributos Atualizáveis

Campo	Tipo	Descrição
`name`	string	Nome do provedor
`status`	enum	Status do provedor
`credentials`	object	Credenciais (atualização parcial)
`settings`	object	Configurações
`metadata`	object	Dados adicionais

cURL
JavaScript

curl -X PATCH 'https://baas.stg.catalisa.app/baas/api/v1/providers/550e8400-e29b-41d4-a716-446655440001' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "providers",
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "attributes": {
        "credentials": {
          "environment": "production",
          "clientId": "prod-client-id",
          "clientSecret": "prod-client-secret"
        },
        "settings": {
          "webhookUrl": "https://api.exemplo.com/webhooks/bank-prod"
        }
      }
    }
  }'

const providerId = '550e8400-e29b-41d4-a716-446655440001';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/providers/${providerId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'providers',
      id: providerId,
      attributes: {
        credentials: {
          environment: 'production',
          clientId: 'prod-client-id',
          clientSecret: 'prod-client-secret',
        },
        settings: {
          webhookUrl: 'https://api.exemplo.com/webhooks/bank-prod',
        },
      },
    },
  }),
});

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

Excluir Provedor

DELETE /baas/api/v1/providers/:id

Remove um provedor bancário. O provedor não pode ter contas ativas vinculadas.

cURL
JavaScript

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

const providerId = '550e8400-e29b-41d4-a716-446655440001';

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

if (response.status === 204) {
  console.log('Provedor excluído com sucesso');
}

Response (204 No Content)

Sem corpo de resposta.

Testar Conexão com Provedor

POST /baas/api/v1/provider-configs/:id/test

Testa a conexão com o provedor bancário, validando se as credenciais configuradas estão corretas e se o provedor está acessível. Útil para verificar a configuração antes de ativá-la em produção.

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/provider-configs/550e8400-e29b-41d4-a716-446655440001/test' \
  -H 'Authorization: Bearer SEU_TOKEN'

const providerId = '550e8400-e29b-41d4-a716-446655440001';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/provider-configs/${providerId}/test`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Conexão: ${data.attributes.status}`);
console.log(`Latência: ${data.attributes.latencyMs}ms`);

if (data.attributes.status === 'FAILED') {
  console.error(`Erro: ${data.attributes.errorMessage}`);
}

Response (200 OK)

{
  "data": {
    "type": "provider-test",
    "attributes": {
      "providerId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "SUCCESS",
      "latencyMs": 245,
      "errorMessage": null,
      "testedAt": "2024-01-15T10:30:00Z",
      "features": {
        "accounts": true,
        "transfers": true,
        "pix": true,
        "boleto": true
      }
    }
  }
}

Dica

Execute este teste após configurar ou atualizar as credenciais do provedor para garantir que a integração está funcionando corretamente.

Definir Provedor Padrão

POST /baas/api/v1/provider-configs/:id/set-default

Define um provedor como padrão para a organização. O provedor padrão será utilizado automaticamente quando nenhum providerId específico for informado ao criar contas ou realizar operações.

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/provider-configs/550e8400-e29b-41d4-a716-446655440001/set-default' \
  -H 'Authorization: Bearer SEU_TOKEN'

const providerId = '550e8400-e29b-41d4-a716-446655440001';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/provider-configs/${providerId}/set-default`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Provedor padrão definido: ${data.attributes.name}`);
console.log(`Status: ${data.attributes.isDefault}`); // true

Response (200 OK)

{
  "data": {
    "type": "providers",
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "attributes": {
      "name": "Banco Principal",
      "code": "BANK_001",
      "type": "FULL",
      "status": "ACTIVE",
      "isDefault": true,
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Provedor padrão

Apenas um provedor pode ser definido como padrão por vez. Ao definir um novo provedor padrão, o anterior deixa de ser padrão automaticamente.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (credenciais, tipo, etc.)
404	`NOT_FOUND`	Provedor não encontrado
409	`CONFLICT`	Código já em uso por outro provedor
409	`CONFLICT`	Provedor possui contas ativas (exclusão)
422	`UNPROCESSABLE`	Credenciais inválidas ou provedor não acessível
422	`CONNECTION_FAILED`	Teste de conexão falhou (credenciais ou rede)

Endpoints​

Atributos​

Estrutura de Credenciais (credentials)​

Tipos de Provedor​

Criar Provedor​

Atributos​

Response (201 Created)​

Listar Provedores​

Query Parameters​

Obter Provedor por ID​

Atualizar Provedor​

Atributos Atualizáveis​

Excluir Provedor​

Response (204 No Content)​

Testar Conexão com Provedor​

Response (200 OK)​

Definir Provedor Padrão​

Response (200 OK)​

Erros Comuns​

Endpoints

Atributos

Estrutura de Credenciais (credentials)

Tipos de Provedor

Criar Provedor

Atributos

Response (201 Created)

Listar Provedores

Query Parameters

Obter Provedor por ID

Atualizar Provedor

Atributos Atualizáveis

Excluir Provedor

Response (204 No Content)

Testar Conexão com Provedor

Response (200 OK)

Definir Provedor Padrão

Response (200 OK)

Erros Comuns