Funcionamento
Endpoints
Permissões
Headers
Path parameters
Body
Response
Erros
Regras de negócio
Compliance
Variáveis de ambiente
Requisitos não funcionais
Relacionado

Registro de adapters — API

Cadastra o adapter — o pacote de integração reaproveitável com um tipo de sistema de terceiro (ex.: um RIS específico) — e gerencia o ciclo de vida das suas versões publicadas. Uma instância de integração (Instâncias de integração) executa sempre uma versão específica de um adapter; o registro não é rota chamada pelo parceiro — é administração interna, feita por quem publica o código do adapter.

Funcionamento

Um adapter (adapterId, ex. clinux-report) é só um nome e uma descrição — o AdapterDefinitionEntity. O que de fato executa é uma versão (IntegrationPlatformAdapterVersion), identificada pelo par (adapterId, version) (SemVer sem pré-release), imutável depois de publicada: manifest e artefato de container (referência OCI/ECR) não mudam.

Registrar o adapter: cadastra o adapterId (^[a-z][a-z0-9-]{1,63}$), nome de exibição e descrição. Exige a permissão assertCanPublishAdapterVersions (hoje equivalente a administrar integrações de plataforma).
Publicar uma versão: exige que o adapter já esteja registrado (AdapterDefinitionNotFoundError senão). Grava o manifest (capabilities, contractVersion, executionProfile, handler, inputSchemaRef, limitsPolicy, outputSchemaRef, runtime, sdkVersion) e a referência do artefato (artifactDigest no formato sha256:<64 hex>, artifactRepository). A versão nasce PUBLISHED.
- Republicar a mesma versão com o mesmo artefato (mesmo digest) é idempotente — devolve a versão existente sem erro.
- Republicar a mesma versão com um artefato diferente é recusado: AdapterVersionConflictError (409) — a identidade de uma versão publicada é o par (versão, digest), nunca só a versão.
Aprovar uma versão (PUBLISHED → APPROVED): sinaliza que a versão passou por revisão antes de ser usada em produção. Só é permitido a partir de PUBLISHED; de qualquer outro estado é 409 (transição inválida).
Revogar uma versão (PUBLISHED/APPROVED → REVOKED): torna a versão definitivamente não-executável. Revogar uma versão já revogada é idempotente (no-op).
Consultar uma versão específica, todas as versões de um adapter, ou a versão executável de um par (adapterId, version) — usada por quem vai vincular uma versão a uma instância (ver Instâncias de integração).

isExecutable é verdadeiro em PUBLISHED ou APPROVED; nunca em DRAFT (nenhum caminho do código cria uma versão em DRAFT hoje — é um estado do enum sem produtor ativo) ou REVOKED.

Endpoints

Método	Rota	Descrição
POST	`/v1/integration-platform/adapters`	Registra um novo adapter
POST	`/v1/integration-platform/adapters/:adapterId/versions`	Publica uma versão do adapter
POST	`/v1/integration-platform/adapters/:adapterId/versions/:version/approval`	Aprova a versão
POST	`/v1/integration-platform/adapters/:adapterId/versions/:version/revocation`	Revoga a versão
GET	`/v1/integration-platform/adapters/:adapterId/versions`	Lista as versões do adapter
GET	`/v1/integration-platform/adapters/:adapterId/versions/:version`	Consulta uma versão específica
GET	`/v1/integration-platform/adapters/:adapterId/versions/:version/executable`	Consulta a versão exigindo que esteja executável (404/409 senão)

Versão: v1

Swagger: Integration Platform — Adapter registry · Rota (Dev): http://localhost:3000/v1/integration-platform/adapters

Estas rotas rodam na API principal (porta 3000), não na API pública — ver visão geral do módulo.

Lógica de decisão da publicação de versão (a rota mais central deste grupo):

Permissões

Rota	Guards	Perfil / escopo exigido
Todas deste grupo	`JwtAuthenticationGuard`	`assertCanPublishAdapterVersions` — hoje delega para `assertCanManagePlatformIntegrations` (administrador de plataforma)

Não há distinção de escopo por tenant aqui: o adapter é um recurso de plataforma, reaproveitável por qualquer tenant que crie uma instância apontando para ele.

