# Contabilidade Contabilidade de partidas dobradas em conformidade com a Circular BCB 4010 (COSIF) para operacoes PIX. ## Pre-requisitos - Migracao #18 (`20260207400001`) aplicada (tabelas GL + seeds) - Conhecimento basico de contabilidade de partidas dobradas - Compreensao do COSIF (Plano Contabil das Instituicoes do Sistema Financeiro Nacional) - Acesso ao portal admin com permissao `accounting` ## Visao Geral O Monetarie PIX implementa um sistema contabil completo para registrar todas as movimentacoes financeiras relacionadas ao PIX: ```mermaid flowchart TB subgraph Eventos["Eventos Financeiros"] TX["Transacao PIX
(pacs.008)"] RT["Devolucao
(pacs.004)"] ST["Liquidacao
(settlement)"] FE["Taxas
(fees)"] end subgraph Contabilidade["Motor Contabil"] AE["AccountingEvent
(evento contabil)"] JE["JournalEntry
(lancamento)"] CA["ChartOfAccounts
(plano de contas)"] CC["CostCenter
(centro de custo)"] end subgraph Saida["Relatorios"] BL["Balancete"] DRE["Demonstrativo"] EX["Exportacao BCB"] end TX & RT & ST & FE --> AE AE -->|auto-cria| JE JE --> CA JE --> CC CA & JE --> BL & DRE & EX ``` ## Modelo de Dados ```mermaid erDiagram chart_of_accounts ||--o{ journal_entries : "debito/credito" accounting_events ||--o{ journal_entries : "gera" cost_centers ||--o{ journal_entries : "vinculado" chart_of_accounts { uuid id PK string account_code string account_name string account_type string cosif_code boolean is_active decimal balance } journal_entries { uuid id PK uuid event_id FK uuid debit_account_id FK uuid credit_account_id FK uuid cost_center_id FK decimal amount decimal running_balance_debit decimal running_balance_credit string description datetime posted_at } accounting_events { uuid id PK string event_type string reference_id decimal amount jsonb metadata datetime occurred_at } cost_centers { uuid id PK string code string name string description boolean is_active } ``` ## Plano de Contas COSIF A migracao #18 cria 44 contas seguindo o padrao BCB Circular 4010: ### Contas Seeded | Codigo COSIF | Nome | Tipo | Descricao | |-------------|------|------|-----------| | 1.1.1.01 | Caixa | Ativo | Disponibilidades em caixa | | 1.1.2.01 | Banco Central - Reservas | Ativo | Depositos no BACEN | | 1.1.2.02 | Banco Central - Liquidacao PIX | Ativo | Conta de liquidacao PIX | | 1.1.3.01 | Creditos a Receber - PIX | Ativo | Creditos pendentes de liquidacao | | 1.1.3.02 | Creditos a Receber - TED | Ativo | Creditos TED pendentes | | 2.1.1.01 | Depositos a Vista | Passivo | Contas correntes dos clientes | | 2.1.1.02 | Depositos de Poupanca | Passivo | Poupancas dos clientes | | 2.1.2.01 | Obrigacoes PIX - Pendentes | Passivo | PIX a liquidar | | 2.1.2.02 | Obrigacoes PIX - Em Processamento | Passivo | PIX em processamento | | 3.1.1.01 | Capital Social | PL | Capital subscrito e integralizado | | 4.1.1.01 | Receita de Tarifas PIX | Receita | Tarifas cobradas em PIX | | 4.1.1.02 | Receita de Tarifas TED | Receita | Tarifas cobradas em TED | | 5.1.1.01 | Despesas de Liquidacao | Despesa | Custos de liquidacao BACEN | | 5.1.1.02 | Despesas de Infraestrutura | Despesa | Custos operacionais | | ... | (mais 30 contas) | ... | ... | ### Tipos de Conta | Tipo | Natureza | Debito | Credito | |------|----------|--------|---------| | Ativo | Devedora | Aumenta | Diminui | | Passivo | Credora | Diminui | Aumenta | | PL (Patrimonio Liquido) | Credora | Diminui | Aumenta | | Receita | Credora | Diminui | Aumenta | | Despesa | Devedora | Aumenta | Diminui | ## Partidas Dobradas ### Principio Fundamental Para cada evento contabil, o sistema cria um lancamento (journal entry) que **debita** uma conta e **credita** outra, mantendo o balanco: ``` Soma dos Debitos = Soma dos Creditos (SEMPRE) ``` ### Exemplo: Transacao PIX Enviada ```mermaid flowchart LR EV["Evento: PIX Enviado
R$ 150,00"] --> JE["Journal Entry"] JE --> D["DEBITO
2.1.1.01 Depositos a Vista
R$ 150,00"] JE --> C["CREDITO
1.1.2.02 BC Liquidacao PIX
R$ 150,00"] ``` ### Exemplo: Transacao PIX Recebida ```mermaid flowchart LR EV["Evento: PIX Recebido
R$ 250,00"] --> JE["Journal Entry"] JE --> D["DEBITO
1.1.2.02 BC Liquidacao PIX
R$ 250,00"] JE --> C["CREDITO
2.1.1.01 Depositos a Vista
R$ 250,00"] ``` ### Exemplo: Cobranca de Tarifa PIX ```mermaid flowchart LR EV["Evento: Tarifa PIX
R$ 1,50"] --> JE["Journal Entry"] JE --> D["DEBITO
2.1.1.01 Depositos a Vista
R$ 1,50"] JE --> C["CREDITO
4.1.1.01 Receita Tarifas PIX
R$ 1,50"] ``` ## Saldo em Tempo de Execucao (Running Balance) Cada lancamento armazena o saldo corrente das contas afetadas: ```json { "id": "uuid", "event_id": "uuid", "debit_account_id": "uuid", "credit_account_id": "uuid", "amount": 15000, "running_balance_debit": 1250000, "running_balance_credit": 3750000, "description": "PIX enviado - E2E: E12345678...", "posted_at": "2026-02-13T14:30:00Z" } ``` ## Centros de Custo 6 centros de custo seeded pela migracao #18: | Codigo | Nome | Descricao | |--------|------|-----------| | CC-001 | Operacoes PIX | Operacoes de pagamento instantaneo | | CC-002 | Liquidacao | Processos de liquidacao e netting | | CC-003 | Compliance | Conformidade regulatoria | | CC-004 | Tecnologia | Infraestrutura e desenvolvimento | | CC-005 | Atendimento | Suporte ao cliente | | CC-006 | Administrativo | Despesas administrativas gerais | ## API de Contabilidade ### Endpoints | Metodo | Path | Descricao | |--------|------|-----------| | GET | `/api/v1/accounting/chart-of-accounts` | Listar 44 contas COSIF | | GET | `/api/v1/accounting/journal-entries` | Lancamentos com saldo corrente | | GET | `/api/v1/accounting/events` | Eventos contabeis | | POST | `/api/v1/accounting/events` | Criar evento (auto-cria lancamento) | | GET | `/api/v1/accounting/cost-centers` | Centros de custo (com busca ilike) | | POST | `/api/v1/accounting/cost-centers` | Criar centro de custo | | PUT | `/api/v1/accounting/cost-centers/:id` | Atualizar centro de custo | | POST | `/api/v1/accounting/cost-centers/:id/toggle-status` | Ativar/desativar centro | ### Listar Plano de Contas ```bash curl -s https://pixapi-dev.fluxiq.com.br/api/v1/accounting/chart-of-accounts \ -H "Cookie: pix_session=" | jq '.data[:3]' ``` Resposta: ```json [ { "id": "uuid", "accountCode": "1.1.2.02", "accountName": "Banco Central - Liquidacao PIX", "accountType": "asset", "cosifCode": "1.1.2.02", "isActive": true, "balance": 1250000 } ] ``` ::: info SERIALIZACAO camelCase A API de contabilidade serializa os campos em **camelCase** (padrao JavaScript), diferente do snake_case interno do Elixir. Ex: `account_code` -> `accountCode`. ::: ### Criar Evento Contabil ```bash curl -X POST https://pixapi-dev.fluxiq.com.br/api/v1/accounting/events \ -H "Cookie: pix_session=" \ -H "Content-Type: application/json" \ -d '{ "eventType": "pix_sent", "referenceId": "E1234567820260213143000000000001", "amount": 15000, "debitAccountCode": "2.1.1.01", "creditAccountCode": "1.1.2.02", "costCenterCode": "CC-001", "description": "PIX enviado para Maria Santos", "metadata": { "end_to_end_id": "E1234567820260213143000000000001", "debtor_cpf": "12345678901" } }' ``` ### Listar Lancamentos ```bash curl -s "https://pixapi-dev.fluxiq.com.br/api/v1/accounting/journal-entries?page=1&per_page=20" \ -H "Cookie: pix_session=" | jq '.data[:2]' ``` Resposta: ```json [ { "id": "uuid", "eventId": "uuid", "debitAccount": { "code": "2.1.1.01", "name": "Depositos a Vista" }, "creditAccount": { "code": "1.1.2.02", "name": "BC Liquidacao PIX" }, "amount": 15000, "runningBalanceDebit": 1250000, "runningBalanceCredit": 3750000, "costCenter": { "code": "CC-001", "name": "Operacoes PIX" }, "description": "PIX enviado para Maria Santos", "postedAt": "2026-02-13T14:30:00Z" } ] ``` ### Buscar Centros de Custo ```bash # Busca com filtro ilike curl -s "https://pixapi-dev.fluxiq.com.br/api/v1/accounting/cost-centers?search=operac" \ -H "Cookie: pix_session=" | jq ``` ## Contexto Contabil (Elixir) O modulo `SettlementService.Accounting` fornece operacoes completas: | Funcao | Descricao | |--------|-----------| | `list_chart_of_accounts/1` | Listar contas com filtros | | `get_account_by_code/1` | Buscar conta por codigo COSIF | | `list_journal_entries/1` | Lancamentos paginados | | `list_events/1` | Eventos contabeis paginados | | `create_event/1` | Criar evento + lancamento (transacao DB) | | `list_cost_centers/1` | Centros de custo com busca | | `create_cost_center/1` | Criar centro de custo | | `update_cost_center/2` | Atualizar centro de custo | | `toggle_cost_center_status/1` | Ativar/desativar | ### Criacao de Evento com Lancamento Automatico ```elixir # Ao criar um evento, o sistema automaticamente: # 1. Valida as contas de debito e credito # 2. Cria o journal_entry com partidas dobradas # 3. Atualiza o running_balance de ambas as contas # 4. Tudo dentro de uma transacao DB (Repo.transaction) ``` ## Resultado Esperado Apos configurar a contabilidade: - O plano de contas exibe 44 contas COSIF ativas - Eventos contabeis criam lancamentos de partidas dobradas automaticamente - O saldo corrente (running balance) e mantido em cada lancamento - 6 centros de custo estao disponiveis para classificacao - A serializacao da API usa camelCase para compatibilidade frontend - O balancete geral respeita `Soma Debitos = Soma Creditos` - A exportacao segue o padrao BCB Circular 4010 (COSIF)