Manual do usuário — Pix Platform

Este manual é para quem opera a plataforma: analistas de Pix, atendimento e back-office

de um participante (PSP). Cobre o que cada tela faz, quais regras o sistema aplica e o que

significa cada estado.

Fonte de manual-do-usuario.html. As imagens ficam em imagens/.

Sobre as imagens. As telas de módulo foram capturadas com o módulo aberto direto

(sem a barra superior do sistema) e sem dados, porque o ambiente de captura não tem

sessão. O conteúdo da área central é exatamente o que aparece dentro da plataforma.

1. O que é a plataforma

Sete módulos de negócio, uma visão operacional transversal e um módulo de identidade.

Cada módulo de negócio cobre um assunto do Pix; a visão operacional reúne o estado

pós-corte sem permitir mudanças nos dados.

O que a plataforma não decide. Ela conversa com o DICT e com o SPI, e obedece aos

prazos e às transições que a norma define. Quando uma ação é recusada, quem recusou foi a

regra — não a tela.

2. Entrar no sistema

1. Informe e-mail e senha e confirme em Entrar.
2. Se a sua conta tem segundo fator, o sistema pede o código de 6 dígitos do aplicativo

autenticador logo depois da senha.

1. O menu superior aparece com apenas os módulos que você tem permissão de ler.

Regras da sessão

O botão Sair, no canto superior direito, encerra a sessão no servidor. Se a rede

falhar nesse momento, você sai da mesma forma no navegador: o pedido foi seu.

Quando o login é recusado

A suspensão vale para todas as contas da instituição ao mesmo tempo, inclusive as

administrativas. Sessões já abertas também param: a renovação do token passa a ser

recusada, e o acesso cai em no máximo 15 minutos.

3. Como o acesso funciona

Autorização é por permissão, não por cargo. Um papel é só um nome dado a um conjunto

de permissões. Quem libera a operação é sempre a permissão.

Operações não cria uma permissão nova. O item aparece se a sessão puder ler pelo

menos um módulo de negócio. Dentro do painel, cada cartão é consultado com a permissão

do próprio bounded context; módulos sem acesso aparecem como restritos.

Três consequências práticas:

• O módulo some do menu quando falta a permissão de leitura. Não fica cinza: um link

que existe mas recusa a entrada ensina a ignorar o menu.

• O menu não é a proteção. Cada serviço revalida o token e a permissão a cada

requisição. Esconder o item é conveniência de navegação.

• O ISPB do seu usuário precisa ser o do participante desta instalação. Se não for, o

login funciona e as telas de Cobranças respondem 403. É o sintoma que mais engana:

parece problema de tela, é divergência de cadastro.

Segundo fator é obrigatório para quem administra usuários

usuarios:administrar é a permissão mais sensível do catálogo: quem a tem pode elevar o

próprio privilégio atribuindo a si um papel mais forte, e pode redefinir a senha de

qualquer conta do participante. Por isso ela exige segundo fator — não é recomendação.

Enquanto o segundo fator não estiver habilitado, a conta administrativa entra, mas o

token sai sem permissão nenhuma. Na prática:

• o login funciona e o seu nome aparece no canto superior direito;
• o menu fica vazio — nenhum módulo, nem mesmo Administração;
• Minha conta continua acessível, e é por ela que se sai da situação.

A contenção existe em vez da recusa do login de propósito: recusar trancaria o

administrador do lado de fora justamente da tela que resolve o problema. Habilite o

segundo fator em Minha conta e entre novamente — as permissões do seu papel voltam ao

token no login seguinte.

A regra vale só para contas de pessoa. Credenciais de máquina não têm como se cadastrar

em um aplicativo autenticador, e exigi-lo delas seria uma porta sem saída.

Minha conta

Clique no seu nome, no canto superior direito, para abrir Minha conta. A página está

disponível para qualquer usuário autenticado, sem exigir permissão administrativa, e mostra

