Aparência
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, comcredentials.fiducia_passworde, para PJ,fiducia_operator_code, guardados na tabelaaccounts). Sem esse login configurado, contas da Fidúcia recebem erro. Ver Fidúcia — autenticação por endpoint.
| Banco | Senha transacional | De onde vem a chave |
|---|---|---|
| Fidúcia | Obrigatória para incluir/excluir | DICT real da Fidúcia |
| Teste | Não exigida | DICT 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) e3(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"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
key_type | inteiro | Sim | 1 CPF/CNPJ · 2 e-mail · 3 celular · 4 aleatória (EVP) |
verification_id | string | Para 2 e 3 | data.id de POST /banking/pix/keys/verification |
code | string | Para 2 e 3 | có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_type | Valor da chave | Campo da conta |
|---|---|---|
1 | CPF/CNPJ só com dígitos | document |
2 | e-mail em minúsculas | email |
3 | celular +55DDDNÚMERO | phone |
4 | gerado 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_typeinvá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 emmessage.
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.comResposta 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.comResposta 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 —
keyausente, ou conta de um banco sem gestão de chaves.
Erros comuns
| Situação | Status |
|---|---|
| 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 |