square.rb 6.3.0.20200826 → 17.1.0.20220120

data/lib/square/api/invoices_api.rb

@@ -7,19 +7,16 @@ module Square
 
     # Returns a list of invoices for a given location. The response
     # is paginated. If truncated, the response includes a `cursor` that you
-    # use in a subsequent request to fetch the next set of invoices.
-    # For more information about retrieving invoices, see [Retrieve
-    # invoices](https://developer.squareup.com/docs/docs/invoices-api/overview#r
-    # etrieve-invoices).
+    # use in a subsequent request to retrieve the next set of invoices.
     # @param [String] location_id Required parameter: The ID of the location for
     # which to list invoices.
     # @param [String] cursor Optional parameter: A pagination cursor returned by
     # a previous call to this endpoint.  Provide this cursor to retrieve the
     # next set of results for your original query.  For more information, see
-    # [Pagination](https://developer.squareup.com/docs/docs/working-with-apis/pa
-    # gination).
+    # [Pagination](https://developer.squareup.com/docs/working-with-apis/paginat
+    # ion).
     # @param [Integer] limit Optional parameter: The maximum number of invoices
-    # to return (200 is the maximum `limit`).  If not provided, the server  uses
+    # to return (200 is the maximum `limit`).  If not provided, the server uses
     # a default limit of 100 invoices.
     # @return [ListInvoicesResponse Hash] response from the API call
     def list_invoices(location_id:,
@@ -52,16 +49,16 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
-    # Creates a draft [invoice](#type-invoice)
+    # Creates a draft [invoice]($m/Invoice)
     # for an order created using the Orders API.
     # A draft invoice remains in your account and no action is taken.
     # You must publish the invoice before Square can process it (send it to the
     # customer's email address or charge the customer’s card on file).
-    # For more information, see [Manage Invoices Using the Invoices
-    # API](https://developer.squareup.com/docs/docs/invoices-api/overview).
     # @param [CreateInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -75,7 +72,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -90,7 +87,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Searches for invoices from a location specified in
@@ -99,10 +98,7 @@ module Square
     # location and
     # optionally one customer.
     # The response is paginated. If truncated, the response includes a `cursor`
-    # that you use in a subsequent request to fetch the next set of invoices.
-    # For more information about retrieving invoices, see [Retrieve
-    # invoices](https://developer.squareup.com/docs/docs/invoices-api/overview#r
-    # etrieve-invoices).
+    # that you use in a subsequent request to retrieve the next set of invoices.
     # @param [SearchInvoicesRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -116,7 +112,7 @@ module Square
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -131,19 +127,21 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Deletes the specified invoice. When an invoice is deleted, the
-    # associated Order status changes to CANCELED. You can only delete a draft
-    # invoice (you cannot delete an invoice scheduled for publication, or a
-    # published invoice).
+    # associated order status changes to CANCELED. You can only delete a draft
+    # invoice (you cannot delete a published invoice, including one that is
+    # scheduled for processing).
     # @param [String] invoice_id Required parameter: The ID of the invoice to
     # delete.
     # @param [Integer] version Optional parameter: The version of the
-    # [invoice](#type-invoice) to delete. If you do not know the version, you
-    # can call [GetInvoice](#endpoint-Invoices-GetInvoice) or 
-    # [ListInvoices](#endpoint-Invoices-ListInvoices).
+    # [invoice]($m/Invoice) to delete. If you do not know the version, you can
+    # call [GetInvoice]($e/Invoices/GetInvoice) or 
+    # [ListInvoices]($e/Invoices/ListInvoices).
     # @return [DeleteInvoiceResponse Hash] response from the API call
     def delete_invoice(invoice_id:,
                        version: nil)
@@ -152,7 +150,7 @@ module Square
       _query_builder << '/v2/invoices/{invoice_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'invoice_id' => invoice_id
+        'invoice_id' => { 'value' => invoice_id, 'encode' => true }
       )
       _query_builder = APIHelper.append_url_with_query_parameters(
         _query_builder,
@@ -176,11 +174,13 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Retrieves an invoice by invoice ID.
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # retrieve.
     # @return [GetInvoiceResponse Hash] response from the API call
     def get_invoice(invoice_id:)
@@ -189,7 +189,7 @@ module Square
       _query_builder << '/v2/invoices/{invoice_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'invoice_id' => invoice_id
+        'invoice_id' => { 'value' => invoice_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
@@ -209,18 +209,20 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
-    # Updates an invoice by modifying field values, clearing field values, or
-    # both
-    # as specified in the request.
-    # There are no restrictions to updating an invoice in a draft state.
-    # However, there are guidelines for updating a published invoice.
-    # For more information, see [Update an
-    # invoice](https://developer.squareup.com/docs/docs/invoices-api/overview#up
-    # date-an-invoice).
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # Updates an invoice by modifying fields, clearing fields, or both. For most
+    # updates, you can use a sparse
+    # `Invoice` object to add fields or change values and use the
+    # `fields_to_clear` field to specify fields to clear.
+    # However, some restrictions apply. For example, you cannot change the
+    # `order_id` or `location_id` field and you
+    # must provide the complete `custom_fields` list to update a custom field.
+    # Published invoices have additional restrictions.
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # update.
     # @param [UpdateInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -233,14 +235,14 @@ module Square
       _query_builder << '/v2/invoices/{invoice_id}'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'invoice_id' => invoice_id
+        'invoice_id' => { 'value' => invoice_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -255,15 +257,17 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Cancels an invoice. The seller cannot collect payments for
     # the canceled invoice.
-    # You cannot cancel an invoice in a terminal state: `PAID`, `REFUNDED`,
-    # `CANCELED`, or `FAILED`.
+    # You cannot cancel an invoice in the `DRAFT` state or in a terminal state:
+    # `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
     # @param [String] invoice_id Required parameter: The ID of the
-    # [invoice](#type-invoice) to cancel.
+    # [invoice]($m/Invoice) to cancel.
     # @param [CancelInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
     # object definition for field details.
@@ -275,14 +279,14 @@ module Square
       _query_builder << '/v2/invoices/{invoice_id}/cancel'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'invoice_id' => invoice_id
+        'invoice_id' => { 'value' => invoice_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -297,7 +301,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
 
     # Publishes the specified draft invoice.
@@ -312,12 +318,8 @@ module Square
     # `UNPAID` if
     # Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on
     # file for a portion of the
-    # invoice amount).
-    # For more information, see
-    # [Create and publish an
-    # invoice](https://developer.squareup.com/docs/docs/invoices-api/overview#cr
-    # eate-and-publish-an-invoice).
-    # @param [String] invoice_id Required parameter: The id of the invoice to
+    # invoice amount.
+    # @param [String] invoice_id Required parameter: The ID of the invoice to
     # publish.
     # @param [PublishInvoiceRequest] body Required parameter: An object
     # containing the fields to POST for the request.  See the corresponding
@@ -330,14 +332,14 @@ module Square
       _query_builder << '/v2/invoices/{invoice_id}/publish'
       _query_builder = APIHelper.append_url_with_template_parameters(
         _query_builder,
-        'invoice_id' => invoice_id
+        'invoice_id' => { 'value' => invoice_id, 'encode' => true }
       )
       _query_url = APIHelper.clean_url _query_builder
 
       # Prepare headers.
       _headers = {
         'accept' => 'application/json',
-        'content-type' => 'application/json; charset=utf-8'
+        'Content-Type' => 'application/json'
       }
 
       # Prepare and execute HttpRequest.
@@ -352,7 +354,9 @@ module Square
       # Return appropriate response type.
       decoded = APIHelper.json_deserialize(_response.raw_body)
       _errors = APIHelper.map_response(decoded, ['errors'])
-      ApiResponse.new(_response, data: decoded, errors: _errors)
+      ApiResponse.new(
+        _response, data: decoded, errors: _errors
+      )
     end
   end
 end