RestApiGotta API Documentation

Complete API reference and integration guide for connecting with RestApiGotta service

Base URL: http://gotta-test.ambiasuite.com/api

1. Authentication
2. Countries
3. Carriers
4. Orders
5. Orders Synchronize
6. Orders Cancel
7. Products

1. Authentication

Authentication

Description

Requests the authentication token used by the other endpoints. Send the code and password given to you by Gotta and receive a JWT token with its expiration time.

Important: Once the token is received, you need to use it as an Authorization Header: "Authorization": "Bearer [token]"

Endpoint and Request Method

Endpoint	Method	Authentication
`/api/auth/login`	POST	Not Required

Parameters

Field	Required	Type	Location	Description
`code`	Yes	String	Body (POST)	API key code provided by Gotta
`password`	Yes	String	Body (POST)	API key password provided by Gotta

Response Data Structure

Field	Type	Description
`message`	String	Response message (e.g., "Successful Operation")
`result.token`	String	JWT authentication token
`result.expires_in`	Integer	Token expiration time in seconds (default: 3600)
`result.role`	String	User role (ALL, ORDERS, or PRODUCTS)
`result.canal`	String	Channel identifier (channel-specific code)

Examples for Request

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "your_api_key_code",
    "password": "your_api_key_password"
  }'