o e-mail, o ISPB, os papéis e o estado do segundo fator da sessão.

No primeiro acesso de uma conta criada pela administração, Minha conta abre

automaticamente e os módulos ficam bloqueados. A senha inicial foi escolhida por outra

pessoa; defina uma nova senha para receber as permissões do seu papel e entrar novamente.

• Alterar senha: informe a senha atual e uma nova senha de 12 a 128 caracteres. Quando

a alteração for aceita, todas as sessões são encerradas e você entra novamente com a

nova senha. Senhas presentes em vazamentos conhecidos são recusadas sem que a senha seja

enviada ao serviço de verificação.

• Habilitar segundo fator: copie a chave ou a URI temporária para um aplicativo

autenticador e confirme um código de seis dígitos. A chave é exibida somente durante a

configuração; não a compartilhe.

• Desabilitar segundo fator: informe um código válido do autenticador. Ter apenas uma

sessão aberta não é suficiente para remover essa proteção.

4. Cobranças

A lista mostra as cobranças imediatas do período. Filtre por início, fim e

status; clique no txid para abrir o detalhe.

Emitir uma cobrança

O valor é string na norma, não número — por isso a máscara é rígida. A vírgula decimal,

que qualquer pessoa digita naturalmente em português, é justamente o caso que a

especificação recusa.

Estados da cobrança

5. Chaves (DICT)

Duas consultas independentes, cada uma no seu cartão:

• Por chave — informe a chave e veja a quem ela pertence hoje.
• Por conta — informe ISPB (8 dígitos) e número da conta para listar todas as

chaves vinculadas àquela conta.

Cadastrar uma chave

Chave com reivindicação em curso fica bloqueada para alteração. A consulta mostra a

data de abertura da reivindicação; enquanto ela existir, a exclusão e a alteração são

recusadas. Resolva a reivindicação primeiro (seção 6).

6. Reivindicações

Uma reivindicação é a disputa por uma chave entre dois participantes: o reivindicante,

que quer a chave, e o doador, que a tem hoje.

O prazo conta a partir do reconhecimento pelo doador. Sem manifestação dentro dele, a

reivindicação é confirmada por decurso. A tela mostra o prazo antes de você enviar,

porque a diferença entre 7 e 30 dias muda a decisão de qual tipo abrir.

Abrir uma reivindicação

Informe a chave, o tipo, e os ISPB do reivindicante e do doador. Os dois ISPB têm 8

dígitos e não podem ser iguais — não existe reivindicação de um participante contra

si mesmo.

Estados e o que você pode fazer em cada um

Os botões que aparecem em cada linha são exatamente os permitidos pelo estado atual. Um

botão que o servidor recusaria é pior que um botão ausente.

Prazo e histórico

A partir do reconhecimento, a reivindicação passa a ter prazo de resolução. A lista

destaca em vermelho o prazo vencido — é ele que decide a favor do reivindicante quando

ninguém se manifesta.

Cada linha do histórico registra quem provocou a mudança:

7. Infrações

Um relato de infração é o registro formal, junto ao DICT, de que algo errado aconteceu em

uma transação específica — identificada pelo EndToEndId.

Abrir um relato

Informe a transação (EndToEndId), o tipo, os participantes envolvidos e os detalhes.

Estados e ações

Ao encerrar, informe o resultado da análise: Concordou ou Discordou. É esse

resultado que a contraparte lê.

O botão Dados abre o infractionData como JSON cru. É de propósito: a norma define

esse campo como objeto livre, e qualquer formatação em campos fixos ficaria errada na

próxima revisão da especificação.

8. Devoluções

O módulo publica dois recursos independentes, ligados apenas pelo identificador da

transação: a solicitação de devolução (DICT Refund) e a recuperação de valores do MED 2.0.

Solicitar devolução

Ao encerrar, informe o resultado: Aceita ou Recusada.

Recuperação de valores (MED 2.0)

