# publisher
Fábrica de Software (Instituto de Informática - UFG)

# contact[].name
Fábrica de Software (Instituto de Informática - UFG)

# description
O **HubSaúde** é um gateway para recuperar e fornecer informações em saúde no Estado de Goiás. As escritas do Command Path são exclusivamente assíncronas e acompanhadas por Task; esse contrato Task-based não substitui o endpoint de status HTTP genérico do Bulk Data `$export`.

# purpose
Detalhar as capacidades oferecidas pelo **HubSaúde** e permitir acompanhamento dos recursos oferecidos ao longo do tempo, registrado pela evolução de versões.

# implementation.description
Instância do **HubSaúde** disponibilizada pela SES-GO

# rest[].documentation
Endpoint /Bundle de produção do **HubSaúde** por meio do qual resultados de exames são submetidos à Secretaria de Estado de Saúde de Goiás.

O contexto de cada requisição é identificado pelo path `/fhir/{ig-alias}/{versao}/...`. Mapeamento entre `{ig-alias}` e a URL canônica do Guia de Implementação (as versões suportadas constam de `implementationGuide`):

| ig-alias | URL canônica |
|---|---|
| `core` | https://fhir.saude.go.gov.br/r4/core/ImplementationGuide/br.go.ses.core |
| `exame` | https://fhir.saude.go.gov.br/r4/exame/ImplementationGuide/br.go.ses.exame |
| `seguranca` | https://fhir.saude.go.gov.br/r4/seguranca/ImplementationGuide/br.go.ses.seguranca |

CONTRATO DE ESCRITA ASYNC-ONLY: não existe variante síncrona para create, update, patch ou delete. Todo kick-off de escrita exige os headers `Prefer: respond-async`, `Accept` compatível com um formato declarado e `Idempotency-Key`. Header obrigatório ausente, inclusive `Prefer` sem a preferência `respond-async`, resulta em `400 Bad Request` com OperationOutcome; `Accept` incompatível resulta em `406 Not Acceptable` com OperationOutcome, sempre sem efeito colateral. Uma escrita aceita ou um replay terminal retorna `202 Accepted` sem representação no corpo, com `Content-Location: /Task/{id}`, `Retry-After`, `Preference-Applied: respond-async`, `correlation-id` e `traceparent` obrigatórios, sem usar `Location` para apontar a Task. `Idempotency-Replayed: true` é ausente na aceitação inicial e obrigatório no replay terminal. Um replay concorrente retorna `409 Conflict` com `Content-Type: application/fhir+json`, corpo FHIR R4 `OperationOutcome` cujo `issue.code=duplicate`, `Content-Location`, `Retry-After`, `correlation-id` e `traceparent` obrigatórios, sem reprocessamento. O cliente acompanha a operação com `GET /Task/{id}`: uma Task existente retorna HTTP `200` em qualquer estado, o andamento fica em `Task.status` e o resultado terminal fica em `Task.output` como referência ao recurso resultante ou OperationOutcome. Esse polling baseado em Task é distinto do endpoint de status HTTP genérico do Bulk Data `$export`, cujo contrato próprio não é redefinido aqui.

# rest[].security.service[].text
Autenticação mTLS usando Certificado ICP-Brasil e emissão de tokens de acesso via SMART Backend Services (Client Credentials).

# rest[].security.description
O HubSaúde expõe exclusivamente um contrato técnico (SMART Backend Services / Client Credentials). Todo cliente — incluindo intermediários confiáveis que atuam em nome de pacientes — autentica-se via mTLS com Certificado ICP-Brasil e obtém tokens com escopos system/*. A autenticação de utilizadores humanos (Gov.br, biometria, etc.) é responsabilidade do intermediário confiável e ocorre fora do perímetro do HubSaúde. O credenciamento deve ser aprovado pela SES-GO. CORS é habilitado nos endpoints públicos de descoberta (/metadata e /.well-known/smart-configuration), restrito a GET/OPTIONS e sem credenciais; o endpoint transacional exige mTLS e não é acessado por navegadores.

# rest[].resource[].documentation
O Bundle é o recurso principal para transferência de exames. O Bundle pode ser de dois tipos: Transferencia e Malote. Será em uma instância de Bundle que o exame será 'empacotado' para ser enviado à SES-GO. Os detalhes do exame a ser enviado estão definidos em perfil próprio ou são uma combinação de observações simples e compostas, por exemplo. Qualquer que seja o caso, contudo, sugere-se observar atentamente os exemplos fornecidos e perfis esperados para serem atendidos.

# rest[].resource[].interaction[].documentation
Escrita exclusivamente assíncrona. Exige `Prefer: respond-async`, `Accept` e `Idempotency-Key`; a aceitação inicial e o replay terminal retornam 202 sem representação no corpo, com `Content-Location`, `Retry-After`, `Preference-Applied: respond-async`, `correlation-id` e `traceparent`, sem `Location` para a Task. `Idempotency-Replayed: true` é ausente na aceitação inicial e obrigatório no replay terminal. Header obrigatório ausente retorna 400 e Accept incompatível retorna 406, ambos com OperationOutcome e sem efeito colateral. Replay concorrente retorna 409 com `Content-Type: application/fhir+json`, `OperationOutcome.issue.code=duplicate`, `Content-Location`, `Retry-After`, `correlation-id` e `traceparent`.

# rest[].resource[].documentation
Acompanhamento do ciclo de vida da operação de escrita assíncrona (status: accepted, in-progress, completed, failed ou rejected). `GET /Task/{id}` retorna HTTP 200 para uma Task existente em qualquer desses estados. O andamento está em `Task.status` e o resultado terminal em `Task.output`, como `valueReference` ao recurso resultante ou OperationOutcome completo. Cada requisitante tem acesso apenas às Tasks das submissões que realizou; consultas a Tasks de terceiros ou inexistentes resultam em 404 (Not Found). Esse recurso não representa o endpoint de status HTTP genérico do Bulk Data `$export`.

# rest[].resource[].interaction[].documentation
GET [base]/Task/[id], em que [id] é obtido do cabeçalho Content-Location retornado na submissão; responde HTTP 200 quando a Task existe.

# rest[].resource[].documentation
Conteúdo assinado digitalmente que acompanha a submissão, transportado dentro do Bundle conforme o Guia de Segurança da Informação. Não é exposto como endpoint REST próprio.

# rest[].resource[].documentation
Gestão de consentimento do titular (LGPD). As decisões de consentimento condicionam o acesso de leitura aos dados do titular.

# rest[].resource[].interaction[].documentation
Escrita exclusivamente assíncrona conforme o contrato async-only descrito em rest.documentation.

# rest[].resource[].interaction[].documentation
Escrita exclusivamente assíncrona conforme o contrato async-only descrito em rest.documentation.

# rest[].resource[].searchParam[].documentation
Titular ao qual o consentimento se aplica.

# rest[].resource[].searchParam[].documentation
Estado do consentimento (draft, active, inactive, etc.).