Quick Start Guide ================= Requirements ------------ The input used in each module consists in a json object which contains the info related to action to do. **pending more** The url to use is the following: `https://oas-beta.ottomate.me/api/docs/ `_ Introduction ------------ To use OAS API you must to check the following requirements: - Have a OAS account - Authenticate your OAS account - Have access token to access to API - Create a organization via OAS API Access Token ------------ The client must have an API access token, which may or may not expire. Afterward, they must create their users and organizations for API access. It won't be necessary to know which API the organization was created from; it will only be linked to the user who created it. This same user will be able to grant access permissions. 1. The user must to fill the registration form 2. Once the request will be approved, a Welcome Email will be sent 3. Admin OAS could create an API client set the user as owner Access token authorization ~~~~~~~~~~~~~~~~~~~~~~~~~~ Once the access token has been provided when the authentication is done; it must be sent in the Authorization header of the request with the value. .. code-block:: text Bearer Access token API ~~~~~~~~~~~~~~~~ The API token is required for most routes, except for authentication. If you don't have a token, you must contact your OAS administrator. The access token must be sent in the X-Api-Key header of the partition, using the token value you previously received via email. .. mermaid:: sequenceDiagram actor User participant OTTO participant OAS Admin User ->> OTTO: Fill registration form OTTO ->> OAS Admin: send request OAS Admin ->> OAS Admin: Approve/Deny request OAS Admin ->> User: Sends a Welcome email OAS Admin -->> OAS Admin: Creates the an API client with user as owner Sign up ------- **POST** ``/api/auth/register/`` .. warning:: No available Sign in ------- **POST** ``/api/auth/login/`` The sign-in route allows existing users to authenticate themselves and gain access to the system. This route requires users to provide their credentials, which are then validated against the stored data in the database. **Form Data** +-------------+------------------+----------------------------+ | Field | Type | Description | +=============+==================+============================+ | username* | string | It's the username used for | | | | OAS | +-------------+------------------+----------------------------+ | email* | string | It's the email used for | | | | OAS | +-------------+------------------+----------------------------+ | password* | string | Password used for OAS | +-------------+------------------+----------------------------+ \* required fields **Response** +---------------+------------------+----------------------------+ | Field | Type | Description | +===============+==================+============================+ | access | string | Access token that will be | | | | used in OAS API | +---------------+------------------+----------------------------+ | refresh | string | Refresh token that will be | | | | used in OAS API | +---------------+------------------+----------------------------+ | user | dict | User information described | | | | bellow | +---------------+------------------+----------------------------+ | id | int | Unique ID user | +---------------+------------------+----------------------------+ | last_login | date | Last login Date | +---------------+------------------+----------------------------+ | is_superuser | boolean | Indicates if the current | | | | user has admin permissions | +---------------+------------------+----------------------------+ | username | string | Username used for OAS | +---------------+------------------+----------------------------+ | email | string | Email used for OAS | +---------------+------------------+----------------------------+ | is_staff | boolean | Indicates if the current | | | | user is a staff member | | | | of their organization | +---------------+------------------+----------------------------+ | is_active | boolean | Indicates if the current | | | | user is active | +---------------+------------------+----------------------------+ Organizations ------------- The organization entity serves the function of grouping a set of users in order to identify them in the system. In its structure, the organization stores data shared by these users, as well as basic entity information, means of contact and, possibly, financial details. The organization becomes crucially important in the processing of the sales files, making it possible to track to which entity the processing was applied, to send reports to that organization and to maintain clear control, with a designated person responsible for these operations. These are the actions that can be performed on an organization: +---------------------+-----------------------+ | Action | Method | +=====================+=======================+ | Save organization | Create organization | +---------------------+-----------------------+ | Update organization | Update organization | | | **Add contact** | +---------------------+-----------------------+ | Active organization | Change status of | | | organization | +---------------------+-----------------------+ .. _create-organization: Create organization ~~~~~~~~~~~~~~~~~~~ **POST** ``/api/organisations/`` This route is used to register an organization, which is necessary for the processing of sales reports and their correct relationship. **Form Data** +----------------+------------------+---------------------------------+ | Field | Type | Description | +================+==================+=================================+ | name* | string | It's the name used for | | | | organization in OAS | +----------------+------------------+---------------------------------+ | base_currency* | string | It's the base currency used | | | | for the sales reports | +----------------+------------------+---------------------------------+ | currencies* | string | Defines the list of supported | | | | currencies used in reports. | | | | | | | | These values are registered | | | | to enable currency conversion | | | | | | | | according to reporting and | | | | business requirements. | +----------------+------------------+---------------------------------+ | image | string | Organization's Image URL | +----------------+------------------+---------------------------------+ \* required fields **Response** +----------------+------------------+---------------------------------+ | Field | Type | Description | +================+==================+=================================+ | id | integer | It's organization ID | +----------------+------------------+---------------------------------+ | owner | dict | It's the organization's owner | | | | information (who registered | | | | the current organization) | +----------------+------------------+---------------------------------+ | name | string | It's the name used for | | | | organization in OAS | +----------------+------------------+---------------------------------+ | base_currency | string | It's the base currency used | | | | for the sales reports | +----------------+------------------+---------------------------------+ | currencies | string | Defines the list of supported | | | | currencies used in reports. | | | | | | | | These values are registered | | | | to enable currency conversion | | | | | | | | according to reporting and | | | | business requirements. | +----------------+------------------+---------------------------------+ | image | string | Organization's Image URL | +----------------+------------------+---------------------------------+ Get organizations ~~~~~~~~~~~~~~~~~ **GET** ``/api/organisations/`` Get all organizations registered under your user **Response** +----------------+------------------+---------------------------------+ | Field | Type | Description | +================+==================+=================================+ | count | integer | Total number of organizations | +----------------+------------------+---------------------------------+ | next | string | Link to see most results | +----------------+------------------+---------------------------------+ | previous | string | Link to see previous results | +----------------+------------------+---------------------------------+ | results | list | It's a list which contains | | | | organizations info. | | | | | | | | (see :ref:`create-organization` | | | | response) | +----------------+------------------+---------------------------------+ Activate organization ~~~~~~~~~~~~~~~~~~~~~ **POST** ``/api/organisations/{id}/make_active/`` This route is used to register an organization, which is necessary for the processing of sales reports and their correct relationship. **Form Data** +----------------+------------------+---------------------------------+ | Field | Type | Description | +================+==================+=================================+ | id* | integer | It's organization ID to be | | | | activated | +----------------+------------------+---------------------------------+ \* required fields **Response** +----------------+------------------+---------------------------------+ | Field | Type | Description | +================+==================+=================================+ | message | string | Indicates if organization has | | | | been activated or not | +----------------+------------------+---------------------------------+ Account settings ---------------- **POST** ``pending`` This section is intended to modify the account parameters, in this module it is possible to update personal information. This process details the functions related to updating and saving configurations. The user assumes responsibility for defining this information. The configurations will be updated and saved in the OAS B database, and will be applied to the organization or saved in the corresponding user profile.