Documentação

Introdução

A API do sistema BEDUC fornece acesso programático aos dados do Cidadão360, permitindo integração com aplicações externas de forma segura e eficiente.

Características Principais:
  • RESTful: Segue os princípios REST para design de APIs
  • JSON: Todas as respostas são em formato JSON (UTF-8)
  • Autenticação: API Key ou Bearer Token (login com CPF/senha)
  • Documentação dinâmica: GET /api/docs retorna a lista de endpoints em JSON
URL Base:
http://cidadao360.jamsistemas.com.br/beduc/api

Ajuste conforme o endereço da sua instalação.

Autenticação

A API utiliza autenticação via API Key. Você deve incluir sua chave em todas as requisições.

Via Header (Recomendado):
X-API-Key: sua_api_key_aqui
Via Authorization Header:
Authorization: Bearer sua_api_key_aqui
Importante: Nunca compartilhe sua API Key publicamente. Mantenha-a segura e rotacione periodicamente.

Endpoints

Candidatos (Cidadãos)
Listar candidatos
GET /candidates
Lista paginada. Parâmetros: page, per_page, search, phonetic
Obter candidato por ID
GET /candidates/{id}
Retorna dados de um candidato específico
Obter candidato por CPF
GET /candidates/cpf/{cpf}
CPF com 11 dígitos (sem formatação)
Obter candidato por número do cartão cidadão
GET /candidates/card/{numero_cartao}
Retorna todas as informações do candidato (inclui telefones e nacionalidade)
Criar candidato
POST /candidates
Corpo JSON com dados do candidato (nome_completo, cpf, email, etc.)
Atualizar candidato
PUT /candidates/{id}
Atualiza dados de um candidato existente
Cartões
Listar cartões
GET /cards
Lista de cartões gerados
Obter cartão por ID
GET /cards/{id}
Dados de um cartão específico
Gerar cartão
POST /cards
Gera cartão do cidadão para o candidato informado
Validar cartão
POST /cards/validate
Corpo: card_number, cpf, nome (ou dados do QR). Retorna se o cartão é válido
Busca
Busca geral
POST /search
Corpo JSON: {"term": "termo"} ou {"search": "termo"}. Campo term/search é obrigatório.
Busca fonética
POST /search/phonetic
Busca por similaridade fonética no nome (term ou search no corpo)
Busca facial
POST /search/facial
Busca por dados faciais (corpo conforme especificação do endpoint)
Outros
Estatísticas
GET /stats
Estatísticas do sistema
Status da API
GET /health
Não exige autenticação. Retorna status, timestamp e versão
Documentação em JSON
GET /docs
Lista de endpoints, autenticação e rate limits em JSON

Formato das Respostas

Resposta de Sucesso:
{
  "success": true,
  "data": {
    "id": 1,
    "nome": "João Silva",
    "email": "joao@email.com"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
Resposta com Paginação:
{
  "success": true,
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "last_page": 8
  }
}

Códigos de Erro

Código Descrição Exemplo
400 Bad Request Dados inválidos na requisição
401 Unauthorized API Key inválida ou ausente
403 Forbidden Sem permissão para o recurso
404 Not Found Recurso não encontrado
429 Too Many Requests Rate limit excedido
500 Internal Server Error Erro interno do servidor

Rate Limiting

Para garantir a estabilidade da API, podem ser aplicados limites de taxa de requisições:

  • Por minuto: até 100 requisições
  • Por hora: até 1.000 requisições

Os limites podem variar conforme o ambiente e a configuração do servidor.

Webhooks

Webhooks estão previstos para permitir notificações em tempo real sobre eventos da API (ex.: novo candidato criado, cartão gerado). A disponibilidade e a configuração dependem da versão e do ambiente. Consulte o suporte ou a documentação técnica para detalhes.