# Formato de importação — Contas em Família, versão 1

Formato recomendado: `.json` UTF-8, com esta estrutura:

```json
{
  "versao": 1,
  "moeda": "BRL",
  "contas": [
    {
      "nome": "Financiamento da casa",
      "valor": 1250.35,
      "vencimento": "2026-12-10",
      "categoria": "Casa",
      "responsavel": "Gabriel",
      "parcela": 1,
      "total_parcelas": 16,
      "id_externo": "contrato-exemplo-001-parcela-01",
      "origem": "carne.pdf, página 1"
    },
    {
      "nome": "Financiamento da casa",
      "valor": 1243.10,
      "vencimento": "2027-01-10",
      "categoria": "Casa",
      "parcela": 2,
      "total_parcelas": 16,
      "id_externo": "contrato-exemplo-001-parcela-02",
      "origem": "carne.pdf, página 2"
    }
  ]
}
```

O exemplo contém somente duas parcelas ilustrativas. Para 16 parcelas, liste os 16 objetos com seus valores e vencimentos reais. O importador não gera parcelas adicionais a partir de total_parcelas.

## Campos de cada conta

| Campo | Regra |
| --- | --- |
| nome | Obrigatório, texto de 1 a 90 caracteres. |
| valor | Obrigatório, número em reais maior que zero, máximo 999999999 e até 2 casas decimais. Sem símbolo R$, vírgulas decimais ou separador de milhar. |
| vencimento | Obrigatório, data real AAAA-MM-DD, de 1900 a 2200. |
| categoria | Opcional: Casa, Serviços, Alimentação, Saúde, Educação, Transporte ou Outros. Ausente ou desconhecida vira Outros; desconhecida gera aviso. |
| responsavel | Opcional, texto de até 60 caracteres. Não envia convite. |
| parcela / total_parcelas | Opcionais em conjunto, inteiros de 1 a 360; parcela não pode superar o total. São informações, não uma instrução de repetição. |
| id_externo | Opcional, texto de até 180 caracteres, identificador estável e único da parcela em sua fonte. Ajuda a detectar duplicatas. |
| origem | Opcional, texto de até 300 caracteres, arquivo/página para conferência. |
| pago | Opcional, booleano true/false; padrão false. |
| data_pagamento | Obrigatória se pago for true, data ISO ou AAAA-MM-DD. |
| pendencia | Opcional, texto: se preenchido, impede importar esse registro até a correção. Use para incertezas da extração. |
| avisos | Opcional, lista de textos exibida na revisão, sem bloquear o registro. |

Campos desconhecidos geram aviso e são ignorados. Metadados de origem, parcela e identificador são preservados nos backups. O aplicativo também aceita os backups antigos com version: 1 e accounts.

## Revisão e importação parcial

A tela lista cada registro, seus erros e avisos. Registros com erro não podem ser selecionados. É possível importar somente os válidos, sem substituir as contas existentes. Nada é salvo antes de “Importar selecionadas”. Para alterar dados de uma linha com erro, corrija o arquivo e envie novamente. O relatório de problemas pode ser baixado na revisão.

Possíveis duplicatas são detectadas por id_externo ou por nome (ignorando maiúsculas/minúsculas), valor e vencimento. São inicialmente desmarcadas, mas podem ser selecionadas se a repetição for intencional. O detector não substitui a conferência humana e não atualiza contas existentes.

Um JSON com erro de sintaxe não pode ser recuperado com segurança. Nesse caso, corrija o arquivo inteiro ou use `.jsonl` / `.txt`: uma conta JSON completa por linha, sem cabeçalho, sem objeto externo e sem vírgulas entre linhas. Nesses formatos, uma linha ilegível não impede revisar e importar as outras:

```text
{"nome":"Internet","valor":99.90,"vencimento":"2026-12-10"}
{"nome":"Energia","valor":183.42,"vencimento":"2026-12-15"}
```

Limites: arquivo de até 5 MB e até 5.000 registros. Apenas BRL, sem conversão de moeda. O PDF não é enviado diretamente ao aplicativo: primeiro converta-o com o chat que fará a leitura. O arquivo é revisado no navegador; ao confirmar, os registros selecionados são enviados para o banco do grupo atual. Os responsáveis das contas importadas serão inicialmente a pessoa que está importando, e a divisão pode ser ajustada depois. A importação de backups não reconstrói divisões nem pagamentos parciais; para restaurar todos os dados, use o backup completo do banco descrito no README.
