Integrar domínios, templates e publicação

As 45 operações A3b estão disponíveis na homologação isolada, em https://api.staging.agilink.io/v1. O portal e o OpenAPI são a referência dos formatos; as entradas de servidor .invalid no arquivo distribuído são placeholders. Consulte a referência detalhada para parâmetros, corpo, exemplo de resposta e erros de cada operação.

Autorização e convenções

Use uma sessão humana verificada ou uma chave restrita aos aplicativos e permissões necessários. A API revalida proprietário ativo, acesso ao aplicativo e permissão. Recursos fora do acesso retornam 404. OAuth será entregue na Tarefa 2; MCP, na Tarefa 3.

Envie Authorization: Bearer <credencial>. Mutações exigem Idempotency-Key UUID v4. Nos endpoints que exigem revisão, envie If-Match: "<revision>" obtido da consulta correspondente. 428 indica ausência; 412, revisão antiga. Leia o recurso novamente e reconcilie a intenção antes de sobrescrever alterações concorrentes.

Os cursores são opacos, assinados e vinculados à credencial, operação, filtros e limite. Não reutilize o cursor com outra consulta. Domínios admitem até 100 itens; listas de templates, escolhas, versões, publicações e DNS usam até 50. A seleção final de DNS pode conter menos registros que o limite, pois remove nomes fora do domínio autorizado.

Conectar um domínio

1. Consulte GET /domain-options?appId=<appId> e escolha um modo habilitado.
2. Envie POST /domains com aplicativo e prefixo ou hostname. A resposta 202 contém uma operação e Location aponta para /v1/operations/{operationId}.
3. Consulte a operação, respeitando Retry-After. succeeded significa que a execução solicitada terminou; consulte o domínio para saber se ainda faltam prova de propriedade, DNS ou certificado.
4. Apresente os dados de verificação retornados pelo domínio. Use POST /domains/{domainId}/verify com revisão atual quando os passos externos estiverem concluídos.
5. Consulte capacidades e diagnóstico antes de configurar ou administrar DNS. Permissões, modo e situação do domínio determinam quais ações são possíveis.

A propagação pode manter um job pendente para nova tentativa. Há leases e limite de recuperação; após falha definitiva consulte o diagnóstico antes de criar outra intenção. A edição DNS envia operações duráveis e volta a verificar a versão do registro antes de mudar o provedor. Nomes de outro aplicativo permanecem protegidos.

Configurar associação e web

Consulte cada recurso native-config, web-config e recovery-config, aplique a mudança usando seu ETag e acompanhe publication. Os três compartilham a revisão do domínio: consulte novamente entre atualizações. Alterar o Android preserva Flutter/web e recuperação. configurationSaved confirma cadastro; publication.status informa a projeção; os indicadores DNS/TLS e os testes em dispositivo têm significado próprio.

Criar e publicar um template

1. Consulte GET /template-catalog?appId=<appId> e o schema do modelo.
2. Crie o template, obtenha o rascunho e salve a configuração com o ETag do rascunho.
3. Use /validate e /preview. O preview é conteúdo resolvido em JSON, sem publicação ou eventos de visita.
4. Crie /versions com o ETag do template e draftRevision atual. Uma versão é imutável.
5. Envie /publish com a versão e os alvos. Para apenas disponibilizar o artefato, use targets: [].
6. Acompanhe o Location em /template-publications/{publicationId}. Confira state, versionAvailability e os resultados dos alvos.
7. Após a disponibilidade, atualize o padrão do aplicativo, do domínio ou a seleção do link, usando a revisão devolvida pela respectiva consulta. Confira a página pública depois da projeção.

As revisões dos alvos pertencem às escolhas de template. Para um alvo de link, o processamento pode exigir também expectedLinkRevision. O ETag do recurso agregado não substitui essas revisões internas. Os exemplos e schemas distinguem cada campo.

Falhas parciais, repetição e restauração

Uma publicação pode aplicar alguns alvos e encontrar conflito em outros. Consulte cada alvo; não considere um estado geral como autorização para substituir alterações posteriores. Repita o mesmo request com a mesma chave de idempotência em caso de resposta incerta. Para retomar uma publicação, consulte sua revisão e envie /retry quando elegível. Para voltar a uma versão ou ao oficial, envie /restore com os alvos e revisões atuais.

A execução revalida a autorização antes dos efeitos pendentes. Uma revogação não desfaz efeitos concluídos. Um ACK comprova a confirmação do dispatcher; a consistência eventual do KV exige conferir o conteúdo no endereço público. Imagens referenciadas por versões permanecem preservadas para sustentar essas versões.

Alcance desta entrega

A homologação exercita o host da plataforma, configuração, DNS TXT na subárvore isolada, artefatos e páginas públicas. Novas conexões são oferecidas apenas no modo platform; criação de zonas e SaaS continuam desabilitados nesse ambiente. Os outros modos retornam 403 feature_disabled antes do enfileiramento. Associação Android/iOS em aparelho, App Clip, analytics e contratos de SDK não são comprovados por esses testes; o próximo marco A3c trata analytics e contratos públicos.