Como integrar o Coletum ao R com o pacote RColetum?

Introdução

O RColetum é um pacote para a linguagem R que permite acessar os dados da sua conta Coletum de forma programática. Com ele, você lista formulários, consulta estruturas de campos e importa todos os preenchimentos diretamente no ambiente R — sem precisar exportar arquivos manualmente.

É a solução ideal para equipes que trabalham com análise de dados, estatística e geração automática de relatórios utilizando R.

Pré-requisitos

Antes de começar, você precisa de:

• R instalado (versão 3.5 ou superior recomendada)

• Uma conta Coletum ativa com pelo menos um formulário e preenchimentos

• Um token de acesso gerado no Coletum Web (veja o Passo 1)

Parte I — Gerar o Token de Acesso no Coletum

O token autentica as requisições feitas pelo RColetum à API do Coletum. Para gerá-lo:

1. Acesse o Coletum Web com suas credenciais de administrador

2. No menu lateral esquerdo, clique em Web service

3. Clique em Adicionar token

4. Informe um nome de identificação (ex: "Análise R") e salve

5. Copie o token gerado e guarde-o em local seguro — ele será utilizado em todas as funções do pacote

Atenção: trate o token como uma senha. Não compartilhe nem inclua diretamente em scripts versionados.

Parte II — Instalar o Pacote RColetum

Com o R aberto, execute um dos comandos abaixo:

Instalação pela CRAN (versão estável):

install.packages("RColetum")

Instalação da versão de desenvolvimento via GitHub:

install.packages("devtools")
devtools::install_github("geo-sapiens/RColetum")

Após a instalação, carregue o pacote na sua sessão:

library(RColetum)

Parte III — Funções Disponíveis

O RColetum oferece quatro funções principais:

1. Listar todos os formulários — GetForms

Retorna um data frame com todos os formulários da conta, incluindo id, nome e status.

meus_formularios <- GetForms("SEU_TOKEN_AQUI")

Use essa função para consultar os IDs dos formulários que serão utilizados nas etapas seguintes.

2. Consultar a estrutura de um formulário — GetForm

Retorna os metadados e a estrutura completa de campos de um formulário específico: rótulos, tipos de campo, opções de resposta e regras de condicionamento.

# Por ID do formulário
estrutura <- GetForm(token = "SEU_TOKEN_AQUI", idForm = 1234)

# Por nome do formulário
estrutura <- GetForm(token = "SEU_TOKEN_AQUI", nameForm = "Nome do Formulário")

3. Importar os preenchimentos — GetAnswers

Importa todas as respostas coletadas de um formulário.

• Quando o formulário não possui campos de cardinalidade múltipla (campos repetitivos), o retorno é um único data frame.

• Quando o formulário possui campos repetitivos, o retorno é uma lista de data frames — um por grupo de campos.

# Por ID do formulário
respostas <- GetAnswers(token = "SEU_TOKEN_AQUI", idForm = 1234)

# Por nome do formulário
respostas <- GetAnswers(token = "SEU_TOKEN_AQUI", nameForm = "Nome do Formulário")

4. Consolidar dados em um único data frame — FlattenAnswers

Quando GetAnswers retorna uma lista de data frames, use FlattenAnswers para consolidar tudo em uma tabela única.

Importante: a consolidação pode duplicar linhas quando há grupos de campos repetitivos. Leve isso em consideração nas suas análises.

dados_flat <- GetAnswers(token = "SEU_TOKEN_AQUI", idForm = 1234) |>
  FlattenAnswers()

Parte IV — Exemplo Completo

O exemplo abaixo demonstra um fluxo completo: desde a autenticação até a criação de um gráfico com os dados importados.

library(RColetum)
library(ggplot2)

# Token de acesso
meu_token <- "SEU_TOKEN_AQUI"

# Listar formulários disponíveis
meus_formularios <- GetForms(meu_token)

# Importar respostas de um formulário pelo ID
respostas <- GetAnswers(token = meu_token, idForm = 1234)

# Consolidar em um único data frame (se necessário)
dados <- FlattenAnswers(respostas)

# Visualizar os dados
head(dados)

# Exemplo de gráfico com os dados coletados
ggplot(dados, aes(x = campo_data, y = campo_valor)) +
  geom_line() +
  labs(title = "Respostas ao longo do tempo", x = "Data", y = "Valor") +
  theme_bw()

Casos de Uso Comuns

• Relatórios automatizados: agende scripts R para importar novos preenchimentos e atualizar relatórios periodicamente

• Análise estatística: combine os dados do Coletum com outras fontes usando os recursos nativos do R

• Visualizações: crie gráficos com ggplot2 ou dashboards interativos com shiny

• Geoestatística: utilize coordenadas capturadas nos formulários para análises espaciais

Próximos Passos

• Explore outros artigos da seção Exportação de Dados e Integrações para conhecer mais opções de integração disponíveis no Coletum

• Consulte a documentação completa do pacote no CRAN ou no GitHub

• Em caso de dúvidas, entre em contato com nosso suporte pelos canais disponíveis na Central de Ajuda