# Conceitos do Ecossistema PIX

Glossario e explicacao detalhada dos conceitos fundamentais do ecossistema PIX implementados pelo FluxiQ PIX.

## Pre-requisitos

- Leitura da [Introducao](./introduction.md)
- Familiaridade basica com o sistema financeiro brasileiro

## PIX — Pagamento Instantaneo

O PIX e o sistema de pagamentos instantaneos criado pelo Banco Central do Brasil (BCB), lancado em novembro de 2020. Permite transferencias e pagamentos em tempo real, 24 horas por dia, 7 dias por semana, 365 dias por ano — incluindo feriados e finais de semana.

**Caracteristicas principais:**
- Liquidacao em segundos (SLA de 1,6 segundos conforme ANS)
- Funcionamento 24/7/365
- Custos reduzidos em comparacao com TED, DOC e boleto
- Multiplos casos de uso: P2P, P2B, B2B, cobranças, pagamentos governamentais

## DICT — Diretorio de Identificadores de Contas Transacionais

O DICT e o servico centralizado mantido pelo Banco Central que armazena a vinculacao entre chaves PIX e contas transacionais. Quando um pagador informa uma chave PIX, o DICT retorna os dados bancarios do recebedor.

### Tipos de Chave PIX

| Tipo | Formato | Exemplo | Descricao |
|------|---------|---------|-----------|
| **CPF** | 11 digitos | `12345678901` | Cadastro de Pessoa Fisica |
| **CNPJ** | 14 digitos | `12345678000190` | Cadastro Nacional de Pessoa Juridica |
| **PHONE** | +55DDDNUMERO | `+5511987654321` | Numero de telefone celular |
| **EMAIL** | email valido | `usuario@email.com` | Endereco de e-mail |
| **EVP** | UUID v4 | `a1b2c3d4-e5f6-...` | Chave aleatoria (Endereco Virtual de Pagamento) |

### Operacoes DICT

| Operacao | Descricao |
|----------|-----------|
| **Criacao** | Vincular uma chave PIX a uma conta transacional |
| **Consulta** | Buscar dados bancarios a partir de uma chave PIX |
| **Exclusao** | Remover a vinculacao de uma chave PIX |
| **Portabilidade** | Transferir uma chave PIX entre instituicoes (mesmo titular) |
| **Reivindicacao (Claim)** | Solicitar a posse de uma chave registrada em outra instituicao |

### Reivindicacoes (Claims)

Quando um usuario deseja vincular uma chave que ja esta registrada em outra instituicao:

1. **Reivindicacao de Posse**: O titular da chave solicita a transferencia para outra instituicao
2. **Reivindicacao de Portabilidade**: O titular solicita que a chave seja movida junto com a mudanca de conta

O processo envolve notificacao ao detentor atual, periodo de contestacao e confirmacao.

## SPI — Sistema de Pagamentos Instantaneos

O SPI e a infraestrutura de liquidacao operada pelo Banco Central que processa as transacoes PIX. Utiliza mensagens no padrao ISO 20022.

### Mensagens ISO 20022

| Codigo | Nome | Descricao |
|--------|------|-----------|
| **pacs.008** | FIToFICustomerCreditTransfer | Transferencia de credito entre instituicoes (mensagem principal de pagamento PIX) |
| **pacs.002** | FIToFIPaymentStatusReport | Relatorio de status de pagamento (confirmacao, rejeicao) |
| **pacs.004** | PaymentReturn | Devolucao de pagamento (parcial ou total) |
| **pacs.028** | FIToFIPaymentStatusRequest | Consulta de status de pagamento |
| **camt.060** | AccountReportingRequest | Consulta de saldo |
| **pibr.001** | PIXEchoRequest | Requisicao de eco (teste de conectividade) |
| **pibr.002** | PIXEchoResponse | Resposta de eco |

### Fluxo de uma Transacao PIX

