Tipo Request (validação por serviço externo)

O tipo de pergunta request permite que seu modelo chame um serviço HTTP externo para validar o que o usuário digitou e use a resposta do serviço para preencher automaticamente outros campos do documento. Destina-se a cenários em que uma única informação (um código, um ID de referência, um identificador fiscal) pode resolver muitos valores já conhecidos que o usuário não deveria precisar digitar manualmente.

---

Quando usar request

Padrões comuns:

• Código promocional / de desconto: o usuário digita um código → o serviço o valida e retorna o valor do desconto, a descrição e a data de expiração, que são preenchidos automaticamente no documento.
• Consulta por referência ou apólice: o usuário digita um número de apólice → o serviço retorna o nome, o endereço e o prêmio do segurado.
• Resolução de identificador fiscal: o usuário digita um NIT/RUT → o serviço retorna a razão social, o endereço e o representante.
• Consulta de reserva / pedido: o usuário digita uma referência de reserva → o serviço retorna datas, nomes dos participantes e valores.

Em todos esses casos, a pergunta request é a entrada principal, e as demais perguntas do mesmo modelo tornam-se saídas preenchidas pela resposta do serviço.

Backend necessário

Este tipo exige que você (ou sua equipe de plataforma) construa e hospede um endpoint HTTP que siga o contrato descrito abaixo. O SDK da Auco não fornece um backend padrão: ele apenas chama a URL que você configurar.

---

Estrutura da pergunta

{
  "name": "promo_code",
  "description": "Digite seu código promocional",
  "type": "request",
  "endpoint": "https://your-service.example.com/promo-validate"
}

Propriedade	Tipo	Obrigatório	Descrição
name	string	Obrigatório	Identificador único da pergunta.
description	string	Obrigatório	Texto exibido ao usuário descrevendo o que deve ser digitado.
type	string	Obrigatório	Deve ser "request".
endpoint	string	Obrigatório	URL HTTPS completa para a qual o SDK enviará um POST.

A interface de entrada do usuário é um campo de texto simples (igual a type: text). O rótulo do botão muda de "Próximo" para "Validar" para que o usuário saiba que o valor será verificado por um serviço antes de avançar.

---

HTML correspondente

A própria pergunta request usa um span padrão — nada de especial:

<p>Código promocional: <span name="promo_code">___________</span></p>

As perguntas que serão preenchidas automaticamente pela resposta também usam spans padrão e devem existir como perguntas no config JSON para que o SDK conheça seus tipos:

<p>Valor do desconto: <span name="discount_amount">___________</span></p>
<p>Descrição da oferta: <span name="promo_description">___________</span></p>
<p>Válido até: <span name="promo_expiration">___________</span></p>

---

Contrato do endpoint

Requisição

O SDK envia uma requisição POST para a URL endpoint com um corpo JSON.

POST {endpoint}
Content-Type: application/json

{
  "key": "<question_name>",
  "value": "<user_input>"
}

Campo	Tipo	Descrição
key	string	O name da pergunta request (por exemplo, "promo_code").
value	string	O texto digitado pelo usuário.

Resposta — Sucesso (HTTP 200)

O corpo deve ser um array JSON de pares {key, value}. Cada par instrui o SDK a preencher uma pergunta do documento.

[
  { "key": "discount_amount",   "value": "15000" },
  { "key": "promo_description", "value": "Oferta especial Black Friday" },
  { "key": "promo_expiration",  "value": "2026-12-31" }
]

Campo	Tipo	Descrição
key	string	O name da pergunta do modelo a ser atualizada.
value	string	A string a ser injetada. Para tipos date, use o formato ISO (YYYY-MM-DD). Para currency / number, use a string numérica pura.

O que o SDK faz com a resposta:

1. Para cada par {key, value}, procura a pergunta em config pelo name e define seu valor interno.
2. Para cada par {key, value}, atualiza cada <span name="{key}"> do documento renderizado com value como innerHTML.
3. Leva o usuário para a próxima pergunta do fluxo.

Resposta — Erro (HTTP 4xx / 5xx ou corpo que não seja um array)

O SDK exibe a mensagem de erro "Código inválido" ("Código inválido") abaixo do campo e impede que o usuário avance até que informe um valor válido.

Mensagens de erro

O SDK exibe uma mensagem de erro genérica, independentemente do código de status HTTP ou do corpo da resposta. Se você precisar diferenciar erros (por exemplo, "código expirado" ou "não encontrado"), considere retornar HTTP 200 com um array vazio e um campo de status separado, ou estender o SDK na sua integração.

---

Exemplo completo — Código promocional

JSON

