Projeto técnico: Contracheques DigitalPrev

Objetivo

Criar ferramenta, no ambiente OnyxPrev®, que possibilite realizar upload de arquivo PDF contendo os contracheques de segurados da folha do Instituto e disponibilizar para visualização e download pelos titulares através do aplicativo móvel DigitalPrev®.

Especificações

O usuário deverá selecionar o Órgão e período para o qual o arquivo será importado, validar as informações extraídas e indexadas pela aplicação e confirmar a importação e disponibilização imediata dos dados aos segurados, daquele órgão, através do aplicativo móvel DigitalPrev®.

Arquivo

Para que seja possível uma extração dos dados com precisão, o arquivo de contracheques a ser processado deverá atender às seguintes características:

• Arquivo PDF de texto
• Exibir as informações de um segurado por página

Indexação

A aplicação deverá fazer a leitura do arquivo PDF e separar os contracheques por página fazendo leitura e reconhecimento do CPF e utilizando essas informações para indexar os arquivos.

Validação

Ao submeter o arquivo para indexação dos contracheques por segurado, a aplicação deverá disponibilizar uma visualização da extração contendo os seguintes dados de cada segurado extraído do arquivo e que possui um cadastro de segurado ativo, inativo ou pensionista na base de dados do OnyxERP para o Órgão selecionado:

• Nome
• CPF
• Arquivo PDF contendo somente o contracheque deste segurado(CPF)

Disponibilização

Uma nova tela deverá ser criada no aplicativo móvel DigitalPrev®, para visualização e download do contracheque pelo titular, com as seguintes características:

• Seletor de Mês e Ano para visualização, com as opções de competência disponíveis para o segurado
• Visualizador do arquivo em tela
• Botão para download do arquivo

Infra

Banco de Dados

Criar as seguintes tabelas no banco de dados da Social para a indexação dos arquivos extraídos com CPF e competência.

Contracheques(contracheque_arquivo)

Column	Type	Constraints
id	INTEGER	PRIMARY KEY
oid	VARCHAR(35)	INDEX
oeid	VARCHAR(35)	INDEX
mes	TINYINT	NOT NULL
ano	SMALLINT	NOT NULL
arquivo	VARCHAR(255)	NOT NULL
arquivo_hash	VARCHAR(64)	NOT NULL / UNIQUE
raw_data	TEXT	NULLABLE / DEFAULT NULL
status	ENUM('A','V','R')	NOT NULL / DEFAULT('A')
uupfid	VARCHAR(35)	NOT NULL
data_hora	DATETIME	NOT NULL

Registro(contracheque_registro)

Column	Type	Constraints
id	INTEGER	PRIMARY KEY
pf_id	VARCHAR(35)	INDEX
pagina	TINYINT(3)	NOT NULL
arquivo	VARCHAR(255)	NOT NULL
data_hora	DATETIME	NOT NULL
contracheque_arquivo_id	INTEGER	FOREIGN KEY(contracheque_arquivo)

Indexes(contracheque_arquivo)

Nome	Coluna
idx_arquivo_oid	oid
idx_arquivo_oeid	oeid
idx_arquivo_mes_ano	mes, ano
idx_arquivo_oid_mes_ano	oid, mes, ano
idx_arquivo_oeid_mes_ano	oeid, mes, ano
idx_arquivo_oid_oeid	oid, oeid
idx_arquivo_oid_oeid_mes_ano	oid, oeid, mes, ano
contracheque_registro

Nome	Coluna
idx_registro_pf_id	pf_id
idx_registro_contracheque_arquivo_id	contracheque_arquivo_id
idx_registro_pf_id_arquivo_id	pf_id, contracheque_arquivo_id

Endpoints

Para dar suporte a tela administrativa a ser utilizada pelos agentes da BRA e as novas telas do aplicativo DigitalPrev®, serão criados os seguintes endpoints:

1. Listar todos os arquivos processados para um determinado Órgão/Entidade independente do status

GET /v2/contracheque/{ano}/?oid={oid}&offset=0&limit=13

