Documentação dos Produtos da AGSinn

# Documentação da API

Esta documentação descreve os endpoints da API do Liber, que definem os pontos de comunicação usando JSON entre o aplicativo Android e o servidor por meio de HTTP para controle de acesso utilizando cartões MIFARE. Cada endpoint representa uma funcionalidade específica, como autenticar um usuário ou registrar um cartão.

# Métodos HTTP

A API do Liber utiliza os métodos HTTP POST e GET para comunicação:

  • POST: Usado para enviar dados ao servidor, como para criar ou atualizar informações.
  • GET: Usado para solicitar dados do servidor.

# Estrutura da API

A API do Liber é organizada em quatro módulos principais:

  1. CredentialApi: Gerencia as credenciais dos usuários, incluindo validação e desabilitação de cartões.
  2. MarkupApi: Lida com o registro e sincronização de marcações.
  3. SessionApi: Gerencia a sessão dos usuários, incluindo a autenticação e o controle de sessão.
  4. StatusApi: Envio de informações do estado do dispositivo para o servidor.

# URLs dos Endpoints e Convenções

As URLs dos endpoints da API LIBER são configuráveis e podem variar de acordo com a implementação. Dessa forma, ao longo da documentação os trechos que se referem às URLs serão identificados por {URL_API}. Da mesma forma, {token} representa o token de autenticação a ser utilizado na requisição, e {deviceId} representa o ID do dispositivo. Os parâmetros entre parênteses no corpo da requisição e na resposta representam os campos de dados que são enviados ou recebidos, respectivamente.

# Endpoints:

# CredentialApi

# 1.1. validateCredential

Valida as credenciais do usuário através do número do crachá, leitor e ID do dispositivo. Retorna informações básicas do usuário, como nome, número do documento e foto, caso a validação seja bem-sucedida.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_VALIDACAO_CRACHA}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados para validação da credencial
{
    "cracha":"123456789", //número do crachá
    "leitor":"leitor001", //ID do leitor
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "location": { //dados de localização (opcional)
        "latitude": "-23.5505",
        "longitude": "-46.6333",
        "altitude": "678"
    }
}
  • Resposta: informa se a validação foi bem-sucedida e dados do usuário
{
    "success":true, //indica se a validação foi bem-sucedida
    "msg":"Credencial validada com sucesso", //mensagem de resposta
    "codigo":201, //código da mensagem
    "first_name":"João", //primeiro nome do usuário
    "document_number":"12345678901", //número do documento do usuário
    "foto":"https://exemplo.com/foto.jpg" //URL da foto do usuário
}

# 1.2. disableCard

Desabilita um cartão, realizando uma baixa provisória.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados para desabilitar o cartão
{
    "numero_cartao":"1234567890", //número do cartão a ser desabilitado
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "id_leitor":"leitor001", //ID do leitor
    "operacao":"baixar_provisorio", //operação a ser realizada
    "location": { //dados de localização (opcional)
        "latitude":"-23.5505",
        "longitude":"-46.6333",
        "altitude":"760"
    }
}
  • Resposta: informa se a desabilitação foi bem-sucedida
{
    "success":true, //indica se a desabilitação foi bem-sucedida
    "msg":"Cartão desabilitado com sucesso.", //mensagem de resposta
    "codigo":201 //código da mensagem
}

# 1.3. getUpdates

Obtém atualizações de dados do servidor, incluindo informações sobre crachás e descrições de bloqueio.
  • Método: GET
  • URL: {URL_API}/{ENDPOINT_OBTER_DADOS}?operacao=obter_dados&id_dispositivo={deviceId}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Resposta: dados das atualizações
{
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "success":true, //indica se a requisição foi bem-sucedida
    "msg":"Dados obtidos com sucesso.", //mensagem de resposta
    "operacao":"confirmar_dados", //operação realizada
    "requer_confirmacao":false, //indica se é necessária confirmação para aplicar as atualizações
    "crachas": { //dados dos crachás
        "total_save":1, //total de crachás a serem salvos
        "total_remove":0, //total de crachás a serem removidos
        "data_save":[ //lista de crachás a serem salvos
            {
                "id_dispositivo":"dispositivo123",
                "tipo_cracha":"Mifare",
                "numero_cartao":"1234567890",
                "nome":"João da Silva",
                "numero_doc":"12345678901",
                "codigo_acesso":"1234"
            }
        ],
        "data_remove":[] //lista de crachás a serem removidos
    },
    "descricao_bloq": { //dados das descrições de bloqueio
        "total_save":0, //total de descrições de bloqueio a serem salvas
        "total_remove":0, //total de descrições de bloqueio a serem removidas
        "data_save":[], //lista de descrições de bloqueio a serem salvas
        "data_remove":[] //lista de descrições de bloqueio a serem removidas
    }
}