Expected Output (200 OK)

                                                            {
  "message": "Successful Operation",
  "result": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "role": "ALL",
    "canal": "CHANNEL_CODE"
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The provided code or password is incorrect.

                                                            {
  "detail": "Invalid credentials"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "wrong_code",
    "password": "wrong_password"
  }'

Error Response: HTTP 401 - Invalid credentials

Description: Required fields are missing or incorrectly formatted.

                                                            {
  "detail": [
    {
      "loc": ["body", "code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "your_api_key_code"
  }'

Error Response: HTTP 400 - Missing required field "password"

Description: An unexpected error occurred on the server.

                                                            {
  "detail": "Authentication error: [error message]"
}

2. Countries

Countries

Description

Gets all the countries listed in our system. This is useful when synchronizing orders to send the customer country code. Each country includes a name and a two-digit ISO code.

Endpoint and Request Method

Endpoint	Method	Authentication	Required Role
`/api/countries/get_all`	GET	Required	ALL or ORDERS

Parameters

Note: This endpoint uses GET method and requires authentication via HTTP-API-KEY header. No query parameters or request body is required.

Parameter	Required	Type	Location	Description
`HTTP-API-KEY`	Yes	String	Header (GET)	API key for authentication

Response Data Structure

Field	Type	Description
`message`	String	Response message (e.g., "Successful Operation")
`result.data`	Array	Array of country objects
`result.data[].iso_code`	String	Two-letter ISO country code (e.g., "ES", "US", "FR")
`result.data[].name`	String	Country name (e.g., "Spain", "United States", "France")

Examples for Request

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/countries/get_all" \
  -H "HTTP-API-KEY: your_api_key_here"

Expected Output (200 OK)

                                                            {
  "message": "Successful Operation",
  "result": {
    "data": [
      {
        "iso_code": "AD",
        "name": "Andorra"
      },
      {
        "iso_code": "AE",
        "name": "United Arab Emirates"
      },
      {
        "iso_code": "ES",
        "name": "Spain"
      },
      {
        "iso_code": "US",
        "name": "United States"
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Missing HTTP-API-KEY header"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/countries/get_all"

Error Response: HTTP 401 - Missing HTTP-API-KEY header

Description: The API key does not have the required role (ALL or ORDERS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL, ORDERS"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/countries/get_all" \
  -H "HTTP-API-KEY: api_key_with_only_products_role"

Error Response: HTTP 403 - API key has role "PRODUCTS" but endpoint requires "ALL" or "ORDERS"

Description: An unexpected error occurred on the server.

                                                            {
  "message": "Unexpected Error",
  "result": {}
}

3. Carriers

Carriers

Description

Gets all the delivery carriers available in the system for RestApiGotta integration. This endpoint returns carriers that are enabled for RESAPI, published, and active. Each carrier includes information about its pricing method (fixed price or based on rules) and availability.

Filtering: Only carriers with gt_resapi = True, website_published = True, and active = True are returned.

Endpoint and Request Method

Endpoint	Method	Authentication	Required Role
`/api/carriers/get_all`	GET	Required	ALL, ORDERS, or PRODUCTS

Parameters

Note: This endpoint uses GET method and requires authentication via HTTP-API-KEY header. No query parameters or request body is required.

RestApiGotta filter: Only carriers with gt_resapi = true, active = true and published are returned. Use result.data[].carrier_id in POST /api/orders/synchronize (orders[].carrier_id) or configure a default on the API key (gt_carrier_id).

Parameter	Required	Type	Location	Description
`HTTP-API-KEY`	Yes	String	Header (GET)	API key for authentication

Response Data Structure

Field	Type	Description
`message`	String	Response message (e.g., "Successful Operation")
`result.data`	Array	Array of carrier objects
`result.data[].carrier_id`	Integer	Carrier ID (unique identifier)
`result.data[].name`	String	Carrier name (e.g., "GLS", "DHL", "UPS")
`result.data[].delivery_type`	String	Delivery type: `"fixed"` for fixed price, `"based_on_rule"` for price rules
`result.data[].fixed_price`	Float	Fixed price (only present when `delivery_type="fixed"`). `null` for rule-based carriers.
`result.data[].has_rules`	Boolean	Whether carrier uses price rules (`true` when `delivery_type="based_on_rule"` and rules exist)
`result.data[].active`	Boolean	Whether carrier is active
`result.data[].published`	Boolean	Whether carrier is published (available on website)

Examples for Request

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/carriers/get_all" \
  -H "HTTP-API-KEY: your_api_key_here"

Expected Output (200 OK)

                                                            {
  "message": "Successful Operation",
  "result": {
    "data": [
      {
        "carrier_id": 1,
        "name": "GLS",
        "delivery_type": "fixed",
        "fixed_price": 0.0,
        "has_rules": false,
        "active": true,
        "published": true
      },
      {
        "carrier_id": 2,
        "name": "DHL Express",
        "delivery_type": "based_on_rule",
        "fixed_price": null,
        "has_rules": true,
        "active": true,
        "published": true
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Missing HTTP-API-KEY header"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/carriers/get_all"

Error Response: HTTP 401 - Missing HTTP-API-KEY header

Description: The API key does not have the required role (ALL, ORDERS, or PRODUCTS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL, ORDERS, PRODUCTS"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/carriers/get_all" \
  -H "HTTP-API-KEY: invalid_api_key"

Error Response: HTTP 403 - Insufficient permissions

Description: An unexpected error occurred on the server.

                                                            {
  "message": "Unexpected Error",
  "result": {}
}

3. Orders

Orders

Description

Query and retrieve orders from the system with advanced filtering capabilities. This endpoint allows you to filter orders by state (PENDING, SHIPPING, FINISHED, CANCELLED, or ALL), supports pagination, and ensures data security by returning only orders belonging to the authenticated user.

Security: Each API user can only access their own orders. Orders are automatically filtered by the authenticated user's credentials (user_auth_id, SERIE, and CODCLIENTE).

Endpoint and Request Method

Endpoint	Method	Authentication	Required Role
`/api/orders/query`	POST	Required	ALL or ORDERS

Parameters

Note: This endpoint uses POST method with query parameters for pagination and a JSON body for state filtering.

Query Parameters:

Parameter	Required	Type	Location	Description
`skip`	No	Integer	Query	Number of items to skip (pagination offset). Default: 0, Minimum: 0
`limit`	No	Integer	Query	Maximum items to return. Default: 100, Range: 1-1000

Request Body Parameters:

Field	Required	Type	Location	Description
`state`	No	String	Body (POST)	Order state filter. Valid values: `ALL` (default), `PENDING`, `SHIPPING`, `FINISHED`, `CANCELLED`, or comma-separated multiple states (e.g., `PENDING,SHIPPING`)

State Values Explanation:

ALL: Returns all orders regardless of state (default)
PENDING: Orders in draft or sent state, or sale orders without pickings
SHIPPING: Orders confirmed with pickings in progress
FINISHED: Orders with all deliveries completed
CANCELLED: Cancelled orders
Multiple states: Comma-separated values (e.g., "PENDING,SHIPPING")

Response Data Structure

Field	Type	Description
`message`	String	Response message (e.g., "Successful Operation")
`result.count`	Integer	Total number of orders matching the filter (before pagination)
`result.data`	Array	Array of order objects (paginated results)
`result.data[].order_state`	String	Order state: PENDING, SHIPPING, FINISHED, or CANCELLED
`result.data[].order_id`	String	Order identifier (NCOMANDA)
`result.data[].customer`	Object	Customer information object
`result.data[].customer.name`	String	Customer full name
`result.data[].customer.address`	String	Customer street address
`result.data[].customer.postal_code`	String	Postal/ZIP code
`result.data[].customer.city`	String	City name
`result.data[].customer.country`	String	Two-letter ISO country code
`result.data[].customer.phone`	String	Phone number
`result.data[].customer.email`	String	Email address
`result.data[].customer.payment_method`	String	Payment method name
`result.data[].customer.vcustomer`	String	VCustomer identifier
`result.data[].customer.vat_number`	String	VAT/Tax identification number (e.g., NIF, CIF, VAT number)
`result.data[].order_items`	Array	Array of order item objects
`result.data[].order_items[].sku`	String	Product SKU (codarticulo + talla + color)
`result.data[].order_items[].units`	Integer	Quantity of items
`result.data[].order_items[].price`	Float	Unit price
`result.data[].order_items[].description`	String	Product description
`result.data[].order_items[].order_item_id`	String	Order item identifier. Can be a custom identifier provided during synchronization (e.g., marketplace order item ID) or an auto-generated identifier if not provided during order creation.
`result.data[].shipping_cost`	Float	Shipping cost amount
`result.data[].date`	String	Order date formatted as dd/MM/yyyy HH:mm:ss
`result.data[].shipping_label`	String	Shipping label download URL (optional). If a shipping label is available for the order, this field contains the URL to download it. The URL format is: `/api/orders/{order_id}/shipping-label` where `{order_id}` is the order's NCOMANDA identifier. Label Types: Binary (PDF): Returns a PDF file download when accessed via GET request URL: Returns a redirect (302) to the external label URL Note: This field is `null` if no shipping label is available for the order.

Downloading Shipping Labels

How to Download: When an order has a shipping label available, the shipping_label field in the query response contains a URL. You can download the label by making a GET request to that URL with your API key.

Label source (native Odoo carriers): Labels are generated when an outgoing delivery (stock.picking) is validated with an integrated carrier (integration_level = rate_and_ship, e.g. SEUR Atlas, Correos, CTT). The PDF is stored as ir.attachment on the picking (SEUR: direct attachment; Correos/CTT: often via picking chatter). Flow: POST /api/orders/synchronize → confirm sale order in Odoo → validate delivery → POST /api/orders/query returns shipping_label → GET /api/orders/{order_id}/shipping-label. Carriers with fixed pricing only (GLS, Standard delivery) do not generate carrier labels. Legacy ICG labels (gt.shipping.label) are used only if no picking attachment exists.

gt_resapi vs carrier credentials: gt_resapi on delivery.carrier only controls whether the carrier can be selected via RestApiGotta (GET /carriers/get_all, orders[].carrier_id). It does not validate Correos JWT, SEUR Atlas, etc. Invalid or expired credentials fail when the delivery is validated in Odoo (e.g. Correos 401 on preregister/labels), not at order synchronize.

Carrier	Generates label	Storage	Notes
SEUR Atlas	Yes	`ir.attachment` on picking	Requires product weight, packages, valid Atlas credentials
Correos Spain	Yes (when API credentials valid)	Picking and/or chatter attachment	401 if Correos REST auth fails at validate
CTT Express	Yes	`ir.attachment` on picking	Validated E2E locally
GLS / Standard delivery	No	—	`delivery_type=fixed`; picking validates without carrier PDF

Step	Description
1. Query Orders	Use the `POST /api/orders/query` endpoint to get order details. Check the `shipping_label` field in the response.
2. Check Availability	If `shipping_label` is not `null`, a shipping label is available for download.
3. Download Label	Make a `GET` request to the URL provided in `shipping_label` field, including your `HTTP-API-KEY` header. The endpoint handles both binary PDF downloads and URL redirects automatically.

Example: Download Shipping Label

                                                # Step 1: Query orders to get shipping_label URL
curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query" \
  -H "Content-Type: application/json" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -d '{"state": "ALL"}'

# Response includes shipping_label field:
# {
#   "result": {
#     "data": [{
#       "order_id": "6946159846619354995",
#       "shipping_label": "http://91.99.87.99:1005/api/orders/6946159846619354995/shipping-label",
#       ...
#     }]
#   }
# }

# Step 2: Download the label using the URL from shipping_label field
# Create destination folder first (curl does not create directories)
mkdir -p ./labels

curl -X GET "http://gotta-test.ambiasuite.com/api/orders/TEST-SEUR-001/shipping-label" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -o ./labels/seur_TEST-SEUR-001.pdf

# Optional: when multiple package labels exist, pass attachment_id
curl -X GET "http://gotta-test.ambiasuite.com/api/orders/TEST-SEUR-001/shipping-label?attachment_id=24893" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -o ./labels/seur_TEST-SEUR-001_pkg2.pdf

Security: The shipping label download endpoint validates that:

The order belongs to the authenticated API user
The order exists and has a shipping label
Only orders accessible by your API key can have their labels downloaded

Examples for Request

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query?skip=0&limit=10" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "ALL"}'

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query?skip=0&limit=20" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "PENDING"}'

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query?skip=10&limit=50" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "PENDING,SHIPPING"}'

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query?skip=20&limit=10" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "FINISHED"}'

Expected Output (200 OK)

                                                            {
  "message": "Successful Operation",
  "result": {
    "count": 1,
    "data": [
      {
        "order_state": "PENDING",
        "order_id": "404-4077035-3192344",
        "customer": {
          "name": "Francisco Ortega Soto",
          "address": "C/ Fondos de segura Edf 17B port. 8 2ªc DNI / NIF",
          "postal_code": "35019",
          "city": "Las Palmas de Gran Canaria",
          "country": "ES",
          "phone": "617754320",
          "email": "[email protected]",
          "payment_method": "amazonES"
        },
        "order_items": [
          {
            "sku": "ABC123MROJO",
            "units": 2,
            "price": 29.99,
            "description": "Product Name - Size M - Color Red",
            "order_item_id": "12345"
          }
        ],
        "shipping_cost": 18.39,
        "date": "07/12/2025 21:13:15",
        "shipping_label": "http://91.99.87.99:1005/api/orders/404-4077035-3192344/shipping-label"
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Not authenticated"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query" \
  -H "Content-Type: application/json" \
  -d '{"state": "ALL"}'

Error Response: HTTP 401 - Missing HTTP-API-KEY header

Description: The API key does not have the required role (ALL or ORDERS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL, ORDERS"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query" \
  -H "HTTP-API-KEY: api_key_with_only_products_role" \
  -H "Content-Type: application/json" \
  -d '{"state": "ALL"}'

Error Response: HTTP 403 - API key has role "PRODUCTS" but endpoint requires "ALL" or "ORDERS"

Description: The state parameter contains invalid values.

                                                            {
  "detail": "Invalid states: ['INVALID_STATE']. Valid states are: PENDING, SHIPPING, FINISHED, CANCELLED, ALL"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "INVALID_STATE"}'

Error Response: HTTP 400 - Invalid state value provided

Description: Pagination parameters are invalid (limit too high, negative skip, etc.).

                                                            {
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 1000",
      "input": "2000",
      "ctx": {"le": 1000}
    }
  ]
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/query?skip=0&limit=2000" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "ALL"}'

Error Response: HTTP 422 - Limit exceeds maximum allowed value (1000)

Description: An unexpected error occurred on the server.

                                                            {
  "detail": "Error querying orders: [error message]"
}

4. Orders Synchronize

Orders Synchronization

Description

Synchronize orders into the Odoo system. This endpoint allows external systems and marketplaces (e.g., Amazon, eBay, other e-commerce platforms) to post orders for creation or modification in the system. Supports both automatic order ID generation and external order identifiers from marketplace systems.

Key Features: External order identifier support (marketplace IDs), automatic order ID generation (system-managed), customer auto-creation, product validation, duplicate prevention, order updates, batch processing, and error isolation.

External Order Identifiers: This endpoint supports external order identifiers from marketplace systems (e.g., Amazon order IDs, eBay order numbers). If you provide an order_id in your request, it will be used as the unique order identifier (gt_ncomanda). If the order already exists with the same identifier and belongs to your API user, it will be updated. If not provided, the system will auto-generate a unique order ID using IR sequences.

Endpoint and Request Method

Endpoint	Method	Authentication	Required Role
`/api/orders/synchronize`	POST	Required	ALL or ORDERS

Parameters

Request Body Structure:

Field	Required	Type	Location	Description
`orders`	Yes	Array	Body (POST)	Array of order objects to synchronize (minimum 1 order)
`orders[].order_id`	No	String	Body	External order identifier (e.g., Amazon order ID, marketplace order number). If provided, must be unique per API user. If not provided, system auto-generates order ID. If order with same `order_id` exists and belongs to your API user, order will be updated.
`orders[].carrier_id`	No	Integer	Body	Delivery carrier ID. Obtain valid IDs from `GET /api/carriers/get_all`. If omitted, uses the default carrier configured on the API key (`gt_carrier_id`).
`orders[].customer`	Yes	Object	Body	Customer information object
`orders[].customer.email`	Yes	String	Body	Email address (required, used for customer lookup)
`orders[].customer.name`	Conditional	String	Body	Customer full name (required only if customer doesn't exist)
`orders[].customer.address`	Conditional	String	Body	Street address (required only if customer doesn't exist)
`orders[].customer.postal_code`	Conditional	String	Body	Postal/ZIP code (required only if customer doesn't exist)
`orders[].customer.city`	Conditional	String	Body	City name (required only if customer doesn't exist)
`orders[].customer.country`	Conditional	String	Body	Two-letter ISO country code (required only if customer doesn't exist, e.g., `ES`, `FR`, `IT`)
`orders[].customer.phone`	No	String	Body	Phone number (optional, updates existing customer if provided)
`orders[].customer.payment_method`	No	String	Body	Payment method name
`orders[].customer.vcustomer`	No	String	Body	VCustomer identifier (optional, can also be provided at order level)
`orders[].customer.vat_number`	No	String	Body	VAT/Tax identification number (e.g., NIF, CIF, VAT number). Automatically set by human when product is configured, but can be provided for customer.
`orders[].order_items`	Yes	Array	Body	Array of order items (minimum 1 item, cannot have duplicate SKUs)
`orders[].order_items[].sku`	Yes	String	Body	Product SKU (must exist in catalog, format: `codarticulo + talla + color`, e.g., `5757MROJO`)
`orders[].order_items[].units`	Yes	Integer	Body	Quantity (must be > 0)
`orders[].order_items[].price`	Yes	Float	Body	Unit price WITHOUT tax (must be >= 0). The system will automatically include tax based on product tax configuration.
`orders[].order_items[].description`	Yes	String	Body	Product description
`orders[].order_items[].order_item_id`	No	String	Body	Custom order item identifier (e.g., Amazon order item ID, marketplace line identifier). If provided, will be stored as-is and returned in query responses. If not provided, system auto-generates an identifier. Useful for tracking order lines from external marketplace systems.
`orders[].shipping_cost`	Yes	Float	Body	Shipping cost amount (must be >= 0)
`orders[].date`	Yes	String	Body	Order date in format `dd/MM/yyyy HH:mm:ss` (e.g., `13/12/2025 14:30:00`)
`orders[].vcustomer`	No	String	Body	VCustomer identifier for the order (optional, takes precedence over customer.vcustomer if both provided)

Important Notes:

SKU Format: Must be codarticulo + talla + color (e.g., 5757MROJO)
Date Format: Must be exactly dd/MM/yyyy HH:mm:ss (e.g., 13/12/2025 14:30:00)
Unit Price: Unit price in the request must be sent WITHOUT tax. The system will automatically include tax based on product tax configuration when processing the order.
Duplicate SKUs: Cannot have the same SKU twice in order_items array (combine units instead)
Customer Lookup: Customer is looked up by email. If customer exists, it will be updated with provided data. If customer doesn't exist, all fields (name, address, postal_code, city, country) are required to create a new customer.
Email Requirement: Email is always required and used for customer lookup. You can upload orders with just email value if customer already exists in the system.
Order ID Generation:
- If order_id provided: Uses your external identifier (e.g., Amazon order ID) as the unique order identifier. Must be unique per API user. If order with same order_id exists and belongs to your API user, it will be updated.
- If order_id not provided: System auto-generates order ID using format {serie}-{sequence} (e.g., VWE-VWE00001).
Order Item ID:
- If order_item_id provided: Your custom identifier (e.g., marketplace order item ID) will be stored as-is and returned in query responses. Useful for tracking and matching order lines with external systems.
- If order_item_id not provided: System auto-generates an identifier. The identifier will be returned in query responses for reference.
- Format: Any string value is accepted. Common formats include marketplace identifiers (e.g., AMAZON-ITEM-001), numeric IDs, or UUIDs.
Order Updates: If you provide an order_id that already exists and belongs to your API user, the order will be updated:
- Order Header: Customer information and order date will be updated with new values
- Order Lines: ALL existing order lines will be completely deleted and replaced with the new order lines from the request. This ensures the order matches exactly what you send.
- Order Item IDs: New order_item_id values will be applied to the recreated lines. Previous line identifiers are not preserved.
This behavior allows marketplace systems to sync order changes and corrections.
Security: Orders can only be updated by the same API user that created them. If an order with the same order_id exists but belongs to a different API user, the request will fail with an error.

Response Data Structure

Field	Type	Description
`message`	String	Status message (always "Orders synchronization completed")
`result.data`	Array	Array of order synchronization results
`result.data[].order_id`	String	Order identifier automatically generated by the system (e.g., `VWE-VWE00001`), or "(generation failed)" if error
`result.data[].error`	Boolean	`false` if order synchronized successfully, `true` if failed
`result.data[].message`	String	Error message if `error: true`, otherwise `null`

Examples for Request

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "John Doe",
        "address": "123 Main Street",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "phone": "+34600123456",
        "email": "[email protected]",
        "payment_method": "amazonES",
        "vcustomer": "VC12345",
        "vat_number": "B12345678"
      },
      "vcustomer": "VC12345",
      "order_items": [
        {
          "sku": "14309..",
          "units": 2,
          "price": 29.99,
          "description": "Product Description"
        }
      ],
      "shipping_cost": 5.50,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Note: No order_id provided - system will auto-generate order ID (e.g., VWE-VWE00001).

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "order_id": "404-4077035-3192344",
      "customer": {
        "name": "John Doe",
        "address": "123 Main Street",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "phone": "+34600123456",
        "email": "[email protected]",
        "payment_method": "amazonES",
        "vcustomer": "VC12345",
        "vat_number": "B12345678"
      },
      "vcustomer": "VC12345",
      "order_items": [
        {
          "sku": "14309..",
          "units": 2,
          "price": 29.99,
          "description": "Product Description"
        }
      ],
      "shipping_cost": 5.50,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Note: order_id provided (e.g., Amazon order ID 404-4077035-3192344). If order with this ID already exists and belongs to your API user, it will be updated. Otherwise, a new order will be created.

Tip: You can also provide order_item_id for each order line to track marketplace line identifiers (e.g., "AMAZON-ITEM-001").

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "order_id": "AMAZON-12345-67890",
      "customer": {
        "name": "John Doe",
        "address": "123 Main Street",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "phone": "+34600123456",
        "email": "[email protected]",
        "payment_method": "amazonES"
      },
      "order_items": [
        {
          "sku": "14309..",
          "units": 2,
          "price": 29.99,
          "description": "Product Description",
          "order_item_id": "AMAZON-ITEM-001"
        },
        {
          "sku": "14309..",
          "units": 1,
          "price": 19.99,
          "description": "Second Product",
          "order_item_id": "AMAZON-ITEM-002"
        }
      ],
      "shipping_cost": 5.50,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Note: This example shows how to use custom order_item_id values (e.g., AMAZON-ITEM-001, AMAZON-ITEM-002) to track order lines from marketplace systems. These identifiers will be stored and returned in query responses, allowing you to match API responses with your marketplace system.

Assign a delivery carrier per order using carrier_id. List valid IDs with GET /api/carriers/get_all. If omitted, the API key default carrier (gt_carrier_id) is used.

                                                            # Step 1: List carriers
curl -X GET "http://gotta-test.ambiasuite.com/api/carriers/get_all" \
  -H "HTTP-API-KEY: your_api_key_here"

# Step 2: Create order with carrier_id (e.g. 8 = SEUR Atlas)
curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [{
    "order_id": "TEST-SEUR-002",
    "carrier_id": 8,
    "date": "22/05/2026 14:00:00",
    "shipping_cost": 5.50,
    "customer": {
      "email": "[email protected]",
      "name": "Test Customer",
      "address": "Carrer Example 1",
      "postal_code": "08001",
      "city": "Barcelona",
      "country": "ES"
    },
    "order_items": [{
      "sku": "44816..",
      "units": 1,
      "price": 10.0,
      "description": "Test product"
    }]
  }]
}'

Priority: explicit carrier_id in the request → default on API key. Carrier must be active and have gt_resapi = true.

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "Customer One",
        "address": "456 First Ave",
        "postal_code": "28001",
        "city": "Madrid",
        "country": "ES",
        "email": "[email protected]",
        "payment_method": "amazonES",
        "vcustomer": "VC67890",
        "vat_number": "A87654321"
      },
      "vcustomer": "VC67890",
      "order_items": [
        {
          "sku": "14309..",
          "units": 1,
          "price": 19.99,
          "description": "Product One"
        }
      ],
      "shipping_cost": 3.50,
      "date": "13/12/2025 14:31:00"
    },
    {
      "customer": {
        "name": "Customer Two",
        "address": "789 Second St",
        "postal_code": "41001",
        "city": "Seville",
        "country": "ES",
        "email": "[email protected]",
        "payment_method": "amazonES",
        "vcustomer": "VC11111",
        "vat_number": "B98765432"
      },
      "vcustomer": "VC11111",
      "order_items": [
        {
          "sku": "14309..",
          "units": 3,
          "price": 39.99,
          "description": "Product Two"
        }
      ],
      "shipping_cost": 7.00,
      "date": "13/12/2025 14:31:00"
    }
  ]
}'

Expected Output (200 OK)

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "VWE-VWE00001",
        "error": false,
        "message": null
      }
    ]
  }
}

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "VWE-VWE00002",
        "error": false,
        "message": null
      },
      {
        "order_id": "VWE-VWE00003",
        "error": false,
        "message": null
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

401 - Unauthorized (Missing or Invalid API Key)

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Not authenticated"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "Content-Type: application/json" \
  -d '{"orders": [...]}'

Error Response: HTTP 401 - Missing HTTP-API-KEY header

403 - Forbidden (Insufficient Permissions)

Description: The API key does not have the required role (ALL or ORDERS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL, ORDERS"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: api_key_with_only_products_role" \
  -H "Content-Type: application/json" \
  -d '{"orders": [...]}'

Error Response: HTTP 403 - API key has role "PRODUCTS" but endpoint requires "ALL" or "ORDERS"

Order Error: Invalid SKU

Description: Product SKU doesn't exist in catalog.

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "(generation failed)",
        "error": true,
        "message": "Product with SKU 'INVALID-SKU' not found in catalog"
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "Test",
        "address": "123",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "email": "[email protected]"
      },
      "order_items": [
        {
          "sku": "INVALID-SKU",
          "units": 1,
          "price": 10.00,
          "description": "Test"
        }
      ],
      "shipping_cost": 1.00,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Error Response: Order returns error: true with message about invalid SKU

Order Error: Missing Customer Email

Description: Customer email is required and cannot be empty.

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "(generation failed)",
        "error": true,
        "message": "Customer email is required"
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "Test",
        "address": "123",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "email": ""
      },
      "order_items": [
        {
          "sku": "14309..",
          "units": 1,
          "price": 10.00,
          "description": "Test"
        }
      ],
      "shipping_cost": 1.00,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Error Response: Order returns error: true with message "Customer email is required"

Order Error: Invalid Date Format

Description: Date format must be dd/MM/yyyy HH:mm:ss, not ISO format.

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "(generation failed)",
        "error": true,
        "message": "Invalid date format: 2025-12-13 12:00:00. Expected format: dd/MM/yyyy HH:mm:ss"
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "Test",
        "address": "123",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "email": "[email protected]"
      },
      "order_items": [
        {
          "sku": "14309..",
          "units": 1,
          "price": 10.00,
          "description": "Test"
        }
      ],
      "shipping_cost": 1.00,
      "date": "2025-12-13 12:00:00"
    }
  ]
}'

Error Response: Order returns error: true with message about invalid date format

Order Error: External Order ID Already Exists (Different API User)

Description: The provided order_id already exists but belongs to a different API user. External order identifiers must be unique per API user for security reasons.

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "404-4077035-3192344",
        "error": true,
        "message": "Order with identifier '404-4077035-3192344' already exists and belongs to a different API user. External order identifiers must be unique per API user."
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "order_id": "404-4077035-3192344",
      "customer": {
        "name": "Test",
        "address": "123",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "email": "[email protected]"
      },
      "order_items": [
        {
          "sku": "14309..",
          "units": 1,
          "price": 10.00,
          "description": "Test"
        }
      ],
      "shipping_cost": 1.00,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Error Response: Order returns error: true with message about order ID belonging to different API user

Order Error: Duplicate SKU in Same Order

Description: Cannot have the same SKU twice in order_items array.

                                                            {
  "message": "Orders synchronization completed",
  "result": {
    "data": [
      {
        "order_id": "(generation failed)",
        "error": true,
        "message": "Duplicate SKU '14309..' found in order_items. Combine units instead."
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/synchronize" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "customer": {
        "name": "Test",
        "address": "123",
        "postal_code": "08001",
        "city": "Barcelona",
        "country": "ES",
        "email": "[email protected]"
      },
      "order_items": [
        {
          "sku": "14309..",
          "units": 1,
          "price": 10.00,
          "description": "First"
        },
        {
          "sku": "14309..",
          "units": 2,
          "price": 10.00,
          "description": "Duplicate"
        }
      ],
      "shipping_cost": 1.00,
      "date": "13/12/2025 14:30:00"
    }
  ]
}'

Error Response: Order returns error: true with message about duplicate SKU

422 - Unprocessable Entity (Invalid Request Body)

Description: Request body structure is invalid (missing required fields, wrong types, etc.).

                                                            {
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "orders", 0, "customer", "email"],
      "msg": "Field required"
    }
  ]
}

5. Orders Cancel

Orders Cancel

Cancel pending orders that meet specific conditions. Orders can be cancelled when:

Order is in draft state
Order is confirmed (sale state) and has no stock pickings created
Order is confirmed and has stock pickings but none are in process (not in confirmed or assigned states). Draft or done pickings do not block cancellation.

Important Notes:

Orders created via API can only be cancelled by the same API user that created them
If an order has multiple pickings blocking cancellation, the error message lists each one explicitly
The system uses core Odoo functions for cancellation, ensuring data integrity and proper state transitions

Endpoint

Method: POST

URL: http://gotta-test.ambiasuite.com/api/orders/cancel

Authentication: Required via HTTP-API-KEY header

Required Role: ALL or ORDERS

Request Parameters

Parameter	Required	Type	Location	Description
`HTTP-API-KEY`	Yes	String	Header	API key for authentication
`orders`	Yes	Array	Body	Array of order IDs to cancel (minimum 1 order ID)
`orders[]`	Yes	String	Body	Order ID (format: `{serie}-{sequence}`, e.g., `VWE-VWE00001`)

Response Data Structure

Field	Type	Description
`message`	String	Status message (always "Orders cancellation completed")
`result.data`	Array	Array of order cancellation results
`result.data[].order_id`	String	Order ID that was requested to cancel
`result.data[].code`	Integer	Result code: `0` = SUCCESS, `1` = IGNORED, `2` = ERROR
`result.data[].message`	String	Result message describing the outcome

Response Codes:

0 (SUCCESS): Order cancelled successfully
1 (IGNORED): Order not found or already cancelled
2 (ERROR): Cannot cancel (e.g., order has picking in process, wrong state, doesn't belong to user)

Examples for Request

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": ["VWE-VWE00001"]
}'

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": ["VWE-VWE00001", "VWE-VWE00002", "VWE-VWE00003"]
}'

Expected Output (200 OK)

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VWE-VWE00001",
        "code": 0,
        "message": "Order cancelled successfully"
      }
    ]
  }
}

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VWE-VWE00001",
        "code": 0,
        "message": "Order cancelled successfully"
      },
      {
        "order_id": "NONEXISTENT-123",
        "code": 1,
        "message": "Order not found"
      },
      {
        "order_id": "VWE-VWE00002",
        "code": 1,
        "message": "Order is already cancelled"
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Not authenticated"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "Content-Type: application/json" \
  -d '{"orders": ["VWE-VWE00001"]}'

Error Response: HTTP 401 - Missing HTTP-API-KEY header

Description: The API key does not have the required role (ALL or ORDERS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL, ORDERS"
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "HTTP-API-KEY: api_key_with_only_products_role" \
  -H "Content-Type: application/json" \
  -d '{"orders": ["VWE-VWE00001"]}'

Error Response: HTTP 403 - API key has role "PRODUCTS" but endpoint requires "ALL" or "ORDERS"

Description: Order cannot be cancelled because one or more stock pickings are in process (confirmed / assigned). The error message lists each blocking picking.

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VV70-00011",
        "code": 2,
        "message": "Order has the following items in process:\n  • Picking WH/OUT/00001 (state: assigned)\n  • Picking WH/OUT/00002 (state: confirmed)"
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": ["VV70-00011"]
}'

Error Response: Order returns code: 2 (ERROR) with explicit list of blocking pickings

Description: Order cannot be cancelled because it has a stock picking in process. Picking states that block cancellation: confirmed, assigned. Draft or done pickings do not block cancellation.

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VV70-00011",
        "code": 2,
        "message": "Order has Picking WH/RMA/IN/00001 (state: assigned)"
      }
    ]
  }
}

