API do Connect

Tudo o que a tela do Connect faz passa por esta API: conectores e versões, segredos, hosts, ensaios, publicar, ligar e pausar, execuções, quarentena, escritas guardadas, agentes locais, a conversa de construção e o Copiloto. A referência de cada rota, gerada do OpenAPI da API, está em API do Connect (rotas).

Endereço e autenticação

Produção: https://api-connect.zoppy.com.br
Staging:  https://api-connect-staging.zoppy.com.br
Header:   Authorization: Bearer <token da sessão da Zoppy>

O token é o da sessão da Zoppy de quem está logado: a API confere a assinatura, a validade, a loja, o papel (só MASTER ou ADMIN) e se o Connect está liberado para a loja. GET /me diz quem está usando e se o acesso está liberado.

Erros

Todo erro vem como JSON (application/json) no formato problem+json: { type, title, status, detail, requestId, meta? }. O type é o código estável (ex.: connect.not_rehearsed); a mensagem é em português. Veja o catálogo de erros.

Prévia e confirmação

Toda ação que muda o que roda ou o que sai para outro sistema tem dois passos: uma rota .../preview, que mostra o que muda e devolve um token de confirmação, e a rota da ação, que recebe esse token.

Ação	Prévia	Confirmação
Publicar	`POST /connectors/{id}/publish/preview`	`POST /connectors/{id}/publish`
Ligar	`POST /connectors/{id}/enable/preview`	`POST /connectors/{id}/enable`
Pausar	`POST /connectors/{id}/pause/preview`	`POST /connectors/{id}/pause`
Aprovar hosts	`POST /connectors/{id}/hosts/preview`	`POST /connectors/{id}/hosts/approve`
Confirmar a 1ª escrita	`POST /connectors/{id}/external-writes/{heldWriteId}/preview`	`POST /connectors/{id}/external-writes/{heldWriteId}/confirm`
Reprocessar a quarentena	`POST /connectors/{id}/quarantine/reprocess/preview`	`POST /connectors/{id}/quarantine/reprocess`
Religar após revogação	`POST /connect/zoppy-token`	`POST /connect/zoppy-token/reenable`

O token vale 10 minutos, uma vez só, preso à pessoa, à loja, ao conector, à mudança e ao estado. Se algo mudar entre a prévia e a confirmação, a confirmação é recusada (connect.confirmation_stale ou connect.confirmation_refused) e é preciso gerar a prévia de novo.

Versões e conflito

Escrever uma versão (pela IA) ou restaurar uma antiga informa a versão em que a mudança se baseou. Se outra versão entrou depois dela, a API recusa com 409 connect.version_conflict.

Manifesto como JSON Schema

GET /connect/manifest.schema.json devolve o schema do manifesto (draft-07), o mesmo que gera a página Manifesto.

O retrato usado por este site também está publicado aqui: /openapi.json e /manifest.schema.json.