Version: 1.0.54

• OpenAPI Spec

To-do Service

This page describes how to integrate with the To-do Service on a technical level. If you need a conceptual overview first, see the **Foundation API Guide **.

---

REST Resources

The To‑do Service lets you:

• Manage and retrieve to-do items within a space.
• Validate and normalize to-do types that contributors register by themselves.
• Summarize to-do items by type for display purposes.

To-do

To-do items are lightweight, actionable tasks stored by the BTX platform. They are typically managed by contributors, but any authorized client can view them. Each item:

• belongs to a space (spaceId)
• has a type (e.g. paymentDue, reviewPurchaseDocument)
• may carry type-specific data (e.g. documentId)

Example to-do item:

{
  "todoItemId": "bf514229-fa39-4bca-b8d9-b96607e9954a",
  "spaceId": "1b34de13-4063-41e6-8b68-237f0c391550",
  "type": "reviewPurchaseDocument",
  "data": {
    "spaceId": "1b34de13-4063-41e6-8b68-237f0c391550",
    "todoItemId": "bf514229-fa39-4bca-b8d9-b96607e9954a"
  },
  "reference": "bf514229-fa39-4bca-b8d9-b96607e9961e",
  "requiredPermission": {
    "resourceId": "1b34de13-4063-41e6-8b68-237f0c391550",
    "scope": "space_read"
  }
}

Todo Type

A Todo Type defines how a category of to-dos should be interpreted and displayed:

• unique identifier (type)
• localized labels (referenced from the Asset Service via labels URI)
• a client action (action) to perform (typically a redirect)
• display options like priority, displayCount, and optional fields

Types are registered via the Plugin Service and validated by the To-do Service.

Required fields

• type (string) — unique identifier of the type, must not be blank
• labels (string) — URL of an i18n asset JSON, e.g. static/ux/todo/todopurchasereview/reviewPurchaseDocument
• action (string) — URL of the todo action endpoint(internal url to avoid apigee limit no more then 200 records in the body) , e.g. http://btx-ux-todo-review-contributor.ns-gcpbe-btxux-dev.svc.cluster.local:8080/ux/todoreview/v1/todoActions
• displayCount (boolean) — whether to show the numeric count
• priority (integer) — higher = more important

Optional fields

• classification (string) — categorization such as daily, weekly, …
• dynamicLabels (boolean) — whether labels should be resolved dynamically etc.

Example Todo Type definition (Plugin Provision Hook payload)

\{
  "pluginInterface": \{
    "namespace": "com.unifiedpost.btx.todo",
    "name": "todoTypes",
    "version": "1.0"
  \},
  "data": \{
    "type": "reviewPurchaseDocument",
    "labels": "static/ux/todo/todopurchasereview/reviewPurchaseDocument",
    "action": "http://btx-ux-todo-review-contributor.ns-gcpbe-btxux-dev.svc.cluster.local:8080/ux/todoreview/v1/todoActions",
    "displayCount": true,
    "priority": 50,
    "classification": "daily",
    "dynamicLabels": true
  \}
\}

Example resolved labels (from Asset Service)

\{
  "description_one": "Purchase invoice review",
  "description_other": "Purchase invoices review",
  "mobile": \{
    "description": "Review purchase"
  \}
\}

Example resolved action(todo action endpoint response, endpoint is implemented by contributor)

 \{
   "actionType": "REDIRECT",
   "uri": "https://app.dev.btx.banqup.com/purchase-invoices?tab=REVIEW&pageIndex=1&pageSize=50"
 \}

Working with to-do

Retrieving to-do items

List all to‑do items in a space: GET /core/todo/v1/spaces/{spaceId}/todoItems (see: ../../../docs/foundation/todo/list-todo-items)

Optional query parameters:

• type — filter by the type value stored on the item. (paymentDue, reviewPurchaseDocument, …)
• reference — filter by the reference value stored on the item.

Both parameters can be combined.

GET /v1/spaces/1b34de13-4063-41e6-8b68-237f0c391550/todoItems?type=paymentDue&reference=bf514229-fa39-4bca-b8d9-b96607e9961e
Accept: application/json, application/x-ndjson

Retrieve a single to‑do by its todoItemId:

GET /v1/spaces/1b34de13-4063-41e6-8b68-237f0c391550/todoItems/bf514229-fa39-4bca-b8d9-b96607e9954a
Accept: application/json

Summarize to-do items by type:

GET /core/todo/v1/spaces/{spaceId}/todoItems:summarize

This endpoint aggregates to-do items by type, providing a count for each, along with a localized label and a client action.

