Acesse o Portal Paraíba Digital

Guia de Uso da API

Saiba como utilizar a API pública da Tabela de Temporalidade Documental

API de Temporalidade Documental

A API de Temporalidade Documental permite consultar de forma programática as informações sobre prazos de guarda e destinação de documentos administrativos, seguindo rigorosamente a estrutura hierárquica de classificação documental.

Sobre a API

Para utilizar a API corretamente, é importante compreender que os documentos são organizados em quatro níveis de classificação utilizados na gestão documental:

1. Função
Área ampla de atuação
2. Subfunção
Subdivisão da função
3. Atividade
Conjunto de ações
4. Documento
Tipo documental vinculado

Estrutura de Classificação Documental

Nível Exemplo de Código Descrição Detalhada
Função 001 Área ampla de atuação da organização
Subfunção 001.01 Subdivisão específica dentro de uma função
Atividade 001.01.01 Conjunto de ações relacionadas e executadas pelo setor
Documento 001.01.01.001 Tipo documental gerado ou recebido, vinculado à atividade

Base da URL da API

Todos os endpoints do sistema devem utilizar o prefixo base descrito abaixo:

/api/v1/

Exemplo Completo:

https://este-site/api/v1/documents/

Endpoints Disponíveis

Consulte abaixo os endpoints de acesso aos dados. Todos os endpoints suportam requisições para listar itens ou resgatar um item específico através do seu id.

GET /api/v1/functions/
GET /api/v1/functions/{id}/

GET /api/v1/subfunctions/
GET /api/v1/subfunctions/{id}/

GET /api/v1/activities/
GET /api/v1/activities/{id}/

GET /api/v1/documents/
GET /api/v1/documents/{id}/

Filtros e Busca Avançada

Os endpoints de listagem suportam buscas e filtragens avançadas. Você pode combinar vários parâmetros simultaneamente na Query String para afunilar os resultados.

Filtrar por código exato
/api/v1/documents/?code=001.01.01.001
Buscar parcialmente por nome
/api/v1/documents/?search=ato normativo
Ordenar resultados

Padrão ascendente. Utilize um hífen - antes do campo para ordenação decrescente.

/api/v1/documents/?ordering=code
/api/v1/documents/?ordering=-code

Exemplos de Casos de Uso

Prazos e Destinação

Buscar documentos com prazo corrente de 5 anos ou eliminação:

GET /api/v1/documents/?current_term=5
GET /api/v1/documents/?destination=E
Hierarquia e Busca Textual

Buscar por atividades filhas ou pesquisar um documento específico:

GET /api/v1/activities/?subfunction=1
GET /api/v1/documents/?search=contrato

Integrando com JavaScript

Se você estiver construindo sua própria interface web, poderá consumir os dados de foma simplificada utilizando o fetch():

script.js 
fetch("https://api.seusite.gov/api/v1/documents/")
  .then(response => response.json())
  .then(data => {
      console.log(data);
  })
  .catch(error => console.error("Erro na API:", error));

Retorno Esperado da API

Abaixo temos o formato mapeado na resposta de listagem ou de recuperação individual.

response.json 
{
  "id": 10,
  "code": "001.01.01.001",
  "name": "Ato normativo",
  "current_term": 5,
  "intermediate_term": 10,
  "destination": "E",
  "activity": 1
}

Entendendo a Destinação Final

A API retorna códigos resumidos para a destinação final. Verifique na tabela abaixo os significados.

Código Retornado Significado Documental
E Eliminação: O documento será destruído após o fim do prazo de guarda.
GP Guarda Permanente: O documento possui valor histórico, legal ou probatório permanente e será preservado.