API Sistema de Senhas

Documentação completa para desenvolvedores

Versão: 1.0.0

Base URL Produção: https://ramon.tech/apis/atendimento

🔐 Autenticação

A API utiliza autenticação JWT (JSON Web Token). A maioria dos endpoints requer autenticação.

Como autenticar:

  1. Faça login através do endpoint /auth/login
  2. Receba o token JWT na resposta
  3. Inclua o token em todas as requisições subsequentes no header: Authorization: Bearer SEU_TOKEN_JWT

⚠️ Importante: O token expira após 6 horas. Use o endpoint de refresh para renovar.

🔑 Endpoints de Autenticação

POST /auth/login
Público

Realizar login no sistema

Request Body:

{
  "email": "joao.silva@secretaria.gov.br",
  "senha": "12345678"
}

Response (200 OK):

{
  "status": "success",
  "message": "Autenticado com sucesso",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "funcionario": {
      "id": 1,
      "nome": "João Silva",
      "email": "joao.silva@secretaria.gov.br",
      "setor": {
        "id": 1,
        "sigla": "DA",
        "nome": "Dívida Ativa"
      }
    },
    "expires_at": 1706745600
  }
}
POST /auth/logout
Requer autenticação

Realizar logout (invalida o token)

Headers:

Authorization: Bearer SEU_TOKEN_JWT

Response (200 OK):

{
  "status": "success",
  "message": "Logout realizado com sucesso"
}
GET /auth/me
Requer autenticação

Obter dados do funcionário autenticado

Response (200 OK):

{
  "status": "success",
  "data": {
    "funcionario": {
      "id": 1,
      "nome": "João Silva",
      "email": "joao.silva@secretaria.gov.br",
      "ativo": true,
      "ultimo_login": "2024-01-25T10:30:00.000Z",
      "criado_em": "2024-01-01T00:00:00.000Z"
    },
    "setor": {
      "id": 1,
      "sigla": "DA",
      "nome": "Dívida Ativa",
      "descricao": "Gerencia as dívidas referente à IPTU...",
      "estatisticas": {
        "total_funcionarios": 5,
        "funcionarios_ativos": 4,
        "senhas_em_espera": 12,
        "senhas_em_atendimento": 3,
        "senhas_atendidas_hoje": 45
      }
    },
    "estatisticas_hoje": {
      "total_atendimentos": 8,
      "atendimentos_finalizados": 6,
      "atendimentos_em_andamento": 2,
      "tempo_medio_atendimento": 15.5
    },
    "atendimento_atual": null
  }
}
POST /auth/refresh
Requer autenticação

Renovar token JWT

Response (200 OK):

{
  "status": "success",
  "message": "Token renovado com sucesso",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "funcionario": {
      "id": 1,
      "nome": "João Silva",
      "email": "joao.silva@secretaria.gov.br",
      "setor": {
        "id": 1,
        "sigla": "DA",
        "nome": "Dívida Ativa"
      }
    },
    "expires_at": "2024-01-25T22:00:00.000Z"
  }
}

🏢 Endpoints de Setores

GET /setores
Público

Listar todos os setores ativos

Response (200 OK):

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "sigla": "DA",
      "nome": "Dívida Ativa",
      "descricao": "Gerencia as dívidas referente à IPTU..."
    },
    {
      "id": 2,
      "sigla": "JU",
      "nome": "Jurídico",
      "descricao": "Analisa solicitações dos contribuintes..."
    }
  ]
}
GET /setores/{id}
Público

Buscar setor específico por ID

Parâmetros:

  • id (integer): ID do setor

Response (200 OK):

{
  "status": "success",
  "data": {
    "id": 1,
    "sigla": "DA",
    "nome": "Dívida Ativa",
    "descricao": "Gerencia as dívidas referente à IPTU...",
    "funcionarios_ativos": 4,
    "senhas_em_espera": 12
  }
}
POST /setores
Requer autenticação

Criar novo setor

Request Body:

{
  "sigla": "TI",
  "nome": "Tecnologia da Informação",
  "descricao": "Suporte técnico e desenvolvimento",
  "ativo": true
}

Response (201 Created):

{
  "status": "success",
  "message": "Setor criado com sucesso",
  "data": {
    "setor": {
      "id": 10,
      "sigla": "TI",
      "nome": "Tecnologia da Informação",
      "descricao": "Suporte técnico e desenvolvimento",
      "ativo": true,
      "criado_em": "2024-01-25T14:30:00.000Z"
    }
  }
}
PUT /setores/{id}
Requer autenticação

Atualizar dados do setor

Request Body (campos opcionais):

{
  "nome": "Tecnologia da Informação e Inovação",
  "descricao": "Suporte técnico, desenvolvimento e inovação",
  "ativo": true
}
DELETE /setores/{id}
Requer autenticação

Remover setor (soft delete)

⚠️ Atenção: Setor não pode ter funcionários vinculados ou senhas em andamento.