```mermaid
sequenceDiagram
    participant Pagador
    participant PSP_Pag as PSP do Pagador
    participant SPI as SPI (BCB)
    participant PSP_Rec as PSP do Recebedor
    participant Recebedor

    Pagador->>PSP_Pag: Inicia pagamento (chave PIX)
    PSP_Pag->>SPI: Consulta DICT (chave)
    SPI-->>PSP_Pag: Dados do recebedor
    PSP_Pag->>Pagador: Confirma dados
    Pagador->>PSP_Pag: Autoriza pagamento
    PSP_Pag->>SPI: pacs.008 (transferencia)

    Note over SPI: Validacao e liquidacao

    SPI-->>PSP_Pag: pacs.002 (ACSP - em processamento)
    SPI->>PSP_Rec: pacs.008 (credito)
    PSP_Rec-->>SPI: pacs.002 (ACCC - aceita)
    SPI-->>PSP_Pag: pacs.002 (STLD - liquidada)
    PSP_Rec->>Recebedor: Notifica credito

    Note over PSP_Pag,PSP_Rec: ANS: <= 1,6 segundos
```

### Status de Transacao (BCB)

| Codigo | Nome | Descricao | Cor |
|--------|------|-----------|-----|
| **PDNG** | Pendente | Transacao recebida, aguardando processamento | Amarelo |
| **ACSP** | Em Processamento | Aceita pelo SPI, em processamento | Azul |
| **ACCC** | Aceita | Aceita pela instituicao recebedora | Verde |
| **ACSC** | Aceita com Liquidacao Confirmada | Confirmacao tecnica da liquidacao | Verde |
| **ACTC** | Aceita Tecnicamente | Validacao tecnica aprovada | Verde |
| **ACWC** | Aceita com Alteracoes | Aceita com modificacoes | Verde |
| **STLD** | Liquidada | Transacao liquidada com sucesso | Esmeralda |
| **RJCT** | Rejeitada | Transacao rejeitada | Vermelho |
| **CANC** | Cancelada | Transacao cancelada | Cinza |
| **RTRN** | Devolvida | Transacao devolvida (pacs.004) | Roxo |

## MED 2.0 — Mecanismo Especial de Devolucao

O MED e o mecanismo definido pelo Banco Central para recuperacao de recursos em casos de fraude, falha operacional ou uso indevido do PIX. A versao 2.0 ampliou os prazos e os motivos de devolucao.

### Fluxo do MED

```mermaid
stateDiagram-v2
    [*] --> OPEN: Abertura do relatorio
    OPEN --> AWAITING_ANALYSIS: Confirmacao de recebimento
    AWAITING_ANALYSIS --> ANALYSED: Analise (AGREED/DISAGREED)
    ANALYSED --> CLOSED: Fechamento com motivo
    OPEN --> CANCELLED: Cancelamento
    AWAITING_ANALYSIS --> CANCELLED: Cancelamento
    CLOSED --> [*]
    CANCELLED --> [*]
```

### Status de Infracoes

| Status | PT Label | Descricao |
|--------|----------|-----------|
| **OPEN** | Aberta | Relatorio criado, aguardando confirmacao do recebedor |
| **AWAITING_ANALYSIS** | Aguardando Analise | Recebedor confirmou recebimento, aguardando analise |
| **ANALYSED** | Analisada | Analise concluida (concordou ou discordou) |
| **CLOSED** | Fechada | Relatorio encerrado com motivo final |
| **CANCELLED** | Cancelada | Relatorio cancelado antes do encerramento |

### Motivos de Devolucao MED

- Fraude (suspeita ou comprovada)
- Falha operacional do PSP
- Credito indevido (erro de envio)
- Coercao/extorsao
- Sequestro relampago

## ANS — Acordo de Nivel de Servico

O ANS define os niveis de servico obrigatorios para participantes do PIX. O principal indicador e o tempo de liquidacao.

