Cadastrando uma chave pix

Este endpoint permite criar uma nova chave PIX ou pré-visualizar a validação. Use preview=true para apenas validar sem salvar.

📍 Endpoint

POST https://api.etherglobalassets.com.br/pix/keys

🧾 Cabeçalhos obrigatórios (Headers)

Cabeçalho	Valor	Descrição
Authorization	Bearer <token>	Token JWT de autenticação
Content-Type	application/json	Formato do corpo da requisição

🧰 Corpo da Requisição (JSON)

{
  "pixKey": "12345678901",
  "pixKeyType": "CPF",
  "preview": false
}

Explicação dos campos:

Campo	Tipo	Obrigatório	Descrição
pixKey	string	✅	Chave PIX a ser cadastrada
pixKeyType	enum	✅	Tipo da chave PIX
preview	boolean	❌	Modo preview - apenas valida DICT sem salvar (padrão: false)

Tipos de Chave PIX Suportados:

Tipo	Descrição	Exemplo
CPF	CPF da pessoa física	“12345678901”
CNPJ	CNPJ da pessoa jurídica	“12345678000199”
EMAIL	Email válido	"usuario@exemplo.com"
PHONE	Telefone com DDD	“11999999999”
RANDOM	Chave aleatória	“550e8400-e29b-41d4-a716-446655440000”

📌 Exemplo com curl

curl https://api.etherglobalassets.com.br/pix/keys \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "pixKey": "12345678901",
    "pixKeyType": "CPF",
    "preview": false
  }'

✅ Dica: Substitua <token> pelo seu JWT de autenticação válido e ajuste os valores conforme necessário.

✅ Resposta esperada (HTTP 201 - Created)

{
  "id": "uuid-12345678-1234-1234-1234-123456789012",
  "pixKey": "12345678901",
  "pixKeyType": "CPF",
  "createdAt": "2025-01-31T10:00:00Z",
  "isActive": true,
  "bankName": "BCO SANTANDER (BRASIL) S.A."
}

🔍 Resposta de Preview (HTTP 200 - OK)

{
  "pixKey": "12345678901",
  "pixKeyType": "CPF",
  "ownerName": "JOAO DA SILVA",
  "bankName": "BCO SANTANDER (BRASIL) S.A.",
  "bankIspb": "90400888",
  "isValid": true,
  "message": "Chave PIX válida e pertence ao usuário"
}

Explicação da resposta de criação:

Campo	Tipo	Descrição	Exemplo
id	string	ID único da chave PIX	“uuid-12345678-1234-1234-1234-123456789012”
pixKey	string	Chave PIX	“12345678901”
pixKeyType	enum	Tipo da chave PIX	“CPF”
createdAt	string	Data de criação da chave PIX	“2025-01-31T10:00:00Z”
isActive	boolean	Status da chave PIX (ativa/inativa)	true
bankName	string	Nome da instituição bancária	“BCO SANTANDER (BRASIL) S.A.”

Explicação da resposta de preview:

Campo	Tipo	Descrição	Exemplo
pixKey	string	Chave PIX validada	“12345678901”
pixKeyType	enum	Tipo da chave PIX	“CPF”
ownerName	string	Nome do proprietário da chave PIX	“JOAO DA SILVA”
bankName	string	Nome da instituição bancária	“BCO SANTANDER (BRASIL) S.A.”
bankIspb	string	Código ISPB da instituição bancária	“90400888”
isValid	boolean	Se a validação foi bem-sucedida	true
message	string	Mensagem de validação	“Chave PIX válida e pertence ao usuário”

⚠️ Possíveis erros

Código	Erro	Causa comum
400	Bad Request	Dados inválidos ou chave PIX já existe
401	Unauthorized	Token inválido ou ausente
500	Internal Server Error	Erro interno do serviço

🎯 Como usar a criação de chaves PIX

Após receber a resposta, você pode:

Validar primeiro: Use preview: true para validar sem salvar
Criar chave: Use preview: false para criar a chave definitivamente
Verificar validação: Use isValid e message para confirmar a validação
Identificar banco: Use bankName e bankIspb para informações bancárias
Confirmar propriedade: Use ownerName para verificar o proprietário

🛡️ Limitações e restrições

✅ FAÇA:

Sempre valide primeiro com preview: true
Use chaves PIX que pertencem ao usuário autenticado
Verifique se a chave não já existe no sistema
Confirme o tipo correto da chave PIX

❌ NÃO FAÇA:

Usar chaves PIX de outras pessoas
Ignorar a validação prévia
Tentar criar chaves duplicadas
Usar tipos de chave incorretos

🆘 Problemas comuns

“Estou recebendo erro 400!”

Verifique se a chave PIX é válida para o tipo especificado
Confirme se a chave não já existe no sistema
Verifique se a chave pertence ao usuário autenticado

“A validação falhou!”

Verifique se o pixKeyType está correto
Confirme se a chave PIX é válida
Verifique se a chave pertence ao usuário

“Erro 401!”

Verifique se o token de autenticação é válido
Faça uma nova autenticação se necessário

📞 Suporte

Se nada funcionar:

Verifique a chave PIX é válida e pertence ao usuário
Confirme o tipo da chave está correto
Entre em contato com nossa equipe de suporte

Mais informações sobre o endpoint:

Acesse aqui