👥 Endpoints de Funcionários

GET /funcionarios
Requer autenticação

Listar funcionários com paginação e filtros

Query Parameters:

  • pagina (integer): Número da página (padrão: 1)
  • limite (integer): Itens por página (padrão: 20, máx: 100)
  • setor_id (integer): Filtrar por setor
  • ativo (boolean): Filtrar por status
  • busca (string): Buscar por nome ou email

Exemplo de requisição:

GET /funcionarios?pagina=1&limite=10&setor_id=1&ativo=true

Response (200 OK):

{
  "status": "success",
  "data": {
    "funcionarios": [
      {
        "id": 1,
        "nome": "João Silva",
        "email": "joao.silva@secretaria.gov.br",
        "ativo": true,
        "setor": {
          "id": 1,
          "sigla": "DA",
          "nome": "Dívida Ativa"
        },
        "criado_em": "2024-01-01T00:00:00.000Z",
        "atualizado_em": "2024-01-25T10:30:00.000Z"
      }
    ],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 3,
      "por_pagina": 10,
      "total_registros": 25,
      "de": 1,
      "ate": 10
    }
  }
}
POST /funcionarios
Requer autenticação

Criar novo funcionário

Request Body:

{
  "nome": "Maria Oliveira",
  "email": "maria.oliveira@secretaria.gov.br",
  "senha": "senha123",
  "setor_id": 2,
  "ativo": true
}

Validações:

  • Nome: mínimo 3 caracteres, máximo 100
  • Email: formato válido e único no sistema
  • Senha: mínimo 8 caracteres
  • Setor: deve existir e estar ativo
PUT /funcionarios/alterar-senha
Requer autenticação

Funcionário altera sua própria senha

Request Body:

{
  "senha_atual": "senha123",
  "senha_nova": "novaSenha456",
  "confirmar_senha": "novaSenha456"
}
POST /funcionarios/verificar-email
Requer autenticação

Verificar se email está disponível

Request Body:

{
  "email": "novo.email@secretaria.gov.br",
  "excluir_id": 5  // Opcional: ID do funcionário a excluir da verificação (útil em updates)
}

Response (200 OK):

{
  "status": "success",
  "data": {
    "email": "novo.email@secretaria.gov.br",
    "disponivel": true,
    "mensagem": "Email disponível"
  }
}

🎫 Endpoints de Senhas

GET /senhas
Requer autenticação

Listar senhas com filtros e paginação

Query Parameters:

  • pagina (integer): Número da página
  • limite (integer): Itens por página
  • setor_id (integer): Filtrar por setor
  • status (string): em_espera, em_atendimento, atendido, nao_atendido
  • prioridade (string): normal, alta, urgente
  • data (string): Filtrar por data (YYYY-MM-DD)
  • busca (string): Buscar por número ou nome do contribuinte
  • busca (string): Buscar por número ou nome do contribuinte
POST /senhas
Requer autenticação

Criar nova senha de atendimento

Request Body:

{
  "setor_id": 1,
  "contribuinte_nome": "José da Silva",
  "prioridade": "normal",  // normal, alta, urgente
  "observacoes": "Contribuinte com dificuldade de locomoção"
}

Response (201 Created):

{
  "status": "success",
  "message": "Senha criada com sucesso",
  "data": {
    "senha": {
      "id": 123,
      "numero": "DA001",
      "contribuinte_nome": "José da Silva",
      "prioridade": "normal",
      "status": "em_espera",
      "setor": {
        "id": 1,
        "sigla": "DA",
        "nome": "Dívida Ativa"
      },
      "posicao_fila": 5,
      "criado_em": "2024-01-25T14:30:00.000Z"
    }
  }
}
POST /senhas/{id}/iniciar-atendimento
Requer autenticação

Iniciar atendimento de uma senha

ℹ️ Nota: Funcionário não pode ter mais de um atendimento em andamento.

Response (200 OK):

{
  "status": "success",
  "message": "Atendimento iniciado com sucesso",
  "data": {
    "atendimento": {
      "id": 456,
      "senha": {
        "id": 123,
        "numero": "DA001",
        "contribuinte_nome": "José da Silva",
        "prioridade": "normal"
      },
      "inicio": "2024-01-25T14:35:00.000Z"
    }
  }
}
POST /senhas/{id}/finalizar-atendimento
Requer autenticação

Finalizar atendimento em andamento

Request Body:

{
  "observacoes": "Atendimento realizado com sucesso",
  "avaliacao": 5  // Opcional: 1 a 5
}

Response (200 OK):

{
  "status": "success",
  "message": "Atendimento finalizado com sucesso",
  "data": {
    "atendimento": {
      "id": 456,
      "duracao_minutos": 15,
      "avaliacao": 5
    }
  }
}
POST /senhas/{id}/cancelar
Requer autenticação

Cancelar atendimento (marcar como não atendido)

Request Body:

{
  "motivo": "Contribuinte não compareceu"
}
POST /senhas/{id}/encaminhar
Requer autenticação