{
  "name": "Assinatura com código promocional",
  "preBuild": false,
  "config": [
    {
      "name": "promo_code",
      "description": "Digite seu código promocional",
      "type": "request",
      "endpoint": "https://api.example.com/promo-validate"
    },
    {
      "name": "promo_description",
      "description": "Descrição da oferta",
      "type": "text"
    },
    {
      "name": "discount_amount",
      "description": "Valor do desconto",
      "type": "currency"
    },
    {
      "name": "promo_expiration",
      "description": "Válido até",
      "type": "date"
    },
    {
      "name": "subscriber_name",
      "description": "Digite seu nome completo",
      "type": "name"
    },
    {
      "name": "subscriber_email",
      "description": "Digite seu e-mail",
      "type": "email"
    }
  ],
  "signatureProfile": [
    {
      "name": "subscriber_name",
      "identification": "subscriber_email",
      "email": "subscriber_email",
      "type": "subscriber"
    }
  ],
  "sign": ["subscriber_name", "subscriber_email"]
}

HTML (trecho)

<h2>Código promocional</h2>
<p>Código: <span name="promo_code">___________</span></p>
<p>Oferta: <span name="promo_description">___________</span></p>
<p>Desconto: <span name="discount_amount">___________</span></p>
<p>Válido até: <span name="promo_expiration">___________</span></p>

Exemplo de implementação do serviço (Node.js / Express)

const express = require('express');
const app = express();
app.use(express.json());

const promos = {
  BLACK2026: {
    promo_description: 'Oferta especial Black Friday',
    discount_amount: '15000',
    promo_expiration: '2026-12-31',
  },
  SPRING10: {
    promo_description: 'Desconto de primavera',
    discount_amount: '5000',
    promo_expiration: '2026-06-30',
  },
};

app.post('/promo-validate', (req, res) => {
  const { value } = req.body;
  const promo = promos[value?.toUpperCase()];

  if (!promo) return res.status(404).json({ message: 'Código não encontrado' });

  const response = Object.entries(promo).map(([key, value]) => ({ key, value }));
  res.json(response);
});

app.listen(3000);

Exemplo de implementação do serviço (Python / FastAPI)

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

promos = {
    "BLACK2026": {
        "promo_description": "Oferta especial Black Friday",
        "discount_amount": "15000",
        "promo_expiration": "2026-12-31",
    },
}

class RequestPayload(BaseModel):
    key: str
    value: str

@app.post("/promo-validate")
def validate(payload: RequestPayload):
    promo = promos.get(payload.value.upper())
    if not promo:
        raise HTTPException(status_code=404, detail="Código não encontrado")

    return [{"key": k, "value": v} for k, v in promo.items()]

---

Diretrizes de implementação

Para equipes de backend que constroem o serviço

1. Use HTTPS. O SDK rejeita endpoints http://.
2. Habilite o CORS para a origem do SDK da Auco — a chamada é feita a partir do navegador, e não de servidor para servidor.
3. Retorne apenas perguntas que existam no config do modelo. Chaves que não correspondem a nenhuma pergunta são ignoradas silenciosamente.
4. Os valores são injetados como strings seguras para HTML. Se você precisar renderizar imagens ou marcação, deve usar um tipo de pergunta que suporte isso (image) e garantir que seu valor seja um data URI válido. HTML puro em value não é sanitizado pelo SDK.
5. Respeite os tipos de dados. Se uma pergunta de destino for type: date, retorne YYYY-MM-DD. Se for type: currency, retorne o número puro, sem formatação — o SDK fará a formatação.
6. Não confie no cliente. O campo key repete o nome da pergunta, mas a lógica de validação real deve usar value. Trate este endpoint como qualquer outro endpoint público no que diz respeito a limites de taxa, autenticação e abuso.

Para autores de modelos

1. Cada {key} retornada pelo seu serviço deve existir como pergunta no config JSON, caso contrário será ignorada.
2. As perguntas preenchidas automaticamente ainda precisam estar presentes no HTML como marcadores <span name="{key}">.
3. Se uma pergunta preenchida automaticamente também aparecer no array sign, o usuário poderá avançar mesmo sem tê-la digitado — o valor fornecido pelo serviço conta como preenchido.
4. Você pode encadear várias perguntas request em um mesmo modelo se entradas diferentes resolverem campos diferentes.

---

Limitações

• Atualmente o SDK faz a requisição a partir do navegador. Nenhuma validação no servidor ocorre automaticamente — seu endpoint deve ser acessível pela internet a partir do navegador do usuário.
• A resposta deve ser um array plano de pares {key, value}. Objetos aninhados não são suportados.
• Todos os campos value da resposta são strings. Booleanos ou números devem ser serializados como strings.
• As respostas de erro são exibidas de forma genérica como "Código inválido". Mensagens de erro detalhadas por campo não são suportadas.
• A própria pergunta request não é enviada de volta ao serviço como parte do documento final — ela apenas dispara a consulta. O valor digitado pelo usuário é armazenado no value da pergunta como qualquer outro campo.