API para automação de laudos
A API da Laudos.AI existe para conectar, não para forçar uma nova interface. O objetivo é reduzir fricção onde o serviço já trabalha: criar exames, recuperar laudos, disparar eventos de assinatura e conectar portais e apps internos. A integração boa começa pequena e auditável — entrada bem definida, saída previsível (texto, PDF, status, evento, DICOM SR) e operação observável com logs. O contrato segue convenções REST que a TI hospitalar já conhece: recursos identificados por URL estável, verbos HTTP com semântica esperada (POST cria, GET recupera, PATCH atualiza parcialmente), corpo em JSON e versionamento explícito no caminho (por exemplo, /v1) para que mudanças incompatíveis nunca quebrem um integrador em produção. Cada requisição que cria ou altera recurso aceita uma chave de idempotência, de modo que um reenvio após timeout de rede não duplique o exame. O ciclo de vida do laudo é assíncrono por natureza — a estruturação leva tempo —, então a API combina criação síncrona do recurso com notificação posterior por webhook, em vez de obrigar o integrador a ficar em polling. O radiologista continua revisando, editando e assinando; a API acelera a estrutura e o fluxo administrativo, não toma a decisão clínica.
O que é API
Uma API REST com webhooks que expõe as operações essenciais do fluxo de laudagem assistida: criar e atualizar exames, recuperar o laudo estruturado, acompanhar status e ser notificado por evento (por exemplo, laudo liberado para revisão ou assinado). O recurso central é o exame, que carrega identificadores (do exame, do paciente, do estudo), modalidade e contexto clínico; a partir dele nascem os recursos laudo (com texto, campos e referências a PDF/DICOM SR) e os eventos de ciclo de vida. As respostas usam códigos HTTP convencionais — 201 ao criar, 200 ao recuperar, 202 quando o processamento ficou enfileirado, 4xx para erro do cliente e 5xx para falha do servidor — e um corpo de erro estruturado com código legível por máquina, mensagem e identificador de correlação para rastrear o caso no suporte. A API não substitui telas nem obriga o radiologista a sair do seu viewer — ela conecta os sistemas que já existem, mantendo o médico no controle da revisão e da assinatura.
Como conecta
A integração deve tirar trabalho administrativo, não criar outra tela. A integração boa começa pequena e auditável.
- Autenticação por chave de API (ou OAuth 2.0 client credentials) com escopos e ambientes separados de teste e produção, cada um com sua própria chave.
- POST de criação de exame com identificadores, contexto clínico e modalidade, retornando 201 e um ID de recurso estável mais a URL para acompanhar o laudo.
- Chave de idempotência por requisição de escrita, para que reenvios após timeout não dupliquem exames nem laudos.
- GET do laudo estruturado (texto, campos e PDF/DICOM SR) por ID do exame, com 202 enquanto o processamento ainda está em curso.
- Webhooks HTTPS para eventos do ciclo de vida (laudo gerado, em revisão, assinado, retificado), com payload assinado e cabeçalho de assinatura HMAC para o receptor validar a origem.
- Paginação por cursor e parâmetros de filtro para listar exames e laudos sem varrer toda a base.
- Logs por requisição com identificador de correlação e retorno de erro consistente para troubleshooting da equipe de TI.
Quando faz sentido
Criar exames e recuperar laudos a partir de sistemas internos sem depender de tela.
Disparar e consumir eventos de assinatura e mudança de status em vez de fazer polling constante.
Conectar portais do paciente, apps internos e BI clínico a uma fonte única de laudos.
Orquestrar fluxos próprios (ex.: notificar o solicitante quando um laudo é assinado) sobre uma base estável e versionada.
Por que Laudos.AI
- REST + JSON + webhooks — padrão amplamente conhecido pela TI hospitalar, com semântica HTTP previsível.
- Versionamento explícito no caminho e mudanças incompatíveis isoladas por versão, sem quebrar integradores em produção.
- Idempotência em escritas e entrega de webhook com reentrega, para sobreviver a falhas de rede sem efeitos colaterais.
- Chaves e escopos por ambiente (teste/produção) e logs detalhados para troubleshooting e auditoria.
Escopo técnico
Entrada
POST/PATCH em JSON com identificadores do exame e do paciente, contexto clínico, modalidade e limites de dados confirmados antes de automatizar. Cabeçalho de idempotência opcional para escritas seguras a reenvio.
Saída
Recurso laudo em JSON com texto, campos estruturados, status e links para PDF e DICOM SR quando aplicável. Códigos HTTP convencionais (200/201/202) e corpo de evento nos webhooks.
Operação
Ambiente de teste isolado, limites de taxa (rate limit) com resposta 429 e cabeçalho de retry, e responsável de suporte designado para a fase de implantação.
Erros
Corpo de erro estruturado (código legível por máquina, mensagem e ID de correlação), 4xx para erro do cliente, 5xx para falha do servidor e diretrizes de retry seguro para 429/5xx.
Monitoramento
Logs por requisição correlacionados por ID, painel de entrega de webhooks com tentativas e reentregas, e endpoint de verificação de saúde para sondas externas.
Padrões suportados
REST / JSON
Recursos por URL estável, verbos HTTP com semântica padrão e versionamento explícito no caminho.
Webhooks (HMAC)
Notificações de evento assinadas por HMAC, com reentrega e janela de tolerância contra repetição.
OAuth 2.0 / API Key
Autenticação por chave ou client credentials, com escopos mínimos por ambiente.
Idempotency-Key
Cabeçalho que torna escritas seguras a reenvio, evitando exames e laudos duplicados.
DICOM SR / HL7
Saída estruturada para devolver o laudo ao PACS/RIS quando o fluxo exigir.
Segurança e residência de dados (Brasil)
Conformidade com a LGPD (Lei 13.709/2018), Encarregado de Proteção de Dados (DPO) designado e trilha de auditoria por usuário responsável.
- Tráfego criptografado em trânsito (TLS 1.2+) e em repouso; endpoints expostos apenas por HTTPS.
- Residência de dados em infraestrutura no Brasil quando contratada, com a API servida a partir dessa região.
- Chaves com escopo mínimo, rotação periódica e revogação imediata; segredos de webhook independentes das chaves de API.
- Ambientes de teste com dados sintéticos ou anonimizados; nunca dados reais de paciente sem base legal.
- Conformidade LGPD com Encarregado de Proteção de Dados (DPO) e trilha de auditoria por usuário e por chave responsável.
Critérios de decisão
Controle médico
O radiologista revisa, edita e assina — a API expõe o conteúdo, mas não decide nem assina por ele.
Integração real
Encaixa em PACS, RIS e worklist existentes sem impor nova interface ao radiologista.
Estabilidade de contrato
Versionamento e idempotência garantem que automações sobrevivam a deploys e falhas de rede.
Governança
Templates, histórico, logs por chave e permissões auditáveis por usuário.
Produtividade mensurável
Tempo, retrabalho e padronização medidos em piloto antes de ampliar o escopo.
Meça em 30 dias. Não compre por promessa.
Perguntas frequentes
Quando uma integração por API faz sentido?
Quando o serviço quer automatizar a criação de exames, a recuperação de laudos e os eventos de assinatura entre sistemas internos. Um piloto útil mede material clínico curado, qualidade de revisão, aderência de templates e fricção de integração — meça em 30 dias, não compre por promessa.
Como evitar exames duplicados se a rede cair no meio de uma chamada?
Enviando um cabeçalho de idempotência (Idempotency-Key) na requisição de criação. Se o cliente não receber a resposta por timeout e reenviar com a mesma chave, a API reconhece a operação já processada e retorna o mesmo recurso, em vez de criar um exame novo. É o mecanismo recomendado para escritas seguras a reenvio.
Por que usar webhooks em vez de ficar consultando o status?
Porque a estruturação do laudo é assíncrona: ficar em polling desperdiça requisições e atrasa a notificação. Com webhooks, a Laudos.AI envia um POST assinado ao seu endpoint quando o laudo muda de estado (gerado, em revisão, assinado). O payload traz assinatura HMAC para você validar a origem, e a entrega é reenviada caso seu endpoint responda com erro.
Como a versão da API protege uma integração já em produção?
A versão é explícita no caminho (por exemplo, /v1). Mudanças incompatíveis entram em uma versão nova; a anterior continua respondendo como antes até a migração planejada. Assim, um deploy nosso não quebra o seu integrador sem aviso.
Onde ficam os dados — região, criptografia e retenção?
Os dados trafegam criptografados em trânsito e em repouso, com residência em infraestrutura no Brasil quando contratada e política de retenção definida em contrato. O tratamento segue a LGPD, com Encarregado de Proteção de Dados (DPO) designado e trilha de auditoria por usuário responsável.
A Laudos.AI substitui o radiologista?
Não. A Laudos.AI estrutura e acelera o laudo, mas o médico revisa, edita e assina. A responsabilidade clínica e a assinatura permanecem sempre com o radiologista, preparado para a Resolução CFM 2.454/2026 sobre uso de inteligência artificial em medicina.
Precisa trocar PACS/RIS?
Não. A implantação prevista é conectar a infraestrutura existente e manter o fluxo de laudagem familiar. A integração começa pequena e auditável, encaixando-se no PACS, RIS e worklist que o serviço já usa.
Referências
- Health Level Seven International · 2023
- NEMA / DICOM Standard · 2024
- Insights into Imaging (Bruls & Kwee) · 2020 · DOI: 10.1186/s13244-020-00925-z
- Journal of Digital Imaging (Forsberg et al.) · 2017 · DOI: 10.1007/s10278-016-9911-z
Conecte API ao Laudos.AI sem trocar de PACS/RIS
Implantação assistida por engenheiro, ambiente de teste com dados sintéticos ou anonimizados e piloto de 30 dias com métricas de tempo, retrabalho e padronização. O radiologista revisa, edita e assina.