Note: Only pickings in confirmed or assigned states block cancellation. Draft pickings are ignored.

Description: Orders created via API can only be cancelled by the same API user that created them. This ensures security and prevents unauthorized cancellations.

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VV70-00011",
        "code": 2,
        "message": "Order does not belong to authenticated user"
      }
    ]
  }
}

Note: This validation only applies to orders created via API (gt_web_service = True). Manual orders can be cancelled by any authorized user.

Description: Order cannot be cancelled because it is in an invalid state. Only orders in draft or sale (confirmed) states can be cancelled.

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VV70-00011",
        "code": 2,
        "message": "Order is in state 'done' and cannot be cancelled"
      }
    ]
  }
}

Note: Orders in states like sent, done, or cancel cannot be cancelled.

Description: Order is already cancelled or doesn't exist.

                                                            {
  "message": "Orders cancellation completed",
  "result": {
    "data": [
      {
        "order_id": "VWE-VWE00001",
        "code": 1,
        "message": "Order is already cancelled"
      }
    ]
  }
}

Wrong Request Example:

                                                            curl -X POST "http://gotta-test.ambiasuite.com/api/orders/cancel" \
  -H "HTTP-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": ["VWE-VWE00001"]
}'

Response: Order returns code: 1 (IGNORED) - order is already cancelled or not found

