Create v4.expense-cash-advance-associations.markdown #1402
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,271 @@ | ||
| --- | ||
| title: Expense Cash Advance Associations v4.0 | ||
| layout: reference | ||
| --- | ||
|
|
||
| # Expense Cash Advance Associations v4.0 | ||
|
|
||
| The Expense Cash Advance Associations v4 API can be used for operations related to associating and disassociating cash advances with an expense report. | ||
|
|
||
| ## <a name="limitations"></a>Limitations | ||
|
|
||
| Access to this documentation does not provide access to the API. | ||
|
|
||
| ## <a name="products-editions"></a>Products and Editions | ||
|
|
||
| * Concur Expense Professional Edition | ||
| * Concur Expense Standard Edition | ||
|
|
||
| ## <a name="scope-usage"></a>Scope Usage | ||
|
|
||
| | Name | Description | Endpoint | | ||
| |----------------------------|--------------------------------------------------------------------------|--------------| | ||
| | `expense.report.read` | Read information about cash advances associated with a report. | GET | | ||
| | `expense.report.readwrite` | Read and write information about cash advances associated with a report. | GET, POST, DELETE | | ||
|
|
||
| ## Dependencies <a name="dependencies"></a> | ||
|
|
||
| - SAP Concur clients must purchase the Expense Cash Advance feature in order to use this API and use the [v4.1 Cash Advance APIs](/api-reference/cash-advance/v4-1.cash-advance.md). to create cash advances. | ||
|
|
||
| Please contact your SAP Concur representative for more information. | ||
|
|
||
| ## Access Token Usage <a name="access-token-usage"></a> | ||
|
|
||
| This API supports both company level and user level access tokens. | ||
|
|
||
| ## Get Cash Advance Associations | ||
|
|
||
| Returns cash advance IDs associated with the specified report. | ||
|
|
||
| ### Scopes | ||
|
|
||
| `expense.report.read` - Refer to [Scope Usage](#scope-usage) for full details. | ||
|
|
||
| ### URI | ||
|
|
||
| ```shell | ||
| https://{datacenterURI}/expensereports/v4/reports/{reportId}/cashAdvances | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |----------|----------|--------|--------------------------------------| | ||
| | reportId | `string` | path | The unique identifier of the report. | | ||
|
|
||
| ### Payloads | ||
|
|
||
| * Request: None | ||
| * Response: [CashAdvancesResponse](#cash-advances-response-schema) | ||
|
|
||
| ### Headers | ||
|
|
||
| * [RFC 7231 Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5) | ||
| * [RFC 7231 Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5) | ||
| * [RFC 7231 Content-Encoding](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) | ||
| * [RFC 7235 Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - Bearer Token that identifies the caller. | ||
| This is the Company or User access token. | ||
| * | ||
| ### Response | ||
|
|
||
| ### Status Codes | ||
|
|
||
| * [200 OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | ||
| * [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | ||
| * [401 Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | ||
| * [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | ||
| * [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | ||
| * [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | ||
|
|
||
| ### Examples | ||
|
|
||
| ### Request | ||
|
|
||
| ```shell | ||
| curl --location --request GET 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/cashAdvances' \ | ||
| --header 'Authorization: Bearer {access_token}' \ | ||
| --header 'Content-Type: application/json' | ||
| ``` | ||
|
|
||
| ### Response | ||
|
|
||
| #### 200 OK | ||
|
|
||
| ```shell | ||
| 200 OK | ||
|
|
||
| { | ||
| "cashAdvances": [ | ||
| { | ||
| "id": "4a205b23-9d47-413f-9eeb-cd7245b75a6a" | ||
| }, | ||
| { | ||
| "id": "75e1fbe2-7de8-467f-9f6f-67073908459b" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Associate Cash Advances with Report | ||
|
|
||
| Associates the specified cash advance(s) with the specified report. Replaces all existing associated cash advance(s) of the report with the provided payload. | ||
|
|
||
| Any invalid Cash Advance Ids will result in a failed action and no update will occur. | ||
|
|
||
|
There was a problem hiding this comment. Need a clarification that the POST operation REPLACES any prior associations rather than add them as amendments. Also it should also be clear that an individual bad/unrecognized CA Id will lead to a non-action with no change to any pre-existing association list. There was a problem hiding this comment.
Isn't that explained in the Swagger Documentation with the description of
Isn't that common usage of a POST in that it does a full replace of the object that is being sent? There was a problem hiding this comment. Minor typo on 111. Cash advances, not Cash advanced. The REPLACES comment was something that came out of the design review. The group felt it would be better to make this explicitly clear. The swagger simply says that 400=bad ID/404=ID not found. It doesn't explain that any single failure for a list of IDs will result in non-action for the entire list. |
||
| ### Scopes | ||
|
|
||
| `expense.report.readwrite` - Refer to [Scope Usage](#scope-usage) for full details. | ||
|
|
||
| ### URI | ||
|
|
||
| ```shell | ||
| https://{datacenterURI}/expensereports/v4/reports/{reportId}/cashAdvances | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |----------|----------|--------|--------------------------------------| | ||
| | reportId | `string` | path | The unique identifier of the report. | | ||
| | body | `CashAdvanceRequest` | application/json | The request body containing the cash advances to associate. | | ||
|
|
||
| ### Payloads | ||
|
|
||
| * Request: [CashAdvanceRequest](#cash-advances-post-schema) | ||
| * Response: [CashAdvancePostResponse](#cash-advance-uri-schema) | ||
|
|
||
| ### Headers | ||
|
|
||
| * [RFC 7231 Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5) | ||
| * [RFC 7231 Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5) | ||
| * [RFC 7231 Content-Encoding](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) | ||
| * [RFC 7235 Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - Bearer Token that identifies the caller. | ||
| This is the Company or User access token. | ||
|
|
||
| ### Response | ||
|
|
||
| ### Status Codes | ||
|
|
||
| * [201 OK](https://tools.ietf.org/html/rfc7231#section-6.3.2) | ||
| * [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | ||
| * [401 Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | ||
| * [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | ||
| * [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | ||
| * [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | ||
|
|
||
ctruzzi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### Examples | ||
|
|
||
| ### Request | ||
|
|
||
| ```shell | ||
| curl --location --request POST 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/cashAdvances' \ | ||
| --header 'Authorization: Bearer {access_token}' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --data-raw '{ | ||
| "cashAdvanceIds": [ | ||
| "3fa85f64-5717-4562-b3fc-2c963f66afa6" | ||
| ] | ||
| }' | ||
| ``` | ||
|
|
||
| ### Response | ||
|
|
||
| #### 201 Created | ||
|
|
||
| ```shell | ||
| 201 Created | ||
|
|
||
| { | ||
| "uri": "https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/cashAdvances" | ||
| } | ||
| ``` | ||
|
|
||
| ## Disassociate Cash Advances with Report | ||
|
|
||
| Disassociate the specified cash advance(s) from the specified report. | ||
|
|
||
| ### Scopes | ||
|
|
||
| `expense.report.readwrite` - Refer to [Scope Usage](#scope-usage) for full details. | ||
|
|
||
| ### URI | ||
|
|
||
| ```shell | ||
| https://{datacenterURI}/expensereports/v4/reports/{reportId}/cashAdvances?cashAdvanceIds={cashAdvanceId} | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |----------|----------------|--------|--------------------------------------| | ||
| | reportId | `string` | path | The unique identifier of the report. | | ||
| | cashAdvanceIds | `List<String>` | query | The unique identifier(s) of the cash advances to disassociate with the report | | ||
|
|
||
| ### Payloads | ||
|
|
||
| * Request: None | ||
| * Response: None | ||
|
|
||
| ### Headers | ||
|
|
||
| * [RFC 7231 Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5) | ||
| * [RFC 7231 Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5) | ||
| * [RFC 7231 Content-Encoding](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) | ||
| * [RFC 7235 Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - Bearer Token that identifies the caller. | ||
| This is the Company or User access token. | ||
|
|
||
| ### Response | ||
|
|
||
| ### Status Codes | ||
|
|
||
| * [204 OK](https://tools.ietf.org/html/rfc7231#section-6.3.2) | ||
| * [400 Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | ||
| * [401 Unauthorized](https://tools.ietf.org/html/rfc7235#section-3.1) | ||
| * [403 Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | ||
| * [404 Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4) | ||
| * [500 Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | ||
|
|
||
ctruzzi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### Examples | ||
|
|
||
| ### Request | ||
|
|
||
| ```shell | ||
| curl --request DELETE 'https://us.api.concursolutions.com/expensereports/v4/reports/764428DD6A664AF0BFCB/cashAdvances?cashAdvanceIds=3fa85f64-5717-4562-b3fc-2c963f66afa6?cashAdvanceIds=75e1fbe2-7de8-467f-9f6f-67073908459b' \ | ||
|
There was a problem hiding this comment. This is slightly different than what is shown in the template, I can keep as a curl or change to how they show them. There was a problem hiding this comment. We have lots of examples with curl. I'm fine with this for now. |
||
| --header 'Authorization: Bearer {access_token}' \ | ||
| --header 'Content-Type: application/json' | ||
| ``` | ||
|
|
||
| ### Response | ||
|
|
||
| #### 204 Created | ||
|
|
||
| ```shell | ||
| 204 No Content | ||
| ``` | ||
| ## Schema <a name="schema"></a> | ||
|
|
||
| ### <a name="cash-advance-response-schema"></a> CashAdvanceResponse | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |------|--------|--------|--------------------------------------| | ||
| | id | string | uuid | The associated cash advance Id. | | ||
|
|
||
ctruzzi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ### <a name="cash-advances-response-schema"></a> CashAdvancesResponse | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |--------------|--------|--------|--------------------------------------------------| | ||
| | cashAdvances | array | [CashAdvanceResponse](#cash-advance-response-schema) | List of the associated cash advance objects. | | ||
|
|
||
| #### <a name="cash-advances-post-schema"></a> CashAdvanceRequest | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |--------------|--------|--------|--------------------------------------------------| | ||
| | cashAdvanceIds | array | uuid | List of the associated cash advance ids | | ||
|
|
||
| ### <a name="cash-advance-uri-schema"></a> CashAdvancePostResponse | ||
|
|
||
| | Name | Type | Format | Description | | ||
| |------|--------|--------|--------------------------------------| | ||
| | uri | string | - | The href to retrieve the cash advance associations | | ||
|
|
||
ctruzzi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
ctruzzi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need Payloads section with link to CashAdvancesResponse schema
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might be worth checking the old pages, I don't see any on https://github.com/SAP-docs/preview.developer.concur.com/blob/main/src/api-reference/expense/expense-report/expense-entry.markdown
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's the v3 markdown. Check the v4 pages. https://github.com/SAP-docs/preview.developer.concur.com/blob/main/src/api-reference/expense/expense-report/v4.expenses.markdown
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FYI... There's actually a template markdown. https://github.concur.com/developer/documentation/blob/master/documentation-template.md
It's not adhered to well, but I'm trying to address documentation consistency, within ERS as a minimum but hopefully globally across Spend, as part of the overall externalization / parity / devcenter enhancement exercise.