Criar uma chave Pix

Visão Geral

Através deste módulo você pode:

• Criar chaves Pix do tipo CPF
• Criar chaves Pix do tipo CNPJ
• Criar chaves Pix do tipo email
• Criar chaves Pix do tipo telefone
• Criar chaves Pix aleatórias (EVP)
• Confirmar chaves que requerem verificação (código por e-mail ou telefone)
• Reenviar código de confirmação
• Finalizar o cadastro após a chave estar verificada
• Consultar dados de uma chave (com limite de requisições)

Autenticação

As rotas deste módulo usam o prefixo /api/v2/baas e os middlewares identification-seller, auth-baas (JWT no guard da API com account_uuid no payload) e hmac-signature.

• Authorization: token JWT BaaS (Bearer {token}). O payload deve incluir account_uuid e, quando o HMAC estiver ativo, o segredo utilizado na assinatura.
• HMAC: se HMAC_ENABLED=true no .env, envie X-Signature, X-Timestamp e X-Nonce em cada requisição. A assinatura usa método HTTP, path (por exemplo /api/v2/baas/key-managements/...), query string, corpo bruto (string) e o secret do JWT. Veja Assinatura HMAC. Com HMAC_ENABLED=false, em ambientes locais costuma bastar Authorization.

Endpoints

Criar Chave Pix

POST /api/v2/baas/key-managements

Cria uma nova chave Pix para a conta autenticada.

Headers

Campos Obrigatórios

key_type (integer, obrigatório)

Tipo da chave Pix a ser criada.

• Valores possíveis:
  • 0: CPF
  • 1: CNPJ
  • 2: Email
  • 3: Telefone
  • 4: Chave aleatória (EVP)
• Validações:
  • Obrigatório
  • Deve ser um número entre 0 e 4
  • Conta PF não pode possuir chave de CNPJ.
  • Conta PJ não pode possuir chave de CPF.
• Exemplo:

  {
    "key_type": 2
  }
  

  Representa chave do tipo email

key (string, condicional)

Valor da chave Pix.

• Validações:
  • Obrigatório para tipos 0, 1, 2, 3 (CPF, CNPJ, email, telefone)
  • Não necessário para tipo 4 (EVP - chave aleatória)
  • Deve ser válido conforme o tipo escolhido
• Exemplos:

  {
    "key": "[email protected]"
  }
  

  {
    "key": "11987654321"
  }
  

  {
    "key": "12345678901"
  }
  

Tipos de Chave

CPF (key_type: 0)

• Formato: 11 dígitos numéricos
• Validação: Deve ser um CPF válido
• Exemplo: "key": "12345678901"

CNPJ (key_type: 1)

• Formato: 14 dígitos numéricos
• Validação: Deve ser um CNPJ válido
• Exemplo: "key": "12345678000190"

Email (key_type: 2)

• Formato: Endereço de e-mail válido
• Validação: Deve seguir formato de e-mail padrão
• Exemplo: "key": "[email protected]"

Telefone (key_type: 3)

• Formato: Número com DDD (11 dígitos)
• Validação: Deve ser um número de telefone válido
• Observação: O sistema adiciona automaticamente o código do país (+55)
• Exemplo: "key": "11987654321"

Chave Aleatória - EVP (key_type: 4)

• Formato: UUID gerado automaticamente
• Validação: Não requer campo key, o sistema gera automaticamente
• Exemplo: Não é necessário enviar o campo key

Exemplo de Requisição - Chave Email

{
  "key_type": 2,
  "key": "[email protected]"
}

Exemplo de Requisição - Chave Telefone

{
  "key_type": 3,
  "key": "11987654321"
}

Exemplo de Requisição - Chave Aleatória (EVP)

{
  "key_type": 4
}

Resposta de Sucesso - Chave Criada Imediatamente (200)

{
  "id": 123,
  "key": "[email protected]",
  "key_type": 2,
  "status": 1,
  "created_at": "2025-01-15 14:30:00"
}

Resposta de Sucesso - Chave Requer Confirmação (200)

{
  "need_confirmation": true,
  "message": "A confirmation code has been sent to your email/phone"
}

Campos da Resposta

Confirmar código de verificação

POST /api/v2/baas/key-managements/verification-code

Confirma o código enviado para uma chave pendente (e-mail ou telefone). Após sucesso, a resposta reflete o recurso da chave com need_confirmation: false.

Headers

Corpo (JSON)

Exemplo de Requisição

{
  "key": "+5511999999999",
  "code": "123456"
}

Exemplo cURL

curl -X POST https://api-h.nuvende.com.br/api/v2/baas/key-managements/verification-code \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" \
  -d '{"key":"+5511999999999","code":"123456"}'

Resposta de Sucesso (200)

Código confirmado. O corpo segue o formato do recurso da chave (ex.: id, key, key_type, reason, status, created_at) e inclui need_confirmation: false.