# 1.4. confirmUpdates

Confirma as atualizações recebidas pela requisição `getUpdates`.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_OBTER_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): (O mesmo objeto retornado por getUpdates)
{
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "success":true, //indica se a requisição foi bem-sucedida
    "msg":"Dados obtidos com sucesso.", //mensagem de resposta
    "operacao":"confirmar_dados", //operação realizada
    "requer_confirmacao":false, //indica se é necessária confirmação para aplicar as atualizações
    "crachas": { //dados dos crachás
    "total_save":1, //total de crachás a serem salvos
    "total_remove":0, //total de crachás a serem removidos
    "data_save":[ //lista de crachás a serem salvos
    {
        "id_dispositivo":"dispositivo123",
        "tipo_cracha":"Mifare",
        "numero_cartao":"1234567890",
        "nome":"João da Silva",
        "numero_doc":"12345678901",
        "codigo_acesso":"1234"
    }
    ],
    "data_remove":[] //lista de crachás a serem removidos
},
    "descricao_bloq": { //dados das descrições de bloqueio
    "total_save":0, //total de descrições de bloqueio a serem salvas
    "total_remove":0, //total de descrições de bloqueio a serem removidas
    "data_save":[], //lista de descrições de bloqueio a serem salvas
    "data_remove":[] //lista de descrições de bloqueio a serem removidas
}
}
  • Resposta: informa se a confirmação foi bem-sucedida
{
    "success":true, //indica se a confirmação foi bem-sucedida
    "msg":"Atualizações confirmadas com sucesso." //mensagem de resposta
}

# 1.5. validateFaceCredential

Valida as credenciais do usuário através do reconhecimento facial e ID do dispositivo. Retorna informações básicas do usuário, como nome, número do documento e foto, caso a validação seja bem-sucedida.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados para a validação facial
{
    "foto":"https://exemplo.com/foto.jpg", //foto
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "operacao":"reconhecimento_facial", //operação a ser realizada
    "location": { //dados de localização (opcional)
        "latitude":"-23.5505",
        "longitude":"-46.6333",
        "altitude":"760"
    }
}
  • Resposta: informa se a validação foi bem-sucedida e dados do usuário
{
    "success":true, //indica se a validação foi bem-sucedida
    "msg":"Credencial validada com sucesso", //mensagem de resposta
    "codigo":201, //código da mensagem
    "first_name":"João", //primeiro nome do usuário
    "document_number":"12345678901", //número do documento do usuário
    "foto":"https://exemplo.com/foto.jpg" //URL da foto do usuário
}

# 2. MarkupApi

# 2.1. syncOfflineMarkups

Sincroniza as marcações offline realizadas pelo dispositivo com o servidor.

  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados das marcações offline
{
    "operacao":"enviar_dados", //operação a ser realizada
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "qtd_marcacoes":1, //quantidade de marcações a serem sincronizadas
    "data":[ //lista de marcações
        {
            "numero_cartao":"1234567890", //número do cartão
            "leitor":"leitor001", //ID do leitor
            "codigo":1, //código da mensagem
            "sincronizado":false, //indica se a marcação já foi sincronizada
            "data":"2023-12-27 10:00:00", //data e hora da marcação
            "location": { //dados de localização da marcação
                "latitude":"-23.5505",
                "longitude":"-46.6333",
                "altitude":"760"
            }
        }
    ]
}
  • Resposta: informa se a sincronização foi bem-sucedida
{

    "success": true,
    "msg": "Marcações sincronizadas com sucesso."
}

# 3. SessionApi (Autenticação)

# 3.1 authenticate

