Documentação Técnica

Especificações TécnicasIntegração Bancária IRPF

Documentação para desenvolvedores e projetistas sobre o uso de JSON como substituição ao PDF no IRPF.

Versão da Especificação: 1.0.0

JSON Schema

Especificação do Formato de Dados

O formato JSON padronizado para transmissão de dados financeiros entre instituições bancárias e a Receita Federal.

Exemplo de Payload JSON

{
  "metadados": {
    "versao_schema": "1.0.0",
    "instituicao": {
      "cnpj": "00.000.000/0001-91",
      "nome": "Banco Exemplo S.A.",
      "codigo_banco": "001"
    },
    "data_geracao": "2024-03-15",
    "ano_calendario": 2024
  },
  "contribuinte": {
    "cpf": "123.456.789-00",
    "nome": "Maria Silva Santos"
  },
  "aplicacoes_financeiras": [
    {
      "tipo": "CONTA_CORRENTE",
      "numero_conta": "12345-6",
      "saldo_31_12": 15000.00,
      "rendimentos_ano": 0.00
    }
  ],
  "rendimentos_tributacao_exclusiva": [
    {
      "tipo": "CDB",
      "instituicao": "Banco Exemplo",
      "valor_aplicado": 50000.00,
      "rendimentos_brutos": 3500.00,
      "ir_retido": 525.00,
      "rendimentos_liquidos": 2975.00
    }
  ],
  "rendimentos_isentos": [
    {
      "tipo": "DIVIDENDOS",
      "fonte_pagadora": "Empresa S.A.",
      "valor": 1200.00,
      "mes_competencia": "12"
    }
  ],
  "bens_direitos": [
    {
      "codigo": "01",
      "descricao": "Conta corrente - Banco Exemplo",
      "valor_31_12_anterior": 12000.00,
      "valor_31_12_atual": 15000.00
    }
  ]
}

Campos Obrigatórios

Especificação detalhada dos dados requeridos em cada seção

Metadados

Informações sobre a instituição e arquivo

versao_schemaVersão semântica

instituicaoCNPJ, nome e código

data_geracaoData ISO 8601

ano_calendarioAno da declaração

Contribuinte

Identificação do titular

cpfFormato XXX.XXX.XXX-XX

nomeNome completo

Aplicações Financeiras

Quando presentes

tipoCONTA_CORRENTE, POUPANCA...

saldo_31_12Valor numérico positivo

numero_contaIdentificação da conta

Rendimentos

Quando presentes

tipoCDB, LCI, FUNDO...

rendimentos_brutosValor bruto dos rendimentos

ir_retidoImposto retido na fonte

Validação Automática

Todos os campos são validados automaticamente contra o schema antes da transmissão

Tipos de dadosFormatos obrigatóriosValores permitidosEstrutura JSON

Formato de Arquivo

Distribuição e Nomenclatura

Especificações sobre como os bancos devem nomear, estruturar e disponibilizar os arquivos JSON para os clientes.

Convenção de Nomenclatura

# Convenção de nomenclatura sugerida:
informe_rendimentos_[codigo_banco]_[ano].json

# Exemplos:
informe_rendimentos_001_2023.json  # Banco do Brasil
informe_rendimentos_341_2023.json  # Itaú Unibanco
informe_rendimentos_237_2023.json  # Bradesco
informe_rendimentos_033_2023.json  # Santander

Características do Arquivo

Formato JSON

Arquivo de texto estruturado, legível e validável

Codificação UTF-8

Suporte completo a caracteres especiais e acentos

Tamanho Compacto

Tipicamente 1-5 KB, muito menor que PDFs equivalentes

Versionamento

Schema versionado permite evolução controlada

Guia de Implementação

Como Implementar

Orientações práticas para bancos e para a Receita Federal implementarem a solução de arquivos JSON.

Exemplo de Implementação

// Exemplo de geração do JSON pelo banco
const informeRendimentos = {
  metadados: {
    versao_schema: "1.0.0",
    instituicao: {
      cnpj: banco.cnpj,
      nome: banco.nome,
      codigo_banco: banco.codigo
    },
    data_geracao: new Date().toISOString().split('T')[0],
    ano_calendario: 2023
  },
  contribuinte: {
    cpf: cliente.cpf,
    nome: cliente.nome
  },
  aplicacoes_financeiras: extrairAplicacoes(cliente),
  rendimentos_tributacao_exclusiva: extrairRendimentos(cliente),
  bens_direitos: extrairBens(cliente)
}

// Salvar arquivo JSON
fs.writeFileSync(
  `informe_rendimentos_${banco.codigo}_2023.json`,
  JSON.stringify(informeRendimentos, null, 2)
)

Passos para Implementação

Mapear Dados Existentes

Identificar onde estão os dados que já são incluídos no PDF

Implementar Geração JSON

Criar rotina que extrai e formata os dados no schema padronizado

Validar Schema

Implementar validação para garantir conformidade com o schema

Disponibilizar Download

Adicionar opção de download JSON junto com o PDF tradicional

Extensões Futuras

Roadmap de Expansão

Após a implementação, o mesmo conceito pode ser aplicado a outros documentos financeiros, criando um ecossistema completo de automação fiscal.

Notas de Corretagem

Complexidade Média

Padronização das notas de corretagem em JSON para importação automática de operações na bolsa

Benefícios:

•Eliminação da digitação manual de centenas de operações
•Cálculo automático de ganhos/perdas de capital
•Controle preciso de custos e taxas
•Histórico completo de operações

Informes de Fundos

Complexidade Baixa

Dados estruturados de fundos de investimento, incluindo come-cotas e distribuições

Benefícios:

•Importação automática de rendimentos de fundos
•Controle de come-cotas
•Histórico de aplicações e resgates
•Dados de tributação específicos

Previdência Privada

Complexidade Média

Informes de PGBL/VGBL com dados de contribuições, portabilidade e resgates

Benefícios:

•Controle automático de contribuições dedutíveis
•Histórico de portabilidade entre fundos
•Cálculo correto de tributação na fonte
•Dados de beneficiários

Cartões de Crédito

Complexidade Baixa

Dados estruturados de programas de pontos e cashback para declaração de rendimentos

Benefícios:

•Declaração automática de cashback
•Controle de programas de pontos
•Histórico de resgates e utilizações
•Tributação correta de benefícios

Documentação Técnica Completa

Esta especificação técnica fornece o mínimo de detalhes necessários para uma primeira versão da facilitação do informe de rendimentos.