{
  "id": 123,
  "key": "+5511999999999",
  "key_type": 3,
  "reason": null,
  "status": 3,
  "created_at": "2025-01-15 14:30:00",
  "need_confirmation": false
}

Erros típicos

Finalizar cadastro após verificação

POST /api/v2/baas/key-managements/{id}/store-after-verification

Finaliza o cadastro para uma chave já verificada ({id} = ID do registro em keys). Não há corpo JSON obrigatório.

Parâmetros de Rota

Headers

Exemplo cURL

curl -X POST https://api-h.nuvende.com.br/api/v2/baas/key-managements/42/store-after-verification \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}"

Resposta de Sucesso (200)

Objeto da chave (mesmo formato geral do recurso: id, key, key_type, status, etc.).

Erros típicos

Reenviar código de confirmação

POST /api/v2/baas/key-managements/resend-code

Reenvia o código de confirmação para uma chave pendente. O controller aceita o campo key via JSON ou form ($request->get('key')).

Headers

Corpo

Exemplo de Requisição

{
  "key": "+5511999999999"
}

Exemplo cURL

curl -X POST https://api-h.nuvende.com.br/api/v2/baas/key-managements/resend-code \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" \
  -d '{"key":"+5511999999999"}'

Resposta de Sucesso (200)

{
  "need_confirmation": true
}

Erros típicos

Consultar chave

POST /api/v2/baas/key-managements/consult

Consulta dados de uma chave. Limite: 20 requisições por minuto por cliente (throttle:20,1). A conta precisa ter pelo menos uma chave cadastrada; caso contrário, retorna 422.

Para detalhes adicionais do mesmo endpoint, veja também Consultar uma chave Pix de uma conta.

Headers

Corpo (JSON)

Exemplo de Requisição

{
  "key": "[email protected]"
}

Exemplo cURL

curl -X POST https://api-h.nuvende.com.br/api/v2/baas/key-managements/consult \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" \
  -d '{"key":"[email protected]"}'

Resposta de Sucesso (200)

{
  "key": "[email protected]",
  "key_type": 2,
  "ispb": "12345678",
  "agency": "0001",
  "account": "12345-6",
  "account_type": 1,
  "person_type": 1,
  "document": "123***8901",
  "name": "João da Silva Santos",
  "favorite": false,
  "bank_name": "Banco Exemplo"
}

Campos da Resposta

Erros típicos

Respostas de Erro

Os cenários abaixo referem-se ao endpoint Criar Chave Pix (POST /api/v2/baas/key-managements). Confirmação, reenvio, finalização e consulta possuem tabelas de erros nas próprias seções.

400 - Chave Já Existe

{
  "message": "Pix Key already exist."
}

422 - Erro de Validação

{
  "message": {
    "key_type": [
      "O campo key_type é obrigatório.",
      "O campo key_type deve ser um número entre 0 e 4."
    ],
    "key": [
      "O campo key é obrigatório quando key_type não é 4.",
      "O campo key deve ser um email válido."
    ]
  }
}

422 - Chave Inválida

{
  "message": {
    "key": [
      "A chave informada não é válida para o tipo selecionado."
    ]
  }
}

401 - Não Autenticado

{
  "message": "Unauthorized"
}

403 - Acesso Negado

{
  "message": "Forbidden"
}

429 - Rate Limit Excedido

{
  "message": "Too Many Requests"
}

Regras de Negócio

Confirmação de Chave e cadastro

• Alguns tipos de chave (e-mail e telefone) passam por aprovação: após a criação, need_confirmation pode vir true e um código é enviado.
• Reenvio do código: POST /api/v2/baas/key-managements/resend-code com o campo key.
• Validar o código: POST /api/v2/baas/key-managements/verification-code com key e code.
• Concluir: quando a chave estiver verificada (status = Verificado, código 3), chame POST /api/v2/baas/key-managements/{id}/store-after-verification com o id retornado no cadastro.
• Consulta: POST /api/v2/baas/key-managements/consult para obter dados da chave no diretório (com throttle e exigência de pelo menos uma chave na conta).

Limite de Chaves

• Cada conta pode ter múltiplas chaves Pix
• Recomenda-se ter pelo menos uma chave ativa para receber pagamentos

Chave Aleatória (EVP)

• A chave aleatória é gerada automaticamente pelo sistema
• Não é necessário informar o campo key para este tipo
• A chave gerada é um UUID único

Validação de Chave

• O sistema valida automaticamente se a chave é válida
• Chaves inválidas retornam erro de validação
• Chaves já cadastradas retornam erro informando que já existem

Próximos Passos

Após criar uma chave Pix, você pode:

1. Consultar Chaves para verificar chaves cadastradas
2. Excluir uma Chave se necessário
3. Realizar Pagamentos usando suas chaves