Dynamic Insurance Contracting Flow API

1. Purpose

This document describes how to integrate an external client with the insurance contracting API using a step-based dynamic flow.

The API consumer does not know in advance the steps of the process nor the required fields. The backend drives the flow by indicating, in each response:

Which endpoint must be called next

Which data is required and optional

Which information must be displayed or selected by the user

This pattern enables flexible, extensible, and configurable flows without requiring client-side versioning.

2. Backend-driven flow

The flow behaves like a state machine:

The client starts the flow

The backend returns the next step

The client submits the requested data

The backend decides the following step

The client must never hardcode forms or endpoints; it only reacts to what the response defines.

Client → Start
Client ← NextStep
Client → Step
Client ← NextStep
...
Client → Payment
Client → Ticket

3. Flow start (Start)

Endpoint

GET

/{parentPath}/insurances/start/{terminalId}/{operatorId}

Description

Starts the contracting flow. The backend returns:

The current phase of the process

The definition of the dynamic form to be displayed

The information required to invoke the next step

Example response

{
  "rc": 0,
  "phases": ["USER", "VEHICULE", "PLAN", "QUOTE"],
  "phase": "USER",
  "name": "Customer validation",
  "description": "Customer data input for identification",
  "front": [
    {
      "name": "documentType",
      "label": "Document type",
      "description": "Identification document type",
      "type": "SELECT",
      "required": true,
      "from": [
        { "text": "ID Card", "value": "cedula" },
        { "text": "Tax ID", "value": "rnc" },
        { "text": "Passport", "value": "pasaporte" }
      ]
    },
    {
      "name": "document",
      "label": "Identification number",
      "description": "Customer identification number",
      "type": "INPUT",
      "required": true
    }
  ],
  "nextStep": {
    "path": "insurances/step/999999/1111/2",
    "method": "POST",
    "inputs": {
      "required": ["documentType", "document"]
    }
  }
}

4. Response interpretation

4.1 nextStep.path

Indicates the exact endpoint that must be invoked next.

✅ The client must use this value as-is, without modifying or manually building the URL.

4.2 inputs.required

List of mandatory fields that must be sent in the next request.

If any field is missing, the backend will reject the request

Field order is not relevant

4.3 inputs.optional

Optional fields accepted by the backend for the specific step.

They may be sent or omitted

If sent, they must comply with the expected format

4.4 front

Defines how the input must be presented to the user.

Available attributes:

Field	Description
name	Field name
type	Field type (`SELECT`, `INPUT`, etc.)
from	Allowed values (if applicable)

✅ If a required field appears in front, only allowed values must be sent.

5. Step submission

Endpoint

POST

/{parentPath}/{nextStep.path}

Body

The request body must be a key–value array containing, at minimum, the fields listed as required.

Request example

[
  { "key": "documentType", "value": "cedula" },
  { "key": "document", "value": "00112345678" }
]

Step response example

{
  "rc": 0,
  "insuranceId": "ABC123DEF456GHI789",
  "phase": "USER",
  "name": "Customer details",
  "description": "Customer data input",
  "front": [
    { "name": "clientName", "label": "First name", "type": "INPUT", "required": true },
    { "name": "clientLastName", "label": "Last name", "type": "INPUT", "required": true },
    { "name": "clientEmail", "label": "Email", "type": "INPUT", "required": true },
    { "name": "clientPhone", "label": "Phone", "type": "INPUT", "required": true }
  ],
  "nextStep": {
    "path": "insurances/step/999999/1111/2",
    "method": "POST",
    "inputs": {
      "required": [
        "insuranceId",
        "clientName",
        "clientLastName",
        "clientEmail",
        "clientPhone"
      ]
    }
  }
}

✅ The insuranceId field must be propagated in all subsequent steps.

6. Flow iteration

After each POST, the backend responds with:

A new nextStep, or

The end of the flow

The client must:

Read the response

Prepare the requested data

Call the new nextStep.path

This loop continues until the backend indicates completion.

6.1 Last step indication

When the current step is the last step before payment, the backend will explicitly indicate it by including the field:

"payment": true

inside the nextStep object.

Example

"nextStep": {
  "path": "insurances/payment/999999/1111",
  "method": "POST",
  "payment": true
}

✅ When payment = true, the client must not request another step and must proceed directly to the Payment operation.

7. Payment

The backend will require a payment.

Payment request body

{
  "amountToSendX100": 100,
  "account": "ABC123DEF456GHI789",
  "localDateTime": "2025-12-01T11:20:46Z"
}

Rules

account must contain the insuranceId

amountToSendX100 is the insurance amount multiplied by 100

Date must be sent in ISO-8601 UTC format

8. Ticket

Once the flow is completed, the backend provides a object with references and data to print the receipt.

Use supplierreference provided by payment method

Endpoint

GET

/{parentPath}/insurances/ticket/{terminalId}/{operatorId}/{reference}

Description

Returns the final contracting result (ticket, summary, or confirmation).

9. Best practices for external clients

✅ Do not assume step order or count
✅ Do not cache forms
✅ Validate inputs using front
✅ Treat the flow as state-driven
❌ Do not manually build endpoints

10. Summary

This API implements a dynamic workflow where:

The backend controls the process

The client acts as a step interpreter

The flow can change without breaking integrations

This pattern is ideal for complex processes such as insurance contracting, onboarding, or guided configuration.

Insurances

Dynamic Insurance Contracting Flow API#

1. Purpose#

2. Backend-driven flow#

3. Flow start (Start)#

Endpoint#

Description#

Example response#

4. Response interpretation#

4.1 nextStep.path#

4.2 inputs.required#

4.3 inputs.optional#

4.4 front#

5. Step submission#

Endpoint#

Body#

Request example#

Step response example#

6. Flow iteration#

6.1 Last step indication#

Example#

7. Payment#

Payment request body#

Rules#

8. Ticket#

Endpoint#

Description#

9. Best practices for external clients#

10. Summary#

Dynamic Insurance Contracting Flow API

1. Purpose

2. Backend-driven flow

3. Flow start (Start)

Endpoint

Description

Example response

4. Response interpretation

4.1 nextStep.path

4.2 inputs.required

4.3 inputs.optional

4.4 front

5. Step submission

Endpoint

Body

Request example

Step response example

6. Flow iteration

6.1 Last step indication

Example

7. Payment

Payment request body

Rules

8. Ticket

Endpoint

Description

9. Best practices for external clients

10. Summary