Encaminhar senha para outro setor

Request Body:

{
  "setor_destino_id": 2,
  "observacoes": "Necessita análise jurídica"
}

Response (200 OK):

{
  "status": "success",
  "message": "Senha encaminhada com sucesso",
  "data": {
    "senha": {
      "id": 123,
      "numero": "DA001",
      "setor_atual": {
        "id": 2,
        "sigla": "JU",
        "nome": "Jurídico"
      },
      "posicao_fila": 3
    }
  }
}
GET /senhas/proxima
Requer autenticação

Obter próxima senha da fila do setor do funcionário

Response (200 OK):

{
  "status": "success",
  "data": {
    "proxima_senha": {
      "id": 124,
      "numero": "DA002",
      "contribuinte_nome": "Maria Santos",
      "prioridade": "alta",
      "tempo_espera_minutos": 45,
      "observacoes": null
    }
  }
}
GET /senhas/estatisticas
Requer autenticação

Obter estatísticas de senhas

Query Parameters:

  • setor_id (integer): Filtrar por setor (opcional)
  • data (string): Data específica (padrão: hoje)
GET /senhas/relatorio
Requer autenticação

Gerar relatório de senhas

Query Parameters:

  • data_inicio (string): Data inicial (obrigatório)
  • data_fim (string): Data final (obrigatório)
  • setor_id (integer): Filtrar por setor (opcional)

⚠️ Limite: Intervalo máximo de 90 dias.

🌐 Endpoints Públicos

GET /senhas/publico/fila/{setor_id}
Público

Visualizar fila de atendimento (para TVs/monitores)

Response (200 OK):

{
  "status": "success",
  "data": {
    "setor": {
      "id": 1,
      "sigla": "DA",
      "nome": "Dívida Ativa"
    },
    "em_atendimento": [
      {
        "numero": "DA015",
        "funcionario": "João Silva",
        "inicio": "14:25"
      }
    ],
    "fila": [
      {
        "posicao": 1,
        "numero": "DA016",
        "prioridade": "urgente",
        "tempo_espera": "14:30"
      },
      {
        "posicao": 2,
        "numero": "DA017",
        "prioridade": "normal",
        "tempo_espera": "14:35"
      }
    ],
    "total_espera": 8
  }
}
GET /senhas/publico/ultimas-chamadas
Público

Últimas senhas chamadas (para painel)

Query Parameters:

  • limite (integer): Quantidade de senhas (padrão: 5, máx: 10)

Response (200 OK):

{
  "status": "success",
  "data": {
    "ultimas_chamadas": [
      {
        "senha": "DA015",
        "setor": "DA",
        "guiche": "João Silva",
        "horario": "14:25:30"
      },
      {
        "senha": "JU008",
        "setor": "JU",
        "guiche": "Maria Santos",
        "horario": "14:24:15"
      }
    ]
  }
}

⚠️ Tratamento de Erros

Códigos de Status HTTP

Código Significado Quando ocorre
200 OK Requisição bem-sucedida
201 Created Recurso criado com sucesso
401 Unauthorized Token inválido ou ausente
403 Forbidden Sem permissão para acessar recurso
404 Not Found Recurso não encontrado
409 Conflict Conflito (ex: email duplicado)
422 Unprocessable Entity Erro de validação
500 Internal Server Error Erro interno do servidor

Formato de Erro

Todos os erros seguem o mesmo formato:

{
  "status": "error",
  "message": "Descrição do erro",
  "errors": [
    "Detalhes específicos do erro"
  ]
}

Exemplo de Erro de Validação (422)

{
  "status": "error",
  "errors": {
    "nome": "Nome deve ter pelo menos 3 caracteres",
    "email": "Email inválido",
    "senha": "Senha deve ter pelo menos 8 caracteres"
  }
}

🧪 Testando a API

Com cURL

Login:

curl -X POST https://ramon.tech/apis/atendimento/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "joao.silva@secretaria.gov.br", "senha": "12345678"}'

Requisição autenticada:

curl -X GET https://ramon.tech/apis/atendimento/funcionarios \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

Com JavaScript (Fetch API)

// Login
const login = async () => {
  const response = await fetch('https://ramon.tech/apis/atendimento/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'joao.silva@secretaria.gov.br',
      senha: '12345678'
    })
  });

  const data = await response.json();
  const token = data.data.token;

  // Salvar token para uso posterior
  localStorage.setItem('token', token);

  return token;
};

// Fazer requisição autenticada
const fetchFuncionarios = async () => {
  const token = localStorage.getItem('token');

  const response = await fetch('https://ramon.tech/apis/atendimento/funcionarios', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  const data = await response.json();
  console.log(data);
};

Credenciais de Teste

⚠️ Ambiente de Desenvolvimento:

  • Email: joao.silva@secretaria.gov.br
  • Senha: 12345678
  • Setor: DA (Dívida Ativa)