feat: sync with the API spec (v2 transactions, v2 items, SCR, balance, model fields)

README.md

@@ -53,3 +53,48 @@ if(connectorsResponse.isSuccessful()) {
   ErrorResponse errorResponse = pluggyClient.parseError(connectorsResponse)
 }
 ```
+
+### Transactions (cursor pagination)
+
+`getTransactions` (`GET /transactions`) is deprecated and returns `410` for newer applications. Use `getTransactionsV2` (`GET /v2/transactions`) and follow the cursor until there is no next page:
+
+```java
+List<Transaction> transactions = new ArrayList<>();
+TransactionsCursorSearchRequest request = new TransactionsCursorSearchRequest().dateFrom("2026-01-01");
+while (true) {
+  TransactionsCursorResponse page = pluggyClient.service()
+    .getTransactionsV2(accountId, request)
+    .execute()
+    .body();
+  transactions.addAll(page.getResults());
+  if (!page.hasNext()) {
+    break;
+  }
+  request = new TransactionsCursorSearchRequest().dateFrom("2026-01-01").after(page.getNextCursor());
+}
+```
+
+### Listing items (opt-in)
+
+> **Opt-in, paid plans only.** Listing items is disabled by default and is only available to paid-plan teams that have explicitly requested it from Pluggy support. Teams without it enabled get `403` with `codeDescription` `LIST_ITEMS_FEATURE_NOT_ENABLED`. For most integrations, store each `itemId` when it is created (Pluggy Connect `onSuccess` or the `item/created` webhook) and use `getItem(id)` instead.
+
+`getItems` (`GET /v2/items`) returns items newest first, optionally filtered by `clientUserId` and/or `connectorId`, and is cursor-paginated like `getTransactionsV2`:
+
+```java
+List<ItemResponse> items = new ArrayList<>();
+ItemsCursorSearchRequest request = new ItemsCursorSearchRequest().clientUserId("user-123");
+while (true) {
+  Response<ItemsCursorResponse> response = pluggyClient.service().getItems(request).execute();
+  if (!response.isSuccessful()) {
+    ErrorResponse error = pluggyClient.parseError(response);
+    // "LIST_ITEMS_FEATURE_NOT_ENABLED" when listing items is not enabled for your team
+    throw new IllegalStateException(error.getCodeDescription() + ": " + error.getMessage());
+  }
+  ItemsCursorResponse page = response.body();
+  items.addAll(page.getResults());
+  if (!page.hasNext()) {
+    break;
+  }
+  request = new ItemsCursorSearchRequest().clientUserId("user-123").after(page.getNextCursor());
+}
+```

pom.xml

@@ -4,7 +4,7 @@
 
   <groupId>ai.pluggy</groupId>
   <artifactId>pluggy-java</artifactId>
-  <version>1.14.0</version>
+  <version>1.15.0</version>
 
   <packaging>jar</packaging>
 

src/main/java/ai/pluggy/client/PluggyApiService.java

@@ -6,6 +6,8 @@
 import ai.pluggy.client.request.CreateItemRequest;
 import ai.pluggy.client.request.InvestmentTransactionsSearchRequest;
 import ai.pluggy.client.request.ItemResourcesSearchRequest;
+import ai.pluggy.client.request.ItemsCursorSearchRequest;
+import ai.pluggy.client.request.TransactionsCursorSearchRequest;
 import ai.pluggy.client.request.TransactionsSearchRequest;
 import ai.pluggy.client.request.UpdateItemMfaRequest;
 import ai.pluggy.client.request.UpdateItemRequest;
@@ -56,6 +58,33 @@ Call<ItemResponse> updateItemSendMfa(@Path("id") String itemId,
   @DELETE("/items/{id}")
   Call<DeleteItemResponse> deleteItem(@Path("id") String existingItemId);
 
+  /**
+   * First page of the team's items, newest first, cursor-paginated. Fetch the following pages by
+   * passing {@link ItemsCursorResponse#getNextCursor()} as
+   * {@link ItemsCursorSearchRequest#after(String)} until it returns null.
+   *
+   * <p><b>Availability: opt-in, paid plans only.</b> Listing items is disabled by default and is
+   * only available to paid-plan teams that have explicitly requested it from Pluggy support. Teams
+   * without it enabled get {@code 403 LIST_ITEMS_FEATURE_NOT_ENABLED}. For most integrations,
+   * store each itemId when it is created (Pluggy Connect {@code onSuccess} or the
+   * {@code item/created} webhook) and use {@link #getItem(String)} instead.
+   */
+  @GET("/v2/items")
+  Call<ItemsCursorResponse> getItems();
+
+  /**
+   * Items filtered by {@code clientUserId} and/or {@code connectorId}, newest first,
+   * cursor-paginated. See {@link #getItems()}.
+   *
+   * <p><b>Availability: opt-in, paid plans only.</b> Listing items is disabled by default and is
+   * only available to paid-plan teams that have explicitly requested it from Pluggy support. Teams
+   * without it enabled get {@code 403 LIST_ITEMS_FEATURE_NOT_ENABLED}. For most integrations,
+   * store each itemId when it is created (Pluggy Connect {@code onSuccess} or the
+   * {@code item/created} webhook) and use {@link #getItem(String)} instead.
+   */
+  @GET("/v2/items")
+  Call<ItemsCursorResponse> getItems(@QueryMap ItemsCursorSearchRequest itemsCursorSearchRequest);
+
   /**
    * Open Finance only: the resources the financial institution declared for the item's consent.
    * Items on other connectors return an empty page.
@@ -67,6 +96,38 @@ Call<ItemResponse> updateItemSendMfa(@Path("id") String itemId,
   Call<ItemResourcesResponse> getItemResources(@Path("id") String itemId,
       @QueryMap ItemResourcesSearchRequest itemResourcesSearchRequest);
 
+  /**
+   * Retrieve the SCR (Bacen's Sistema de Informações de Crédito) for the document behind an item,
+   * for the last 4 available base dates. The response is Bacen's own payload, forwarded unchanged.
+   *
+   * <p>Opt-in: requires the SCR feature to be enabled for your team (ask Pluggy support); otherwise
+   * 403 SCR_FEATURE_NOT_ENABLED (see {@link ErrorResponse#getCodeDescription()}). Only available for
+   * Open Finance items with a known CPF/CNPJ (otherwise 422 SCR_ITEM_NOT_SUPPORTED).
+   *
+   * @param itemId item primary identifier
+   */
+  @GET("/items/{id}/scr")
+  Call<ScrResponse> getItemScr(@Path("id") String itemId);
+
+  /**
+   * Retrieve the SCR (Bacen's Sistema de Informações de Crédito) for the document behind an item,
+   * for a range of base dates. Base dates are months, and Bacen consolidates each one with a few
+   * months of delay, so the current month returns nothing.
+   *
+   * <p>Opt-in: requires the SCR feature to be enabled for your team (ask Pluggy support); otherwise
+   * 403 SCR_FEATURE_NOT_ENABLED (see {@link ErrorResponse#getCodeDescription()}). Only available for
+   * Open Finance items with a known CPF/CNPJ (otherwise 422 SCR_ITEM_NOT_SUPPORTED).
+   *
+   * @param itemId item primary identifier
+   * @param from first base date to consult, as YYYYMM (e.g. {@code 202604}); null to default to 3
+   *     base dates before {@code to}
+   * @param to last base date to consult, as YYYYMM (e.g. {@code 202607}); null to default to 2
+   *     months before the current one
+   */
+  @GET("/items/{id}/scr")
+  Call<ScrResponse> getItemScr(@Path("id") String itemId, @Query("from") String from,
+      @Query("to") String to);
+
   @GET("/accounts")
   Call<AccountsResponse> getAccounts(@Query("itemId") String itemId);
 
@@ -76,19 +137,49 @@ Call<ItemResourcesResponse> getItemResources(@Path("id") String itemId,
   @GET("/accounts/{id}")
   Call<Account> getAccount(@Path("id") String accountId);
 
+  /**
+   * Real-time balance fetched from the institution. Only available for Open Finance connectors;
+   * accounts on other connectors get an error response.
+   */
+  @GET("/accounts/{id}/balance")
+  Call<AccountBalance> getAccountBalance(@Path("id") String accountId);
+
   @GET("/bills")
   Call<BillsResponse> getBills(@Query("accountId") String accountId);
 
   @GET("/bills/{id}")
   Call<Bill> getBill(@Path("id") String billId);
 
+  /**
+   * @deprecated {@code GET /transactions} is deprecated and returns 410 for newer applications.
+   * Use {@link #getTransactionsV2(String)} (cursor pagination) instead.
+   */
+  @Deprecated
   @GET("/transactions")
   Call<TransactionsResponse> getTransactions(@Query("accountId") String accountId);
 
+  /**
+   * @deprecated {@code GET /transactions} is deprecated and returns 410 for newer applications.
+   * Use {@link #getTransactionsV2(String, TransactionsCursorSearchRequest)} (cursor pagination)
+   * instead.
+   */
+  @Deprecated
   @GET("/transactions")
   Call<TransactionsResponse> getTransactions(@Query("accountId") String accountId,
       @QueryMap TransactionsSearchRequest transactionsSearchRequest);
 
+  /**
+   * First page of an account's transactions, cursor-paginated. Fetch the following pages by
+   * passing {@link TransactionsCursorResponse#getNextCursor()} as
+   * {@link TransactionsCursorSearchRequest#after(String)} until it returns null.
+   */
+  @GET("/v2/transactions")
+  Call<TransactionsCursorResponse> getTransactionsV2(@Query("accountId") String accountId);
+
+  @GET("/v2/transactions")
+  Call<TransactionsCursorResponse> getTransactionsV2(@Query("accountId") String accountId,
+      @QueryMap TransactionsCursorSearchRequest transactionsCursorSearchRequest);
+
   @GET("/transactions/{id}")
   Call<Transaction> getTransaction(@Path("id") String transactionId);
 

src/main/java/ai/pluggy/client/request/ItemsCursorSearchRequest.java

@@ -0,0 +1,70 @@
+package ai.pluggy.client.request;
+
+import static ai.pluggy.utils.Asserts.assertNotNull;
+
+import java.util.HashMap;
+
+/**
+ * Query params for GET /v2/items (cursor pagination). All filters are optional. The API rejects
+ * unknown query params, so only the filters below can be sent.
+ *
+ * <p><b>Availability: opt-in, paid plans only.</b> Listing items is disabled by default and is
+ * only available to paid-plan teams that have explicitly requested it from Pluggy support. Teams
+ * without it enabled get {@code 403 LIST_ITEMS_FEATURE_NOT_ENABLED}. For most integrations, store
+ * each itemId when it is created (Pluggy Connect {@code onSuccess} or the {@code item/created}
+ * webhook) and use {@code getItem(id)} instead.
+ */
+public class ItemsCursorSearchRequest extends HashMap<String, Object> {
+
+  private static final int CLIENT_USER_ID_MAX_LENGTH = 255;
+
+  /**
+   * @param clientUserId String - only items created with this clientUserId (max 255 chars)
+   * @return this instance, useful to continue adding params
+   */
+  public ItemsCursorSearchRequest clientUserId(String clientUserId) {
+    assertNotNull(clientUserId, "clientUserId");
+    if (clientUserId.length() > CLIENT_USER_ID_MAX_LENGTH) {
+      throw new IllegalArgumentException(
+        "'clientUserId' cannot be longer than " + CLIENT_USER_ID_MAX_LENGTH + " characters");
+    }
+    put("clientUserId", clientUserId);
+    return this;
+  }
+
+  /**
+   * @param connectorId Integer - only items of this connector (>= 0)
+   * @return this instance, useful to continue adding params
+   */
+  public ItemsCursorSearchRequest connectorId(Integer connectorId) {
+    assertNotNull(connectorId, "connectorId");
+    if (connectorId < 0) {
+      throw new IllegalArgumentException("'connectorId' cannot be negative");
+    }
+    put("connectorId", connectorId);
+    return this;
+  }
+
+  /**
+   * @param after String - opaque cursor from a previous response
+   * ({@code ItemsCursorResponse#getNextCursor()}).
+   * @return this instance, useful to continue adding params
+   */
+  public ItemsCursorSearchRequest after(String after) {
+    assertNotNull(after, "after");
+    put("after", after);
+    return this;
+  }
+
+  public String getClientUserId() {
+    return (String) get("clientUserId");
+  }
+
+  public Integer getConnectorId() {
+    return (Integer) get("connectorId");
+  }
+
+  public String getAfter() {
+    return (String) get("after");
+  }
+}

src/main/java/ai/pluggy/client/request/Options.java

@@ -2,8 +2,10 @@
 
 import lombok.AllArgsConstructor;
 import lombok.Builder;
+import lombok.NoArgsConstructor;
 
 @Builder
+@NoArgsConstructor
 @AllArgsConstructor
 public class Options {
 

src/main/java/ai/pluggy/client/request/TransactionsCursorSearchRequest.java

@@ -0,0 +1,97 @@
+package ai.pluggy.client.request;
+
+import static ai.pluggy.utils.Asserts.assertNotEmpty;
+import static ai.pluggy.utils.Asserts.assertNotNull;
+
+import java.util.HashMap;
+import java.util.List;
+
+/**
+ * Query params for GET /v2/transactions (cursor pagination). {@code accountId} is passed
+ * separately to the service method. The API rejects unknown query params, so only the filters
+ * below can be sent.
+ */
+public class TransactionsCursorSearchRequest extends HashMap<String, Object> {
+
+  /**
+   * @param ids List<String> - list of transaction ids to return
+   * @return this instance, useful to continue adding params
+   */
+  public TransactionsCursorSearchRequest ids(List<String> ids) {
+    assertNotEmpty(ids, "ids");
+    put("ids", String.join(",", ids));
+    return this;
+  }
+
+  /**
+   * @param dateFrom String - transaction date lower bound, 'YYYY-MM-DD' or ISO-8601 date.
+   * Cannot be combined with {@link #createdAtFrom(String)}.
+   * @return this instance, useful to continue adding params
+   */
+  public TransactionsCursorSearchRequest dateFrom(String dateFrom) {
+    assertNotNull(dateFrom, "dateFrom");
+    assertNotCombined("createdAtFrom", "dateFrom");
+    put("dateFrom", dateFrom);
+    return this;
+  }
+
+  /**
+   * @param dateTo String - transaction date upper bound, 'YYYY-MM-DD' or ISO-8601 date.
+   * @return this instance, useful to continue adding params
+   */
+  public TransactionsCursorSearchRequest dateTo(String dateTo) {
+    assertNotNull(dateTo, "dateTo");
+    put("dateTo", dateTo);
+    return this;
+  }
+
+  /**
+   * @param createdAtFrom String - ISO-8601 timestamp; only transactions created in Pluggy from this
+   * moment on. Cannot be combined with {@link #dateFrom(String)}.
+   * @return this instance, useful to continue adding params
+   */
+  public TransactionsCursorSearchRequest createdAtFrom(String createdAtFrom) {
+    assertNotNull(createdAtFrom, "createdAtFrom");
+    assertNotCombined("dateFrom", "createdAtFrom");
+    put("createdAtFrom", createdAtFrom);
+    return this;
+  }
+
+  /**
+   * @param after String - opaque cursor from a previous response
+   * ({@code TransactionsCursorResponse#getNextCursor()}).
+   * @return this instance, useful to continue adding params
+   */
+  public TransactionsCursorSearchRequest after(String after) {
+    assertNotNull(after, "after");
+    put("after", after);
+    return this;
+  }
+
+  private void assertNotCombined(String existing, String adding) {
+    if (containsKey(existing)) {
+      throw new IllegalArgumentException(
+        "'" + adding + "' cannot be combined with '" + existing + "'");
+    }
+  }
+
+  public String getIds() {
+    return (String) get("ids");
+  }
+
+  public String getDateFrom() {
+    return (String) get("dateFrom");
+  }
+
+  public String getDateTo() {
+    return (String) get("dateTo");
+  }
+
+  public String getCreatedAtFrom() {
+    return (String) get("createdAtFrom");
+  }
+
+  public String getAfter() {
+    return (String) get("after");
+  }
+}

src/main/java/ai/pluggy/client/response/Account.java

@@ -1,10 +1,14 @@
 package ai.pluggy.client.response;
 
+import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
+import lombok.NoArgsConstructor;
 
 @Data
 @Builder
+@NoArgsConstructor
+@AllArgsConstructor
 public class Account {
 
   String id;