API Overview
============

Integrate shipment ordering and packing optimization into your systems. Submit
orders, run optimization, and retrieve packing instructions through a single REST API.

.. _environments:

API Base URLs
-------------

Use the base URL that matches your environment:

.. list-table::
   :header-rows: 1
   :align: left

   * - **Environment**
     - **Base URL**
     - **Portal**
   * - Production
     - ``https://api.alphaaugmented.com``
     - `Portal <https://portal.alphaaugmented.com>`_
   * - Sandbox
     - ``https://api-sandbox.alphaaugmented.com``
     - `Sandbox Portal <https://sandbox.alphaaugmented.com>`_

.. important::

   Onboarding must be completed before creating orders. Supplier, consignee, items,
   boxes, pallets, and packing specifications must be configured in the ALPHA Portal.
   Contact your point of contact if anything is missing.

.. note::

   Use **Sandbox** for testing. It mirrors Production but uses separate data.
   Switch to Production when ready to create live orders.

Quick Start Guide
-----------------

1. **Obtain an API key** — Log in to the ALPHA Portal → API Keys → Generate Key
2. **Add authentication** — Include ``Authorization: Api-Key <your-key>`` in every request
3. **Submit an order** — POST to the submit-order endpoint with your payload

Typical Order Flow
------------------

1. **Submit** — POST your order payload to create the order
2. **Processing** — The optimizer runs. The PI is emailed to defined recipients, or fetch it via :ref:`Download Packing Instructions <download-pi>`.
3. **Optional** — Use :ref:`Get Order by ID <get-order>` or :ref:`List All Orders <get-all-orders>` to check status

See :ref:`authentication` for full details.

API Reference
-------------

.. toctree::
   :maxdepth: 4
   :titlesonly:

   authentication
   orders/index
   units_of_measure