Sync

O Sync é o endpoint da CDA que sincroniza os recursos publicados de um Space de forma incremental (delta). Em vez de receber novamente, a cada vez, todos os Content, Media e Content Type publicados, o cliente recebe tudo uma única vez, mantém um cache local e, a partir daí, recebe apenas o que mudou e o que foi excluído desde a última sincronização para atualizar esse cache. É usado para reduzir o volume de transferência em aplicações que precisam manter todos os recursos publicados (cache offline, índice de busca, build de site estático, etc.).

A sincronização ocorre em duas etapas. Primeiro, a sincronização inicial recebe tudo e armazena o nextSyncUrl que vem na resposta. A partir de então, você chama a sincronização delta com o sync-token contido nessa URL para receber apenas as alterações e exclusões, e a resposta devolve um novo nextSyncUrl, que você armazena e repete o processo.

Fluxo de sincronização

1. Sincronização inicial: chame com ?initial=true&type=All para receber todos os recursos publicados. No fim da resposta vem o nextSyncUrl.
2. Armazenar o nextSyncUrl: armazene o valor de nextSyncUrl recebido tal como está. Dentro dessa URL está o sync-token a ser usado na próxima chamada.
3. Sincronização delta: chame novamente com o sync-token do nextSyncUrl armazenado. Apenas o que mudou e o que foi excluído desde a última sincronização vem na resposta, junto com um novo nextSyncUrl no fim.
4. Repetir: armazene o novo nextSyncUrl recebido e repita o passo 3 sempre que precisar sincronizar.

O sync-token não é um valor que você cria, mas sim um cursor opaco. Não interprete o seu formato nem o monte manualmente; passe na próxima chamada o valor recebido no nextSyncUrl da resposta anterior, tal como está.

Estrutura da resposta

A seguir está a resposta de uma sincronização inicial (type=All) de um Space de demonstração. Em items vêm misturados as entidades publicadas e os marcadores de exclusão e, no fim, o nextSyncUrl a usar na próxima sincronização delta.

{
  "sys": { "type": "PageResponse" },
  "limit": 15,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T15:16:12.151Z",
        "updatedAt": "2026-06-16T14:31:20.073Z",
        "revision": 3
      },
      "fields": {
        "price": { "ko-KR": 18000 },
        "description": { "ko-KR": "이중 진공 단열로 보온·보냉이 오래갑니다. 500ml 대용량." },
        "photo": {},
        "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
      }
    },
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7O7vFALWs1GJ",
        "type": "DeletedContent",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T07:34:41.522Z",
        "updatedAt": "2026-06-15T07:41:57.198Z",
        "revision": 1
      }
    }
  ],
  "links": {},
  "nextSyncUrl": "/v1/spaces/HnQ32YiH/sync?sync-token=165rWhDiuLNoYOwjVQQAYXMA7makztXnhAV3qamYU75jFldqtvaEhMnr29PqsKTAbcoy6xs0iKpafM0KsKfZ2OHtA6pmbpx2pgx5jJ6bFzrkrBvoSvXF8tYZPkbw4X7B2EpCr95lgkQv4UJVCu1SSZIeH2ewzF"
}

Chaves principais:

• sys.type: o tipo do envelope que envolve a resposta de sincronização; é sempre "PageResponse".
• limit: o número de itens incluídos de uma vez.
• items: o array em que vêm misturados as entidades publicadas e os marcadores de exclusão. O primeiro item do exemplo acima é um Content vivo (com corpo), e o segundo é um marcador de exclusão (DeletedContent), que vem apenas com sys, sem corpo. Os tipos de item são tratados a seguir, em Tipos de item.
• links: o objeto de links de página. Como o Sync encadeia a próxima página e o próximo delta pelo nextSyncUrl, esse objeto pode estar vazio.
• nextSyncUrl: o caminho a chamar na próxima sincronização delta. Use o sync-token dessa URL na próxima chamada, tal como está.

Os fields de items vêm como o mapa de locales, sem ter sido reduzidos a um único idioma. Assim como o productName do exemplo acima é { "ko-KR": "스테인리스 텀블러 500ml" }, cada valor de campo vem como um mapa contendo os valores por locale. Ao contrário das consultas de CDA Content e CDA Media, que escolhem o valor como um único valor pelo parâmetro locale, o Sync não reduz a um único idioma e envia o mapa completo tal como está. O cliente recebe esse mapa, mantém-no em cache local e escolhe o valor do idioma desejado quando precisa. Por isso o Sync não tem parâmetro locale.

O photo do exemplo acima ser {} (mapa vazio) deve-se a não haver Media associado em nenhum locale.

Tipos de item

Em items vêm misturados itens com sys.type diferentes. Em linhas gerais, dividem-se em duas vertentes: entidades vivas e marcadores de exclusão.

O marcador de exclusão é o sinal de que aquele recurso já não está nos recursos publicados. O cliente olha o sys.id do marcador e remove o item correspondente do cache local.

Na sincronização inicial, você escolhe o que receber pelo parâmetro type.

Quando type é Content ou DeletedContent, você pode limitar apenas aos itens pertencentes a um Content Type específico pelo parâmetro content-type.

API

A URL base dos dois endpoints abaixo é https://cda.weegloo.com/v1, e é necessário um token Bearer que autentique a CDA no cabeçalho Authorization. Ambos usam o mesmo caminho GET /spaces/{spaceId}/sync e distinguem a sincronização inicial da sincronização delta pelos parâmetros de consulta. Ao contrário das consultas de Content e Media, o Sync não tem parâmetro locale. Os valores vêm como o mapa de locales, tal como está.

Um items vazio significa que não houve alterações desde a última sincronização. Mesmo nesse caso vem um novo nextSyncUrl, então armazene esse valor e use-o na próxima sincronização, tal como está.

Documentos relacionados

• Visão geral da CDA: a CDA como um todo e o comportamento de entrega comum.
• CDA Content: Content publicado recebido por consulta unitária, escolhendo apenas o valor de um idioma.
• CDA Locale: a lista de Locale usada para escolher valores no mapa de locales recebido pela sincronização.
• Multi-idioma (conceito): seleção de valor por locale e fallback.