Headers

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer <token de sessão de usuário>`

Path parameters

Nome	Tipo	Obrigatório	Descrição
`adapterId`	string	Sim	`^[a-z][a-z0-9-]{1,63}$`
`version`	string	Sim	SemVer sem pré-release (`^(0

Body

RegisterIntegrationPlatformAdapterRestRequest (POST /adapters):

json
{
  "adapter_id": "clinux-report",
  "display_name": "Clinux report",
  "description": "Reads signed reports from Clinux."
}

Campo	Tipo	Obrigatório	Validação
`adapter_id`	string	Sim	`^[a-z][a-z0-9-]{1,63}$`
`display_name`	string	Sim	1–255 caracteres
`description`	string	Não	até 2.000 caracteres

PublishIntegrationPlatformAdapterVersionRestRequest (POST /adapters/:adapterId/versions):

json
{
  "version": "2.1.0",
  "artifact_digest": "sha256:aaaaaaaa...(64 hex)",
  "artifact_repository": "mobilemed/clinux-report",
  "capabilities": ["portal.exam.read"],
  "contract_version": 1,
  "execution_profile": "<AdapterExecutionProfile>",
  "handler": "dist/handler.mjs",
  "input_schema_ref": "schemas/input-v1.json",
  "output_schema_ref": "schemas/output-v1.json",
  "limits_policy": "adapter-standard-v1",
  "runtime": "<AdapterRuntime>",
  "sdk_version": 1
}

Campo	Tipo	Obrigatório	Validação
`version`	string	Sim	SemVer sem pré-release/build
`artifact_digest`	string	Sim	`^sha256:[a-f0-9]{64}$`
`artifact_repository`	string	Sim	formato de repositório ECR/OCI
`capabilities`	string[]	Sim	ao menos 1 item, sem repetição
`contract_version`	number	Sim	inteiro ≥ 1
`execution_profile`	enum `AdapterExecutionProfile`	Sim	valor válido do enum
`handler`	string	Sim	1–255 caracteres
`input_schema_ref` / `output_schema_ref`	string	Sim	1–255 caracteres
`limits_policy`	string	Sim	1–255 caracteres
`runtime`	enum `AdapterRuntime`	Sim	valor válido do enum
`sdk_version`	number	Sim	inteiro ≥ 1

AdapterExecutionProfile, AdapterRuntime e a validação interna do AdapterManifest vêm do pacote @mobilemed/adapter-contracts, fora do escopo lido neste levantamento — os valores possíveis de cada enum ficam a confirmar — responsável: time de Integration Platform; data: 24/09/2026.

Response

201/200 — IntegrationPlatformAdapterVersionRestResponse:

json
{
  "adapter_id": "clinux-report",
  "version": "2.1.0",
  "version_id": "0198f3a4-...-uuid",
  "artifact_digest": "sha256:...",
  "artifact_repository": "mobilemed/clinux-report",
  "capabilities": ["portal.exam.read"],
  "contract_version": 1,
  "execution_profile": "...",
  "executable": true,
  "handler": "dist/handler.mjs",
  "input_schema_ref": "schemas/input-v1.json",
  "output_schema_ref": "schemas/output-v1.json",
  "limits_policy": "adapter-standard-v1",
  "published_by_user_id": "0198f3a4-...-uuid",
  "runtime": "...",
  "sdk_version": 1,
  "status": "PUBLISHED"
}

Erros

Classe de erro	errorCode	Status	Quando ocorre
(validação de payload)	—	400	corpo inválido/incompleto
`AdapterDefinitionNotFoundError`	`INTEGRATION_PLATFORM_ADAPTER_DEFINITION_NOT_FOUND`	404	publica versão de um `adapterId` nunca registrado
`AdapterVersionNotFoundError`	`INTEGRATION_PLATFORM_ADAPTER_VERSION_NOT_FOUND`	404	consulta/aprova/revoga uma versão inexistente
`AdapterVersionConflictError`	`INTEGRATION_PLATFORM_ADAPTER_VERSION_CONFLICT`	409	republica a mesma versão com um artefato de bytes diferente
`AdapterVersionNotExecutableError`	`INTEGRATION_PLATFORM_ADAPTER_VERSION_NOT_EXECUTABLE`	409	pede a versão "executável" de uma versão `DRAFT` ou `REVOKED`
(transição de status inválida)	`INTEGRATION_PLATFORM_ADAPTER_VERSION_INVALID`	400	aprova uma versão que não está `PUBLISHED`

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	Versão publicada é imutável	manifest e artefato nunca mudam depois de `publishVersion`; só o `status` avança
RN-02	Identidade de versão é `(versão, digest)`	republicar a mesma versão com os mesmos bytes é idempotente; com bytes diferentes é `409`
RN-03	Lifecycle só anda para frente	`DRAFT → PUBLISHED → APPROVED`, e `PUBLISHED`/`APPROVED → REVOKED`; qualquer outra transição é rejeitada
RN-04	Revogar é idempotente	revogar uma versão já revogada não é erro
RN-05	Só `PUBLISHED` ou `APPROVED` executam	vincular ou iniciar execução com uma versão `DRAFT`/`REVOKED` falha

Compliance

Órgão / norma	Exigência	Como a rota atende
ANVISA (indireto)	rastreabilidade de mudança de configuração que afeta integração clínica	todo registro/publicação/aprovação/revogação grava evento de auditoria (`integration_platform.adapter_version.*`) com autor, IP e snapshot antes/depois

Variáveis de ambiente

Nenhuma específica desta rota — usa a configuração geral do banco integration-platform e do OAuth da API principal.

Requisitos não funcionais

Requisito	Definição
Idempotência	Sim para republicar a mesma versão com os mesmos bytes; não para as demais operações
Paginação	Não — `listVersionsOfAdapter` devolve todas as versões do adapter
Rate limit	Não específico (protegido pelo rate limit padrão da API principal)
Auditoria	Sim — evento de auditoria por registro/publicação/aprovação/revogação, via outbox assinado

Relacionado

🖥️ Tela: Não se aplica — administração feita hoje só via API/Swagger neste levantamento; não foi localizada tela de portal para este cadastro.
📂 Módulo: API Pública (Integrações)
🔗 Próximo passo: Instâncias de integração (vincula uma versão publicada a uma instância)

Funcionamento​

Endpoints​

Permissões​

Headers​

Path parameters​

Body​

Response​

Erros​

Regras de negócio​

Compliance​

Variáveis de ambiente​

Requisitos não funcionais​

Relacionado​