Add invoice ZIP request methods

Author: raul-facturapi

CHANGELOG.md

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add draft support methods for retentions: `retentions.updateDraft(String id, Map<String, Object> data)`, `retentions.copyToDraft(String id)`, `retentions.stampDraft(String id)`, and `retentions.cancel(String id)`.
 
+- Add `invoices.createZipRequest(Map<String, Object> data)` for `POST /invoices/zip-requests`.
+- Add `invoices.listZipRequests(Map<String, ?> params)` for `GET /invoices/zip-requests`.
+- Add `invoices.retrieveZipRequest(String id)` for `GET /invoices/zip-requests/{id}`.
+- Add `invoices.downloadZipRequest(String id)` for streaming `GET /invoices/zip-requests/{id}/zip`.
+
 ## [1.3.0] - 2026-06-07
 
 ### Added

src/main/java/io/facturapi/resources/InvoicesResource.java

@@ -142,6 +142,63 @@ public InputStream downloadZipStream(String id) {
     return client.getStream("/invoices/" + id + "/zip");
   }
 
+  /**
+   * Creates a ZIP request or returns the existing request for the same criteria.
+   *
+   * @param data ZIP request criteria.
+   * @return ZIP request data.
+   * @see <a href="https://docs.facturapi.io/api#tag/Invoices">API reference</a>
+   */
+  public Map<String, Object> createZipRequest(Map<String, Object> data) {
+    return post(
+      "/invoices/zip-requests",
+      data,
+      null,
+      new TypeReference<Map<String, Object>>() {}
+    );
+  }
+
+  /**
+   * Gets a paginated list of ZIP requests.
+   *
+   * @param params Search and pagination parameters.
+   * @return Paginated ZIP request result.
+   * @see <a href="https://docs.facturapi.io/api#tag/Invoices">API reference</a>
+   */
+  public SearchResult<Map<String, Object>> listZipRequests(Map<String, ?> params) {
+    return get(
+      "/invoices/zip-requests",
+      params,
+      new TypeReference<SearchResult<Map<String, Object>>>() {}
+    );
+  }
+
+  /**
+   * Gets a ZIP request by id.
+   *
+   * @param id ZIP request id.
+   * @return ZIP request data.
+   * @see <a href="https://docs.facturapi.io/api#tag/Invoices">API reference</a>
+   */
+  public Map<String, Object> retrieveZipRequest(String id) {
+    return get(
+      "/invoices/zip-requests/" + id,
+      null,
+      new TypeReference<Map<String, Object>>() {}
+    );
+  }
+
+  /**
+   * Downloads the ZIP generated for a request.
+   *
+   * @param id ZIP request id.
+   * @return ZIP stream. Caller owns closing it.
+   * @see <a href="https://docs.facturapi.io/api#tag/Invoices">API reference</a>
+   */
+  public InputStream downloadZipRequest(String id) {
+    return client.getStream("/invoices/zip-requests/" + id + "/zip");
+  }
+
   /**
    * Downloads the cancellation receipt XML file.
    *

src/test/java/io/facturapi/FacturapiResourcesTest.java

@@ -206,6 +206,98 @@ void retentionDraftCancelAndListUseExpectedPaths() {
     assertEquals("/v2/retentions?status=draft", listRequest.uri().getPath() + "?" + listRequest.uri().getQuery());
   }
 
+  @Test
+  void invoiceZipRequestCanBeCreated() {
+    StubHttpClient httpClient = new StubHttpClient();
+    httpClient.enqueueJson(200, "{\"id\":\"zip_1\",\"status\":\"pending\"}");
+
+    Facturapi sdk = new Facturapi(
+      FacturapiConfig.builder("sk_test")
+        .httpClient(httpClient.client())
+        .build()
+    );
+
+    var response = sdk.invoices().createZipRequest(
+      Map.of(
+        "year", 2025,
+        "month", 3,
+        "issuer_type", "issuing",
+        "invoice_types", java.util.List.of("I", "E")
+      )
+    );
+
+    assertEquals("zip_1", response.get("id"));
+    var request = httpClient.requests().get(0);
+    assertEquals("POST", request.method());
+    assertEquals("/v2/invoices/zip-requests", request.uri().getPath());
+    assertTrue(request.bodyUtf8().contains("\"issuer_type\":\"issuing\""));
+  }
+
+  @Test
+  void invoiceZipRequestsCanBeListed() {
+    StubHttpClient httpClient = new StubHttpClient();
+    httpClient.enqueueJson(
+      200,
+      "{\"page\":1,\"total_pages\":1,\"total_results\":1,\"data\":[{\"id\":\"zip_1\"}]}"
+    );
+
+    Facturapi sdk = new Facturapi(
+      FacturapiConfig.builder("sk_test")
+        .httpClient(httpClient.client())
+        .build()
+    );
+
+    var response = sdk.invoices().listZipRequests(
+      Map.of("year", 2025, "month", 3, "status", "finished", "limit", 20, "page", 1)
+    );
+
+    assertEquals("zip_1", response.getData().get(0).get("id"));
+    var request = httpClient.requests().get(0);
+    assertEquals("GET", request.method());
+    assertEquals("/v2/invoices/zip-requests", request.uri().getPath());
+    assertTrue(request.uri().getQuery().contains("year=2025"));
+    assertTrue(request.uri().getQuery().contains("status=finished"));
+  }
+
+  @Test
+  void invoiceZipRequestCanBeRetrieved() {
+    StubHttpClient httpClient = new StubHttpClient();
+    httpClient.enqueueJson(200, "{\"id\":\"zip_1\",\"status\":\"finished\"}");
+
+    Facturapi sdk = new Facturapi(
+      FacturapiConfig.builder("sk_test")
+        .httpClient(httpClient.client())
+        .build()
+    );
+
+    var response = sdk.invoices().retrieveZipRequest("zip_1");
+
+    assertEquals("finished", response.get("status"));
+    var request = httpClient.requests().get(0);
+    assertEquals("GET", request.method());
+    assertEquals("/v2/invoices/zip-requests/zip_1", request.uri().getPath());
+  }
+
+  @Test
+  void invoiceZipRequestCanBeDownloaded() throws Exception {
+    StubHttpClient httpClient = new StubHttpClient();
+    httpClient.enqueueBinary(200, "ZIP-CONTENT".getBytes(StandardCharsets.UTF_8), "application/zip");
+
+    Facturapi sdk = new Facturapi(
+      FacturapiConfig.builder("sk_test")
+        .httpClient(httpClient.client())
+        .build()
+    );
+
+    try (InputStream stream = sdk.invoices().downloadZipRequest("zip_1")) {
+      assertEquals("ZIP-CONTENT", new String(stream.readAllBytes(), StandardCharsets.UTF_8));
+    }
+
+    var request = httpClient.requests().get(0);
+    assertEquals("GET", request.method());
+    assertEquals("/v2/invoices/zip-requests/zip_1/zip", request.uri().getPath());
+  }
+
   @Test
   void organizationUploadsAcceptBytes() {
     StubHttpClient httpClient = new StubHttpClient();