Desenvolvedores

Autenticação

A clínica cria a chave em Configurações › Integrações › API pública (quem tem permissão de configurar), escolhe os escopos e, se quiser, a validade. A chave aparece uma vez; o banco guarda só o SHA-256. Toda chamada leva o cabeçalho:

Authorization: Bearer oi_live_…

Base: https://odontoinvest.com.br/api/v1/public. Datas da agenda no fuso da clínica (AAAA-MM-DD); instantes das rotas de leitura em UTC (ISO 8601). O que a chave faz fica na trilha de auditoria da clínica como “Integração · nome da chave”.

Escopos

Rotas

Listas com cursor: mande de volta o next_cursor recebido em cursor, com os mesmos filtros, até has_more ser falso. Consultas: até 31 dias por pedido; títulos: até 93 dias de vencimento; páginas de até 500 itens (padrão 100). O paciente por id é mínimo (nome de exibição, prontuário e situação): nunca contato, documento, anamnese, evolução ou odontograma, e cada leitura vai para a trilha.

Idempotência nos POST

Mande Idempotency-Key (1 a 255 caracteres visíveis, um valor novo por operação) para repetir um POST com segurança: a mesma chave com o mesmo pedido devolve a MESMA resposta por 24 horas, com Idempotent-Replayed: true. A mesma chave com outro pedido responde 422; um pedido igual ainda em andamento, 409. Erro 5xx não fica guardado: pode tentar de novo.

Erros

Sempre {"error": {"code": "...", "message": "..."}}, com a mensagem em português pronta para mostrar.

Limites

• 120 chamadas por minuto por chave (janela deslizante). Toda resposta liberada leva X-RateLimit-Limit e X-RateLimit-Remaining; a recusada, Retry-After.
• Antes de olhar a chave, um teto por IP; chave errada repetida bloqueia o IP por alguns minutos.
• Até 10 chaves ativas por clínica.

Feed de eventos e webhooks

Os mesmos eventos podem ser recebidos de dois jeitos. No feed (GET /events, escopo eventos:read) a integração busca: a primeira leitura usa since (padrão: últimas 24 h; até 30 dias) e as seguintes, after com o next_after recebido. Eventos com menos de 10 segundos entram na leitura seguinte. Nos webhooks de saída (Configurações › Integrações › Webhooks) o Odonto Invest entrega cada evento num endereço https da integração, com nova tentativa e assinatura. O envelope é o mesmo nos dois: só ids, datas, números e valores — nenhum nome, telefone ou dado clínico.

Cada entrega de webhook leva estes cabeçalhos:

• X-OdontoInvest-Timestamp
• X-OdontoInvest-Signature
• X-OdontoInvest-Event
• X-OdontoInvest-Delivery
• X-OdontoInvest-Attempt

A assinatura é v1=<HMAC-SHA256(segredo, "<timestamp>.<corpo bruto>")>; na troca do segredo, vêm duas separadas por vírgula. Recuse carimbos com mais de 5 minutos de diferença. Exemplo em Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

// corpo = texto BRUTO da requisição (antes de JSON.parse)
function assinaturaValida(segredo, cabecalhos, corpo) {
  const ts = cabecalhos['x-odontoinvest-timestamp']
  const recebidas = String(cabecalhos['x-odontoinvest-signature'] ?? '').split(',')
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // anti-replay: 5 minutos
  const esperada = 'v1=' + createHmac('sha256', segredo).update(ts + '.' + corpo).digest('hex')
  return recebidas.some((a) => a.trim().length === esperada.length &&
    timingSafeEqual(Buffer.from(a.trim()), Buffer.from(esperada)))
}

Política de versão

A v1 só recebe acréscimo: rota nova, campo novo na resposta e parâmetro opcional novo. Nada é removido nem muda de significado — ignore os campos que você não conhece. Uma mudança incompatível vira /api/v2, com aviso antes.

Histórico de mudanças

1. 4 de outubro de 2026

   API pública: feed de eventos, calendário assinável e documentação completa

   A API v1 ganhou o feed de eventos com cursor, o calendário iCal do membro e a documentação OpenAPI na página de desenvolvedores. Só acréscimos: nada mudou de significado.

2. 24 de setembro de 2026

   API pública v1 e webhooks de saída

   Chaves de integração por clínica, com escopos, e webhooks assinados para sistemas externos. Tudo desligado até a clínica criar a chave.