> For the complete documentation index, see [llms.txt](https://docs.xorosoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xorosoft.com/developers-api/api-requirements.md).
# API Requirements
#### End Point
Endpoints are located at the following domain and will need to have a specific reference added to return data. PLEASE NOTE: You cannot access this URL directly and must reference one of the specific endpoints below.
#### Private App
Private applications can interact with Xorosoft ERP through APIs using basic authentication. This documentation provides guidance on generating API credentials and accessing Xorosoft ERP's functionalities programmatically.
To authenticate with Xorosoft ERP's API, follow these steps:
**Step 1: Navigate to the Private App Module**
Log in to your Xorosoft ERP account and navigate to the Private App module. 
**Step 2: Generate API Credentials**
* Enter the name of your API.
* Select the read/write access for the modules you require, including the 3PL option.
* Click "Save".
**Step 3: View Generated API Keys**
The generated API keys will be displayed on the page after saving.
#### 3PL Platform APIs
This guide introduces Xorosoft ERP as a leading third-party logistics (3PL) platform, emphasizing its role in streamlining logistics through secure integration APIs. Tailored for connected clients, these APIs provide secure access to account-specific data, enhancing operational efficiency and competitiveness. Learn how to leverage Xorosoft ERP's capabilities for your logistics needs.
**Step 1: Generate 3PL Account Token**
* Navigate to the 3PL account module for the specific 3PL account you intend to make requests to and locate the "Generate 3PL Account Token" button within the "Options" section.
* Click on the "Generate 3PL Account Token" button to create a token specific to the selected 3PL account. The generated token will be displayed in a popup window, allowing users to copy the token directly from the popup.
* Use the generated token directly as a parameter in the API requests targeting the corresponding 3PL account.
**Step 2: Making GET and POST API Requests with the Generated Token**
Once you have obtained the token specific to your 3PL account, you can use it as a parameter in your API requests to authenticate and access the desired resources. Here's how to incorporate the token into your API requests:
**GET Request**
This GET request retrieves data from the API using the generated token.
* **Endpoint**: Specify your API endpoint here
* **Parameters**:
* id: `123`
* account\_token: `Token generated for specific 3PL account.`
```http
/your-api-endpoint (nullable)id=123&account_token=YOUR_GENERATED_TOKEN_HERE
```
**POST Request**
This POST request sends data to the API using the generated token included in the JSON body.
* **Endpoint**: Specify your API endpoint here
* **Request Body**: Include the necessary data to be sent in the request body along with the account\_token.
* **Headers**:
* Content-Type: application/json
```http
POST /your-api-endpoint HTTP/1.1
Host: your-api-host
Content-Type: application/json
{
"SoEstimateHeader":{...},
"SoEstimateItemLineArr":[...],
"AccountToken": "YOUR_GENERATED_TOKEN_HERE"
}
```
#### Public App
Public applications can interact with APIs from Xorosoft ERP through OAuth, assuming the application has been granted permission by the user. Please contact Xorosoft if you would like to use Public Applications.
\* Public apps are added to the Xorosoft ERP App store.
Terminology
Before getting into the nitty-gritty of the authorization process, let's go over some of the terms that we'll be using for the rest of the guide.
* Client
Any application that would like access to a Xorosoft ERP's data. A user must grant permission before the client can access any data.
* User
An ERP account holder. This is the person giving permission to a client to access their data through the APIs.
Step 1: Get client credentials
Contact us for the API Key and Secret Key.
Step 2: Ask for permission
The first step of process is to get authorization from the user. This is done by displaying a prompt provided by Xorosoft ERP;
{redirect\_uri}\&state={user}
* {user} - substitute this with the username of user.
* {api\_key} - substitute this with the app's API Key.
* {redirect\_uri} - (Required) substitute this with the URL where you want to redirect the users after they authorize the client.
Step 3: Confirm installation
When the user clicks the Install button in the prompt, they will be redirected to the client server as specified above. One of the parameters passed in the confirmation redirect is the Authorization Code and the same state. Get Access Token:
POST }\&redirect\_uri={redirect\_uri} \&code={code}
Response:
*{"access\_token": "`f85632530bf277ec9ac6f649fc327f17`","token\_type": "bearer","expires\_in": 1199,"refresh\_token": "`f8563SDFasdfasdfdsfa2530bf277ec9ac6f649fc327fasdf17`"*
*}*
Note: The Public App documentation is undergoing an update. Please contact us if you would like to pursue the Public App option for getting the refresh token and HMAC verification.
#### Authentication
The Xorosoft API uses [Basic HTTP authentication](http://en.wikipedia.org/wiki/Basic_access_authentication). Use your Xorosoft `API Key` as the username and `API Secret` as the password. You can generate `API Key` and `API Secret` under Private Apps module in Xorosoft ERP.
The Authorization header is constructed as follows:
* Username (`API KEY`) and password (`API Secret`) are combined into a string "username:password"
* The resulting string is then encoded using the RFC2045-MIME variant of Base64
* The authorization method and a space i.e. "Basic " is then put before the encoded string.
For example, if the `API KEY` given is 'Xorosoft' and the `API Secret` is 'Xorosoft ERP' then the header is formed as follows:
* Authorization: Basic 09SDFkjklj09890llksdjgf9ja3M=
#### API Rate Limits
In an effort to ensure consistent application performance and increased scalability, we have implemented rate limiting of 2 API requests per second on the Xorosoft API.
#### Server Responses
| Status Code | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK - The request was successful (some API calls may return 201 instead). |
| `400` | Bad Request - The request could not be understood or was missing required parameters. |
| `401` | Unauthorized - Authentication failed or user does not have permissions for the requested operation. |
| `403` | Forbidden - Access denied. |
| `404` | Not Found - Resource was not found. |
| `405` | Method Not Allowed - Requested method is not supported for the specified resource. |
| | |
| `408` | Request Timeout - The server timed out waiting for the request to complete. The client should retry the request without modifications. |
| `429` | Too Many Requests - Exceeded Xorosoft's API limits. When the limit is reached, your application should stop making requests and ensure that no more than 2 requests are made within one second. |
| `500` | Internal Server Error - Xorosoft has encountered an error. |
#### Response Data Object
All the authorized API calls must return the valid response code 200 and data in specific Xorosoft ERP format with following properties - Result, Message and Data\
`{`\
`"Data": {},`\
`"Result": true,`\
`"Message": "Wave data loaded successfully",`\
`"Page": 1,`\
`"TotalPages": 0`\
`}`\
Result - If the result is false, it states that an error has occurred and Message property will contain the error message
Message - Contains the response message from Api call
Data - Object returned as a response from the successful api call
\
\
Paging Support:
Some APIs have paging support enabled which means the data returned in the APIs will always be paged. Those APIs will mention paging enabled in the get calls. The page number will be manadatory as a part of request parameters. For these paged APIs, the reponse will contain extra following properties.
Page - Page number of the data set
TotalPages - Total pages of the data set
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.xorosoft.com/developers-api/api-requirements.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.