Skip to content

Documentação da API: Chaves Pix ​

Gestão das chaves Pix da própria conta (para recebimento) sobre o DICT (Diretório de Identificadores de Contas Transacionais) através do banco da conta, pela Fidúcia (a única integração bancária). Para testar sem dinheiro real, use uma conta na homologação da Fidúcia (sandbox).

Autenticação na Fidúcia: estas rotas chamam a API de Contas com o login da própria conta (POST /login, com credentials.fiducia_password e, para PJ, fiducia_operator_code, guardados na tabela accounts). Sem esse login configurado, contas da Fidúcia recebem erro. Ver Fidúcia — autenticação por endpoint.

BancoSenha transacionalDe onde vem a chave
FidúciaObrigatória para incluir/excluirDICT real da Fidúcia
TesteNão exigidaDICT simulado: dados da própria conta

Estes endpoints exigem autenticação padrão da plataforma e conta ativa (Authorization: Bearer {token} + account: {account_id}).

Não há um "editar chave": o DICT só permite criar uma nova ou excluir a atual.

Regras do Banco Central (Regulamento Pix, Resolução BCB nº 1/2020), aplicadas antes de chamar o banco:

  • Limite por conta: até 5 chaves para pessoa física (CPF) e até 20 para pessoa jurídica (CNPJ). Na 6ª (ou 21ª) inclusão a API responde 422.
  • Posse de e-mail e celular: chaves dos tipos 2 (e-mail) e 3 (celular) só são incluídas com o código enviado a esse e-mail ou, por SMS, a esse celular (POST /banking/pix/keys/verification, abaixo).

Listar e consultar chave são locais (GET /banking/pix/keys, GET /banking/pix/keys/{chave}) — não batem na API da Fidúcia a cada chamada; leem de uma cópia mantida na nossa base, sincronizada quando uma chave é incluída ou removida por aqui. Uma chave registrada fora deste fluxo (direto no painel da Fidúcia, ou antes desta cópia local existir) não aparece em GET /banking/pix/keys até ser recriada por aqui. Incluir e remover chave (POST/DELETE) sempre chamam a Fidúcia de verdade — é lá que a chave é criada/removida; a cópia local só é atualizada depois, como consequência.


Senha transacional da Fidúcia ​

Incluir e excluir uma chave exigem a senha transacional da própria Fidúcia (diferente do PIN da conta na plataforma). Ela é configurada uma vez, de forma criptografada, e reaproveitada automaticamente nessas operações — nunca é enviada nos endpoints de chave Pix diretamente.

Configurar: PUT /access/account (autenticado com o PIN da conta, ver Gestão — Conta):

json
{
    "pin": "123456",
    "credentials": {
        "fiducia_transactional_password": "<senha transacional da Fidúcia>"
    }
}

O retorno de GET /access/account / PUT /access/account nunca inclui o valor da senha — só a flag has_fiducia_transactional_password (true/ false), informando se já foi configurada.


1. Listar Chaves Pix ​

Endpoint: GET /banking/pix/keys

Lista as chaves Pix já incluídas pela conta através desta API (cópia local — ver nota acima). O meta informa se o banco da conta exige a senha transacional e se ela já está configurada, e em account_values o valor que cada tipo de chave usaria (null = dado não cadastrado na conta).

Resposta de Sucesso (200 OK) ​

json
{
    "success": true,
    "message": "Chaves Pix listadas com sucesso.",
    "data": [
        { "id": 1, "key_type": 1, "key_value": "12345678000199", "created_at": "2026-09-30T12:00:00.000000Z" },
        { "id": 2, "key_type": 2, "key_value": "financeiro@empresa.com", "created_at": "2026-09-30T12:05:00.000000Z" }
    ],
    "meta": {
        "account_values": { "1": "12345678000199", "2": "financeiro@empresa.com", "3": null },
        "key_limit": 20,
        "keys_count": 2,
        "verified_types": [2, 3],
        "requires_transactional_password": true,
        "has_transactional_password": false
    }
}

2. Incluir Chave Pix ​

2.1. Código de posse (e-mail e celular) ​

Endpoint: POST /banking/pix/keys/verification · Limite: 5 por minuto

Envia um código de 6 dígitos ao e-mail (key_type: 2) ou, por SMS, ao celular (key_type: 3) cadastrado na conta — o valor que vai virar chave. O código vale 10 minutos; 5 tentativas erradas o invalidam. Também recusa (422) se a conta já estiver no limite de chaves ou se o dado não estiver cadastrado.

json
{ "key_type": 2 }

Resposta 201:

json
{
    "message": "Enviamos um código para o e-mail da conta.",
    "data": { "id": "9d41c3a0-…", "key_type": 2, "destination": "fi***@empresa.com", "expires_at": "2026-10-15T15:10:00-03:00" }
}

2.2. Incluir ​

Endpoint: POST /banking/pix/keys

Body ​

json
{
    "key_type": 2,
    "verification_id": "9d41c3a0-…",
    "code": "123456"
}
CampoTipoObrigatórioDescrição
key_typeinteiroSim1 CPF/CNPJ · 2 e-mail · 3 celular · 4 aleatória (EVP)
verification_idstringPara 2 e 3data.id de POST /banking/pix/keys/verification
codestringPara 2 e 3código recebido no e-mail ou celular

