O recurso Call API permite que um campo de pesquisa faça uma solicitação HTTP a um serviço externo e use a resposta para preencher um valor calculado ou validar a entrada do usuário. Isso habilita consultas em tempo real, verificação de ID, buscas de código de barras e qualquer outra verificação no lado do servidor durante a coleta de dados.

Existem duas funções:

  • callapi() — busca um valor de uma API e o armazena em um campo calculate ou text
  • callapi-verify() — chama uma API e bloqueia o progresso se a resposta não corresponder ao valor esperado (usado em constraint)

callapi() — Buscar e armazenar uma resposta de API

Sintaxe

Coloque callapi() na coluna calculation de um campo calculate ou text:

  callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)

Parâmetros

#ParâmetroDescrição
1methodMétodo HTTP: 'GET' ou 'POST'
2urlURL do endpoint da API
3allowed_auto1 para chamar automaticamente quando o campo é alcançado; 0 para exigir um botão de acionamento manual
4max_retryNúmero máximo de tentativas de repetição em caso de falha
5no_overwrite1 para manter o valor existente se o campo já tiver um; 0 para sempre sobrescrever
6extract_exprExpressão JSONPath para extrair o valor desejado da resposta (por exemplo, $.data.name)
7timeoutTempo limite da solicitação em milissegundos
8lifetimePor quanto tempo (ms) a resposta em cache permanece válida antes de buscar novamente
9response_qNome de um campo para armazenar o código de resposta HTTP bruto (por exemplo, ${response_status})
10call_type(Opcional) Modo de chamada especial: 'lazy-upload' ou 'lazy-upload-multiple'
11post_body(Opcional) String do corpo POST. Referencie campos do formulário com ##fieldname##

Exemplo: Solicitação GET para buscar um domicílio por ID

typenamelabelappearancecalculation
texthousehold_idID do domicílio
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayDomicílio: ${hh_name}

Exemplo: Solicitação POST com corpo JSON 

  callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')

No post_body, use ##fieldname## para injetar o valor atual de qualquer campo do formulário.

Aparência: callapi

Adicione callapi à coluna appearance do campo para habilitar a integração de chamada de API:

typenamelabelappearancecalculation
calculateapi_resultcallapicallapi('GET', ...)

Quando allowed_auto é 0, o rtSurvey mostra um botão “Buscar” que o entrevistador toca manualmente.

callapi-verify() — Validar um valor contra uma API

callapi-verify() bloqueia o envio de um campo até que uma API confirme que o valor inserido é válido. Use-o na coluna constraint.

Sintaxe 

  callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)

Parâmetros

#ParâmetroDescrição
1methodMétodo HTTP: 'GET' ou 'POST'
2urlEndpoint de API de verificação
3extract_exprJSONPath para extrair o valor esperado da resposta
4match_exprExpressão que compara o valor extraído com o valor do campo (por exemplo, $.status = 'valid')
5timeoutTempo limite da solicitação em milissegundos
6constraint_mode'soft' apenas para aviso; 'hard' para bloquear o progresso
7post_body(Opcional) Corpo POST com substituições ##fieldname##
8message(Opcional) Mensagem de erro. Suporta múltiplos idiomas: <en>Invalid!</en><vi>Không hợp lệ!</vi>

Exemplo: Verificar um código de barras contra um registro de ativos

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeEscaneie o código de barras do ativocallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Ativo não encontrado no registro

Aparência: callapi-verify(...)

A coluna appearance em um campo com callapi-verify() na restrição deve conter callapi-verify(params) ou callapi-verify(dynamicParams) para sinalizar ao rtSurvey que este campo usa verificação de API.

Usando dados da API do aplicativo junto com callapi

Combine callapi() com pulldata('app-api', 'user.token') para injetar o token do usuário autenticado na sua solicitação de API:

  callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
  concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))

Práticas recomendadas

  1. Sempre defina um timeout razoável (5000–15000 ms) — não use 0 ou valores muito altos.
  2. Defina allowed_auto=0 para verificações que o entrevistador deve acionar conscientemente (por exemplo, verificações de ID).
  3. Defina no_overwrite=1 quando o campo puder ser editado posteriormente e você não quiser que a nova busca sobrescreva as correções manuais.
  4. Use extract_expr com um JSONPath específico em vez de depender do texto de resposta bruto.
  5. Teste as chamadas de API no modo off-line — callapi falhará graciosamente e mostrará um erro, mas o formulário ainda deve ser completável para campos não críticos.

Limitações

  • Requer conectividade de rede no momento da chamada — as chamadas falharão quando o dispositivo estiver off-line.
  • As respostas da API devem ser JSON — respostas XML ou de texto simples requerem análise adicional.
  • Alta frequência de chamadas (por exemplo, uma chamada de API por instância de repetição) pode diminuir a navegação no formulário.
Esta página foi útil?