Autenticação
Credenciais, perfis e escopo de acesso à API.
| Header | Uso |
|---|---|
token |
Obrigatório nas chamadas de integração |
api |
Opcional; quando enviado, aceita one ou mob |
Content-Type |
application/json; worklist também aceita application/xml |
O header api não muda o perfil da credencial. O perfil MobileMed utiliza identificadores externos numéricos persistentes; o perfil Legacy conserva contratos anteriores com UUID. Os contratos completos de cada operação estão no OpenAPI.
Exemplo de consulta, com valores fictícios:
BASE='https://staging.themishealth.com.br'
TOKEN='substitua-pelo-token-de-homologacao'
curl --fail-with-body "$BASE/v1/exam/TESTE0001" \
-H "token: $TOKEN" \
-H 'api: one'
Use o token apenas no header. Não o inclua em URLs, capturas de tela ou páginas de documentação.
Escopo da credencial
O token pertence a uma unidade e permite acesso aos exames da organização. Não é uma credencial restrita apenas aos exames da unidade. Novos itens de worklist nascem na unidade da credencial.
Emissão e revogação
- Admin → Unidades, selecione a unidade e abra a aba Tokens de API (a aba já tem o link "Documentação da API (/v1/doc)").
- Em Nova credencial, dê um nome que identifique o sistema/equipamento (ex.:
his-clinica-x), escolha o Perfil do contrato e clique em Gerar token. O padrão para credenciais novas é MobileMed; escolha Legacy para integrações que esperam UUID. O token aparece uma única vez — copie na hora; a plataforma guarda só o hash. Perdeu? Revogue e gere outro. - Webhook de retorno (na linha da credencial): informe a URL de entrega do laudo e, se o sistema terceiro exigir autenticação, o Nome do header (ex.:
Authorization) e o Valor do header (ex.:Bearer …, gravado cifrado). Sem URL, não há entrega — o terceiro precisa buscar o laudo pela API. - Log: cada chamada que entrou por esta credencial (método, rota, accession, HTTP) e cada entrega do laudo ao webhook (tentativa, HTTP, erro) — o mesmo conteúdo de
GET /v1/exam/logs/integration. - Revogar é imediato: a credencial para de autenticar na hora. Emitir, revogar e configurar o webhook é de quem responde pela organização (
ORGANIZATION_OWNER/ORGANIZATION_ADMIN, ouPLATFORM_ADMIN); o admin de unidade só enxerga a lista e o Log.
Credenciais existentes na implantação do perfil permanecem Legacy. Para migrar uma delas, abra Perfil do contrato na própria linha, selecione MobileMed e salve; o mesmo token continua válido. O PATCH administrativo aceita contractProfile: "legacy" | "mobilemed"; omitir o campo preserva a escolha. O header api: one|mob não seleciona o perfil. Os IDs externos já emitidos são persistentes, mesmo quando o perfil da credencial muda.
Erros de autenticação
| Situação | HTTP | Corpo |
|---|---|---|
sem token |
406 | { "error": { "error_code": 406, "error_msg": "\"Integration token\" not provided" } } |
api com outro valor |
406 | { "error": { "error_code": 406, "error_msg": "\"api\" header invalid" } } |
token desconhecido (ou ambíguo) |
404 | { "error": { "message": "No integration found for the given token" } } |
Erros de negócio seguem { "message": "..." } (ex.: 400 Could not find any study). Somente credenciais identificadas como legacy recebem statusCode, timestamp e path; mobilemed usa o JSON da regra de negócio.