Opera sobre uma transação por vez, não sobre uma lista — por isso tem tela própria.

1. Abrir informando a transação (EndToEndId) e o participante, ou carregar uma

recuperação existente pelo identificador.

1. Bloquear o valor encontrado na conta do recebedor.
2. Recuperar o valor bloqueado. Recuperações sucessivas acumulam.
3. Encerrar quando não houver mais o que recuperar.

Recuperação parcial não é um estado. O caso segue em Valores bloqueados e o que muda

é o número recuperado. O sistema passa a Recuperada sozinho quando o total é atingido.

9. Operações pós-corte

O menu Operações abre uma visão consolidada da Fase 5. Ela confirma que Charges,

Keys/DICT, Claims, Infractions e Refunds/MED usam a Pix Platform como fonte de verdade e

que os respectivos legados estão desligados.

O painel permite ajustar a janela histórica, a quantidade mínima de amostras e a taxa

máxima de divergência. Para cada módulo, apresenta:

• amostras convergentes e divergentes do shadow mode;
• erros históricos do legado e itens descartados da fila;
• ressalvas do gate na janela consultada;
• detalhamento por operação obrigatória.

Um rótulo Evidência histórica incompleta não religa o legado nem desfaz o corte. Após

o desligamento não surgem novas comparações, portanto uma janela recente pode não conter

amostras. O registro formal do corte permanece no change management da instituição.

A interface é somente leitura. Ela não altera rotas, não restaura bancos, não revoga

certificados e não exclui infraestrutura. Essas ações exigem changes operacionais

separados. Liquidações possuem tela operacional própria e não fazem parte das evidências

históricas do corte.

10. Liquidações

O menu Liquidações aparece para quem possui liquidacoes:ler. A tela mostra a posição

disponível informada pelo adaptador ativo e permite consultar uma instrução pelo seu

identificador. A opção Reconciliar consulta novamente o provedor apenas quando o estado

local ainda é Pending ou Unknown; resultados terminais não são reabertos.

Quem também possui liquidacoes:escrever pode enviar uma instrução com valor,

EndToEndId opcional e os dados completos de pagador e recebedor: chave Pix, nome,

CPF/CNPJ, ISPB, agência, conta e tipo de conta. Agência pode ficar vazia em contas que não

a utilizam. O CPF continua numérico; o CNPJ pode usar o formato alfanumérico previsto no

catálogo vigente. Cada envio recebe uma chave de

idempotência: repetir a mesma requisição não cria outra movimentação. A modalidade

Direta ou Indireta é configuração da instalação e não pode ser escolhida pelo operador.

Nas consultas, a tela mostra somente ISPB, agência, conta e tipo. Chave Pix, documento e

nome são enviados ao conector e armazenados cifrados; não são reexibidos pela consulta.

A seção Mensagens SPI mostra as respostas recebidas do conector e pode ser filtrada

por Pending, Processed ou Failed. Ela apresenta tipo, identificador externo,

EndToEndId, resultado, tentativas e último erro. Failed significa que o limite de

retentativas foi alcançado e deve ser investigado; a tela não permite alterar o resultado

nem reenviar a mensagem manualmente.

No ambiente local de desenvolvimento, a tela usa um simulador com saldo controlado. Esse

simulador não pode iniciar em homologação ou produção; nesses ambientes é obrigatório

configurar o canal RSFN/SPI ou o participante liquidante contratado.

11. Contabilidade

O menu Contabilidade aparece para quem possui contabilidade:ler. O balancete agrupa

débitos, créditos e saldo por conta; o razão recente mostra a origem, a referência e cada

partida do lançamento. Os dados exibidos pertencem exclusivamente ao ISPB da sessão.

Com contabilidade:escrever, o operador pode:

• informar o identificador de uma liquidação para consultá-la no Settlement e contabilizar

automaticamente um resultado Settled;

• registrar um ajuste manual com descrição, referência, conta de débito, conta de crédito

