Pular para o conteúdo principal

Introdução

O módulo IntegrationCollections armazena dados usados para integrar diferentes serviços e sistemas.

Para integrar serviços de terceiros, você primeiro precisa criar e configurar coleções.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/integration-collections

🎯 O que este módulo faz?​

O módulo IntegrationCollections permite que você leia e gerencie coleções — tabelas estruturadas de registros usadas para integrar o OneEntry com serviços e sistemas externos. Cada coleção é definida por um formulário (seu esquema); cada registro (linha) contém os formData enviados.

Defina uma coleção e seu formulário no painel de administração, e então busque, crie, atualize e exclua suas linhas a partir do seu aplicativo.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { IntegrationCollections } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque todas as coleções e leia seus campos:

// Returns an array of collections (langCode defaults to the configured language).
const collections = await IntegrationCollections.getICollections("en_US");

collections.forEach((collection) => {
  console.log(collection.id, collection.identifier, collection.formId);
});

✨ Conceitos Chave​

Coleção vs. Linha​

  • Coleção (ICollectionEntity) — o contêiner/esquema. Ela referencia um formulário (formId) e um conjunto de atributos, e carrega informações localizadas.
  • Linha (ICollectionRow) — um único registro dentro de uma coleção, contendo formData (um array de { marker, type, value }), timestamps e uma entidade vinculada opcional (entityType / entityId).

Estrutura da Coleção​

{
  id: 1,
  identifier: 'collection1',
  formId: 1234,
  localizeInfos: { title: 'Admins text' },
  attributeSetId: 1234,
  selectedAttributeMarkers: 'collection_marker'
}

Estrutura da Linha​

{
  id: 1,
  createdDate: '2025-06-06T19:08:54.616Z',
  updatedDate: '2025-06-06T19:08:54.616Z',
  collectionId: 1,
  formData: [
    { marker: 'name_1', type: 'string', value: 'Value' }
  ],
  entityType: null,
  entityId: null,
  attributeSetIdentifier: null
}

Criando ou atualizando linhas​

Passe um objeto de formulário (ICollectionFormObject) com o identificador do formulário e os valores dos campos:

const body = {
  formIdentifier: 'collection-form',
  formData: [
    { marker: 'collection_marker', type: 'string', value: 'Collection marker' }
  ]
};

await IntegrationCollections.createICollectionRow('collection1', body);

📋 O que você precisa saber​

Coleções são definidas no painel de administração​

Coleções e seus formulários são criados e configurados no painel de administração do OneEntry. O SDK é para ler coleções e gerenciar suas linhas (criar / atualizar / excluir).

Excluir linhas requer uma permissão​

deleteICollectionRowByMarkerAndId() requer o direito collections.row.delete; sem ele, a exclusão falha.

📊 Tabela de Referência Rápida​

MétodoDescrição
getICollections()Obter todas as coleções.
getICollectionById()Obter uma única coleção pelo id.
getICollectionRowsById()Obter todas as linhas de uma coleção pelo id da coleção.
getICollectionRowsByMarker()Obter todas as linhas de uma coleção pelo marcador.
getICollectionRowByMarkerAndId()Obter uma única linha pelo marcador da coleção e id da linha.
validateICollectionMarker()Verificar se um marcador de coleção existe.
createICollectionRow()Criar uma linha em uma coleção.
updateICollectionRow()Atualizar uma linha em uma coleção.
deleteICollectionRowByMarkerAndId()Excluir uma linha de coleção (requer o direito collections.row.delete).

❓ Perguntas Comuns (FAQ)​

Onde as coleções são criadas?​

Coleções e seus formulários são criados e configurados no painel de administração do OneEntry. O SDK é para ler coleções e gerenciar suas linhas (criar / atualizar / excluir).

Qual é a diferença entre uma coleção e uma linha de coleção?​

Uma coleção é a definição da tabela (seu esquema de formulário e metadados). Uma linha de coleção é um único registro armazenado nessa coleção, carregando seus valores de formData.

🎓 Melhores Práticas​

  • Defina coleções no painel de administração - O SDK lê coleções e gerencia suas linhas, não o esquema.
  • Valide marcadores antes de usar - Use validateICollectionMarker() para confirmar que um marcador de coleção existe.
  • Combine campos de formulário com o esquema - Os marcadores/tipos de formData devem corresponder ao formulário da coleção.
  • Garanta a permissão de exclusão - deleteICollectionRowByMarkerAndId() precisa do direito collections.row.delete.

🔗 Documentação Relacionada​