Optional localization parameters can be provided for the summary's label:

• l (query parameter) — the primary locale (e.g. en-GB).
• Accept-Language (header) — a list of fallback locales (e.g. en-GB,en).

GET /v1/spaces/1b34de13-4063-41e6-8b68-237f0c391550/todoItems:summarize?l=en
Accept: application/x-ndjson
Accept-Language: en,fr

Example line from the NDJSON response stream:

{
  "type": "reviewPurchaseDocument",
  "count": 1,
  "displayCount": true,
           "priority": 50,
  "labels": {
    "description_one": "Purchase invoice review",
    "description_other": "Purchase invoices review",
    "mobile": {
      "description": "Review purchase"
    }
  },
  "action": {
    "actionType": "REDIRECT",
    "uri": "https://app.dev.btx.banqup.com/purchase-invoices?tab=REVIEW&pageIndex=1&pageSize=50"
  }
}

Creating to-do items

Create a to‑do item with POST /core/todo/v1/spaces/{spaceId}/todoItems (see: ../../../docs/foundation/todo/create-todo-item)

POST /v1/spaces/1b34de13-4063-41e6-8b68-237f0c391550/todoItems
Content-Type: application/json

{
  "type": "reviewPurchaseDocument",
  "data": {
    "spaceId": "1b34de13-4063-41e6-8b68-237f0c391550",
    "todoItemId": "bf514229-fa39-4bca-b8d9-b96607e9954a"
  },
  "reference": "bf514229-fa39-4bca-b8d9-b96607e9961e"
}

A successful creation returns HTTP 201 and the created item.

Updating to-do items

Update an existing to‑do item with PUT /core/todo/v1/spaces/{spaceId}/todoItems/{todoItemId} (see: ../../../docs/foundation/todo/update-todo-item)

PUT /v1/spaces/1b34de13-4063-41e6-8b68-237f0c391550/todoItems/bf514229-fa39-4bca-b8d9-b96607e9954a
Content-Type: application/json

{
  "data": {
    "spaceId": "1b34de13-4063-41e6-8b68-237f0c391550",
    "todoItemId": "bf514229-fa39-4bca-b8d9-b96607e9954a"
  },
  "reference": "bf514229-fa39-4bca-b8d9-b96607e9961e"
}

A successful update returns HTTP 200 and the updated item.

Deleting to-do items

Delete a to‑do item with DELETE on the same path. A successful deletion returns HTTP 204 No Content.

---

Security

To interact with the To‑do Service you must hold the right UMA permissions and OAuth scopes.

1. Create / Update / Delete to-do items

You need both of these:

• Todo type management permission on the specific type (subject, <todoType>, todo_type_manage) — granted in UMA bootstrap. Example: (subject, reviewPurchaseDocument, todo_type_manage)

• Write permission on the space (subject, <spaceId>, space_foundation_todo_write) — granted via the Access Management permissions manifest when your service is registered in the Service Store. Example manifest snippet:

{
  "resource": "space",
  "scope": "space_foundation_todo_write"
}

2. Get / List / Summarize to-do items

Every to‑do item carries its own permission

"requiredPermission": {
"resourceId": "1b34de13-4063-41e6-8b68-237f0c391550",
"scope": "space_read"
}

Your token must always grant space-level read permission: (subject, <spaceId>, space_read) in the default UMA audience ( uma-authz). If the to-do item also specifies a requiredPermission, your token must additionally grant: ( subject, <resourceId>, <scope>) in the default UMA audience (uma-authz). If either resourceId or scope is missing at requiredPermission of to-do item, the item is treated as public within the space and only the space-level check applies.

For the list and summarize endpoints, only items for which the caller has the required permission will be returned or included in the count.

Typical read permission on a space (subject, <resourceId>, space_read) — granted via the Access Management permissions manifest when your service is registered in the Service Store. Example manifest snippet:

{
  "resource": "space",
  "scope": "space_read"
}

3. Register / Update a Todo Type

Again, todo_type_manage is required on that type: (subject, <todoType>, todo_type_manage) — checked by the Todo Type Authorizer endpoint.

Authentication

OAuth 2.0: oauth2

Security Scheme Type:	oauth2
OAuth Flow (clientCredentials):	Token URL: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken Scopes: info: Scopes are endpoint-specific, see each endpoint for required scope.
OAuth Flow (authorizationCode):	Token URL: https://api.btx.fr.banqup.com/oauth2/token Authorization URL: https://api.btx.fr.banqup.com/oauth2/auth Scopes: info: Scopes are endpoint-specific, see each endpoint for required scope.