Utilizando os dados do token do usuário ou o {oid} na QueryString da URL, executar uma busca na tabela contracheque_arquivo por oid e oeid e listar os resultados paginados de acordo com o offset e limit informados na URL e ordenados por ano/mês em order decrescente.

Resposta:

{
  "paginas": 10,
  "resultados": [
    {
      "id":  999,
      "oid":  "XYZ",
      "oeid":  "ZYX",
      "mes": 1,
      "ano": 2025,
      "contracheques": 100,
      "segurados": 90, // 10 segurados estão em 2 páginas distintatas, logo: 2 contracheques
      "status": "A",
      "uupdif": "5403600818138761067",
      "data_hora": "2025-01-01 00:00:01"
    }
  ]
}

Status:

200 | 403 | 404

2. Listar as informações de um arquivo específico processado para um Órgão/Entidade

GET /v2/contracheque/{id}/

Após aplicar as verificações de propriedade, listar os dados do registro com a {id} informada no seguinte formato.

Resposta:

{
  "id": 999,
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025,
  "status": "A",
  "arquivo_url": "https://storage3.onyxerp.com.br/fopag/{arquivo_hash}",
  "raw_data": {}, // Dados da extração executada mapeando os CPF para as páginas do PDF
  "uupdif": "5403600818138761067",
  "data_hora": "2025-01-01 00:00:01"
}

Status:

200 | 403 | 404

3. Pre-processar um arquivo e exibir as estatísticas para visualização

POST /v2/contracheque/

Este endpoint irá receber o arquivo PDF binário contendo os contracheques a serem importados e deverá retornar as informações de estatísticas acerca do arquivo para validação por parte do usuário. O processo se dará da seguinte forma:

• Verificar se o hash do arquivo existe na tabela contracheque_arquivo, se sim retornar o segundo JSON com status code 409
• Aplicação do script para extração dos conjuntos de CPF e o número de suas respectivas páginas.
• Localizar no banco da Social o pf_id pra cada CPF extraído, os que não forem localizados devem ir para a lista nao_encontrados(número da página).
• Os registros de CPF que puderem ser encontrados na base de dados do OnyxERP® devem ser incluídos na lista encontrados, conforme o exemplo abaixo.
• Esses dados devem ser salvos na coluna raw_data data tabela contracheque_registro, juntamente com as informações de competência e Órgão/Entidade. Request:

{
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025
}

Multi-part form: (file)

Resposta:

{
  "id": 999,
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025,
  "uupdif": "5403600818138761067",
  "data_hora": "2025-01-01 00:00:01",
  "status": "A", // Aguardando validação
  "arquivo_url": "https://storage3.onyxerp.com.br/fopag/{arquivo_hash}",
  "raw_data": {// Dados da extração executada mapeando os CPFs para as páginas do PDF
    "encontrados": [
      {
        "pf_id": "6435183219272900584",
        "pagina": 10 // Página onde o contracheque deste segurado foi encontrado
      }
    ],
    "nao_encontrados": [
      // Páginas onde nenhum CPF pôde ser extraído ou com CPF que não foram encontrados na base do OnyxERP®
      15, 10
    ]
  }
}

Status:

200 | 403 | 404

Error 409 - Arquivo já processado:

{
  "id": 999,
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025,
  "status": "V",
  "uupdif": "5403600818138761067",
  "data_hora": "2025-01-01 00:00:01"
}

4. Atualizar o status de um arquivo processado

PATCH /v2/contracheque/{id}/

Este endpoint atualizar as informações de um processamento de arquivo já realizado. Se o status for alterado de "A"(Aguardando) paraV(Validado), os registros dos segurados encontrados devem ser criados na tabela contracheque_registro e os arquivos de cada segurado deverá ser extraído para um PDF individual de acordo com o mapeamento realizado no endpoint POST.

Request:

{
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025,
  "status": "A|V|R",  // Aguardando | Validado | Rejeitado
}

Status:

200 | 403 | 404

