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 dados
Formatos obrigatórios
Valores permitidos
Estrutura 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
1

Mapear Dados Existentes

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

2

Implementar Geração JSON

Criar rotina que extrai e formata os dados no schema padronizado

3

Validar Schema

Implementar validação para garantir conformidade com o schema

4

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.