Quick Start Guide

Requirements

Each request to the API must include a JSON object containing the information related to the action to be performed.

The base URL for all API requests is:

https://oas-beta.ottomate.me/api/docs/

Tools

You can test the API using any of the following tools. .

Postman — Widely used by developers. Features a graphical interface, supports saving collections, environment variables, and tokens.
Insomnia — Similar to Postman but lighter and with a cleaner interface.
Hoppscotch — Works directly in the browser (no installation required). Ideal for quick tests.
cURL — Available by default on most operating systems. Great for testing endpoints directly from the terminal.

Note

Each section in this guide includes ready-to-use request examples you can copy directly in cURL tool

Introduction

To use the OAS API, make sure you meet the following requirements:

Have an active OAS account
Authenticate your OAS account
Have a valid access token
Have an organization created via the OAS API

API Key

The API key is a credential that allows users to make requests to protected OAS API routes. This key is delivered to the user via a welcome email once their account is approved.

The API key is unique, non-transferable, and tied exclusively to the email address associated with the account. It follows an alphanumeric format of 41 characters combining letters and numbers. Below is an example of an OAS API key:

A2QnAjPg.2tBY21luBv1V1X1krrXQtmadPpwcuUjH

Warning

Store this key securely and never share it with anyone. It grants full access to your account’s API resources.

To obtain an API access token, follow these steps:

Fill out the registration form
Once approved, a Welcome Email will be sent to you
An OAS administrator will create an API client and assign you as the owner

        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: Send Welcome Email
  OAS Admin -->> OAS Admin: Create API client with user as owner

Access Token

The access token is a short-lived credential generated after a successful login. It must be included in the Authorization header of every protected request.

Below is an example of a valid access token (228 alphanumeric characters):

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzc1Nzk3NTc3LCJpYXQiOjE3NzU3OTAzNzcsImp0aSI6ImY3OGNmNWYyYzZlZjQ4YmRiODY4OTYyYzM1NmUyZmZkIiwidXNlcl9pZCI6MX0.lnqbS6ibHvRkmwxnVzeANpsPA0ddswf2MNL83nhVu_o

The organization linked to a token is always tied to the user who created it. That user can also manage and grant access permissions to others.

Access token authorization

Once you have your access token, include it in every request using the Authorization header:

Authorization: Bearer <token>

API key authorization

The API key must be sent in the X-Api-Key header of every request. You can find this key in the welcome email you received when your account was created.

X-Api-Key: <your_api_key>

TEST API

This section is designed to help you get familiar with the OAS API before making more complex requests. We have created a simple “Hello World” route as your first point of contact — it requires authentication and returns a plain text response so you can confirm everything is working correctly.

Paged responses

In some cases, the amount of data returned by certain routes can be quite large, often consisting of thousands of records, which can make it difficult to handle efficiently. To address this, the data is divided into smaller, more manageable pages. This approach improves both performance and overall user experience.

To navigate through these pages, routes accept GET parameters such as <page> (for example, ?page=2). When pagination is implemented, the response typically returns a structured JSON object that includes both the data and relevant navigation metadata, rather than a simple list of objects.

{
    "count": 100,
    "next": "http://example.com",
    "previous": "http://example.com",
    "results": [
        {"id": 1, "title": "Post 1", ...},
        ...
    ]
}

Steps to consume it:

Make the initial request: Request the base URL api/items/.
Read the response: Access the data for the current page in data[‘results’].
Manage navigation:
- Use the value of data[‘next’] for the “Next” button.
- Use the value of data[‘previous’] for the “Previous” button.
- If data[‘next’] is null, disable the “Next” button.

GET /helloworld

Test route that verifies API token authentication is working correctly. Returns a personalized greeting message with the name of the token owner.

Note

This route is useful for confirming that your token is active and that you have connectivity with the API before making more complex calls.

Example

curl -X GET https://oas-beta.ottomate.me/helloworld \
     -H "X-Api-Key: <your_api_key>"

Required headers

Header	Type	Description
`X-Api-Key`	string (required)	Your API key received via email

Responses

200 OK — Successful request

Hello world @username

401 Unauthorized — Missing or invalid token

{"detail": "Authentication credentials were not provided or are invalid."}

Sign In

POST /api/auth/login/

Authenticates an existing user and returns the access and refresh tokens required to interact with the rest of the API.

Note

You will need the access token returned by this route to authorize all subsequent requests.

Example

