O Web Service V2 é a API REST do Coletum. Com ela, você conecta qualquer sistema externo — dashboards, ERPs, scripts de automação, ferramentas de BI — diretamente aos dados coletados pela plataforma.
A versão 2 substitui a API GraphQL anterior e traz uma interface mais simples, baseada em requisições HTTP padrão, com paginação consistente, filtros avançados e respostas em JSON.
A documentação técnica completa — com todos os endpoints, parâmetros e exemplos interativos — está disponível em: https://coletum.com/pt_BR/webservice/v2/docs
Recupere todos os formulários da sua conta com informações como nome, status, versão e categoria. Filtre por nome (busca parcial) ou por status (enabled / disabled).
Cole a URL abaixo no navegador para testar (substitua SEU_TOKEN pelo seu token):
https://coletum.com/api/webservice/v2/forms?status=enabled&Token=SEU_TOKEN
Obtenha a lista completa de campos (componentes) de um formulário — tipos, rótulos, campos agrupados e identificadores únicos de cada campo. Essa consulta é o ponto de partida para interpretar corretamente os preenchimentos.
https://coletum.com/api/webservice/v2/forms/42?Token=SEU_TOKEN
Acesse todos os preenchimentos de um formulário e filtre por:
Período de criação: created_after e created_before
Período de atualização: updated_after e updated_before
Origem do preenchimento: aplicativo mobile (mobile), sistema web (web_private) ou preenchimento público (web_public)
Usuário responsável: por ID de quem criou ou editou o preenchimento
https://coletum.com/api/webservice/v2/forms/42/answers?created_after=2024-01-01&created_before=2024-12-31&Token=SEU_TOKEN
Toda requisição exige um token de acesso. Para criar o seu:
Acesse o Coletum com uma conta administrador.
Vá em Menu principal > Web Service.
Clique em Adicionar Token, dê um nome e salve.
Copie o token gerado e guarde em local seguro — ele não será exibido novamente.
Você pode enviar o token de duas formas:
Como query parameter (útil para testes rápidos no navegador):
?Token=SEU_TOKEN
Como header HTTP (recomendado para produção):
Token: SEU_TOKEN
Cada preenchimento retornado contém um objeto answer cujas chaves são os identificadores dos campos do formulário. Esses identificadores seguem o padrão snake_case(label) + id_numérico — por exemplo, um campo "Nome completo" com ID 42 gera a chave nome_completo42.
Consulte sempre a estrutura do formulário (GET /forms/{formId}) antes de processar os preenchimentos, para mapear corretamente cada campo.
Exemplo de resposta:
{
"id": "ABC-001",
"answer": {
"nome_completo42": "João Silva",
"dados_de_contato43": {
"e_mail44": "[email protected]",
"telefone45": "(11) 98765-4321"
}
},
"meta_data": {
"created_at": "2024-07-20T14:30:00+00:00",
"created_by_user_name": "João Silva",
"created_at_source": "mobile"
}
}
Campos agrupados (group) retornam um objeto aninhado. Quando o grupo é coletável (permite múltiplas respostas), o valor é um array de objetos.
Cada preenchimento inclui um objeto meta_data com informações contextuais:
Campo
Descrição
| Data e hora de criação e última atualização |
| Nome do usuário responsável |
| Origem: |
| Coordenadas geográficas no momento do preenchimento (GeoJSON Point) |
| Tamanho total dos arquivos anexados (em bytes) |
Todos os endpoints que retornam listas usam paginação. Cada resposta inclui um objeto pagination:
{
"pagination": {
"page": 1,
"page_size": 100,
"total_items": 342,
"total_pages": 4,
"has_next": true
}
}
O tamanho máximo de página é 500 itens. Para percorrer todos os registros, avance as páginas enquanto has_next for true.
Dashboards em tempo real: conecte o Coletum ao Power BI, Metabase ou Tableau e atualize os dados automaticamente com as respostas mais recentes.
Integração com ERP ou CRM: envie automaticamente preenchimentos para outros sistemas assim que forem registrados.
Automações com scripts: use Python, Node.js ou qualquer linguagem para processar e transformar dados coletados.
Auditorias e relatórios periódicos: extraia preenchimentos de períodos específicos para relatórios regulares.