Autentica um usuário no sistema usando o número do crachá.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados para autenticação do usuário
{
    "cracha":"123456789", //número do crachá
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "operacao":"autenticar", //operação a ser realizada
    "location": { //dados de localização (opcional)
        "latitude":"-23.5505",
        "longitude":"-46.6333",
        "altitude":"760"
    }
}
  • Resposta: informa se a autenticação foi bem-sucedida e dados do usuário
{
    "success":true, //indica se a autenticação foi bem-sucedida
    "msg":"Usuário autenticado com sucesso.", //mensagem de resposta
    "codigo":200, //código da mensagem
    "first_name":"João", //primeiro nome do usuário
    "foto":"https://exemplo.com/foto.jpg" //URL da foto do usuário (opcional)
}

# 3.2 registerAuthCard

Registra um novo cartão para autenticação.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados para registro do cartão
{
    "numero_cartao":"9876543210", //número do cartão a ser registrado
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "operacao":"cadastrar_auth", //operação a ser realizada
    "location": { //dados de localização (opcional)
        "latitude":"-23.5505",
        "longitude":"-46.6333",
        "altitude":"760"
    }
}
  • Resposta: informa se o registro foi bem-sucedido
{
    "success":true, //indica se o registro foi bem-sucedido
    "msg":"Cartão registrado com sucesso.", //mensagem de resposta
    "codigo":201 //código da mensagem
}

# 3.3 getOnlineAuthCards

Obtém a lista de cartões autorizados para autenticação online.
  • Método: GET
  • URL: {URL_API}/{ENDPOINT_OBTER_DADOS}?operacao=obter_auth_cards&id_dispositivo={deviceId}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Resposta: lista de cartões autorizados online
{
    "success":true, //indica se a requisição foi bem-sucedida
    "msg":"Cartões obtidos com sucesso.", //mensagem de resposta
        "crachas":[ //lista de cartões autorizados
        {
            "numero_cartao":"1234567890", //número do cartão
            "nome":"João da Silva" //nome do usuário
        },
        {
            "numero_cartao":"9876543210", //número do cartão
            "nome":"Maria Souza" //nome do usuário
        }
    ]
}

# 3.4 syncOfflineAuths

Envia as autenticações realizadas offline para o servidor.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_ENVIAR_DADOS}
  • Cabeçalhos:
    • Authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados das autenticações offline
{
    "operacao":"sync_auths", //operação a ser realizada
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "qtd_auths":2, //quantidade de autenticações a serem sincronizadas
    "data":[ //lista de autenticações offline
        {
            "numero_cartao":"1234567890", //número do cartão
            "nome":"João da Silva", //nome do usuário
            "data":"2023-12-27 10:00:00", //data e hora da autenticação
                "location": { //dados de localização da autenticação
                "latitude":"-23.5505",
                "longitude":"-46.6333",
                "altitude":"760"
            }
        },
        {
            "numero_cartao":"9876543210", //número do cartão
            "nome":"Maria Souza", //nome do usuário
            "data":"2023-12-27 10:15:00", //data e hora da autenticação
            "location": { //dados de localização da autenticação
                "latitude":"-23.5500",
                "longitude":"-46.6330",
                "altitude":"762"
            }
        }
    ]
}
  • Resposta: informa se a sincronização foi bem-sucedida
{
    "success":true, //indica se a sincronização foi bem-sucedida
    "msg":"Autenticações sincronizadas com sucesso." //mensagem de resposta
}

# 4. StatusApi

# 4.1 getStatus

Envia informações de status do dispositivo para o servidor.
  • Método: POST
  • URL: {URL_API}/{ENDPOINT_CHECK_STATUS}
  • Cabeçalhos:
    • authorization: Bearer {token}
  • Parâmetros da Requisição (corpo): dados de status do dispositivo

{
    "id_dispositivo":"dispositivo123", //ID do dispositivo
    "crachas_offline":5, //quantidade de crachás offline
    "marcacoes_offline":10, //quantidade de marcações offline
    "location": { //dados de localização do dispositivo
    "latitude":"-23.5505",
    "longitude":"-46.6333",
    "altitude":"760"
}
}
  • Resposta: informa se o envio do status foi bem-sucedido
{
    "success":true, //indica se o envio do status foi bem-sucedido
    "msg":"Status enviado com sucesso." //mensagem de resposta
}

←