Widget Redirection & Completion

The Spain Public Administration Flow API allows you to control the user’s browser redirection behavior once they complete or exit the data extraction widget. This is done by configuring completion settings during session initialization.

Redirection Settings

When calling Create Session, you can customize redirection behaviors under the settings object using the following parameters:

• completion_mode: The redirection behavior (e.g. standard redirect, opening a new tab, closing the tab, or doing nothing).
• completion_url: The destination URL to navigate to (required if redirecting). Supports dynamic template variables in both the URL path and query string.
• completion_extra_data: A dictionary of key-value pairs. All keys and values are automatically serialized into query parameters and appended to the final redirect URL. Values in this dictionary support dynamic template variables.

Completion Modes

You can specify how the widget behaves upon exit by setting completion_mode to one of the following values:

Dynamic Query Parameters & Templating

The widget engine supports dynamic runtime template variables to construct customized redirect flows. These settings are configured inside the settings object of the Create Session initialization request payload.

These template variables can be used in two ways:

1. Directly in the URL: Interpolated within the completion_url string (either in the URL path or in query parameters).
2. In Extra Data values: Interpolated inside the values of the completion_extra_data dictionary.

Additionally, the completion_extra_data dictionary is automatically converted to query parameters and appended to the final URL.

Available Template Variables

• {app_id}: The unique identifier of your application.
• {customer_id}: The customer ID associated with the session.
• {session_id}: The active widget session ID.
• {status_code}: The final status code of the session (e.g. COMPLETED).

Example Parameter Mapping

If you initialize a session with a URL template path and an extra data dictionary (demonstrating how template variables can be partially interpolated inside composite strings, such as prefixing the session ID):

1
{
2
  "customer_id": "cust_esp_202406",
3
  "settings": {
4
    "completion_mode": "redirect",
5
    "completion_url": "https://your-server.com/onboarding/{customer_id}/verify",
6
    "completion_extra_data": {
7
      "session": "sess_{session_id}",
8
      "status": "{status_code}",
9
      "source": "widget_flow"
10
    }
11
  }
12
}

The template variables are resolved and the dictionary is serialized into query parameters, redirecting the user to:

1
https://your-server.com/onboarding/cust_esp_202406/verify?session=sess_644599da47847b79c03cc94f&status=COMPLETED&source=widget_flow

Real-World Examples

The following examples demonstrate how to construct the request payload when calling the Create Session endpoint.

Note that all redirection settings must be nested inside the settings object of the initialization payload, alongside other session configurations (such as required features).

1
{
2
  "customer_id": "cust_esp_202406",
3
  "settings": {
4
    "completion_mode": "redirect",
5
    "completion_url": "https://portal.mycompany.com/onboarding/verify",
6
    "completion_extra_data": {
7
      "session_id": "{session_id}",
8
      "customer": "{customer_id}",
9
      "status": "{status_code}"
10
    }
11
  }
12
}

1
https://portal.mycompany.com/onboarding/verify?session_id=644599da47847b79c03cc94f&customer=cust_esp_202406&status=COMPLETED

1
{
2
  "customer_id": "cust_esp_202406",
3
  "settings": {
4
    "completion_mode": "redirect",
5
    "completion_url": "https://wa.me/34600000000",
6
    "completion_extra_data": {
7
      "text": "I want to apply for my loan. Session ID: {session_id}"
8
    }
9
  }
10
}

1
https://wa.me/34600000000?text=I%20want%20to%20apply%20for%20my%20loan.%20Session%20ID%3A%20644599da47847b79c03cc94f

1
{
2
  "customer_id": "cust_esp_202406",
3
  "settings": {
4
    "completion_mode": "redirect",
5
    "completion_url": "https://api.whatsapp.com/send",
6
    "completion_extra_data": {
7
      "phone": "34600000000",
8
      "l": "en",
9
      "text": "I want to apply for my loan. Session ID: {session_id}"
10
    }
11
  }
12
}

1
https://api.whatsapp.com/send?phone=34600000000&l=en&text=I%20want%20to%20apply%20for%20my%20loan.%20Session%20ID%3A%20644599da47847b79c03cc94f

Iframe postMessage Events

If you embed the widget inside an HTML <iframe> on your website, the widget will dispatch a JavaScript message event to the parent window upon completion or exit, regardless of the configured completion_mode. This is useful for programmatically closing the iframe, refreshing parent page components, or showing custom UI elements on the host platform.

Event Message Structure

When the session reaches its end screen, the widget calls window.parent.postMessage() with a payload structured as follows:

• event: The event identifier string (always es-public-administration:ended).
• status_code: The final execution status of the session (e.g. COMPLETED, FAILED, WAITING).
• cursor: The identifier of the active cursor/screen the user was on when the widget session finished. Possible values include:
  • es-public-administration:bye:completed: The user successfully completed the data retrieval and signature flow.
  • es-public-administration:bye:failure: An execution failure occurred and the session ended.
  • es-public-administration:connect:wait: The session is temporarily waiting for an asynchronous background task or report generation (e.g., generating the CIRBE report).

Integration Example

To handle the completion event in your host application, register a listener for the window message event:

1
window.addEventListener("message", (event) => {
2
  // Recommended: Verify origin to secure the communication channel
3
  if (event.origin !== "https://infonite.dev") return;
4
5
  const payload = event.data;
6
7
  // Check if the message is the completion event
8
  if (payload && payload.event === "es-public-administration:ended") {
9
    const { status_code, cursor } = payload;
10
    console.log(`Widget session ended with status: ${status_code} at cursor: ${cursor}`);
11
12
    // Programmatically close your iframe modal or update UI
13
    if (status_code === "COMPLETED") {
14
      // Refresh user onboarding state or fetch data securely from your backend
15
    } else {
16
      // Handle exit/failure scenarios
17
    }
18
  }
19
});