6. Products

Products Query

Description

Query and retrieve products from the catalog with advanced filtering capabilities. This endpoint allows you to filter products by SKU or EAN codes (barcodes), supports pagination, and ensures products are filtered by channel (CANAL) from the authenticated user.

Channel Filtering: Products are automatically filtered by the authenticated user's channel. All users with the same channel see ALL products for that channel.

Endpoint and Request Method

Endpoint	Method	Authentication	Required Role
`/api/products/get_all`	GET	Required	ALL or PRODUCTS

Parameters

Parameter	Required	Type	Location	Description
`skip`	No	Integer	Query	Number of items to skip (pagination offset). Default: 0, Minimum: 0
`limit`	No	Integer	Query	Maximum items to return. Default: 100, Range: 1-1000
`sku`	No	String	Query	Comma-separated list of SKUs to filter (e.g., `520123456789,520987654321`)
`ean`	No	String	Query	Comma-separated list of EAN/barcode codes to filter (e.g., `789545,8888744`). Searches in all barcode fields (ean, ean2, ean3) from product.barcode table.

Filtering Notes:

SKU Filtering: Filters products by their SKU code (codarticulo + talla + color format)
EAN Filtering: Filters products by barcode codes. Searches in all barcode fields (ean, ean2, ean3) from the product.barcode table. If no products match the provided EANs, returns empty result.
Combined Filters: SKU and EAN filters can be used together (AND logic)
Channel Filtering: Products are automatically filtered by authenticated user's channel (CANAL)

