Developer Docs

English

Español

English

Español

Appearance

Operation list​

GET
/flow/v1/operations

Lists individual operations within flows. Used for operational reconciliation, backoffice work and collection tracking.

Paginated. Supports filtering by operation UUID, externalId, parent flow UUID, status, type, invoice external ID, amount range and date ranges. Results can be sorted by createdAt, statusUpdatedAt, status, flowUuid, operationUuid, externalId, paymentAmount or invoiceExternalId.

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
"operationUuid""externalId""status""flowUuid""createdAt""statusUpdatedAt""paymentAmount""invoiceExternalId"
Por defecto
"createdAt"
sort_dir

Indicates the sort direction (case insensitive)

Tipo
string
Valores válidos
"ASC""DESC"
Por defecto
"DESC"
q_operationUuid

Filters operations by UUID (exact match)

Tipo
string
Ejemplo"f47ac10b-58cc-4372-a567-0e02b2c3d479"
Formato
"uuid"
q_externalId

Filters operations by external ID (exact match)

Tipo
string
Ejemplo"EXT-2025-0001"
q_flowUuid

Filters operations by flow UUID (exact match)

Tipo
string
Ejemplo"3fa85f64-5717-4562-b3fc-2c963f66afa6"
Formato
"uuid"
q_status

Filters operations by status (case insensitive). Supports 0, 1 or N values separated by comma.

Tipo
array
Ejemplo"OPENED""CREATED"
q_type

Filters operations by type (case insensitive). Supports 0, 1 or N values separated by comma.

Tipo
array
Ejemplo"PAYMENT""SIGNATURE"
q_fromCreatedAt

Finds operations with 'createdAt' after or equal the specified date time

Tipo
string
Ejemplo"2025-03-10T14:23:45Z"
Formato
"ISO 8601"
q_toCreatedAt

Finds operations with 'createdAt' before or equal the specified date time

Tipo
string
Ejemplo"2025-03-10T14:23:45Z"
Formato
"ISO 8601"
q_fromStatusUpdatedAt

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

Tipo
string
Ejemplo"2025-03-10T14:23:45Z"
Formato
"ISO 8601"
q_toStatusUpdatedAt

Finds operations with 'statusUpdatedAt' before or equal the specified date time

Tipo
string
Ejemplo"2025-03-10T14:23:45Z"
Formato
"ISO 8601"
q_amountFrom

Filters PAYMENT operations with amount greater or equal than this value

Tipo
number
Ejemplo1000
q_amountTo

Filters PAYMENT operations with amount lower or equal than this value

Tipo
number
Ejemplo5000
q_invoiceExternalId

Filters PAYMENT operations by invoice external ID (exact match)

Tipo
string
Ejemplo"INV-2025-0012"
q_origin

Filters operations by the channel origin of their owning flow (case insensitive):
DIRECT for flows created directly by the organisation, COLLABORATOR for flows
created on behalf of the organisation by a delegated collaborator. Incompatible with
q_collaboratorUuid and/or q_collaboratorLegalName when set to DIRECT, since a
direct flow has no collaborator attribution.

This filter is combined (AND) with the caller's channel isolation: a collaborator
caller only sees operations of 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 operations whose owning flow is attributed to this collaborator UUID
(exact match, FLOWS.COLLABORATOR_BUSINESS_UUID). Only matches operations of
COLLABORATOR-originated flows. Cannot be combined with q_origin=DIRECT (400).

Tipo
string
Ejemplo"7f70e314-32d7-49eb-9721-1f986574f912"
Formato
"uuid"
q_collaboratorLegalName

Filters operations whose owning flow's collaborator legal name contains this value
(case-insensitive substring match over the legal name snapshotted at flow creation,
FLOWS.COLLABORATOR_LEGAL_NAME). Only matches operations of COLLABORATOR-originated
flows. Cannot be combined with q_origin=DIRECT (400).

Tipo
string
Ejemplo"Gestoria Perez SL"

Respuestas​

Operation list

application/json
JSON
{
  
"total": 2,
  
"results": [
  
  
{
  
  
  
"uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  
  
  
"externalId": "EXT-2025-0001",
  
  
  
"flowUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  
  
  
"type": "PAYMENT",
  
  
  
"status": "OPENED",
  
  
  
"createdAt": "2025-09-15T09:00:00Z",
  
  
  
"statusUpdatedAt": "2025-09-15T09:55:00Z",
  
  
  
"payment": {
  
  
  
  
"amount": 2500,
  
  
  
  
"currency": "EUR"
  
  
  
},
  
  
  
"invoice": {
  
  
  
  
"externalId": "INV-2025-0001",
  
  
  
  
"dueDate": "2025-10-15T00:00:00Z"
  
  
  
},
  
  
  
"flow": {
  
  
  
  
"collaborator": {
  
  
  
  
  
"uuid": "7f70e314-32d7-49eb-9721-1f986574f912",
  
  
  
  
  
"legalName": "Gestoria Perez SL"
  
  
  
  
}
  
  
  
}
  
  
},
  
  
{
  
  
  
"uuid": "a2b3c4d5-e6f7-8901-2345-67890abcdef0",
  
  
  
"externalId": null,
  
  
  
"flowUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  
  
  
"type": "SIGNATURE",
  
  
  
"status": "CREATED",
  
  
  
"createdAt": "2025-09-16T08:22:00Z",
  
  
  
"statusUpdatedAt": null,
  
  
  
"payment": null,
  
  
  
"invoice": null,
  
  
  
"flow": {
  
  
  
  
"collaborator": null
  
  
  
}
  
  
}
  
]
}

Playground​

Servidor
Autorización
Headers
Variables
Key
Value

Ejemplos​