Autenticação¶

Visão Geral¶

A API de Integração SISBOV utiliza um sistema de autenticação em duas camadas:

Par de chaves (Access Key + Secret Key) — identificação do sistema integrante
Token JWT — usado como bearer em todas as requsições subsequentes

Obtenção das credenciais

O par de chaves (Access Key e Secret Key) é gerado diretamente na aplicação web SISBOV. Os administradores da certificadora devem acessar o portal e cadastrar as chaves antes de iniciar a integração.

Etapa 1 — Cadastro do Par de Chaves¶

Acesse o portal web da certificadora e registre seu par de chaves de acesso. O processo é feito pelo responsável da certificadora diretamente na interface administrativa.

Cadastro do par de chaves

Etapa 2 — Autenticação na API¶

Com as credenciais em mãos, faça uma requisição ao endpoint de autenticação para obter o token JWT. Solicitação do token

Endpoint de Autenticação¶

POST /integracao/auth/system

Headers Obrigatórios¶

Header	Tipo	Obrigatório	Descrição	Exemplo
`X-ACCESS-KEY`	string	✅	Chave de acesso pública do sistema	`cert_abc123`
`X-SECRET-KEY`	string	✅	Chave secreta privada do sistema	`sk_xyz987...`
`Content-Type`	string	✅	Tipo do conteúdo	`application/json`

Atenção: A X-SECRET-KEY nunca deve ser exposta em logs, repositórios ou ambientes públicos.

Resposta de Sucesso (200)¶

{
  "access_token": "<jwt-token-gerado>"
}

Resposta de Erro (401)¶

HTTP/1.1 401 Unauthorized

Exemplo cURL¶

curl -X POST https://api-cert-hom.sisbov.agro.br/integracao/auth/system \
  -H "X-ACCESS-KEY: {{access_key}}" \
  -H "X-SECRET-KEY: {{secret_key}}" \
  -H "Content-Type: application/json"

Etapa 3 — Uso do Token JWT¶

Após obter o token, inclua-o como Bearer Token no header Authorization de todas as requisições subsequentes.

Uso do token nas requisições

# Exemplo de uso do token JWT
curl -X GET "https://api-cert-hom.sisbov.agro.br/integracao/animal/{{id}}" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"

Estrutura do Token JWT¶

O token retornado é um JSON Web Token (JWT) que contém as seguintes informações internas:

Campo	Descrição
`sub`	E-mail do usuário autenticado
`upn`	Username (e-mail) no padrão MicroProfile
`groups`	Perfil(s) do usuário (ex: `["certificadora"]`)
`iss`	Issuer — URL do ambiente que gerou o token
`iat`	Data/hora de emissão
`exp`	Data/hora de expiração

Validade do Token

O token JWT possui tempo de expiração configurado pelo sistema. Quando expirar, uma nova autenticação deve ser realizada para obter um novo token. Requisições com token expirado retornam HTTP 401.

Validações de Segurança¶

A autenticação verifica as seguintes condições antes de emitir o token:

Condição	Mensagem de Erro
Chaves em branco ou nulas	`"Credenciais invalidas."`
Usuário inativo no sistema	`"Usuário desabilitado no sistema."`
Técnico sem supervisor vinculado	`"Usuário não vinculado a um supervisor no sistema."`
RT sem responsável técnico	`"Usuário não vinculado a um responsável técnico no sistema."`

Lógica de Negócio da Autenticação (Portugol)¶

FUNÇÃO autenticarSistema(accessKey, secretKey):
  SE accessKey ESTÁ_VAZIO OU secretKey ESTÁ_VAZIO ENTÃO
    RETORNAR ERRO 401 "Credenciais invalidas."
  FIM_SE

  usuario ← BUSCAR_USUARIO_POR_ACCESS_KEY(accessKey)

  SE usuario NÃO_ENCONTRADO ENTÃO
    RETORNAR ERRO 401 "Credenciais invalidas."
  FIM_SE

  SE usuario.secretKey ≠ secretKey ENTÃO
    RETORNAR ERRO 401 "Credenciais invalidas."
  FIM_SE

  SE usuario.ativo = FALSO ENTÃO
    RETORNAR ERRO 401 "Usuário desabilitado no sistema."
  FIM_SE

  SE usuario.perfil = "técnico" ENTÃO
    SE usuario.supervisor = NULO ENTÃO
      RETORNAR ERRO 401 "Usuário não vinculado a um supervisor no sistema."
    FIM_SE
  FIM_SE

  token ← GERAR_JWT(usuario)
  RETORNAR 200 { access_token: token }
FIM_FUNÇÃO

Diagrama do Fluxo de Autenticação¶

Certificadora                    API SISBOV
     │                               │
     │── POST /auth/system ─────────>│
     │   X-ACCESS-KEY: {{key}}       │
     │   X-SECRET-KEY: {{secret}}    │
     │                               │── Valida credenciais
     │                               │── Gera token JWT
     │<── 200 { access_token: "..." }─│
     │                               │
     │── GET /animal/{id} ──────────>│
     │   Authorization: Bearer ...   │
     │                               │── Valida JWT
     │<── 200 { dados do animal }  ──│

Códigos de Status¶

Código	Descrição
`200`	Autenticação bem-sucedida — token gerado
`401`	Credenciais inválidas ou usuário não autorizado