Response Data Structure

Field	Type	Description
`message`	String	Response message (e.g., "Products retrieved successfully")
`result.count`	Integer	Total number of products matching the filter (before pagination)
`result.data`	Array	Array of product objects (paginated results)
`result.data[].sku`	String	Product SKU (codarticulo + talla + color)
`result.data[].ean`	String	Primary EAN/barcode code (from product.barcode table)
`result.data[].ean2`	String	Secondary EAN/barcode code (from product.barcode table)
`result.data[].ean3`	String	Tertiary EAN/barcode code (from product.barcode table)

Examples for Request

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/products/get_all?skip=0&limit=10" \
  -H "HTTP-API-KEY: your_api_key_here"

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/products/get_all?ean=789545,8888744&limit=10" \
  -H "HTTP-API-KEY: your_api_key_here"

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/products/get_all?sku=520123456789,520987654321&limit=10" \
  -H "HTTP-API-KEY: your_api_key_here"

Expected Output (200 OK)

                                                            {
  "message": "Products retrieved successfully",
  "result": {
    "count": 2,
    "data": [
      {
        "sku": "49609..",
        "description": "GOLD TREE COLLAGEN HYALUR 4D CR 50 ML",
        "price": 29.99,
        "stock": 10.0,
        "brand_name": "GOLD TREE",
        "ean": "789545",
        "ean2": "8888744",
        "ean3": null
      }
    ]
  }
}

