Pix DICT — Chave Dinâmica (W15)

Visão Geral

O módulo pix permite ao tenant registrar uma chave Pix DICT para recebimento de pagamentos dinâmicos. A integração usa Mercado Pago como PSP intermediário na v1 (integração BCB direta exige parceiro BaaS — roadmap futuro).

---

Módulo

backend/src/pix/

Arquivo	Papel
pix.module.ts	Providers + imports
pix.controller.ts	Endpoints REST
dict.service.ts	Lógica de registro + validação de formato
dto/register-dict-key.dto.ts	DTO com validação de tipos de chave

---

Schema de Configuração

Os campos são armazenados no documento Tenant (sem coleção separada):

Campo	Tipo	Descrição
pixDictKey	string?	Valor da chave Pix registrada
pixDictKeyType	string?	cpf | cnpj | email | phone | random
pixDictKeyRegistered	boolean	true se confirmada pelo PSP
mpAccessToken	string?	Access Token do Mercado Pago (nunca retornado via API)

---

Tipos de Chave Pix Suportados

Tipo	Formato esperado	Validação
cpf	11 dígitos numéricos	regex ^\d{11}$
cnpj	14 dígitos numéricos	regex ^\d{14}$
email	formato válido de e-mail	regex básico
phone	+55XXXXXXXXXXX	regex ^\+55\d{10,11}$
random	gerada pelo PSP	sem validação de entrada

---

API Routes

Prefixo: GET/POST /t/:slug/admin/pix

Requer: JwtAuthGuard + TenantGuard + PermissionsGuard(settings.manage.integrations)

Método	Rota	Descrição
GET	/config	Retorna configuração segura (sem mpAccessToken): { pixDictKey, pixDictKeyType, pixDictKeyRegistered, hasMpToken }
POST	/dict/register	Registra/atualiza chave DICT

POST /dict/register — Request

{
  "dictKey": "empresa@exemplo.com.br",
  "dictKeyType": "email"
}

POST /dict/register — Response (modo stub sem MP token)

{
  "registered": false,
  "dictKey": "empresa@exemplo.com.br",
  "dictKeyType": "email",
  "stub": true
}

POST /dict/register — Response (com MP token válido)

{
  "registered": true,
  "dictKey": "empresa@exemplo.com.br",
  "dictKeyType": "email",
  "confirmationId": "mp-account-12345-key-email-confirmed",
  "stub": false
}

---

Modos de Operação

Modo Stub (sem mpAccessToken)

Quando o tenant não tem mpAccessToken configurado:

• A chave é persistida localmente no documento Tenant.
• pixDictKeyRegistered = false.
• Log: [DICT-STUB] tenant=... key=... type=... MP access token absent.
• Adequado para ambientes de desenvolvimento e homologação.

Modo Real (com mpAccessToken)

1. O serviço chama GET https://api.mercadopago.com/v1/account para validar o token.
2. Se o token é válido, persiste pixDictKeyRegistered = true com um confirmationId.
3. Chave salva mesmo em caso de falha na probe — operador pode retentar.

Limitação v1: O Mercado Pago não expõe um endpoint de registro DICT standalone para merchants. A v1 valida as credenciais e persiste a chave localmente. Integração BCB direta (endpoint DICT real) requer parceiro BaaS (~6 semanas de onboarding).

---

Geração de TxId

PixDictService.generateTxId() — método estático:

• Formato: YYYYMMDD + 16 hex chars (8 bytes aleatórios)
• Total: 24 chars
• Adequado à spec BCB (alfanumérico, globalmente único)
• Exemplo: 20260528A3F9C12E45B6D7E8

---

Relacionados

• Configuração de Pagamentos
• Fiscal / NF-e
• User Guide — Configurar Pagamentos