e valor.

O serviço rejeita lançamentos desbalanceados mesmo que a interface seja contornada. A

mesma liquidação ou chave de idempotência não gera partidas duplicadas. Liquidações

pendentes aguardam conciliação; liquidações rejeitadas são marcadas como não aplicáveis e

não movimentam o razão.

12. Administração

O menu Administração aparece para quem possui usuarios:ler. A tela lista somente

as contas e os papéis do participante identificado pelo ISPB da sessão; não existe campo

para escolher outro participante.

Quem possui apenas leitura pode consultar usuários, status, uso de segundo fator e

papéis. Com usuarios:administrar, também é possível:

• convidar uma pessoa por link de uso único, ou criar a conta com senha temporária e papéis

iniciais (as duas formas comparadas adiante);

• reemitir o convite de uma conta ainda pendente de ativação;
• redefinir a senha de uma conta como temporária quando o titular perder o acesso;
• substituir o conjunto de papéis de uma conta;
• bloquear, desbloquear ou desativar um usuário;
• criar, editar e excluir papéis que não sejam de sistema;
• consultar a trilha de autenticação por período, usuário e tipo de evento.

Alterar papéis revoga as sessões anteriores do usuário. A desativação preserva a conta e

sua auditoria; ela não é uma exclusão. Papéis de sistema não podem ser alterados nem

removidos. A conta nova só recebe permissões no token depois que o titular substitui a

senha inicial; até lá, pode acessar apenas o autocuidado necessário para concluir a troca.

Dar acesso a uma pessoa nova

Há dois caminhos, e eles não são equivalentes.

O convite é preferido porque não existe senha para transmitir. Na senha temporária, o

canal usado para entregá-la (mensagem, e-mail, bilhete) passa a ser o elo mais fraco da

cadeia, e continua valendo até o titular entrar.

O link do convite vale 24 horas e serve uma única vez: assim que o titular define

a senha, ele deixa de funcionar. Enquanto isso não acontece, a conta fica em **Pendente de

ativação** — ela existe, já tem os papéis atribuídos, mas não entra em lugar nenhum.

Se o link expirar ou não chegar, reemita o convite para a mesma conta. Reemitir

invalida os anteriores — dois links vivos ao mesmo tempo dobram a superfície de ataque e

tornam impossível saber qual foi usado. Não recrie a conta: recriar perde os papéis já

atribuídos e a data de criação, que é o que a auditoria usa para reconstruir quando o

acesso foi concedido.

Hoje o convite existe só na API (POST /users/invites, POST /users/{id}/invites

para reemitir e POST /auth/invites/accept para o titular aceitar). A tela de

Administração ainda oferece apenas a criação com senha temporária. Até a tela existir, o

caminho deve ser conduzido pelo suporte autorizado, conforme o guia técnico de integração.

Em Redefinir senha, informe uma credencial provisória de 12 a 128 caracteres e

entregue-a ao titular por um canal seguro. A operação invalida a senha anterior e todos

os refresh tokens ativos. Tokens de acesso já emitidos não podem ser recolhidos e podem

permanecer válidos por até 15 minutos; para uma contenção imediata, bloqueie também a

conta. No próximo login, o titular acessa apenas Minha conta até escolher a senha

definitiva.

Atenção: usuarios:administrar permite elevar privilégios, inclusive os do próprio

administrador. Use um papel dedicado e revise a auditoria periodicamente. O segundo fator

não é opcional aqui — sem ele a conta entra sem permissão alguma (seção 3).

13. Quando algo dá errado

Erro de preenchimento e conflito têm cores diferentes de propósito: "corrija o formulário"

e "o recurso mudou, reconsulte" pedem reações distintas.

14. Integrações e suporte técnico

O uso de tokens e Swagger fica no guia técnico de integração. Para recuperar ou administrar acesso, solicite ajuda ao responsável autorizado; não compartilhe seu token.

15. Glossário