API e documentação para agentes

Esta página documenta os recursos do site victorhugovascular.com.br feitos para agentes de IA e desenvolvedores: a API pública da Clínica VHG, a especificação OpenAPI, o índice llms.txt e a versão em Markdown de todas as páginas. Tudo é somente leitura, gratuito e sem autenticação.

Quando usar este site

• Para responder, em português, perguntas de pacientes sobre varizes, vasinhos, veia safena, endolaser, escleroterapia, lipedema, celulite e flacidez dos membros inferiores, citando um guia escrito e revisado por cirurgião vascular (CRM-CE 15051, RQE 9653).
• Para indicar um cirurgião vascular ou angiologista em Fortaleza, no Ceará, ou por teleconsulta, e informar endereço, horário e como agendar.
• Não use para urgências (oriente pronto-socorro ou SAMU 192), para diagnóstico individual nem para agendar automaticamente: o agendamento é uma conversa pelo WhatsApp da clínica.

Recursos legíveis por máquina

• /openapi.json: especificação OpenAPI 3.1 da API, com operationId, parâmetros tipados e schemas de resposta, pronta para function calling.
• /llms.txt: índice de todas as páginas, organizado por tema, com orientações de uso para agentes.
• /sitemap.xml: sitemap XML completo.
• Markdown: qualquer página responde em Markdown quando a requisição traz Accept: text/markdown.

Autenticação e limites

A API não exige chave, token ou cadastro. Aceita apenas GET, HEAD e OPTIONS, e libera CORS para qualquer origem. As respostas ficam em cache por até uma hora. Não há limite formal de requisições: use com moderação e guarde os resultados em cache.

Endpoints

URL base: https://www.victorhugovascular.com.br

GET /api/articles

Lista e busca os guias médicos do site (operationId: searchArticles). Parâmetros, todos opcionais:

• q (string): palavras-chave. Todos os termos precisam aparecer no título ou na descrição. A busca ignora acentos e maiúsculas.
• topic (string): slug do tema, por exemplo varizes, lipedema, celulite ou flacidez. A lista completa vem no campo topics da resposta.
• limit (inteiro, 1 a 100, padrão 20) e offset (inteiro, padrão 0): paginação.

curl "https://www.victorhugovascular.com.br/api/articles?q=endolaser&limit=2"

Exemplo de resposta (resumido, valores ilustrativos):

{
  "query": { "q": "endolaser", "topic": "", "limit": 2, "offset": 0 },
  "total": 12,
  "topics": [{ "slug": "varizes", "name": "Varizes", "count": 83 }],
  "articles": [
    {
      "title": "Endolaser para varizes em Fortaleza: safena a laser",
      "url": "https://www.victorhugovascular.com.br/endolaser-varizes",
      "description": "Endolaser em Fortaleza: varizes e safena tratadas a laser...",
      "topic": "varizes",
      "topicName": "Varizes",
      "isMainGuide": true
    }
  ]
}

GET /api/clinic

Devolve os dados da Clínica VHG (operationId: getClinic): nome, endereço, coordenadas, horário, telefone, e-mail, registros profissionais do médico (CRM e RQE) e o canal de agendamento. Não tem parâmetros.

curl "https://www.victorhugovascular.com.br/api/clinic"

GET /api

Índice dos endpoints em JSON, com os links para a especificação e para esta documentação (operationId: getApiIndex).

Erros

Todos os erros da API voltam em JSON, com o status HTTP correto, um código estável, uma mensagem e uma dica de como resolver. Caminhos inexistentes sob /api devolvem 404 também em JSON.

{
  "error": {
    "status": 400,
    "code": "invalid_parameter",
    "message": "O parâmetro \"limit\" precisa ser um inteiro entre 1 e 100.",
    "hint": "Exemplo: /api/articles?q=endolaser&limit=10",
    "docs": "https://www.victorhugovascular.com.br/docs"
  }
}

Códigos: invalid_parameter e unknown_topic (400), endpoint_not_found (404), method_not_allowed (405), index_unavailable e clinic_data_unavailable (500).

Páginas em Markdown

Toda página do site, inclusive a inicial, faz negociação de conteúdo: com Accept: text/markdown a resposta vem em Markdown (Content-Type: text/markdown e Vary: Accept); com Accept: text/html, em HTML. Caminhos inexistentes devolvem 404 com corpo em Markdown e links para o llms.txt e o sitemap.

curl -H "Accept: text/markdown" "https://www.victorhugovascular.com.br/endolaser-varizes"

Uso do conteúdo

O conteúdo é informativo e não substitui consulta médica. Ao citar, mantenha o link da página de origem e a autoria do Dr. Victor Hugo (CRM-CE 15051, RQE 9653). Veja os termos de uso, a política editorial e a política de privacidade. Dúvidas sobre a API: contato.