Wrong Request with Wrong Answers Descriptions

Description: The API key is missing, invalid, or expired.

                                                            {
  "detail": "Missing HTTP-API-KEY header"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/products/get_all"

Error Response: HTTP 401 - Missing HTTP-API-KEY header

Description: The API key does not have the required role (ALL or PRODUCTS).

                                                            {
  "detail": "Insufficient permissions. Required role: ALL or PRODUCTS"
}

Wrong Request Example:

                                                            curl -X GET "http://gotta-test.ambiasuite.com/api/products/get_all" \
  -H "HTTP-API-KEY: api_key_with_only_orders_role"

Error Response: HTTP 403 - API key has role "ORDERS" but endpoint requires "ALL" or "PRODUCTS"

Additional Information

For more information or support, please contact Gotta technical support team. This API follows RESTful principles and uses JSON for data exchange.

RestApiGotta API Documentation

Table of Contents

1. Authentication

Authentication

Description

Endpoint and Request Method

Parameters

Response Data Structure

Examples for Request

Login Example

Expected Output (200 OK)

Success Response

Wrong Request with Wrong Answers Descriptions

401 - Unauthorized (Invalid Credentials)

400 - Bad Request (Missing Required Fields)

500 - Internal Server Error

2. Countries

Countries

Description

Endpoint and Request Method

Parameters

Response Data Structure

Examples for Request

Get All Countries Example

Expected Output (200 OK)

Success Response

Wrong Request with Wrong Answers Descriptions

401 - Unauthorized (Missing or Invalid API Key)

403 - Forbidden (Insufficient Permissions)

500 - Internal Server Error

3. Carriers

Carriers

Description

Endpoint and Request Method

Parameters

Response Data Structure

Examples for Request

Get All Carriers Example

Expected Output (200 OK)

Success Response

Wrong Request with Wrong Answers Descriptions

401 - Unauthorized (Missing or Invalid API Key)

403 - Forbidden (Insufficient Permissions)

500 - Internal Server Error

3. Orders

Orders

Description

Endpoint and Request Method

Parameters

Query Parameters:

Request Body Parameters:

State Values Explanation:

Response Data Structure

Downloading Shipping Labels

Example: Download Shipping Label

Examples for Request

Example 1: Get All Orders (Default)

Example 2: Get Pending Orders

Example 3: Get Multiple States with Pagination

Example 4: Get Finished Orders (Second Page)

Expected Output (200 OK)

Success Response

Wrong Request with Wrong Answers Descriptions

401 - Unauthorized (Missing or Invalid API Key)

403 - Forbidden (Insufficient Permissions)

400 - Bad Request (Invalid State Parameter)

422 - Unprocessable Entity (Invalid Pagination)

500 - Internal Server Error

4. Orders Synchronize

Orders Synchronization

Description

Endpoint and Request Method

Parameters

Request Body Structure:

Important Notes:

Response Data Structure

Examples for Request

Example 1: Synchronize Single Order (Auto-Generated ID)

Example 1b: Synchronize Order with External Identifier (Amazon/Marketplace)

Example 1c: Synchronize Order with Custom Order Item IDs (Marketplace Identifiers)