@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:genO 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ção | Endpoints |
|---|---|
rgps.rmi.api | cálculo RMI JSON principal |
rgps.rmi.api.stream | cálculo RMI via SSE |
rgps.rmi.api.async | criação de job assíncrono JSON e conclusão/erro do job |
rgps.rmi.api.arquivo-calc | cálculo RMI a partir de .calc |
rgps.rmi.api.arquivo-calc.stream | cálculo RMI via SSE a partir de .calc |
rgps.rmi.api.arquivo-calc.async | criação e conclusão/erro de job assíncrono a partir de .calc |
rgps.rmi.api.desvinculada | cálculo desvinculado JSON ou .calc |
rgps.rmi.api.por-fundamento | cálculo por fundamento |
rgps.rmi.api.job-status | consulta do estado de um job |
rgps.rmi.api.job-resultado | obtenção do resultado de um job |
rgps.rmi.api.job-cancelar | cancelamento de um job |
rgps.rmi.api.fundamentos | listagem de fundamentos disponíveis |
rgps.rmi.api.marcos-temporais | listagem de marcos temporais disponíveis |
rgps.documentos.api.arquivo-calc | leitura 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 2Parâ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álculopor-fundamentopara o fundamento informado--marco-temporal NA_DIB: fixa o cálculo em um único marco temporal (valor fora do catálogo deGET /marcos-temporaisé rejeitado)--output ./tmp/benchmark-rmi.json: salva o relatório em JSON
Métricas coletadas:
TTFB: tempo até os headers da respostaTTLB: tempo até o fim da resposta JSONTTFE: tempo até o primeiro evento útil do SSEPrimeiro parcial: tempo até o primeirofundamento_calculadooubloco_finalizadoTTLE: tempo até o evento finalfim
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étodo | Caminho | Descrição |
|---|---|---|
POST | /rgps/api/v1/calculos-rmi | Calcula a RMI para todos os benefícios aplicáveis |
POST | /rgps/api/v1/calculos-rmi/async | Cria job assíncrono de cálculo de RMI (retorna 202 + jobId) |
POST | /rgps/api/v1/calculos-rmi/stream | Calcula a RMI com streaming SSE por bloco e fundamento |
POST | /rgps/api/v1/calculos-rmi/por-fundamento | Calcula a RMI apenas para o fundamento informado |
POST | /rgps/api/v1/calculos-rmi/desvinculada | Calcula RMI desvinculada com parâmetros fornecidos pelo usuário |
Fonte externa: arquivo .calc
| Método | Caminho | Descrição |
|---|---|---|
POST | /rgps/api/v1/calculos-rmi/arquivo-calc/ler | Lê 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-desvinculada | Lê 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/calcular | Leitura + cálculo em uma única chamada |
POST | /rgps/api/v1/calculos-rmi/arquivo-calc/calcular/async | Leitura + cálculo em job assíncrono (retorna 202 + jobId) |
POST | /rgps/api/v1/calculos-rmi/arquivo-calc/calcular/stream | Leitura + cálculo com streaming SSE |
POST | /rgps/api/v1/calculos-rmi/arquivo-calc/calcular-desvinculada | Leitura + 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étodo | Caminho | Descriçã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}/resultado | Obté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étodo | Caminho | Descrição |
|---|---|---|
GET | /rgps/api/v1/fundamentos | Lista os fundamentos aceitos nos endpoints filtrados |
GET | /rgps/api/v1/marcos-temporais | Lista 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/streamquando o cliente puder manter a conexão aberta e quiser progresso em tempo real.POST /rgps/api/v1/calculos-rmi/arquivo-calc/calcular/asyncquando o cliente precisar apenas receber umjobIde 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
| Rota | Situação | HTTP | status |
|---|---|---|---|
POST /calculos-rmi/async | job criado | 202 | in-progress |
POST /calculos-rmi/arquivo-calc/.../async | job criado | 202 | in-progress |
GET /jobs/{jobId} | pendente / processando | 200 | in-progress |
GET /jobs/{jobId} | concluído | 200 | ok |
GET /jobs/{jobId} | cancelado | 200 | ok |
GET /jobs/{jobId} | inexistente ou de outra chave | 404 | error |
GET /jobs/{jobId}/resultado | concluído | 200 | ok |
GET /jobs/{jobId}/resultado | pendente / processando / falhou / cancelado | 409 | error |
GET /jobs/{jobId}/resultado | inexistente ou de outra chave | 404 | error |
DELETE /jobs/{jobId} | pendente / processando / já cancelado | 200 | ok |
DELETE /jobs/{jobId} | concluído / falhou | 409 | error |
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.calccom 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 commessagesdescritivas (caminho: mensagempara 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
asyncestream, o cálculo já foi aceito quando o motor falha, então o desfecho não vira status HTTP: sai emerro.codigoeerro.mensagemdo job (GET /jobs/{jobId}) e empayload.codigoepayload.mensagemdo eventoerrodo SSE, com os mesmosENTRADA_CALCULO_RECUSADA(corrija o payload) eDADOS_INDISPONIVEIS(transitório) e a mensagem do motor;CAPACIDADE_TEMPORARIAMENTE_ATINGIDA(fila cheia, repita mais tarde) eFALHA_CALCULO_RMI(falha interna) saem com mensagem genérica. Jobs gravados antes do campocodigotrazem só a mensagem; - upload acima do teto de 5 MiB → 413;
- arquivo
.calclegí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— nuncacreateErrorcru.
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). Apenascalculos-rmicanônico earquivo-calc/calcularcanô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(...)ecriarDadosCalculoRgpsDeApiRmiDesvinculada(...) - cálculos de
.calcusamcriarDadosCalculoRgpsDeArquivoTcRmi(...) - saídas serializadas usam
CalculoRmi.paraApiBloco(...)eCalculoRmiDesvinculada.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
| Tag | Descrição |
|---|---|
rmi-api | Log operacional — registra toda requisição recebida |
rmi-api, auditoria | Log 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-apipara 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.