Call API
Call API permite que o seu inquérito obtenha dados de um serviço web externo e use a resposta para preencher campos ou validar respostas.
A funcionalidade Call API permite que um campo do inquérito faça um pedido HTTP a um serviço externo e use a resposta para preencher um valor calculado ou validar a entrada do utilizador. Isto permite pesquisas em tempo real, verificação de ID, pesquisas de código de barras e qualquer outra verificação do lado do servidor durante a recolha de dados.
Existem duas funções:
callapi()— obtém um valor de uma API e armazena-o num campocalculateoutextcallapi-verify()— chama uma API e bloqueia o progresso se a resposta não corresponder ao valor esperado (usado emconstraint)
callapi() — Obter 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âmetro | Descrição |
|---|---|---|
| 1 | method | Método HTTP: 'GET' ou 'POST' |
| 2 | url | URL do endpoint da API |
| 3 | allowed_auto | 1 para chamar automaticamente quando o campo é alcançado; 0 para exigir um botão de acionamento manual |
| 4 | max_retry | Número máximo de tentativas de repetição em caso de falha |
| 5 | no_overwrite | 1 para manter o valor existente se o campo já tiver um; 0 para sempre substituir |
| 6 | extract_expr | Expressão JSONPath para extrair o valor desejado da resposta (por ex., $.data.name) |
| 7 | timeout | Tempo limite de pedido em milissegundos |
| 8 | lifetime | Quanto tempo (ms) a resposta em cache permanece válida antes de ser novamente obtida |
| 9 | response_q | Nome de um campo para armazenar o código de resposta HTTP bruto (por ex., ${response_status}) |
| 10 | call_type | (Opcional) Modo de chamada especial: 'lazy-upload' ou 'lazy-upload-multiple' |
| 11 | post_body | (Opcional) Cadeia de corpo POST. Referencie campos do formulário com ##fieldname## |
Exemplo: Pedido GET para pesquisar um agregado familiar por ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID do Agregado Familiar | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Agregado familiar: ${hh_name} |
Exemplo: Pedido 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 ativar a integração de chamada de API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Quando allowed_auto é 0, o rtSurvey mostra um botão “Obter” que o enumerador toca manualmente.
callapi-verify() — Validar um valor contra uma API
callapi-verify() bloqueia a submissão de um campo até que uma API confirme que o valor introduzido é 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âmetro | Descrição |
|---|---|---|
| 1 | method | Método HTTP: 'GET' ou 'POST' |
| 2 | url | Endpoint de API de verificação |
| 3 | extract_expr | JSONPath para extrair o valor esperado da resposta |
| 4 | match_expr | Expressão que compara o valor extraído com o valor do campo (por ex., $.status = 'valid') |
| 5 | timeout | Tempo limite de pedido em milissegundos |
| 6 | constraint_mode | 'soft' apenas para aviso; 'hard' para bloquear progressão |
| 7 | post_body | (Opcional) Corpo POST com substituições ##fieldname## |
| 8 | message | (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 registo de ativos
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Digitalize o código de barras do ativo | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Ativo não encontrado no registo |
Aparência: callapi-verify(...)
A coluna appearance num campo com callapi-verify() em constraint deve conter callapi-verify(params) ou callapi-verify(dynamicParams) para sinalizar ao rtSurvey que este campo usa verificação de API.
Usar dados da App API juntamente com callapi
Combine callapi() com pulldata('app-api', 'user.token') para injetar o token do utilizador autenticado no seu pedido 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##"}'))
Melhores Práticas
- Defina sempre um
timeoutrazoável (5000–15000 ms) — não use 0 ou valores muito altos. - Defina
allowed_auto=0para verificações que o enumerador deve acionar conscientemente (por ex., verificações de ID). - Defina
no_overwrite=1quando o campo pode ser editado posteriormente e não pretende que a nova obtenção substitua correções manuais. - Use
extract_exprcom um JSONPath específico em vez de depender do texto de resposta bruto. - Teste as chamadas de API em modo offline — callapi falhará graciosamente e mostrará um erro, mas o formulário deve ainda 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 offline.
- As respostas da API devem ser JSON — as respostas XML ou de texto simples requerem análise adicional.
- Alta frequência de chamadas (por ex., uma chamada de API por instância de repetição) pode abrandar a navegação do formulário.