Em caso de conflito com oid/oeid/mes/ano, retornar o seguinte JSON com status 409

{
  "id": 999,
  "oid": "XYZ",
  "oeid": "ZYX",
  "mes": 1,
  "ano": 2025,
  "status": "V",
  "uupdif": "5403600818138761067",
  "data_hora": "2025-01-01 00:00:01"
}

Status:

409

5. Listar os contracheques disponíveis para um segurado específico por exercício

GET /external/v2/contracheque/{ano}/

Endpoint acessível a usuários do nível Segurado, devendo-se utilizar o pf_id do token para busca dos dados. Buscar no banco todos os registros de contracheque_registro para o pi_id selecionado e listar conforme o JSON abaixo ou 404(sem body) caso nenhum registro seja encontrado. Se o arquivo não existir mais no storage, ele deverá ser gerado novamente a partir do arquivo original em contracheque_arquivo e o número da página em contracheque_registro.

Resposta:

{
  "resultados": [
    {
      "id": 999,
      "contracheque_arquivo_id": 999,
      "mes": 1,
      "ano": 2025,
      "arquivo_url": "https://storage3.onyxerp.com.br/fopag/{arquivo_hash}"
    }
  ]
}

Status:

200 | 403 | 404

UI

As seguintes telas serão criadas para disponibilizar este recurso ao usuário.

Listagem /Governanca/ContrachequesDigitalPrev/

Nesta tela serão exibidos todos os registros de arquivos já processados para o Órgão selecionado em uma tabela, ordenados de forma decrescente por ano e mês, com 13 registros por página.

Os seguintes filtros serão usados:

• Órgão. Default: BRA
• Ano. Default: {ano_atual}

A tabela com os registros sera composta pelas seguintes colunas:

#	Entidade	Competência	Registros	Segurados	Status
999	IPREV	02/2025	100	90	Em análise
998	IPREV	01/2025	100	90	Validado

Ao clicar na ID, o usuário será redirecionado para /Governanca/ContrachequesDigitalPrev/{id}/ para visualizar os detalhes do processamento de um arquivo específico.

Criação: /Governanca/ContrachequesDigitalPrev/novo/

Nesta tela o usuário poderá enviar um novo arquivo para processamento e ela terá os seguintes componentes:

• Órgão
• Entidade
• Competência - Mês/Ano em um único campo
• drag-and-drop zone para seleção ou lançamento do arquivo PDF para processamento.

Em caso de erro 409(conflito) um modal será usado para exibir as informações do processamento ao qual o arquivo enviado já está vinculado com um link, caso o usuário queira inspecioná-lo.

Visualização: /Governanca/ContrachequesDigitalPrev/{id}/

Nesta tela o usuário poderá ver todos os registros de segurados extraídos do arquivo e localizados na base de dados do OnyxERP®.

Os registros serão exibidos em uma tabela com a seguinte estrutura:

#	Nome	CPF	Página	Arquivo
1	Segurado Sobrenome	000.000.000-00	10	Visualizar
2	Nome Segurado	000.000.000-00	20	Visualizar
3	CPF não encontrado*	000.000.000-00	30	Visualizar

(*) Pagina em que não foi possível extrair o CPF com precisão ou que CPF que não existe na base de dados do OnyxERP®.

Ao clicar em "Visualizar", uma pop-up será exibida renderizando somente a página selecionada no PDF original.

Ainda nesta tela o usuário poderá alterar as seguintes informações do processamento selecionado:

• Órgão
• Entidade
• Mes
• Ano
• Status

Caso ao salvar o endpoint retorne status 409, um modal será exibido ao usuário com as informações do processamento com o qual este está conflitando com um link para o usuário acessá-lo caso queira conferir.

DigitalPrev®

Seguir o modelo da tela "Contribuições" já existente no aplicativo, onde o usuário seleciona um Exercício e nas opções para as quais existirem registros um novo seletor deverá ser exibido com as opções de meses com registros disponíveis para download, ao selecionar uma visualização do arquivo será exibida no próprio aplicativo e com a opção uma de download.