Referência API
Interfaces para desenvolvedores: endpoints públicos, widget de chat, início de sessão e a API REST com chaves de API.
A referência da API descreve as interfaces da Zentor App que pode chamar a partir dos seus próprios websites e programas: endpoints públicos para formulários, o configurador de produto e conteúdo, o widget de chat, o chatbot de demonstração, bem como o início de sessão, incluindo o início de sessão único (SSO). Cada página de endpoint indica o método, o caminho, a autenticação, os parâmetros, um exemplo de pedido e resposta, e os códigos de erro documentados.
Autenticação: os endpoints de formulários, configurador de produto e conteúdo são acessíveis sem iniciar sessão. Os endpoints do widget de chat esperam o token de incorporação do seu widget no cabeçalho `X-Widget-Token` e só aceitam chamadas a partir dos domínios aprovados para esse widget. Os endpoints de início de sessão emitem um token de acesso (JWT) e um token de renovação (refresh token) para as sessões de utilizador.
Acesso à API com chave de API: para os seus próprios programas e ligações servidor a servidor, a API REST está disponível no URL base `https://zentor-app.de/api/v1`. A Zentor ativa o acesso à API para a sua conta mediante pedido. Em seguida, os administradores criam as suas próprias chaves no painel, em «Chaves de API», e definem as suas permissões (scopes) – para marcações e reservas, chatbot, comunicação, ficheiros, base de conhecimento, relatórios e dados web. Cada área tem um scope de leitura (`<área>.read`, apenas GET) e um scope de escrita (`<área>.write`, que inclui a leitura), por exemplo `appointments.read` ou `knowledge.write`. Envie a chave no cabeçalho `Authorization: Bearer <chave de API>` ou, em alternativa, no cabeçalho `X-API-Key`. Use `GET /api/v1/me` para verificar a que conta e a que scopes uma chave está associada.
A chave completa é exibida apenas uma vez, no momento da criação. Guarde-a em segurança e exclusivamente do lado do servidor, nunca em código do navegador ou em aplicações móveis. As chaves podem receber uma data de expiração, ser rodadas e revogadas. Através da API REST só estão acessíveis as funções incluídas no seu pacote, e todos os dados permanecem limitados à sua conta. Erros típicos: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` ou `API_KEY_REVOKED` (chave em falta, incorreta, expirada ou revogada), 403 `API_ACCESS_NOT_ENABLED` (acesso à API não ativado para a conta), 403 `API_SCOPE_MISSING` (falta à chave o scope necessário), 403 `TENANT_NOT_ACTIVE` ou `TENANT_LOCKED` (conta inativa ou bloqueada) e 404 `API_ENDPOINT_NOT_AVAILABLE` (o endpoint não está disponível através da API REST).
Respostas e limites: todos os endpoints respondem com JSON. Uma resposta bem-sucedida tem um estado 2xx e `"ok": true`; uma resposta de erro contém um código de erro legível por máquina (no campo `error` ou `error.code`) e uma mensagem. Por endereço IP são possíveis 2000 pedidos em 15 minutos; para os endpoints de formulários, confirmação e início de sessão aplicam-se limites mais rigorosos, indicados na respetiva página. Em caso de exceder o limite, o servidor responde 429 `RATE_LIMIT_EXCEEDED`. Os endpoints marcados como não idempotentes não devem ser repetidos automaticamente após uma falha de ligação, pois podem surgir pedidos ou mensagens duplicadas.
Transmita palavras-passe, tokens, chaves de API e códigos de confirmação apenas no corpo do pedido ou em cabeçalhos via HTTPS — nunca em URLs, registos ou pedidos de suporte.