--- title: Integrar domínios, templates e publicação description: Sequência de integração A3b, autenticação, revisões e acompanhamento assíncrono. --- 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](/api/endpoints-a3b/) 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 `. Mutações exigem `Idempotency-Key` UUID v4. Nos endpoints que exigem revisão, envie `If-Match: ""` 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=` 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=` 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.