Request Type (External Service Validation)

The request question type lets your template call an external HTTP service to validate the user's input and use the service's response to pre-fill other fields in the document. It is intended for scenarios where a single piece of information (a code, a reference ID, a tax ID) can resolve to many pre-known values that the user should not have to type manually.

---

When to use request

Common patterns:

• Promo / discount code: user types a code → the service validates it and returns the discount amount, description, and expiration date, which auto-fill into the document.
• Reference or policy lookup: user types a policy number → the service returns the policyholder's name, address, and premium.
• Tax ID resolution: user types a NIT/RUT → the service returns the legal name, address, and representative.
• Booking / order lookup: user types a booking reference → the service returns dates, participant names, and amounts.

In all these cases, the request question is the driver input, and other questions in the same template become outputs populated by the service response.

Backend required

This type requires you (or your platform team) to build and host an HTTP endpoint that speaks the contract described below. The Auco SDK does not provide a default backend — it just calls the URL you configure.

---

Question Structure

{
  "name": "promo_code",
  "description": "Enter your promotional code",
  "type": "request",
  "endpoint": "https://your-service.example.com/promo-validate"
}

Property	Type	Required	Description
name	string	Required	Unique identifier for the question.
description	string	Required	Text shown to the user describing what to enter.
type	string	Required	Must be "request".
endpoint	string	Required	Fully qualified HTTPS URL that the SDK will POST to.

The user's input UI is a plain text input (same as type: text). The button label changes from "Next" to "Validate" so the user knows the value will be checked against a service before advancing.

---

Corresponding HTML

The request question itself uses a standard span — nothing special:

<p>Promotional code: <span name="promo_code">___________</span></p>

The questions that will be pre-filled by the response also use standard spans, and must exist as questions in the JSON config so the SDK knows their types:

<p>Discount amount: <span name="discount_amount">___________</span></p>
<p>Offer description: <span name="promo_description">___________</span></p>
<p>Valid until: <span name="promo_expiration">___________</span></p>

---

Endpoint Contract

Request

The SDK sends a POST request to the endpoint URL with a JSON body.

POST {endpoint}
Content-Type: application/json

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

Field	Type	Description
key	string	The name of the request question (e.g. "promo_code").
value	string	The text the user entered.

Response — Success (HTTP 200)

The body must be a JSON array of {key, value} pairs. Each pair instructs the SDK to populate one question in the document.

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

Field	Type	Description
key	string	The name of the question in the template to update.
value	string	The string to inject. For date types, use ISO format (YYYY-MM-DD). For currency / number, use the raw numeric string.

What the SDK does with the response:

1. For each {key, value} pair, looks up the question in config by name and sets its internal value.
2. For each {key, value} pair, updates every <span name="{key}"> in the rendered document with value as innerHTML.
3. Moves the user to the next question in the flow.

Response — Error (HTTP 4xx / 5xx or non-array body)

The SDK shows the error message "Código inválido" ("Invalid code") under the input and blocks the user from advancing until they enter a valid value.

Error messaging

The SDK surfaces a generic error message regardless of the HTTP status code or response body. If you need to differentiate errors (e.g., "expired code" vs. "not found"), consider returning HTTP 200 with an empty array and a separate status field, or extend the SDK in your integration.

---

Complete Example — Promotional Code

JSON

{
  "name": "Subscription with Promo Code",
  "preBuild": false,
  "config": [
    {
      "name": "promo_code",
      "description": "Enter your promotional code",
      "type": "request",
      "endpoint": "https://api.example.com/promo-validate"
    },
    {
      "name": "promo_description",
      "description": "Offer description",
      "type": "text"
    },
    {
      "name": "discount_amount",
      "description": "Discount amount",
      "type": "currency"
    },
    {
      "name": "promo_expiration",
      "description": "Valid until",
      "type": "date"
    },
    {
      "name": "subscriber_name",
      "description": "Enter your full name",
      "type": "name"
    },
    {
      "name": "subscriber_email",
      "description": "Enter your email",
      "type": "email"
    }
  ],
  "signatureProfile": [
    {
      "name": "subscriber_name",
      "identification": "subscriber_email",
      "email": "subscriber_email",
      "phone": "subscriber_email",
      "type": "subscriber"
    }
  ],
  "sign": ["subscriber_name", "subscriber_email"]
}

HTML (excerpt)

<h2>Promotional Code</h2>
<p>Code: <span name="promo_code">___________</span></p>
<p>Offer: <span name="promo_description">___________</span></p>
<p>Discount: <span name="discount_amount">___________</span></p>
<p>Valid until: <span name="promo_expiration">___________</span></p>

Example Service Implementation (Node.js / Express)

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

const promos = {
  BLACK2026: {
    promo_description: 'Black Friday Special',
    discount_amount: '15000',
    promo_expiration: '2026-12-31',
  },
  SPRING10: {
    promo_description: 'Spring Discount',
    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: 'Code not found' });

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

app.listen(3000);

Example Service Implementation (Python / FastAPI)

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

promos = {
    "BLACK2026": {
        "promo_description": "Black Friday Special",
        "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="Code not found")

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

---

Implementation Guidelines

For backend teams building the service

1. Use HTTPS. The SDK rejects http:// endpoints.
2. Enable CORS for the Auco SDK origin — the call is made from the browser, not server-to-server.
3. Return only questions that exist in the template's config. Keys that don't match any question are silently ignored.
4. Values are injected as HTML-safe strings. If you need to render images or markup, you must use a question type that supports it (image) and ensure your value is a valid data URI. Plain HTML in value is not sanitized by the SDK.
5. Respect data types. If a target question is type: date, return YYYY-MM-DD. If it's type: currency, return the raw number without formatting — the SDK will format it.
6. Do not trust the client. The key field echoes the question name but the actual validation logic must use value. Treat this as any other public endpoint regarding rate limits, authentication, and abuse.

For template authors

1. Every {key} returned by your service must exist as a question in the JSON config, or it will be ignored.
2. Pre-filled questions still need to be present in the HTML as <span name="{key}"> placeholders.
3. If a pre-filled question also appears in the sign array, the user will be able to advance even though they didn't type it themselves — the service-provided value counts as filled.
4. You can chain multiple request questions in a single template if different inputs resolve different fields.

---

Limitations

• The SDK currently makes the request from the browser. No server-side validation happens automatically — your endpoint must be internet-reachable from the user's browser.
• The response must be a flat array of {key, value} pairs. Nested objects are not supported.
• All value fields in the response are strings. Booleans or numbers must be serialized as strings.
• Error responses are surfaced generically as "Código inválido". Detailed per-field error messages are not supported.
• The request question itself is not stored back to the service as part of the final document — it only drives the lookup. The user's input is stored in the question's value like any other field.