Flow list

GET

/flow/v1/flows

Returns all of the organisation's collection flows. Primarily used for reconciliation, reporting and overall collections oversight.

Paginated. Supports filters by flow UUID, externalId, status, product label and creation/status-change date ranges. Results can be sorted by createdAt, statusUpdatedAt, flowUuid, externalId or status.

Also supports filtering by channel attribution origin (q_origin) and collaborator (q_collaboratorUuid, q_collaboratorLegalName); each list item carries a collaborator block with the attributed collaborator's snapshot, absent for direct flows.

Autorizaciones

OAuth2

OAuth2 security scheme

clientCredentials Flow

URL del token"/api/v2/auth/token"

Scopes:

• "zertiban-api"Access to the API

Parámetros

Header Parameters

x-tenant-id*

Tenant identifier that contains the organisation UUID

Tipo

string

Requerido

Ejemplo"1f56c928-7621-44fe-8cda-c211fda0a828"

Formato

"uuid"

Query Parameters

limit

Page size

Tipo

integer

Mínimo

0

Máximo

100

Por defecto

10

offset

Zero-based offset

Tipo

integer

Mínimo

0

Por defecto

0

sort_by

Indicates the property to sort the result list (case insensitive)

Tipo

string

Valores válidos

"flowUuid""externalId""status""createdAt""statusUpdatedAt"

Formato

"string"

Por defecto

"createdAt"

sort_dir

Indicates the sort direction (case insensitive)

Tipo

string

Valores válidos

"ASC""DESC"

Formato

"string"

Por defecto

"DESC"

q_fromStatusUpdatedAt

Finds flows with 'statusUpdatedAt' after or equal the specified date time

Tipo

string

Ejemplo"2025-03-10T14:23:45Z"

Formato

"ISO 8601"

q_toStatusUpdatedAt

Find flows 'statusUpdatedAt' before or equal the specified date time

Tipo

string

Ejemplo"2025-03-10T14:23:45Z"

Formato

"ISO 8601"

q_fromCreatedAt

Find flows with 'createdAt' after or equal the specified date time

Tipo

string

Ejemplo"2025-03-10T14:23:45Z"

Formato

"ISO 8601"

q_toCreatedAt

Find flows with 'createdAt' before or equal the specified date time

Tipo

string

Ejemplo"2025-03-10T14:23:45Z"

Formato

"ISO 8601"

q_uuid

Filters flows by a UUID

Tipo

string

Ejemplo"12087dd4-336d-4c21-90e1-3dbd58f14f87"

Formato

"UUID v4"

q_externalId

Filters flows by external ID

Tipo

string

Ejemplo"my-external-id"

q_productLabelValue

Retrieves flows that have a label with name "product" and the specified value. Accepts multiple comma separated

Tipo

string

Ejemplo"whatever product label value"

q_status

Filters flows by Status. Accepts multiple comma separated

Tipo

array

Ejemplo"CREATED""COMPLETED"

q_origin

Filters flows by channel attribution origin (case insensitive). DIRECT matches flows
with no collaborator attribution; COLLABORATOR matches flows attributed to any
collaborator channel. DIRECT cannot be combined with q_collaboratorUuid or
q_collaboratorLegalName.

This filter is combined (AND) with the caller's channel isolation: a collaborator
caller only sees flows attributed to its own channel, so DIRECT always yields an
empty list for collaborator callers.

Tipo

string

Valores válidos

"DIRECT""COLLABORATOR"

Ejemplo"COLLABORATOR"

q_collaboratorUuid

Filters flows originated by the given collaborator organisation UUID (exact match).
Only matches COLLABORATOR-originated flows. Cannot be combined with
q_origin=DIRECT (400).

Tipo

string

Ejemplo"f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8"

Formato

"uuid"

q_collaboratorLegalName

Filters flows whose collaborator legal name contains the given value
(case-insensitive substring match over the legal name snapshotted at flow
creation). Only matches COLLABORATOR-originated flows. Cannot be combined
with q_origin=DIRECT (400).

Tipo

string

Ejemplo"Gestoria Perez SL"

Respuestas

Flow list

Content-Type

application/json

{

  

"results": [

  

  

{

  

  

  

"uuid": "string",

  

  

  

"externalId": "FLW-99881",

  

  

  

"status": "CREATED",

  

  

  

"createdAt": "2025-03-10T14:23:45Z",

  

  

  

"statusUpdatedAt": "2025-03-10T14:23:45Z",

  

  

  

"labels": [

  

  

  

  

{

  

  

  

  

  

"name": "my-label",

  

  

  

  

  

"value": "my-label-value"

  

  

  

  

}

  

  

  

],

  

  

  

"operationsCount": 1,

  

  

  

"collaborator": {

  

  

  

  

"uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8",

  

  

  

  

"legalName": "Gestoria Perez SL"

  

  

  

}

  

  

}

  

],

  

"total": 0

}

GET

/flow/v1/flows

Playground

Servidor

Autorización

OAuth2

Headers

x-tenant-id*

Variables

Key

Value

limit

offset

sort_by

sort_dir

q_fromStatusUpdatedAt

q_toStatusUpdatedAt

q_fromCreatedAt

q_toCreatedAt

q_uuid

q_externalId

q_productLabelValue

q_status

q_origin

q_collaboratorUuid

q_collaboratorLegalName

Ejemplos