Autenticação, permissões e limites

Token por conta

Toda chamada leva o token da conta no cabeçalho Authorization: Bearer clk_.... Os tokens são criados no painel (Configurações > Conta > Avançado > Integrações), até 10 ativos por conta, cada um com nome, permissões e validade (sem prazo, 30, 90 ou 365 dias). O painel mostra o último uso e revoga na hora. O CliLink guarda só um resumo irreversível (hash) do token: se perder, crie outro.

O token age como o próprio profissional, na conta dele. A sessão do painel (cookie) não vale nas rotas da API: só o token. Chamadas vêm do seu servidor; não coloque o token em código que roda no navegador do paciente.

Permissões (escopos)

Marque só o que o sistema precisa. Quem pode mudar também pode ler o mesmo grupo (agenda:write vale como agenda:read).

Limites

• 60 pedidos por minuto por token e 120 por conta (somando os tokens) e por endereço IP. Passou: 429 com Retry-After: 60.
• Corpo do pedido até 64 KB. Listas com até 200 itens por página.
• Horários livres: até 31 dias por pedido. Consultas: até 93 dias por pedido.

Resposta e erro

Sempre JSON, sem cache. Sucesso: { "ok": true, "data": ... }. Erro: { "ok": false, "erro": { "codigo", "mensagem" } }, com campos, avisos ou escopos_necessarios quando ajudam. A mensagem é em português e pode ser mostrada para quem usa o seu sistema. O campo error (code e message) continua igual para quem já usava a API antes.

{
  "ok": false,
  "erro": {
    "codigo": "escopo_insuficiente",
    "mensagem": "Este token não tem o escopo agenda:write. Crie outro token com ele no painel.",
    "escopos_necessarios": ["agenda:write"]
  },
  "error": { "code": "escopo_insuficiente", "message": "Este token não tem o escopo agenda:write. Crie outro token com ele no painel." }
}

Toda resposta traz x-clilink-requisicao: mande esse valor se falar com o suporte.

Paginação por cursor

Listas devolvem proximo_cursor. Para a próxima página, mande o valor em cursor (com os mesmos filtros). null quer dizer que acabou. O cursor não tem significado fora da API: não monte um.

async function todosOsPacientes() {
  const todos = [];
  let cursor = null;
  do {
    const url = new URL("https://app.clilink.bio/api/v1/pacientes");
    url.searchParams.set("limite", "200");
    if (cursor) url.searchParams.set("cursor", cursor);
    const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.CLILINK_TOKEN}` } });
    const corpo = await r.json();
    if (!corpo.ok) throw new Error(corpo.erro.mensagem);
    todos.push(...corpo.data);
    cursor = corpo.proximo_cursor;
  } while (cursor);
  return todos;
}

Idempotency-Key

Nos POST, mande Idempotency-Key com um valor novo por ação (um UUID serve; de 8 a 255 caracteres). Se o mesmo pedido chegar de novo com a mesma chave em até 24 horas, a API devolve a mesma resposta, com Idempotent-Replayed: true, sem marcar, cadastrar ou cobrar outra vez. A mesma chave com outro corpo dá 422. Resposta 5xx ou 429 não fica guardada: pode tentar de novo com a mesma chave.

Fuso e datas

Instantes em ISO 8601 (UTC), como inicio e fim. Para marcar e remarcar, mande dia (AAAA-MM-DD) e hora (HH:MM) no fuso da agenda do consultório, o mesmo que volta em fuso. Valores em dinheiro vêm em centavos (valor_centavos).