Skip to content

@fc/rmi-api ​

API REST de cálculo de RMI (Renda Mensal Inicial) para benefícios do RGPS. Expõe OpenAPI em /_openapi.json e deixa /_swagger disponível apenas em desenvolvimento local.

Esta aplicação é um deployment separado por razões operacionais (cálculo de RMI é intensivo em CPU/memória). Do ponto de vista do contrato público, todos os endpoints vivem sob o namespace /rgps/api/v1/* e compartilham o módulo rgps com a prev-api.

Todas as respostas JSON seguem o envelope PDPJ-Br:

json
{
  "status": "ok",
  "code": "200",
  "messages": [],
  "result": {
    /* ... */
  }
}

Geração do spec ​

Para regenerar o spec OpenAPI localmente:

bash
pnpm --filter @fc/rmi-api spec:gen

O comando usa as anotações @swagger dos arquivos em server/routes/** e os tipos declarados em nuxt.config.ts.

O contrato público canônico é /_openapi.json; principal.json é a fonte gerada no build. Ao servir o documento, o runtime acrescenta a origem atual, a proteção por chave de API e os schemas do envelope de erro, exclui rotas internas e impede cache compartilhado com Cache-Control: no-store. O antigo public/openapi-spec.json não é consumido pela aplicação e está excluído do contexto Docker.

Chave de API estrutural ​

A proteção por x-api-key é declarativa por path, sem anotação nos handlers, e fica ligada por padrão. O nuxt.config.ts fixa o glob /rgps/api/v1/calculos-rmi/**; assim, a rota-base e todas as suas subrotas exigem a chave sem depender de variáveis de ambiente de deploy.

Os GETs de dados de referência /rgps/api/v1/fundamentos e /rgps/api/v1/marcos-temporais não pertencem a esse glob e permanecem públicos.

A chave é validada pela plataforma contra o cadastro central, com cache curto. Em desenvolvimento local, o assistente pode desligar essa proteção para facilitar testes; fora de dev e test, esse override interrompe o boot e o caminho protegido continua fazendo parte da configuração estrutural da app.

Fail-fast no boot: se o glob não casar com nenhuma rota registrada, a subida da app falha com mensagem clara.

Ver @fc/base-api/README.md para a mecânica completa.

Telemetria de uso ​

A rmi-api registra telemetria best effort no fim da resposta HTTP. O envio não participa do fluxo principal; falhas no backoffice entram apenas no log operacional. Quando a rota estiver protegida por chave de API, o evento reaproveita event.context.apiKeyValidada e preserva o idTokenApiKey sem revalidar a chave.

Eventos emitidos:

AçãoEndpoints
rgps.rmi.apicálculo RMI JSON principal
rgps.rmi.api.streamcálculo RMI via SSE
rgps.rmi.api.asynccriação de job assíncrono JSON e conclusão/erro do job
rgps.rmi.api.arquivo-calccálculo RMI a partir de .calc
rgps.rmi.api.arquivo-calc.streamcálculo RMI via SSE a partir de .calc
rgps.rmi.api.arquivo-calc.asynccriação e conclusão/erro de job assíncrono a partir de .calc
rgps.rmi.api.desvinculadacálculo desvinculado JSON ou .calc
rgps.rmi.api.por-fundamentocálculo por fundamento
rgps.rmi.api.job-statusconsulta do estado de um job
rgps.rmi.api.job-resultadoobtenção do resultado de um job
rgps.rmi.api.job-cancelarcancelamento de um job
rgps.rmi.api.fundamentoslistagem de fundamentos disponíveis
rgps.rmi.api.marcos-temporaislistagem de marcos temporais disponíveis
rgps.documentos.api.arquivo-calcleitura isolada de .calc, vinculada ou desvinculada

O dicionário de @fc/comum é a fonte canônica dos nomes. Um teste de contrato compara o mapa com as rotas físicas nas duas direções, valida cada ação para a origem rmi-api e impede que uma rota nova fique silenciosa. Eventos de conclusão de job carregam apenas fase e endpoint; payload, conteúdo e nome do documento não entram na telemetria. Nos logs operacionais, os prefixos rmi.job.* e arquivo-calc.rmi.job.* distinguem a origem sem depender do nome do arquivo.

Benchmark de latência ​

Há um benchmark reproduzível para comparar os endpoints JSON e SSE equivalentes:

bash
pnpm --filter @fc/rmi-api bench:latency -- --cenario implementacao-postergados --runs 8 --warmup 2

Parâmetros úteis:

  • --listar-cenarios: lista os cenários disponíveis
  • --base-url http://127.0.0.1:8003: aponta para uma instância já em execução
  • --execucao fundamento --fundamento EC_103_ART_20: executa o cálculo por-fundamento para o fundamento informado
  • --marco-temporal NA_DIB: fixa o cálculo em um único marco temporal (valor fora do catálogo de GET /marcos-temporais é rejeitado)
  • --output ./tmp/benchmark-rmi.json: salva o relatório em JSON

Métricas coletadas:

  • TTFB: tempo até os headers da resposta
  • TTLB: tempo até o fim da resposta JSON
  • TTFE: tempo até o primeiro evento útil do SSE
  • Primeiro parcial: tempo até o primeiro fundamento_calculado ou bloco_finalizado
  • TTLE: tempo até o evento final fim

O benchmark usa as amostras de test/amostras/*.json e as converte para CalculoRmiApi com lerArquivoTc, mantendo o payload o mais próximo possível dos casos reais do projeto.

Dependência externa ​

A rmi-api consome a API pública de índices (endpoints /indices/api/v1/*) para obter a tabela de indexadores e a série de piso e teto do RGPS utilizadas nos cálculos. O endereço efetivo é fornecido pela implantação.

Se a API de índices estiver indisponível, os endpoints de cálculo retornam 503 com o seguinte corpo:

json
{
  "error": true,
  "statusCode": 503,
  "statusMessage": "API de índices indisponível",
  "message": "API de índices indisponível"
}

A retenção e a capacidade dos jobs assíncronos são limites operacionais configurados pela implantação. Ao atingir o teto de registros, a API descarta primeiro o resultado terminal mais antigo; jobs ativos não são expulsos. Os cálculos são executados fora do fluxo HTTP principal, mantendo o health check responsivo durante operações longas.

Endpoints ​

Todos os caminhos são servidos sob o namespace /rgps/api/v1/*.

Cálculo principal (JSON) ​

MétodoCaminhoDescrição
POST/rgps/api/v1/calculos-rmiCalcula a RMI para todos os benefícios aplicáveis
POST/rgps/api/v1/calculos-rmi/asyncCria job assíncrono de cálculo de RMI (retorna 202 + jobId)
POST/rgps/api/v1/calculos-rmi/streamCalcula a RMI com streaming SSE por bloco e fundamento
POST/rgps/api/v1/calculos-rmi/por-fundamentoCalcula a RMI apenas para o fundamento informado
POST/rgps/api/v1/calculos-rmi/desvinculadaCalcula RMI desvinculada com parâmetros fornecidos pelo usuário

Fonte externa: arquivo .calc ​

MétodoCaminhoDescrição
POST/rgps/api/v1/calculos-rmi/arquivo-calc/lerLê arquivo .calc de RMI canônica (períodos) e devolve o JSON pronto para o cálculo canônico; arquivo de RMI desvinculada responde 422 orientando ler-desvinculada
POST/rgps/api/v1/calculos-rmi/arquivo-calc/ler-desvinculadaLê arquivo .calc de RMI desvinculada (coeficiente e, se houver, tempo informados) e devolve o JSON pronto para o cálculo desvinculado; arquivo de RMI canônica responde 422 orientando ler
POST/rgps/api/v1/calculos-rmi/arquivo-calc/calcularLeitura + cálculo em uma única chamada
POST/rgps/api/v1/calculos-rmi/arquivo-calc/calcular/asyncLeitura + cálculo em job assíncrono (retorna 202 + jobId)
POST/rgps/api/v1/calculos-rmi/arquivo-calc/calcular/streamLeitura + cálculo com streaming SSE
POST/rgps/api/v1/calculos-rmi/arquivo-calc/calcular-desvinculadaLeitura + cálculo desvinculado em uma única chamada

Como escolher o leitor. O arquivo .calc de RGPS Benefícios guarda um de dois tipos de RMI: a canônica, derivada dos períodos e das regras de tempo, e a desvinculada (salário-pura), em que o usuário informou o coeficiente e, opcionalmente, o tempo, que só entra no fator previdenciário (sem ele, onde há fator, a rota recusa com 400). arquivo-calc/ler → POST /rgps/api/v1/calculos-rmi; arquivo-calc/ler-desvinculada → POST /rgps/api/v1/calculos-rmi/desvinculada. Cada leitor recusa (422) o arquivo do outro tipo, em vez de devolver um payload que recalcularia a RMI como zero; arquivo-calc/calcular despacha sozinho e não exige essa escolha.

Ler e calcular dá o mesmo que calcular o arquivo. O JSON de arquivo-calc/ler, reenviado a POST /rgps/api/v1/calculos-rmi, reproduz o resultado de arquivo-calc/calcular: leva os benefícios recebidos computados como salário (beneficios), o fato gerador, a opção do IRSM de fev/94, a do cálculo dos benefícios da pessoa com deficiência pela Lei nº 9.876/99, os salários desconsiderados (excluido: true no salário) e o Modo Descarte Manual, quando ligado. A DER reafirmada é uma comodidade da interface Web, que mostra as duas datas no mesmo cálculo, e não é campo da API: para calcular na DER e na reafirmação, faça duas chamadas, uma com cada data em der e dataApuracao. O arquivo que traz a reafirmação é lido como a chamada da reafirmação, com der igual a dataApuracao, nos dois leitores (ler e ler-desvinculada). Os salários também preservam a lista opcional indicadores, inclusive nos vínculos e no ano civil, para reproduzir a memória do PBC. A lista deve conter strings; não altera o valor da contribuição.

O mesmo vale para arquivo-calc/ler-desvinculada → POST /rgps/api/v1/calculos-rmi/desvinculada: o campo opcional beneficios preserva os benefícios recebidos que podem ocupar competências sem salário da atividade principal. A precedência entre salário e benefício é resolvida pelo motor; não é necessário convertê-los em salários independentes antes de reenviar o JSON. Nos cálculos anteriores à CF/88, o leitor também preserva o critério de correção dos salários, os grupos de contribuições acima do menor valor-teto (inclusive zero) e o salário mínimo do local de trabalho, quando informados no arquivo. O JSON lido pode ser reenviado sem repor esses parâmetros.

Jobs (operações assíncronas) ​

MétodoCaminhoDescrição
GET/rgps/api/v1/calculos-rmi/jobs/{jobId}Consulta status, progresso e resultado eventual de job assíncrono
GET/rgps/api/v1/calculos-rmi/jobs/{jobId}/resultadoObtém apenas o resultado final de job assíncrono concluído
DELETE/rgps/api/v1/calculos-rmi/jobs/{jobId}Cancela job pendente ou em processamento da mesma chave

Metadados ​

MétodoCaminhoDescrição
GET/rgps/api/v1/fundamentosLista os fundamentos aceitos nos endpoints filtrados
GET/rgps/api/v1/marcos-temporaisLista os marcos temporais aceitos em marcoTemporal

Os endpoints de upload de arquivo aceitam multipart/form-data com o arquivo no campo file. Os demais aceitam application/json, com exceção dos endpoints SSE, que recebem JSON (ou multipart/form-data para os que têm .calc) e respondem com text/event-stream.

A query opcional numeroMaximoIteracoes limita a quantidade de iterações de descarte nos cálculos canônicos JSON e .calc, inclusive nos modos stream e async, e no cálculo por fundamento. Quando omitida, a API usa 120 como padrão para evitar payloads excessivamente grandes em casos com muitos salários descartáveis.

As rotas síncronas que efetivamente calculam aceitam também permalink=true (ou 1). Quando solicitada, a API persiste um snapshot imutável e reabrível no prev-tc e acrescenta permalink — uma URL pública completa — no topo do envelope, sem alterar result. Omitir a query, ou usar false/0, preserva integralmente o contrato anterior. Os modos async e stream não oferecem esse campo. O snapshot segue a retenção longa da plataforma, atualmente dez anos; o opt-in não amplia os limites de entrada de 10 MiB para JSON e 5 MiB para .calc. Valor diferente dos quatro aceitos responde 400, indisponibilidade da capacidade responde 503 e uma resposta interna sem URL válida responde 502.

As mesmas cinco rotas síncronas aceitam também a query opcional demonstrativo=true (ou 1): o envelope ganha demonstrativoPdf — o demonstrativo do cálculo em PDF, na identidade visual da calculadora, com conteúdo em base64, nome de arquivo sugerido, quantidade de páginas e tamanho em bytes (schema DemonstrativoPdfApi no OpenAPI). As rotas de RMI canônica, por fundamento e .calc devolvem ainda demonstrativoDescartesPdf, o demonstrativo dos cálculos a cada descarte, quando alguma hipótese descartou competências; a RMI desvinculada rende um PDF só. O PDF sempre embute um permalink do cálculo no card de reprodução — por isso a geração cria um snapshot como o do permalink=true, e as duas queries podem ser combinadas sem criação duplicada; a query permalink decide apenas se a URL também sai como campo separado. Cálculo interrompido pelo limite de iterações não vira PDF: com a query, a rota responde 422. Os mesmos códigos valem para a capacidade de permalink (503/502), e falha na geração do PDF responde 500.

Para cálculos longos com upload .calc, prefira:

  • POST /rgps/api/v1/calculos-rmi/arquivo-calc/calcular/stream quando o cliente puder manter a conexão aberta e quiser progresso em tempo real.
  • POST /rgps/api/v1/calculos-rmi/arquivo-calc/calcular/async quando o cliente precisar apenas receber um jobId e consultar o resultado depois via polling.

Limitação conhecida da trilha assíncrona: os jobs ficam no storage local do processo da rmi-api. Em ambientes com múltiplas instâncias, é necessário afinidade de sessão, ou futuramente migrar essa trilha para storage/fila distribuídos.

Cada job pertence à identidade estável (idToken) da chave de API que o criou. Consulta, resultado e cancelamento exigem a mesma identidade; outra chave recebe o mesmo 404 de um identificador inexistente, sem confirmar a existência do job. A resposta pública expõe somente estado, datas, progresso, erro e resultado eventual — o payload interno de criação não faz parte do contrato público.

As rotas async aceitam o header opcional Idempotency-Key (até 128 caracteres). Repetir a mesma requisição com a mesma chave devolve o jobId original; reutilizá-la com conteúdo diferente responde 409. Quando a capacidade estiver inteiramente ocupada por jobs ativos, a fila de cálculos ou a cota de jobs ativos da chave estiver cheia, a API responde 429; nos limites de jobs, Retry-After: 5 orienta uma nova tentativa curta.

Fechar uma conexão SSE cancela o cálculo correspondente. DELETE /jobs/{jobId} faz o mesmo para jobs pendentes ou em processamento; repetir o cancelamento é seguro, enquanto jobs já concluídos ou encerrados com erro respondem 409.

Semântica HTTP dos jobs ​

RotaSituaçãoHTTPstatus
POST /calculos-rmi/asyncjob criado202in-progress
POST /calculos-rmi/arquivo-calc/.../asyncjob criado202in-progress
GET /jobs/{jobId}pendente / processando200in-progress
GET /jobs/{jobId}concluído200ok
GET /jobs/{jobId}cancelado200ok
GET /jobs/{jobId}inexistente ou de outra chave404error
GET /jobs/{jobId}/resultadoconcluído200ok
GET /jobs/{jobId}/resultadopendente / processando / falhou / cancelado409error
GET /jobs/{jobId}/resultadoinexistente ou de outra chave404error
DELETE /jobs/{jobId}pendente / processando / já cancelado200ok
DELETE /jobs/{jobId}concluído / falhou409error

Resultado de job assíncrono só é entregue em /resultado quando o job está concluído; nos demais estados a resposta é 409 Conflict com mensagem descritiva (alinhada ao Swagger). Para polling genérico — que precisa distinguir "ainda processando" de "já terminou" — use GET /jobs/{jobId} e observe status.

Descarte manual ​

Por padrão, o cálculo canônico descarta sozinho os menores salários da média (EC 103/2019, art. 26, § 6º) enquanto o benefício mantém o direito. O campo opcional descarteManual troca a escolha automática pela de quem chama; a regra de descartes vale do mesmo modo. Vale em POST /calculos-rmi e nos modos async, stream e por-fundamento. Nas rotas .calc, vem do arquivo salvo com o Modo Descarte Manual ligado.

json
{ "descarteManual": { "competencias": ["2016-03", "2015-02"] } }
  • As competências (aaaa-mm) são descartadas na ordem da lista. Cada benefício para no descarte em que perderia o direito, e os demais seguem. Não há erro por isso.
  • Lista vazia: nenhum descarte. Campo ausente: descarte automático.
  • Os marcos sem descarte (direito adquirido, Lei 9.876, regra de pontos) seguem sem descarte. Competência que o PBC de um marco não tem é ignorada nele.
  • A escolha do resultado de cada benefício (a linha de maior RMI) e o corte dos descartes esgotados são os mesmos do automático.

Com o campo presente, cada bloco em que há descarte traz descarteManual (schema ResumoDescarteManualApi):

  • aplicadas, na ordem de aplicação — sempre as das linhas devolvidas, também quando o limite de iterações corta o cálculo;
  • foraDoPbc: as competências que o PBC do marco não tem (ex.: posteriores ao marco de uma regra progressiva);
  • semSalarioComputavel: as que estão no PBC do marco sem salário computável;
  • naoAplicadas: as que ficaram sem aplicar porque o cálculo parou antes, inclusive pelo limite de iterações;
  • interrupcoes: por benefício, a competência cujo descarte o faria perder o direito e os requisitos que deixariam de ser cumpridos (só das linhas devolvidas, ou da competência que encerrou o cálculo);
  • aviso: por que o marco inteiro ficou sem descarte — DIB anterior à EC 103, benefício não programado, PCD pela regra anterior, ou arquivo .calc com o Modo RMI Desvinculada também ligado, quando prevalece a RMI desvinculada.

As linhas de descarte ganham salarioOriginalDescartado: o total da competência antes da correção (salário mais benefícios computados, com piso e teto), o mesmo valor que salarioDescartado traz corrigido. Competência fora do formato aaaa-mm responde 400.

Sinalização de conclusão e truncamento ​

Cada bloco calculado inclui conclusao.completo. Se o limite interromper o descarte antes do fim, o bloco informa:

json
{
  "conclusao": {
    "completo": false,
    "motivoInterrupcao": "LIMITE_ITERACOES",
    "limitesAtingidos": { "numeroMaximoIteracoes": 120 }
  }
}

O evento final fim do SSE e o status do job assíncrono expõem a mesma conclusao, agregada para todos os blocos. Um resultado completo contém apenas { "completo": true }.

Por compatibilidade, respostas HTTP síncronas truncadas também incluem:

x-fc-rmi-iteracoes-limitadas: true
x-fc-rmi-max-iteracoes: <valor aplicado>

O log de auditoria registra iteracoesLimitadas: true no evento rmi.calculado. Clientes devem preferir o campo do corpo, que também sobrevive a fachadas como o MCP, para decidir se reexecutam com um limite maior ou apresentam ressalva ao usuário.

Validação de entrada e contrato de erro ​

Rotas JSON e multipart validam o payload com schemas Zod (apps/rmi-api/server/utils/esquemas.ts) e uploads com validarUploadUnico. Em falha, a resposta é:

  • JSON malformado, Zod inválido, ErroDominio, exceção conhecida do core → 400 + envelope PDPJ com messages descritivas (caminho: mensagem para Zod);
  • dado de entrada recusado pelo motor durante o cálculo → 400 com a mensagem do motor e errorCode: ENTRADA_CALCULO_RECUSADA;
  • tabelas da plataforma sem cobertura para a data pedida (índice, piso ou teto) → 503, transitório, com a mensagem e errorCode: DADOS_INDISPONIVEIS;
  • nos modos async e stream, o cálculo já foi aceito quando o motor falha, então o desfecho não vira status HTTP: sai em erro.codigo e erro.mensagem do job (GET /jobs/{jobId}) e em payload.codigo e payload.mensagem do evento erro do SSE, com os mesmos ENTRADA_CALCULO_RECUSADA (corrija o payload) e DADOS_INDISPONIVEIS (transitório) e a mensagem do motor; CAPACIDADE_TEMPORARIAMENTE_ATINGIDA (fila cheia, repita mais tarde) e FALHA_CALCULO_RMI (falha interna) saem com mensagem genérica. Jobs gravados antes do campo codigo trazem só a mensagem;
  • upload acima do teto de 5 MiB → 413;
  • arquivo .calc legível, mas incompatível com o endpoint → 422;
  • exceção não classificada → 500 + envelope genérico (erro registrado via logOperacional.error);
  • sempre via tratarErroRota(event, erro) de @base-api/server/utils/erros — nunca createError cru.

Os uploads multipart aceitam tanto content-length quanto transfer-encoding: chunked, sem alterar o teto nem a resposta 413.

Espécie do benefício. opcoesContagem.especie é obrigatória em todas as entradas JSON (canônica, por fundamento, desvinculada e PrevJud): sem ela a resposta é 400 com a mensagem que diz onde informá-la e os códigos aceitos — a API não presume espécie alguma. Aceita todas as espécies do dicionário (aposentadorias 41, 42, 46 e 57; incapacidade 31, 32, 91 e 92; auxílio-acidente 36, 94 e 95; pensões 21 e 93; auxílio-reclusão 25; salário-maternidade 80; amparos 87 e 88), e cada uma segue as próprias regras de RMI. Na RMI desvinculada isso vale igual: com especie: 94, o auxílio-acidente sai com coeficiente de 50%, piso proporcional e sem fator previdenciário; os benefícios não programados aceitam fatoGerador (DII, óbito) quando ele difere da DER. Num arquivo .calc, o campo é parametrosGerais.especie, e o arquivo sem ele também responde 400.

Auxílio-acidente acidentário e auxílio suplementar. A espécie 94 segue as mesmas regras da 36, com o fundamento Lei 8.213, art. 86 c/c arts. 19 e ss.; a 95 tem coeficiente fixo de 20%, pela Lei 6.367/1976, art. 9º, para acidente de 01/01/1977 a 24/07/1991, quando a Lei 8.213/91 a absorveu no auxílio-acidente.

Vigência das regras. Uma regra de concessão só se aplica se estiver em vigor na data de referência: o fato gerador, nos benefícios não programados, e a data de apuração, nos programados. Fora dela, a regra não se aplica, o que não quer dizer que o segurado não tenha direito. No cálculo de RMI de um benefício não programado sem nenhuma regra em vigor no fato gerador, a resposta é 400 com a mensagem "Não se aplica: …".

Regime anterior à CF/88. Com a RMI desvinculada e DIB de 11/06/1973 a 05/10/1988 (espécies 31, 32, 41, 42, 46 e 57), todas as rotas calculam pelas regras da época (Lei 5.890/73, Lei 6.210/75, Decreto 83.080/79): PBC de 36 salários (48 até 06/1975; 12 na incapacidade) na moeda da DIB, salário de benefício entre o salário mínimo e o maior valor-teto, e a fórmula do menor valor-teto. A resposta traz dadosRmi.anteriorCf88 com o detalhe: sistemática e base legal, critério de correção dos salários, moeda, o PBC linha a linha (salário na moeda da competência, teto de contribuição, conversão, índice e corrigido), MVT, mVT, parcelas básica e adicional, RMI e equivalência em salários mínimos; pbc, soma, divisor, media e rmi de dadosRmi repetem os valores dele, e não há evolução nem descartes. Na entrada JSON de /rgps/api/v1/calculos-rmi/desvinculada, três campos opcionais valem só nesse regime: criterioCorrecaoSalariosAnteriorCf88 (COEFICIENTES_INSS, padrão, para reconstituir a concessão; ORTN_OTN para a RMI revista), gruposContribuicoesAcimaMenorValorTeto (inteiro, exigido quando o salário de benefício passa do mVT) e salarioMinimoLocalTrabalho (DIB anterior a 05/1984). O que o motor não aceita (DIB anterior a 11/06/1973, espécie fora do escopo, PBC sem salários, SB acima do mVT sem os grupos) é recusado com 400 e errorCode: ENTRADA_CALCULO_RECUSADA. O PDF da rota com demonstrativo traz as seções desse regime.

Direito adquirido na RMI desvinculada. A rota /rgps/api/v1/calculos-rmi/desvinculada aceita o campo opcional marcoDireitoAdquirido: VESPERA_EC_20 (15/12/1998) ou VESPERA_LEI_9876 (27/11/1999). Com ele, o PBC e o divisor são os das regras vigentes nessa data (o PBC termina no mês anterior a ela), sem fator previdenciário, e a correção dos salários, o piso, o teto e a RMI são os da DIB, sem evolução. A resposta traz dadosRmi.dataDireitoAdquirido (aaaa-mm-dd). O marco é ignorado quando a DIB não é posterior à data ou a espécie não tem regra própria de direito adquirido (benefícios não programados); nesse caso a resposta traz dadosRmi.avisoDireitoAdquirido. Valor fora do dicionário responde 400. O permalink e a leitura de .calc preservam o marco.

Atividades concomitantes na RMI desvinculada. A mesma rota aceita o campo opcional atividadesConcomitantes, para aplicar o art. 32, II e III, da Lei 8.213/91 na redação anterior à Lei 13.846/2019. Os salarios do corpo são os da atividade principal; cada item de atividadesConcomitantes.secundarias traz os salarios da atividade secundária, a fração que multiplica a média dela — numerador (de zero até o denominador) e denominador (maior que zero), como a carta de concessão do INSS os imprime no bloco da secundária, "(002 / 030)" — e o fator previdenciário dela, com quatro casas, obrigatório quando o benefício tem fator a aplicar. Só contam os salários da secundária nas competências em que a principal tem salário; os demais ficam fora, com aviso. Cada atividade tem média própria, com o período básico de cálculo e o divisor da DIB, inclusive o mínimo (com marcoDireitoAdquirido, os da data do marco); a principal usa o fator do tempo total. O salário-de-benefício é a soma do de cada atividade — média × fator na principal, média × fator × fração na secundária, truncados em centavos —, com piso e teto sobre a soma. A resposta traz dadosRmi.atividadesConcomitantes (a principal primeiro: soma, divisor, media, fator, parcela e o pbc de cada uma, e das secundárias o numero na lista de entrada e a fracao; soma, divisor, media e pbc do topo são os da principal) e dadosRmi.competenciasSomaAcimaDoTeto, as competências em que a soma das atividades passou do teto, sinal do § 2º do artigo, que o cálculo aponta mas não decide. Secundária sem o fator, com fator a aplicar, ou sem salário concomitante fica fora do cálculo, com o motivo em dadosRmi.avisosAtividadesConcomitantes. Com DIB em 18/06/2019 ou depois, os salários das secundárias somam-se aos da principal, com o mesmo aviso. Fração fora do intervalo, fator não positivo ou secundária sem salários respondem 400. O permalink e a leitura de .calc (arquivo-calc/ler-desvinculada) preservam as secundárias (a leitura, só com a parte opcional "Atividades concomitantes" ligada no arquivo); na leitura, os salarios são os da aba Salários somados aos dos vínculos, competência a competência.

null no arquivo .calc. A leitura trata null como campo ausente no conteúdo do cálculo: a propriedade é descartada antes da migração e da validação. Dentro de uma sequência ordenada o elemento nulo permanece, porque removê-lo deslocaria os demais. O envelope fica de fora, porque ali nulo é dado — em online.idPasta ele significa a pasta raiz. Não é preciso adaptar geradores que escrevem null no lugar do campo omitido — é o que se espera deles. Um registro de coleção escrito como null deixa de existir, em vez de abrir a calculadora como registro em branco. Já o registro cujo conteúdo não é null nem um objeto de campos — um texto ou um número onde se espera o conjunto de campos — é recusado com 422 e a identificação do registro em messages, porque ali há um dado que a Fábrica não sabe interpretar e não pode adivinhar. A recusa vale para o formato corrente: num arquivo de versão antiga, a conversão pode moldar esse conteúdo antes da conferência, e então ele segue como seguia.

O campo opcional criterioSalarioMaternidade aceita UM_DOZE_AVOS ou MEDIA_SIMPLES_DOZE_ULTIMOS e mantém a escolha presente em um Arquivo .calc. A origem dos períodos usa valores nominais (CALCULO_INSS, CNIS, USUARIO, NENHUMA, PREVJUD ou MULTIPLA); valores divergentes retornam 400. Só CNIS, PREVJUD e CALCULO_INSS têm coluna própria no salário; USUARIO, MULTIPLA e a origem omitida entram como valor digitado pelo usuário, e o resultado os rotula como USUARIO — o número não muda. Cada salário aceita excluido (booleano, padrão false): o salário desconsiderado segue no corpo, com a competência e a data de recolhimento, mas o valor não entra no cálculo. dadosSegurado.tipo é obrigatório: informe COMUM, PCD ou RURICOLA. A omissão é recusada, sem presumir um tipo. O campo opcional salariosAnoCivil traz os valores consolidados por competência do quadro do ano civil (CNIS ou PrevJud), que prevalecem sobre os salários dos períodos na mesma competência. Cada um pode trazer valorLc123, a parcela recolhida pela LC 123/2006: o benefício que não computa a LC 123 é calculado sem ela. A leitura do .calc devolve o campo, e a leitura do CNIS (serviço de leitura documental) também. Nos resultados, cada benefício traz fundamento (a citação legal legível, EC 103, art. 20) e chaveFundamento (a chave, EC_103_ART_20) — a mesma aceita em POST /calculos-rmi/por-fundamento e listada em valor por GET /fundamentos, que devolve a citação em rotulo. As chaves de diferencas nos descartes usam a citação.

Convenções ​

Princípio central: um endpoint = um contrato (input único, output único).

  • Recurso (plural hifenizado): calculos-rmi.
  • Variantes de cálculo (sub-path): por-fundamento, desvinculada.
  • Fonte externa (sub-recurso aninhado): arquivo-calc/ler, arquivo-calc/calcular.
  • Modo de entrega (sub-path): async (202 + jobId), stream (SSE). Apenas calculos-rmi canônico e arquivo-calc/calcular canônico têm modos async/stream; as variantes são exclusivamente síncronas.

RMI fixada em um salário mínimo (Lei 11.718/2008, art. 3º) ​

Com opcoesContagem.aplicarArt3Lei11718 ligado (booleano, padrão false), a carência da aposentadoria por idade rural (Lei 8.213/91, art. 48, § 1º) conta em triplo somente os meses de empregado rural de 2011 a 2015 e em dobro os de 2016 a 2020, até 12 por ano civil. Quando essa contagem acrescenta meses, a RMI desse benefício é o salário mínimo da DIB, e dadosRmi.rmiFixadaSalarioMinimoLei11718 vem true; sem acréscimo o campo não aparece e a RMI segue a apuração normal.

Benefícios da pessoa com deficiência pela Lei nº 9.876/99 ​

Com calcularRmiPcdComRegraAnterior ligado (booleano na raiz do corpo de POST /calculos-rmi e dos modos async, stream e por-fundamento; padrão false), os benefícios da pessoa com deficiência (LC 142/2013) são calculados conforme a Lei nº 9.876/99 — média dos 80% maiores salários — também depois da EC 103. Nas rotas .calc, a opção vem do arquivo salvo, e arquivo-calc/ler a devolve no corpo.

Fundamentação do coeficiente e regras anteriores à Lei 9.032 ​

Em cada benefício, dadosApuracao.naApuracao.coeficiente traz valor, nota opcional e os campos opcionais fundamentacao (o dispositivo legal que fixa o coeficiente, como "EC 103, art. 15, § 4º, c/c art. 26, § 2º, I, e § 5º"; nos não programados, pelo fundamento do benefício e pela data do fato gerador), composicao (a conta do coeficiente composto da pensão e do auxílio-reclusão anteriores à Lei 9.032/95, como "95% da aposentadoria-base × 90% da pensão, 1 dependente"), naoSeAplica (o motivo, com a citação, quando não há coeficiente) e rmiSalarioMinimo (true quando a RMI é um salário mínimo sem coeficiente, no auxílio-reclusão a partir da EC 103). O antigo rótulo parametro deixa de integrar a resposta. fatorPrevidenciario.dispensadoPelosPontos vem true quando o fator não se aplica porque o segurado atingiu a regra dos pontos (Lei 8.213/91, art. 29-C).

Antes da Lei 9.032/95 (fato gerador anterior a 28/04/1995), dois campos opcionais de opcoesContagem entram no coeficiente, e são ignorados nas demais espécies e épocas: numeroDependentes (inteiro a partir de 1; no .calc, parametrosGerais.numeroDependentes), na pensão por morte previdenciária (21) e no auxílio-reclusão (25) — o coeficiente é o da aposentadoria-base, 80% mais 1% por grupo de 12 contribuições até 100%, multiplicado por 80% mais 10% por dependente, até dois (Lei 8.213/91, art. 75, "a", redação original); e coeficienteAuxilioAcidente (0.3, 0.4 ou 0.6; no .calc, parametrosGerais.coeficienteAuxilioAcidente), no auxílio-acidente (36 e 94), pelo grau da redução (art. 86, § 1º, redação original). Sem eles, o coeficiente sai 0 com a nota do que falta. Valor fora desses domínios é recusado com erro de validação.

Nos acidentários anteriores à Lei 9.032/95 (espécies 91, 92, 93, 94 e 36), a API apura duas RMIs na DIB e devolve a maior (Lei 8.213/91, arts. 44, "b", 61, "b", 75, "b", e 86, § 1º, redação original): uma com o coeficiente sobre o salário-de-benefício, outra sobre o salário de contribuição da competência do fato gerador, lido de salarios, limitado ao teto e corrigido até a DIB com os índices do PBC. dadosRmi.comparacaoAcidente traz competencia (aaaa-mm), salario, salarioCorrigido, rmiSalarioBeneficio, rmiSalarioAcidente e prevaleceSalarioAcidente; sem fatoGerador, ou sem salário na competência dele, vale a RMI sobre o salário-de-benefício e dadosRmi.avisoBaseCalculoAcidente diz o que faltou. Na pensão acidentária (93) o fato gerador é o óbito, e o salário comparado é o do mês do acidente: informe-o em dataAcidente (dd/mm/aaaa ou aaaa-mm-dd, não posterior ao óbito; no .calc, parametrosGerais.dataAcidente); sem ele, vale a RMI sobre o salário-de-benefício, com o aviso. Nas demais espécies o campo é ignorado. No auxílio-reclusão a partir da EC 103, rmi é o piso da DIB.

Implementação interna ​

Os fluxos de cálculo desta app usam a superfície central do core. O cálculo direto de .calc hidrata o estado completo; a projeção do leitor canônico tem a limitação temporária documentada acima:

  • entradas JSON usam criarDadosCalculoRgpsDeApiRmi(...) e criarDadosCalculoRgpsDeApiRmiDesvinculada(...)
  • cálculos de .calc usam criarDadosCalculoRgpsDeArquivoTcRmi(...)
  • saídas serializadas usam CalculoRmi.paraApiBloco(...) e CalculoRmiDesvinculada.paraApi(...)

Os módulos legados em @fc/calculos-rgps/utilidades-apis/* seguem exportados como compatibilidade transitória, mas novas integrações internas devem preferir essa superfície centralizada.

Logs ​

A aplicação emite logs estruturados em JSON via a classe Logger de @fc/utils. Todos os logs são escritos em stdout, prontos para ingestão por qualquer coletor (Loki, Elasticsearch, etc.).

Tipos de log ​

TagDescrição
rmi-apiLog operacional — registra toda requisição recebida
rmi-api, auditoriaLog de auditoria — registra cada operação de cálculo/leitura concluída

Os loggers vêm de @base/server/utils/loggers e usam como primeira tag o valor de nomeApp declarado em app/app.config.ts (aqui: rmi-api):

  • logOperacional — usado pelo middleware de log da layer @fc/base-api para registrar todas as requisições com a URL acessada.
  • logAuditoria — usado em cada endpoint para registrar a operação realizada.

Filtragem ​

Para isolar logs de auditoria em um coletor centralizado, filtre pela presença da tag auditoria:

json
{ "tags": ["rmi-api", "auditoria"], ... }

Recuperação explícita de arquivos de benefícios ​

Nos endpoints que recebem .calc de benefícios, recuperarArquivo=true autoriza substituir parâmetros inválidos com padrão conhecido. Sem essa opção, uma recuperação necessária responde 422 com as substituições propostas. Com ela, cada substituição aparece em messages e os resultados devem ser revisados antes do uso. Defeitos sem fallback continuam impedindo o processamento. O arquivo enviado não é sobrescrito.

Na RMI por SSE, os avisos aparecem em payload.avisosRecuperacao nos eventos inicio e fim. Na criação de job assíncrono, acompanham a resposta 202; o consumidor deve conservá-los junto do resultado consultado posteriormente.