Documentação da API CAEPI

A API CAEPI provê validação automatizada e em tempo real de Certificados de Aprovação (CA) de Equipamentos de Proteção Individual (EPI), servindo como ponte direta com a base de dados mantida pelo Ministério do Trabalho e Emprego.

O principal objetivo da API é permitir a integração de validações automáticas em ERPs, sistemas de compras, almoxarifados ou sistemas de RH, mitigando os riscos de entrega de EPIs vencidos ou irregulares aos trabalhadores.

⚡ Alta Disponibilidade e Performance

Para garantir tempos de resposta sub-milissegundos (< 1ms), a API processa e mantém a base de dados de mais de 120 mil registros diretamente em um Singleton de memória RAM, atualizado diariamente de forma assíncrona.

Autenticação

Todas as requisições para endpoints de dados da API devem ser autenticadas informando uma chave de acesso (API Key) ativa. Chaves de API podem ser criadas e administradas através do Painel de Controle de Acesso.

A chave deve ser enviada em cada requisição HTTP através do cabeçalho customizado X-API-Key.

Exemplo de Cabeçalho HTTP

GET /ca/45545 HTTP/1.1
Host: localhost:8000
X-API-Key: caepi_live_58c2134dbde0ef6731ad2b78d654aa02

⚠ Cuide da sua Chave

Chaves de API geradas concedem acesso total de leitura à base de dados. Nunca as exponha em repositórios públicos de código ou no código do lado do cliente (front-end).

Consultar CA

Retorna as informações resumidas e estruturadas de validade e cadastrais de um determinado Certificado de Aprovação de EPI.

GET /ca/{NumeroCA}

Parâmetros de Rota

Parâmetro	Tipo	Obrigatório	Descrição
NumeroCA	string	Sim	O número do Certificado de Aprovação (CA) a ser consultado (ex: 45545).

Exemplo de Integração

cURL
Python
JavaScript

curl -X GET "http://localhost:8000/ca/45545" \
  -H "X-API-Key: caepi_live_58c2134dbde0ef6731ad2b78d654aa02"

Resposta de Sucesso (200 OK)

JSON Response

{
  "numero_ca": "45545",
  "is_active": true,
  "status_validade": "REGULAR",
  "equipamento": "LUVA PARA PROTEÇÃO CONTRA AGENTES TÉRMICOS E MECÂNICOS",
  "fabricante": "BT EQUIPAMENTOS INDUSTRIAIS LTDA",
  "data_vencimento": "2031-03-18"
}

Baixar Ficha de Conformidade (PDF)

Gera e exporta dinamicamente a Ficha Técnica de Conformidade do CA no formato PDF seguindo exatamente o layout oficial emitido pelo Ministério do Trabalho e Emprego (MTE) com o Brasão de Armas, informações cadastrais completas do fabricante (CNPJ, CNAE e Endereço consultados na Receita Federal) e a chave digital de validação de auditoria SST.

GET /ca/{NumeroCA}/pdf

O endpoint de exportação aceita a autenticação tanto através do header padrão X-API-Key quanto diretamente através de parâmetro de Query String na URL (?api_key=...). O envio por query string permite que seus usuários cliquem em links de download direto sem a necessidade de tratamento de headers via scripts.

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
api_key	string	Não (se informado no header)	Sua chave de acesso da API. Permite chamadas e links de download direto pelo navegador.

Exemplo de Link para Download Direto

URL de Download Direto

https://api-caepi.oscon.com.br/ca/45545/pdf?api_key=caepi_live_58c2134dbde0ef6731ad2b78d654aa02

Exemplo de Integração

cURL
Python
JavaScript

curl -X GET "http://localhost:8000/ca/45545/pdf" \
  -H "X-API-Key: caepi_live_58c2134dbde0ef6731ad2b78d654aa02" \
  --output CA_45545.pdf

Exportação em Lote

A API permite consultar e exportar múltiplos CAs de uma só vez, retornando os dados agregados em formato JSON ou gerando um arquivo de planilha do Excel (.xlsx).

POST /exportarJSON

Corpo da Requisição (Body)

Enviar JSON contendo um array de strings com as chaves a buscar.

JSON Payload

{
  "listaCAs": ["45545", "32023"]
}

Códigos de Resposta HTTP

A API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha das operações.

Status	Significado	Descrição
200 OK	Sucesso	A requisição foi processada com êxito e os dados retornados no formato correto.
400 Bad Request	Requisição Inválida	Parâmetros ausentes, incorretos ou erro de formatação do payload.
401 Unauthorized	Não Autorizado	Chave de acesso ausente, revogada, expirada ou inválida no cabeçalho.
404 Not Found	Não Encontrado	O número do CA consultado não consta na base de dados governamental.
503 Service Unavailable	Serviço Indisponível	A base de dados em memória está em fase de carregamento inicial ou falha temporária. Tente novamente em alguns segundos.

Conformidade Legal (NR-06)

O uso de Equipamentos de Proteção Individual (EPI) regulamentados é obrigatório em atividades de risco. O uso de EPIs com CAs vencidos sujeita as organizações a infrações trabalhistas, multas pesadas e riscos civis em acidentes.

Item NR-06	Exigência da Norma	Aplicação correspondente na API
6.4.1	Validação da validade do CA do equipamento em estoque e uso.	O campo `status_validade` retorna o status em tempo real comparado com o dia atual.
6.9.2.1	Fornecimento exclusivo de EPIs com Certificado de Aprovação ativo.	O campo `is_active` funciona como um gatilho booleano para travar o cadastro e entrega no ERP/RH.