Skip to content

@fc/prev-api ​

API REST de cálculos previdenciários do RGPS: tempo de contribuição, análise de benefícios e atrasados. Expõe Swagger em /_swagger e OpenAPI em /_openapi.json.

Todas as respostas JSON dos endpoints sob /rgps/api/v1/* seguem o envelope PDPJ-Br:

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

Contrato OpenAPI ​

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.

Endpoints ​

Os endpoints canônicos vivem sob o módulo rgps (Regime Geral de Previdência Social) e compartilham o namespace /rgps/api/v1/* com a rmi-api. Os endpoints /api/v1/* legados foram removidos após o sunset de 2026-05-31 (RFC 8594) e hoje respondem 404.

Pesquisa de enquadramentos de tempo especial ​

GET /rgps/api/v1/enquadramentos-tempo-especial exige x-api-key e pesquisa o mesmo catálogo da ferramenta /rgps-utils, com sinônimos e correção aproximada. A consulta não decide o enquadramento de um período trabalhado nem aplica filtro temporal.

ParâmetroContrato
termoCódigo ou texto, até 200 caracteres. Ausente ou vazio lista o catálogo filtrado.
decretosIDs separados por vírgula; ausente seleciona todos.
tiposAGENTE_NOCIVO e/ou CATEGORIA_PROFISSIONAL, separados por vírgula; ausente seleciona ambos.
pagesize:N,page:M, padrão size:20,page:1, tamanho de 1 a 100 e página inteira positiva segura.

Catálogos disponíveis:

IDConteúdo
decreto-53831-agentesDecreto 53.831/1964, agentes nocivos do Quadro Anexo
decreto-53831-ocupacoesDecreto 53.831/1964, categorias profissionais do Quadro Anexo
decreto-83080-agentesDecreto 83.080/1979, agentes nocivos do Anexo I
decreto-83080-atividadesDecreto 83.080/1979, atividades profissionais do Anexo II
decreto-2172Decreto 2.172/1997, Anexo IV
decreto-3048Decreto 3.048/1999, Anexo IV

Exemplo: GET /rgps/api/v1/enquadramentos-tempo-especial?termo=ruido&decretos=decreto-3048&page=size:20,page:1.

O envelope PDPJ contém result (lista) e page-info (current, last, size, count). Cada resultado traz entrada (id, decreto, secao, item), pontuacao, campos encontrados e, quando aplicável, termoCorrigido. Os registros preservam textos normativos, redações revogadas, observações, notas editoriais, tempo mínimo, classificação, vigência e fonte. Os identificadores não têm garantia de permanência entre revisões do catálogo.

A ordenação é por relevância decrescente e código; sem termo útil, por publicação e código. Empates preservam a posição no catálogo. A paginação ocorre depois da busca e dos filtros. Resultado inexistente ou página além do total retorna 200 com lista vazia; uma coleção vazia informa last: 1.

Parâmetros repetidos, filtros vazios ou desconhecidos, paginação malformada e limites excedidos retornam 400. Chave ausente/inválida retorna 401; falta de autorização, 403; limite de borda por IP, 429 com Retry-After; indisponibilidade do validador, 503; erro inesperado, 500. Erros usam o envelope PDPJ com result: null. A resposta envia Cache-Control: no-store. Como consulta GET, não consome a cota por classe reservada às operações POST.

Cálculos canônicos (JSON) ​

MétodoCaminhoDescrição
POST/rgps/api/v1/calculos-tempoCalcula tempo de contribuição e analisa elegibilidade a benefícios
POST/rgps/api/v1/calculos-tempo/por-gruposCalcula o tempo para todos os grupos de benefícios
POST/rgps/api/v1/calculos-atrasadosCalcula atrasados previdenciários

Nos resultados, cada benefício analisado traz fundamento (a citação legal legível, EC 103, art. 20) e chaveFundamento (a chave estável, EC_103_ART_20, a mesma usada pela API de RMI no cálculo por fundamento).

Fontes externas: documentos e arquivo .calc ​

MétodoCaminhoDescrição
POST/rgps/api/v1/calculos-tempo/prevjud/calcularLeitura + cálculo de tempo a partir do JSON PrevJud
POST/rgps/api/v1/calculos-tempo/prevjud/calcular-por-gruposLeitura + cálculo de tempo por grupos a partir do JSON PrevJud
POST/rgps/api/v1/calculos-tempo/arquivo-calc/lerLê arquivo .calc de tempo e devolve o JSON pronto
POST/rgps/api/v1/calculos-tempo/arquivo-calc/calcularLeitura + cálculo em uma única chamada
POST/rgps/api/v1/calculos-tempo/arquivo-calc/calcular-por-gruposLeitura + cálculo por grupos em uma única chamada
POST/rgps/api/v1/calculos-atrasados/arquivo-calc/lerLê arquivo .calc de atrasados e devolve o JSON pronto
POST/rgps/api/v1/calculos-atrasados/arquivo-calc/calcularLeitura + cálculo de atrasados em uma única chamada

Os endpoints que recebem arquivo .calc (arquivo-calc/*) aceitam multipart/form-data com o arquivo no campo file. Os demais, inclusive os de PrevJud (prevjud/calcular*), aceitam application/json.

As rotas que efetivamente calculam aceitam a query opcional permalink=true (ou 1). Quando solicitada, a API persiste um snapshot imutável e reabrível na calculadora correspondente 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. Rotas que apenas leem ou extraem documentos não criam permalink. 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 oito rotas que efetivamente calculam (tempo e atrasados) 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). O PDF sempre embute um permalink do cálculo no card de reprodução — por isso a geração do demonstrativo 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. Os mesmos códigos valem para a capacidade de permalink (503/502), e falha na geração do PDF responde 500. No corpo JSON canônico, o campo opcional processo (nomeCalculo, numero, autor) preenche o bloco de identificação do PDF sem afetar o cálculo. Nas rotas de atrasados, quando o cálculo apura alçada, o envelope traz também demonstrativoAlcadaPdf, o demonstrativo de alçada, no mesmo schema.

Dependência externa ​

A prev-api consome a API pública de índices (endpoints /indices/api/v1/*) para obter, por requisição, a tabela de indexadores e a série de piso e teto do RGPS usadas nos cálculos de tempo e atrasados. O endereço efetivo é fornecido pela implantação. Se a API de índices estiver indisponível, os endpoints de cálculo retornam 503 (API de índices indisponível).

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 os globs /rgps/api/v1/calculos-tempo/** e /rgps/api/v1/calculos-atrasados/**; assim, as rotas-base e todas as suas subrotas exigem a chave sem depender de variáveis de ambiente de deploy.

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 os caminhos protegidos continuam fazendo parte da configuração estrutural da app.

Fail-fast no boot: se algum 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 prev-api registra telemetria best effort no fim da resposta HTTP, sem bloquear o cálculo nem alterar erros. Quando a rota estiver protegida por chave de API, o evento reaproveita event.context.apiKeyValidada e preserva o idTokenApiKey sem chamar o validador novamente.

Eventos emitidos:

AçãoEndpoints
rgps.beneficios.apicálculo de tempo canônico e PrevJud
rgps.beneficios.api.gruposcálculo de tempo por grupos canônico e PrevJud
rgps.beneficios.api.arquivo-calccálculo de tempo a partir de .calc
rgps.beneficios.api.arquivo-calc.gruposcálculo de tempo por grupos a partir de .calc
rgps.atrasados.apicálculo de atrasados
rgps.atrasados.api.arquivo-calccálculo de atrasados a partir de .calc
rgps.atrasados.api.valor-causavalor da causa frente ao limite de alçada
rgps.documentos.api.arquivo-calcleitura de .calc (tempo e atrasados)

A leitura isolada de .calc (arquivo-calc/ler) emite rgps.documentos.api.arquivo-calc; quando o arquivo é calculado, vale a ação do cálculo. As ações de leitura de documentos (CNIS, Carta de Concessão, RDCTC, PrevJud e PAP) são emitidas pelo serviço de leitura documental, que responde por essas leituras desde o sunset de 30/09/2026.

Os cálculos são executados fora do fluxo HTTP principal, mantendo o health check responsivo durante operações longas. Se a capacidade temporária estiver ocupada, a API responde 429 Too Many Requests com Retry-After; repetir depois desse intervalo é seguro.

Convenções ​

Nos cálculos de tempo, dadosSegurado.tipo é obrigatório: informe COMUM, PCD ou RURICOLA. A omissão é recusada, sem presumir um tipo.

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

  • Recurso (plural hifenizado): calculos-tempo, calculos-atrasados.
  • Variantes de cálculo (sub-path): calculos-tempo/por-grupos.
  • Fonte externa (sub-recurso aninhado): calculos-tempo/prevjud/calcular, calculos-tempo/arquivo-calc/calcular.

Sem Content-Type negotiation. As queries permalink e demonstrativo só acrescentam campos opcionais ao envelope; não alteram o schema de result. Cada endpoint tem um único requestBody.content tipado.

Contagem multiplicada da carência rural (Lei 11.718/2008, art. 3º) ​

opcoesContagem.aplicarArt3Lei11718 (booleano, padrão false; no .calc, parametrosTempo.aplicarArt3Lei11718) liga a contagem multiplicada na aposentadoria por idade rural (Lei 8.213/91, art. 48, § 1º): cada mês de período com formaContagem RURAL e naturezaVinculo EMPREGADO conta três de 2011 a 2015 e dois de 2016 a 2020, até 12 meses por ano civil, somados os meses rurais do ano que não se multiplicam. As demais regras e o tempo de contribuição seguem com a contagem simples. No grupo RURICOLA da espécie 41, carenciaRural dos períodos e dos totais já vem acrescida, e result.contagemMultiplicadaLei11718 traz o quadro por ano civil (linhas com ano, mesesComprovados, multiplicador, mesesMultiplicados, mesesComputados e acrescimo, mais os totais); o campo só aparece quando a contagem acrescentou meses. Valor que não seja booleano é recusado com erro de validação.

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

Em cada benefício de result, 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. A pensão acidentária (93) aceita ainda, na raiz do corpo, dataAcidente (dd/mm/aaaa ou aaaa-mm-dd, não posterior ao óbito; no .calc, parametrosGerais.dataAcidente): esta API só a valida e repassa, sem efeito na análise de tempo; a API de RMI a usa para o salário de contribuição do mês do acidente. Nas demais espécies o campo é ignorado.

Em calculos-atrasados, inicioDiferencas e terminoDiferencas são opcionais — com a prescrição ligada, o início ausente passa a ser o marco prescricional —, mas, quando informados, precisam ser datas válidas: fora do formato, a resposta é 400 com ENTRADA_CALCULO_RECUSADA.

Tratamento de erros ​

Espécie do benefício. opcoesContagem.especie é obrigatória nas entradas JSON e na leitura de arquivo .calc (parametrosGerais.especie): 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 do INSS.

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.

Toda rota canônica (/rgps/api/v1/**) responde com o envelope PDPJ inclusive em falha — nunca com erro cru do framework. A normalização é feita por tratarErroRota(event, erro) de @base-api/server/utils/erros:

Origem do erroHTTPstatus
JSON malformado no corpo (SyntaxError de JSON.parse)400error
Falha de schema Zod (ZodError)400error
ErroDominio lançado pelo handler (validação semântica, upload, etc.)400error
Exceção conhecida do core @fc/calculos-previdenciarios400error
Dado de entrada recusado pelo motor durante o cálculo (campo obrigatório ausente, valor incoerente)400, errorCode: ENTRADA_CALCULO_RECUSADAerror
Upload acima do limite do endpoint413error
.calc com JSON válido, mas incompatível com o endpoint422error
Tabelas da plataforma sem cobertura para a data pedida (índice, piso ou teto)503, errorCode: DADOS_INDISPONIVEISerror
Qualquer outra exceção500error

Em 400, messages lista os detalhes (caminho.do.campo: mensagem para falhas Zod; a mensagem do motor, nas recusas durante o cálculo). O 503 é transitório: a data pedida está além das tabelas publicadas e a atualização delas resolve. Em 500, a mensagem é genérica e o erro é registrado via logOperacional.error — sem vazar stack trace: 500 é reservado a falha da própria plataforma.

Validação de entrada: payloads JSON e uploads multipart/form-data passam por schemas Zod defensivos de superfície (apps/prev-api/server/utils/esquemas.ts). A regra de negócio completa segue dentro do core (DadosCalculo.deApiTempo, desserializarAtrasados, etc.); o Zod existe para transformar entradas catastroficamente inválidas em 400 determinístico, não para duplicar a regra. Corpos JSON são limitados a 10 MiB pela contagem dos bytes recebidos e não dependem de content-length.

Uploads: o multipart deve conter exatamente um arquivo no campo obrigatório file; campo ausente, nome diferente, segundo arquivo ou tipo inválido → 400 com mensagem descritiva. Os uploads multipart aceitam tanto content-length quanto transfer-encoding: chunked; os limites de tamanho continuam valendo e o excesso responde 413.

Endpoints legados (removidos) ​

Os caminhos /api/v1/* foram desativados após o sunset de 2026-05-31, anunciado desde a criação do namespace canônico via headers RFC 8594 (Deprecation, Sunset, Link: rel="successor-version"). Hoje respondem 404. Consumidores remanescentes devem migrar para o sucessor:

LegadoSucessor
POST /api/v1/tempo/calcularPOST /rgps/api/v1/calculos-tempo
POST /api/v1/tempo/calcular-gruposPOST /rgps/api/v1/calculos-tempo/por-grupos
POST /api/v1/atrasados/calcularPOST /rgps/api/v1/calculos-atrasados
POST /api/v1/cnis/lerPOST /rgps/api/v1/documentos/cnis/ler (serviço de leitura documental)
POST /api/v1/rdctc/lerPOST /rgps/api/v1/documentos/rdctc/ler (serviço de leitura documental)
POST /api/v1/prevjud/lerPOST /rgps/api/v1/documentos/prevjud/ler (serviço de leitura documental)
POST /api/v1/prevjud/tempo/calcularPOST /rgps/api/v1/calculos-tempo/prevjud/calcular
POST /api/v1/prevjud/tempo/calcular-gruposPOST /rgps/api/v1/calculos-tempo/prevjud/calcular-por-grupos
POST /api/v1/arquivo-calc/tempo/lerPOST /rgps/api/v1/calculos-tempo/arquivo-calc/ler
POST /api/v1/arquivo-calc/tempo/calcularPOST /rgps/api/v1/calculos-tempo/arquivo-calc/calcular
POST /api/v1/arquivo-calc/tempo/calcular-gruposPOST /rgps/api/v1/calculos-tempo/arquivo-calc/calcular-por-grupos
POST /api/v1/arquivo-calc/atrasados/lerPOST /rgps/api/v1/calculos-atrasados/arquivo-calc/ler
POST /api/v1/arquivo-calc/atrasados/calcularPOST /rgps/api/v1/calculos-atrasados/arquivo-calc/calcular

As leituras documentais (/rgps/api/v1/calculos-tempo/{cnis,rdctc,carta,pap,prevjud}/ler) saíram desta API após o sunset de 30/09/2026, anunciado desde a criação do serviço de leitura documental pelos cabeçalhos Deprecation, Sunset e Link da RFC 8594. Hoje respondem 404. Os sucessores são /rgps/api/v1/documentos/{cnis,rdctc,carta,pap,prevjud}/ler, no serviço de leitura documental, com o mesmo contrato de entrada e saída.

Os fluxos compostos de PrevJud (leitura + cálculo em uma única chamada) estão disponíveis via prevjud/calcular e prevjud/calcular-por-grupos. Clientes que preferirem inspecionar/editar o JSON lido antes de calcular podem usar o fluxo em duas chamadas: POST /rgps/api/v1/documentos/prevjud/ler (no serviço de leitura documental) → POST /rgps/api/v1/calculos-tempo.

Implementação interna ​

Os endpoints de tempo usam a superfície central do core para unificar o comportamento entre web e API:

  • entradas JSON de tempo: DadosCalculo.deApiTempo(...)
  • entradas JSON de tempo com PrevJud: DadosCalculo.deApiTempoPrevjud(...)
  • entradas .calc: DadosCalculo.deArquivoTc(...)
  • saídas serializadas: AnaliseBeneficios.paraApiResultado(...) e AnaliseBeneficios.paraApiGrupos(...)

Os wrappers legados de @fc/calculos-rgps/utilidades-apis/* continuam existindo por compatibilidade transitória; novas integrações internas devem preferir a 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
prev-apiLog operacional — registra toda requisição recebida
prev-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: prev-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 e o IP de origem.

Filtragem ​

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

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

Eventos de auditoria ​

Cada endpoint emite um evento:

  • calculos-tempo → tempo.calculado
  • calculos-tempo/por-grupos → tempo.grupos.calculado
  • calculos-atrasados → atrasados.calculado
  • calculos-tempo/prevjud/calcular → tempo.prevjud.calculado
  • calculos-tempo/prevjud/calcular-por-grupos → tempo.prevjud.grupos.calculado
  • calculos-tempo/arquivo-calc/ler → arquivo-tc.lido
  • calculos-tempo/arquivo-calc/calcular → arquivo-tc.calculado
  • calculos-tempo/arquivo-calc/calcular-por-grupos → arquivo-tc.grupos.calculado
  • calculos-atrasados/arquivo-calc/ler → arquivo-atrasados.lido
  • calculos-atrasados/arquivo-calc/calcular → arquivo-atrasados.calculado

Cada evento inclui o campo ip com o endereço de origem confirmado pela borda confiável.

Honorários contratuais ​

O cálculo de Atrasados aceita o parâmetro opcional honorariosContratuais: { destacar: true, percentual: 0.3 }, equivalente a 30%. O percentual é uma fração de 0 a 1, com até quatro casas decimais (duas casas percentuais); ativação sem percentual é recusada. Ausência ou destacar: false desativa o destaque.

O resultado opcional honorariosContratuais contém percentual, valores discriminados de honorarios e autor, além de dadosRra quando disponível. A divisão incide sobre o Resultado Atrasados final, conserva valores e meses de RRA e mantém a condenação e os honorários sucumbenciais. JSON, .calc, MCP e PDF usam essa mesma regra. O quadro “Honorários Contratuais (Destaque)” aparece após Resultado Atrasados e fica oculto na apuração exclusiva de sucumbenciais.

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.