API Documentation: Orders Export API

Table of Contents

1. Base URL
2. Authentication
3. Endpoints
   • Export Orders
4. Request and Response Formats
   • Export Orders Request
   • Export Orders Response
5. Error Handling
6. Rate Limiting
7. Order Attributes
8. HTTP Status Codes
9. Changelog
10. Important Notes
11. Contact Support

Base URL

https://app.quotiza.com/api/v1

Authentication

All API requests require authentication using an API token associated with your account. The token must be included in the Authorization header of each request.

Authentication Header

Authorization: Bearer YOUR_API_TOKEN

• Replace YOUR_API_TOKEN with the API token provided for your account.

How to Obtain an API Token

• Log in to your account dashboard.
• Navigate to the API settings section.
• Generate a new API token or retrieve your existing token.

Important: Keep your API token secure. Do not share it publicly or expose it in client-side code.

Endpoints

1. Export Orders

Export multiple orders based on specific criteria such as date range and status.

• URL: /orders/export
• Method: GET
• Authentication: Required
• Content-Type: application/json

Parameters

• account_id (integer, required): The ID of your account.
• n_days (integer, optional): Number of days in the past to include orders from. Defaults to 7 if not provided or invalid.
• status (string, optional): Filter orders by status. Allowed values are open, approved, cancelled.

Request and Response Formats

Export Orders Request

Endpoint: /orders/export

Method: GET

Request Headers

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Query Parameters

https://app.quotiza.com/api/v1/orders/export?account_id=6&n_days=7&status=approved

Export Orders Response

Success Response

• Status Code: 200 OK
• Content-Type: application/json

{
  "orders": [
    {
      "id": 7,
      "sequential_id": "240125-8",
      "status": "approved",
      "price_list": "Sellantes y Silicona",
      "total": 15738.0,
      "n_items": 9,
      "created_at": "2024-01-25T10:12:40.706Z",
      "updated_at": "2024-02-07T09:44:14.177Z",
      "cart_data": [
        {
          "sku": "SKU001",
          "quantity": 1,
          "price": 100.0,
          "name": "Product Zero Discount",
          "brand": "BrandA",
          "subtotal": 100.0,
          "format": "Box - 12 bottles",
          "price_discounted": 100.0,
          "subtotal_discounted": 100.0,
          "discount_rules": "",
          "discount": 0
        },
        {
          "sku": "SKU002",
          "quantity": 2,
          "price": 150.0,
          "name": "Product Ten Percent Discount",
          "brand": "BrandB",
          "subtotal": 300.0,
          "format": "Unidad - 1 unidad",
          "price_discounted": 135.0,
          "subtotal_discounted": 270.0,
          "discount_rules": "{\"type\":\"percentage\",\"value\":10}",
          "discount": 10
        },
        {
          "sku": "SKU003",
          "quantity": 3,
          "price": 200.0,
          "name": "Product Twenty Percent Discount",
          "brand": "BrandC",
          "subtotal": 600.0,
          "format": "Caja - 10 unidades",
          "price_discounted": 160.0,
          "subtotal_discounted": 480.0,
          "discount_rules": "{\"type\":\"percentage\",\"value\":20}",
          "discount": 20
        }
      ],
      "customer_info": {
        "name": "Juan Pérez ",
        "email": "Juan@3chanchitos.com",
        "phone": "+12123334444",
        "company_name": "Los 3 Chanchitos Inc."
      }
    },
    // ... other orders ...
  ]
}

Error Responses

See Error Handling for details on possible error responses.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request. In addition to the status code, error responses include a JSON body with details about the error.

Error Response Format

{
  "error": {
    "code": "error_code",
    "message": "Error message",
    "status": http_status_code
  }
}

Common Error Codes and Messages

HTTP Status Code	Error Code	Message
400 Bad Request	invalid_n_days	n_days must be a positive integer
400 Bad Request	invalid_status	status must be one of: open, approved, cancelled
400 Bad Request	missing_account_id	account_id is required
401 Unauthorized	unauthorized	Authentication token is missing or invalid
404 Not Found	account_not_found	Account not found
500 Internal Server Error	internal_server_error	An unexpected error occurred on the server.

Example Error Response

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication token is missing or invalid",
    "status": 401
  }
}

Rate Limiting

To ensure fair usage and protect the system from abuse, the API enforces rate limits on incoming requests.

Rate Limits

• Export Orders Endpoint (/orders/export):
  • Limit: 5 requests per minute per IP address.
  • Limit: 5 requests per minute per account ID.
• All API Endpoints:
  • Limit: 10 requests per minute per IP address.

Response When Rate Limit is Exceeded

• Status Code: 429 Too Many Requests
• Headers:
  • Retry-After: Number of seconds to wait before retrying.

Example Error Response:

    {
      "error": {
      "code": "throttle_limit_reached",
      "message": "Rate limit exceeded. Try again in 30 seconds.",
      "status": 429
      }
      }
    
  

Order Attributes

Below are the attributes for each order in the orders array.

Attribute	Type	Description
id	integer	Unique identifier of the order.
sequential_id	string	Sequential ID of the order.
status	string	Status of the order. Allowed values: open, approved, cancelled.
price_list	string	Name of the price list used for the order.
total	number	Total amount of the order.
n_items	integer	Number of items in the order.
created_at	string (ISO 8601)	Date and time when the order was created.
updated_at	string (ISO 8601)	Date and time when the order was last updated.
cart_data	array of objects	Details of the items in the order.
customer_info	object	Information about the customer who placed the order.

Nested cart_data Attributes

Attribute	Type	Description
sku	string	Stock Keeping Unit (unique identifier for the product).
quantity	integer	Quantity of the product ordered.
price	number	Price per unit of the product.
name	string	Name of the product.
brand	string	Brand name of the product.
subtotal	number	Subtotal amount for this product (price x quantity).
format	string	Packaging format of the product.
price_discounted	number	Discounted price per unit if applicable.
subtotal_discounted	number	Discounted subtotal amount for this product.
discount_rules	string (JSON)	Details of any discount rules applied.
discount	number	Discount percentage applied.

Nested customer_info Attributes

Attribute	Type	Description
name	string	Name of the customer.
email	string	Email address of the customer.
phone	string	Phone number of the customer.
company_name	string	Company name of the customer.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request.

• 200 OK: The request was successful.
• 400 Bad Request: The request is invalid or cannot be processed.
• 401 Unauthorized: Authentication failed or was not provided.
• 404 Not Found: The requested resource does not exist.
• 429 Too Many Requests: The client has sent too many requests in a given amount of time.
• 500 Internal Server Error: An unexpected error occurred on the server.

Changelog

• v1.0
  • Initial release of the Orders Export API.
  • Supports bulk export of orders based on date range and status.
  • Implements authentication and parameter validation.
  • Provides detailed error responses for better client-side handling.

Important Notes

• Data Validation: Ensure that all required fields are provided and that data types are correct. Invalid data may cause the export process to fail for specific orders.
• Security: Protect your API token and ensure that it is not exposed in client-side code or shared publicly.
• Rate Limits: Adhere to the rate limits to prevent your requests from being throttled.
• API Changes: Future updates to the API may introduce new features or modify existing ones. Always refer to the latest documentation.

Contact Support

If you have any questions or need assistance, please contact our support team at support@quotiza.fly.dev.

Thank You

Thank you for using our Orders Export API. We continuously strive to improve our services. Your feedback is valuable to us.