curl -X POST https://oas-beta.ottomate.me/api/auth/login/ \
     -H "Content-Type: application/json" \
     -d '{
           "username": "your_username",
           "email": "your@email.com",
           "password": "your_password"
         }'

Request body

Field	Type	Description
`username`	string (required)	Username registered in OAS
`email`	string (required)	Email address registered in OAS
`password`	string (required)	Password associated with the OAS account

Response

200 OK — Successful login

Field	Type	Description
`access`	string	Access token used to authorize API requests. Send this in the `Authorization` header.
`refresh`	string	Refresh token used to obtain a new access token when the current one expires.
`user`	object	Object containing the authenticated user’s information (see fields below).
`user.id`	integer	Unique user ID
`user.last_login`	date	Timestamp of the user’s last login
`user.is_superuser`	boolean	`true` if the user has administrator permissions
`user.username`	string	Username registered in OAS
`user.email`	string	Email address registered in OAS
`user.is_staff`	boolean	`true` if the user is a staff member of their organization
`user.is_active`	boolean	`true` if the user account is currently active

401 Unauthorized — Invalid credentials

{"detail": "Unable to log in with the provided credentials."}

Organizations

An organization groups a set of users within the system and stores shared data such as contact information, basic entity details, and financial settings. Organizations are essential for processing sales files, as they determine which entity a report belongs to, where results are sent, and who is responsible for those operations.

The following actions are available for organizations:

Action	Route
Create an organization	`POST /api/organisations/`
List all organizations	`GET /api/organisations/`
Activate an organization	`POST /api/organisations/{id}/make_active/`

Create organization

POST /api/organisations/

Registers a new organization in the system. An organization is required before you can process any sales reports.

Example

curl -X POST https://oas-beta.ottomate.me/api/organisations/ \
     -H "X-Api-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Acme Corp",
           "base_currency": "USD",
           "currencies": ["USD", "EUR", "MXN"]
         }'

Request body

Field	Type	Description
`name`	string (required)	Display name of the organization in OAS
`base_currency`	string (required)	Primary currency used for sales reports (e.g. `USD`)
`currencies`	array (required)	List of supported currencies for this organization. These values enable currency conversion according to reporting and business requirements.
`image`	string	URL of the organization’s logo or profile image

Response

201 Created — Organization successfully created

Field	Type	Description
`id`	integer	Unique ID of the newly created organization
`owner`	object	Information about the user who created this organization
`name`	string	Organization name
`base_currency`	string	Primary currency used for sales reports
`currencies`	array	List of supported currencies
`image`	string	Organization image URL

401 Unauthorized — Missing or invalid token

{"detail": "Authentication credentials were not provided or are invalid."}

Get organizations

GET /api/organisations/

Returns a paginated list of all organizations registered under your user account.

Example

curl -X GET https://oas-beta.ottomate.me/api/organisations/ \
     -H "X-Api-Key: <your_api_key>"

Response

200 OK — Successful request

Field	Type	Description
`count`	integer	Total number of organizations found
`next`	string	URL to retrieve the next page of results (`null` if none)
`previous`	string	URL to retrieve the previous page of results (`null` if none)
`results`	array	List of organization objects. See Create organization for the structure of each item.

401 Unauthorized — Missing or invalid token

{"detail": "Authentication credentials were not provided or are invalid."}

Activate organization

POST /api/organisations/{id}/make_active/

Sets the specified organization as the active one for the current user session. Only the active organization will be used when processing sales reports.

Example

curl -X POST https://oas-beta.ottomate.me/api/organisations/42/make_active/ \
     -H "X-Api-Key: <your_api_key>"

URL parameters

Parameter	Type	Description
`id`	integer (required)	ID of the organization to activate

Response

200 OK — Organization successfully activated

Field	Type	Description
`message`	string	Confirmation message indicating whether the organization was successfully activated

404 Not Found — Organization not found

{"detail": "Organization not found."}

401 Unauthorized — Missing or invalid token

{"detail": "Authentication credentials were not provided or are invalid."}

Account Settings

POST pending

This section covers the configuration of account parameters, including the ability to update personal information and preferences.

All changes are saved to the OAS database and applied to the corresponding user profile or organization. The user is responsible for keeping this information accurate and up to date.

Quick Start Guide

Requirements

Tools

Introduction

API Key

Access Token

Access token authorization

API key authorization

TEST API

Paged responses

GET /helloworld

Example

Required headers

Responses

Sign Up

Sign In

Example

Request body

Response

Organizations

Create organization

Example

Request body

Response

Get organizations

Example

Response

Activate organization

Example

URL parameters

Response

Account Settings