Configuración de flujo

Endpoints para consultar las configuraciones de flujo creadas desde el Dashboard de Zertiban. Una configuración de flujo define el comportamiento funcional y visual que experimentará el usuario final al acceder a una operación de pago.

Estas configuraciones permiten centralizar aspectos como la identidad visual del flujo (logo, colores, idioma), las reglas operativas (caducidad, posibilidad de rechazo), así como las redirecciones y callbacks utilizados para sincronizar el estado final de las operaciones con los sistemas del cliente.

Cada organización dispone automáticamente de una configuración predeterminada creada durante el onboarding. No obstante, la plataforma permite crear múltiples configuraciones para adaptar distintos escenarios de uso, marcas, verticales o comportamientos operativos según las necesidades de integración.

Las configuraciones pueden referenciarse opcionalmente durante el registro de operaciones mediante su configurationUuid. Si no se especifica ninguna configuración en la petición API, Zertiban utilizará automáticamente la configuración marcada como predeterminada (isDefault=true) para el negocio.

Únicamente las configuraciones con estado ACTIVE pueden utilizarse para generar nuevos flujos de pago.

TIP

Para ver el detalle de todos los campos configurables desde el Dashboard, consulta "Cómo empezar > Post-Onboarding" en Primeros pasos.

Listado

GET/flow-customization/v1/configurations

curl "https://nc-api-sandbox.zertiban.com/flow-customization/v1/configurations?offset=0&limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Query parameters

Parámetro	Tipo	Default	Descripción
offset	int	0	Posición inicial
limit	int	10	Resultados por página
q_isDefault	boolean	—	true devuelve solo la predeterminada; false solo las no predeterminadas; sin informar devuelve todas
q_status	enum (ACTIVE / DISABLED)	—	Filtra por estado de la configuración. Sin informar devuelve todas

Comportamiento por defecto

Sin filtros, el listado devuelve todas las configuraciones, incluidas las que están en estado DISABLED.

Respuesta 200

{
  "total": 3,
  "results": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Cobros estandar 30d",
      "description": "Configuracion principal con caducidad de 30 dias",
      "createdAt": "2026-01-15T10:00:00Z",
      "isDefault": true,
      "status": "ACTIVE"
    }
  ]
}

Detalle

GET/flow-customization/v1/configurations/{configurationUuid}

Devuelve la configuración completa incluyendo apariencia, comportamiento y redirección.

curl https://nc-api-sandbox.zertiban.com/flow-customization/v1/configurations/{configurationUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Respuesta 200

{
  "name": "Cobros estandar 30d",
  "description": "Configuracion principal",
  "isDefault": true,
  "status": "ACTIVE",
  "visualConfiguration": {
    "targetValues": [
      {
        "applicationTarget": "WEB_APP",
        "properties": {
          "icon": "https://tuapp.com/favicon.ico",
          "logo": "https://tuapp.com/logo.png",
          "brandColor": "#003366",
          "accentColor": "#FF9900",
          "language": "es"
        }
      }
    ]
  },
  "operationConfiguration": {
    "operationConfiguration": {
      "rejectAllowed": false,
      "expirationOffset": "P30D"
    },
    "redirection": {
      "callback": {
        "url": "https://tuapp.com/pago-completado",
        "requestTimeout": 3,
        "parameters": ["operationId", "operationStatus", "operationResult", "externalOperationId"]
      },
      "return": {
        "url": "https://tuapp.com/pago-cancelado",
        "parameters": ["operationId", "externalOperationId"]
      }
    }
  }
}

Campos del nivel raíz

Campo	Tipo	Descripción
isDefault	Boolean	Si esta configuración es la predeterminada del negocio
status	String	ACTIVE o DISABLED. Solo las ACTIVE se pueden usar al crear flujos

Campos principales de operationConfiguration

Campo	Tipo	Descripción
operationConfiguration.rejectAllowed	Boolean	Si true, el pagador puede rechazar la operación en la página de pago
operationConfiguration.expirationOffset	String	Duración hasta caducidad en formato ISO 8601 (ej. "P30D")
redirection.callback.url	String	URL a la que se redirige el navegador del pagador al alcanzar un estado final
redirection.callback.requestTimeout	Long	Segundos que espera la página antes de redirigir automáticamente
redirection.callback.parameters	Array	Parámetros dinámicos incluidos como query string en la callback URL
redirection.return.url	String	URL del botón de salir. Si no se configura, el botón de salir no aparece
redirection.return.parameters	Array	Parámetros dinámicos incluidos en la return URL

Parámetros dinámicos disponibles

Para callback y return:

Valor	Disponible en	Descripción
flowId	callback return	UUID del flujo
externalFlowId	callback return	Tu externalId del flujo
operationId	callback return	UUID de la operación
externalOperationId	callback return	Tu externalId de la operación
language	callback return	Idioma de la sesión del pagador
operationStatus	solo callback	Estado final de la operación
operationResult	solo callback	OK si COMPLETED; KO si REJECTED, EXPIRED o CANCELLED
flowStatus	solo callback	Estado final del flujo
flowResult	solo callback	OK si COMPLETED; KO en los demás finales