O código só é marcado como usado depois que o banco registra a chave (uma recusa do banco não o consome). Se o e-mail/celular da conta mudar depois do envio, o código deixa de valer.

Valor padrão de cada tipo: CPF/CNPJ, e-mail e celular são sempre os dados cadastrados na própria conta — não é possível informar um valor arbitrário:

key_typeValor da chaveCampo da conta
1CPF/CNPJ só com dígitosdocument
2e-mail em minúsculasemail
3celular +55DDDNÚMEROphone
4gerado pelo banco—

Para usar um desses dados como chave, ele precisa estar cadastrado na conta antes (PUT /access/account, ou Minha Conta no portal). Sem o dado, ou se ele já for uma chave da conta, a inclusão é recusada com 422 sem chamar o banco. Na Fidúcia, a chamada envia só o tipo_chave (o banco usa os dados que ele tem da conta); o valor gravado em key_value é o da resposta do banco ou, se ela não trouxer, o da conta.

Resposta de Sucesso (201 Created) ​

json
{
    "data": { "id": 3, "key_type": 4, "key_value": "3e5bd858-6df6-4012-947d-c3772117c74a", "created_at": "2026-09-30T12:10:00.000000Z" },
    "message": "Chave Pix incluída com sucesso."
}

key_value é extraído da resposta da Fidúcia — para CPF/CNPJ, e-mail e celular, sem o valor na resposta é usado o da conta; para a chave aleatória, ela ainda é salva localmente (com key_value nulo) em vez de falhar; a resposta bruta completa da Fidúcia fica guardada internamente para conferência manual.

Erros ​

  • 422 — limite de chaves da conta atingido (data.key_type: "Limite de 5 chaves Pix por conta de pessoa física atingido…"), código de posse ausente, inválido ou expirado (data.code), key_type inválido, senha transacional não configurada (Fidúcia), conta de um banco sem gestão de chaves, chave já registrada no DICT, dado já usado como chave da conta, ou conta sem o dado usado como chave (ex.: sem celular — data.key_type: "Cadastre o celular da conta antes de incluí-lo como chave Pix..."). Recusas do banco vêm em message.

3. Consultar Chave Pix ​

Endpoint: GET /banking/pix/keys/{chave}

Consulta uma chave da cópia local pelo valor exato — {chave} deve vir com URL-encode quando contiver caracteres especiais (ex.: e-mail).

GET /banking/pix/keys/financeiro%40empresa.com

Resposta de Sucesso (200 OK) ​

json
{
    "success": true,
    "message": "Chave Pix consultada com sucesso.",
    "data": { "id": 2, "key_type": 2, "key_value": "financeiro@empresa.com", "created_at": "2026-09-30T12:05:00.000000Z" }
}

Erros ​

  • 404 — nenhuma chave com esse valor na cópia local da conta (inclui chaves registradas fora deste fluxo — ver nota no topo da página).

4. Remover Chave Pix ​

Endpoint: DELETE /banking/pix/keys/{chave}

Remove uma chave Pix da conta. Não recebe corpo — a senha transacional é lida automaticamente de accounts.credentials (ver seção acima). Sempre chama a Fidúcia de verdade, mesmo que a chave não esteja na cópia local (ex.: registrada fora deste fluxo) — a cópia local só é limpa depois, como consequência.

Respostas ​

  • 200 — chave removida na Fidúcia (a cópia local é removida junto, quando existir).
  • 404 — chave não encontrada nesta conta.
  • 422 — senha transacional não configurada (Fidúcia), ou conta de um banco sem gestão de chaves.

5. Verificar Chave Pix ​

Endpoint: GET /banking/pix/keys/verify?key={chave}

Consulta no DICT do banco da conta a quem pertence uma chave Pix, própria ou de terceiro, sem movimentar dinheiro. Use antes de divulgar uma chave, ou para conferir uma chave recebida.

GET /banking/pix/keys/verify?key=financeiro%40empresa.com

Resposta de Sucesso (200 OK) ​

json
{
    "success": true,
    "message": "Chave Pix verificada com sucesso.",
    "data": {
        "key": "financeiro@empresa.com",
        "found": true,
        "owner": {
            "name": "EMPRESA LTDA",
            "document": "12345678000199",
            "bank_name": "FIDUCIA SCMEPP LTDA",
            "agency": "0001",
            "account": "100001"
        },
        "raw": { "...": "resposta completa do banco" }
    }
}

O mapeamento de owner para a Fidúcia é best-effort: a coleção da Fidúcia não tem exemplo salvo dessa resposta. Os campos que não baterem vêm null, e a resposta completa sempre vem em raw.

Erros ​

  • 404 — chave não encontrada no DICT.
  • 422 — key ausente, ou conta de um banco sem gestão de chaves.

Erros comuns ​

SituaçãoStatus
Conta de banco sem gestão de chaves (nem Fidúcia nem Teste)422
key_type fora de 1–4 (incluir)422
CPF/CNPJ, e-mail ou celular não cadastrado na conta, ou já usado como chave (incluir)422
Senha transacional não configurada (incluir/excluir)422
Chave não encontrada na cópia local (consultar)404
Recusa do banco com status 4xx (ex.: chave já existe)o mesmo status do banco, com a mensagem em message
Chave não encontrada no DICT (verificar)404