Guia 3/12

Autenticação e âmbitos

As integrações autenticam-se com OAuth 2.0 client credentials em POST https://anagen.pt/api/v1/oauth/token (corpo em formulário ou JSON).

Pedido

• grant_type=client_credentials
• client_id e client_secret (no corpo ou em HTTP Basic)
• scope (opcional, separado por espaços): um subconjunto dos âmbitos concedidos à integração; sem ele, todos os concedidos.

Resposta

Resposta OAuth padrão — fora do envelope da API. Os erros seguem o RFC 6749: invalid_client, invalid_grant, invalid_scope, unsupported_grant_type.

{
  "access_token": "8f3a…c21",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "crm.leads:editar agenda:ver"
}

{
  "error": "invalid_client",
  "error_description": "Credenciais inválidas."
}

Âmbitos

Cada âmbito corresponde a uma linha da matriz de permissões da clínica: modulo:ver (ler) ou modulo:editar (ler e escrever). Dentro da clínica da integração o alcance é «todos os registos». Os módulos de administração (admin.*) nunca estão disponíveis para integrações. Exemplos: crm.leads:editar, agenda:ver, financeiro.pagamentos:ver, indicadores.vendas:ver, equipa.tarefas:editar. A lista completa está na referência (esquema de segurança integracao).

Validade e revogação

• O token de acesso vale 3600 s; peça outro antes de expirar (neste fluxo não há token de renovação).
• Mudar os âmbitos, as redes, o estado ou a validade da integração — ou rodar o segredo — termina logo todos os seus tokens (401 token_revogado).
• Restrição por endereço de origem: 403 ip_nao_permitido; origem do navegador não autorizada por CORS: 403 origem_nao_permitida.

As pessoas da equipa (app) e os pacientes (portal) entram por processos interativos diferentes; os endpoints do portal do paciente nunca aceitam tokens de integração.