Conceitos Fundamentais
Para utilizar a API de Validação de Contas Bancárias, é importante entender alguns conceitos-chave:
Workspace
O workspace é o identificador único da sua aplicação dentro do sistema. Todas as requisições devem incluir o workspace_id no header para:
- Identificar o cliente
- Aplicar limites de uso
- Rastrear o consumo
- Garantir isolamento de dados
Formatos aceitos
- UUID:
550e8400-e29b-41d4-a716-446655440000 - Short ID:
AbC123(será convertido automaticamente para UUID)
ISPB
O ISPB (Identificador do Sistema de Pagamentos Brasileiro) é o código único de 8 dígitos que identifica cada instituição financeira no Brasil.
Exemplo
00000000 - Banco do Brasil
00360305 - Caixa Econômica Federal
60701190 - Itaú
Tipos de Conta
A API utiliza códigos numéricos para os tipos de conta, seguindo o padrão PIX:
Códigos Aceitos
| Código | Tipo PIX | Descrição |
|---|---|---|
0 |
CACC | Conta Corrente (Current Account) - Conta Depósito à Vista |
1 |
SLRY | Conta Salário (Salary Account) - Conta destinada ao recebimento de salários |
2 |
SVGS | Conta Poupança (Savings Account) - Conta de Poupança |
3 |
TRAN | Conta de Pagamento (Transaction Account) - Conta de Pagamento pré-paga |
Importante
- O campo
account_typeaceita valores string (“0”, “1”, “2”, “3”) - Contas do tipo salário (1) podem ter restrições para receber transferências
- Nem todos os bancos suportam todos os tipos de conta
Código Fiscal
O código fiscal refere-se ao documento de identificação do titular da conta:
CPF (Pessoa Física)
- 11 dígitos
- Formato:
123.456.789-00ou12345678900
CNPJ (Pessoa Jurídica)
- 14 dígitos
- Formato:
12.345.678/0001-90ou12345678000190
Nota: A API aceita os documentos com ou sem formatação. Pontos, traços e barras são removidos automaticamente.
Status de Validação
Cada validação passa por diferentes estados:
validating (Em validação)
Estado inicial quando a validação é criada e está sendo processada.
validated (Validada)
A conta foi validada com sucesso e o código de confirmação foi gerado.
invalidated (Invalidada)
A validação falhou devido a dados incorretos ou problemas na verificação.
Código de Confirmação
É um código alfanumérico de 6 caracteres gerado aleatoriamente quando a validação é bem-sucedida.
Características:
- Apenas letras maiúsculas (A-Z)
- Enviado ao titular via PIX
- Único por validação
- Sensível a maiúsculas/minúsculas
Exemplo: ABCDEF
Próximos passos
Agora que você conhece os conceitos, veja como implementar:
- Guia do Usuário - Integração passo a passo
- Referência de Erros - Lista completa de erros