| Metrica | Requisito | Descricao |
|---------|-----------|-----------|
| **Tempo de liquidacao** | <= 1,6 segundos | Da operacao (pacs.008 enviado) ate a liquidacao (STLD) |
| **Disponibilidade** | 99,998% | Tempo de atividade mensal do servico |
| **Capacidade** | Variavel por participante | TPS minimo conforme volume do participante |

O FluxiQ PIX monitora o ANS em tempo real:
- **Dashboard**: Mostra delta de liquidacao por transacao (Operacao --> Aceite --> Liquidacao)
- **Badge**: "OK" (verde, <= 1.600ms) ou "EXCEDIDO" (vermelho, > 1.600ms)
- **Metricas**: Prometheus coleta percentis de latencia

## ISO 20022

Padrao internacional de mensageria financeira definido pela ISO (International Organization for Standardization). O SPI do Banco Central adota o ISO 20022 como formato de todas as mensagens de pagamento.

**Caracteristicas no FluxiQ PIX:**
- Mensagens em formato XML
- Assinatura digital XMLDSig RSA-SHA256 com certificados ICP-Brasil
- Validacao contra schemas XSD (27 tipos de mensagem)
- Canonicalizacao Exclusive XML C14N

## COSIF — Plano Contabil das Instituicoes do Sistema Financeiro Nacional

O COSIF e o plano de contas padronizado definido pelo Banco Central (Circular 4010) para contabilidade de instituicoes financeiras.

O FluxiQ PIX implementa:
- **44 contas COSIF** pre-cadastradas conforme Circular BCB 4010
- **6 centros de custo** para alocacao de despesas e receitas
- **Lancamentos de dupla entrada** (debito e credito) com saldo corrente
- **Eventos contabeis** vinculados a transacoes PIX

## Participantes

### Participante Direto

Instituicao que possui conexao direta com o SPI do Banco Central. Identificada por um ISPB (Identificador do Sistema de Pagamentos Brasileiro) de 8 digitos.

**Responsabilidades:**
- Manter conexao com o SPI 24/7/365
- Cumprir ANS
- Manter certificados ICP-Brasil validos
- Processar mensagens ISO 20022

### Participante Indireto

Instituicao que opera no PIX por intermedio de um participante direto (liquidante). Nao possui conexao direta com o SPI.

**Exemplos:** Fintechs, cooperativas menores, instituicoes de pagamento

## Ciclos de Liquidacao e Netting

### Liquidacao

Processo de efetivacao financeira de uma transacao PIX. No modo instantaneo, a liquidacao ocorre transacao a transacao em tempo real.

### Netting (Compensacao)

Processo de apuracao de posicoes liquidas entre participantes ao final de um ciclo. O FluxiQ PIX suporta:

- **Netting bilateral**: Apuracao entre 2 participantes
- **Netting multilateral**: Apuracao entre multiplos participantes
- **Ciclos diarios**: Execucao automatica conforme calendario do BACEN

### Reconciliacao

Processo de confronto entre os registros internos do participante e os registros do Banco Central para identificacao de discrepancias.

O FluxiQ PIX executa reconciliacao automatica com:
- Limite de 10.000 registros por execucao (prevencao de OOM)
- Identificacao automatica de discrepancias
- Relatorio de divergencias

## Resultado Esperado

Ao final desta secao, voce tera compreensao dos seguintes conceitos:

- O que e o PIX e como funciona o ecossistema de pagamentos instantaneos
- O papel do DICT como diretorio central de chaves PIX
- Os tipos de mensagem ISO 20022 processados pelo SPI
- O fluxo completo de uma transacao PIX (da iniciacao a liquidacao)
- Como funciona o MED 2.0 para recuperacao de fraude
- Os requisitos de ANS e como o FluxiQ PIX os monitora
- A contabilidade COSIF implementada na plataforma
- A diferenca entre participantes diretos e indiretos