Docs
  • Introdução
  • Conceitos
  • Guia do Usuário
  • Referência de Erros
  • Sumário de Implementação
    • API
    ...

    This page

    Endpoints da API

    Esta seção detalha todos os endpoints disponíveis na API de Validação de Contas Bancárias.

    Criar Validação

    Endpoint para criar uma nova validação de conta bancária.

    post https://bank-account-validator-br.iugu.com/api/v1/validate

    Criar validação de conta bancária

    Cria uma nova validação de conta bancária e envia o código de verificação via PIX

    Sem ações implementadas definidas

    Request

    Headers

    workspace_id

    Required

    Type: string

    Identificador único do workspace (UUID ou short ID)

    Ex: 550e8400-e29b-41d4-a716-446655440000

    Body Required

    Content Type: application/json
    bank

    Required

    String ^[0-9]{8}$

    ISPB do banco (8 dígitos)

    Ex: 00000000
    branch

    Required

    String

    Número da agência

    Ex: 0001
    account

    Required

    String

    Número da conta

    Ex: 123456
    account_digit
    String

    Dígito verificador da conta

    Ex: 7
    account_type

    Required

    String
    Enum: `0`, `1`, `2`, `3`

    Tipo da conta

    Ex: 0
    fiscal_code

    Required

    String

    CPF (11 dígitos) ou CNPJ (14 dígitos) do titular

    Ex: 12345678900
    Example 
    1
2
3
4
5
6
7
8

    {
  "bank": "00000000",
  "branch": "0001",
  "account": "123456",
  "account_digit": "7",
  "account_type": "0",
  "fiscal_code": "12345678900"
}

    Response

    201

    Validação criada com sucesso

    id
    Integer

    ID único da validação
    bank
    String

    ISPB do banco
    branch
    String

    Número da agência
    account
    String

    Número da conta
    account_digit
    String

    Dígito verificador da conta
    account_type
    String

    Tipo da conta (0=CACC, 1=SLRY, 2=SVGS, 3=TRAN)
    fiscal_code
    String

    CPF ou CNPJ do titular
    status
    String
    Enum: `validating`, `validated`, `invalidated`

    Status da validação
    error_code
    String

    Código do erro (vazio se não houver erro)
    error_message
    String

    Mensagem de erro (vazio se não houver erro)
    Example 
    1
2
3
4
5
6
7
8
9
10
11
12

    {
  "id": "<ID>",
  "bank": "<BANK>",
  "branch": "<BRANCH>",
  "account": "<ACCOUNT>",
  "account_digit": "<ACCOUNT_DIGIT>",
  "account_type": "<ACCOUNT_TYPE>",
  "fiscal_code": "<FISCAL_CODE>",
  "status": "<STATUS>",
  "error_code": "<ERROR_CODE>",
  "error_message": "<ERROR_MESSAGE>"
}

    400

    Requisição inválida

    error
    String

    Mensagem de erro
    Example 
    1
2
3

    {
  "error": "<ERROR>"
}

    422

    Entidade não processável

    error_code
    String

    Código do erro de validação
    error_message
    String

    Mensagem descritiva do erro
    Example 
    1
2
3
4

    {
  "error_code": "<ERROR_CODE>",
  "error_message": "<ERROR_MESSAGE>"
}

    Tipos de Conta Aceitos

    Código Tipo PIX Descrição
    0 CACC Conta Corrente
    1 SLRY Conta Salário
    2 SVGS Conta Poupança
    3 TRAN Conta de Pagamento

    Fluxo de Validação

    1. A API recebe os dados bancários
    2. Valida o ISPB do banco e o CPF/CNPJ
    3. Envia uma transação PIX de R$ 0,01 com o código de verificação
    4. O titular recebe o código de 6 letras
    5. Retorna o ID da validação para confirmação posterior

    Confirmar Código

    Endpoint para confirmar o código de validação recebido via PIX.

    post https://bank-account-validator-br.iugu.com/api/v1/match_code/{id}

    Confirmar código de validação

    Confirma o código de 6 caracteres recebido via PIX para completar a validação

    Sem ações implementadas definidas

    Request

    Path variables

    id

    Required

    Type: integer

    ID da validação a ser confirmada

    Ex: 123

    Headers

    workspace_id

    Required

    Type: string

    Identificador único do workspace (UUID ou short ID)

    Ex: 550e8400-e29b-41d4-a716-446655440000

    Body Required

    Content Type: application/json
    short_code

    Required

    String ^[A-Z]{6}$

    Código de 6 caracteres recebido via PIX

    Ex: ABCDEF
    Example 
    1
2
3

    {
  "short_code": "ABCDEF"
}

    Response

    200

    Resultado da confirmação

    match_result
    Boolean

    Indica se o código informado está correto
    Example 
    1
2
3

    {
  "match_result": "<MATCH_RESULT>"
}

    404

    Validação não encontrada

    error
    String

    Mensagem de erro
    Example 
    1
2
3

    {
  "error": "<ERROR>"
}

    Importante

    • O código é composto por 6 letras maiúsculas
    • É sensível a maiúsculas/minúsculas
    • Cada código é único por validação
    • O código é enviado na descrição da transação PIX

    Próximos passos