openapi: 3.0.3
info:
  title: Extensiv 3PL Warehouse Manager API (modeled)
  version: 1.0.0
  description: >-
    Modeled OpenAPI description of the Extensiv 3PL Warehouse Manager REST API
    (formerly the 3PL Central REST API). Authentication is CONFIRMED against
    Extensiv's public help documentation: a Base64-encoded "Client ID:Client
    Secret" authorization header plus a grant_type is POSTed to
    https://secure-wms.com/AuthServer/api/Token to mint a short-lived bearer
    access token (typically valid 30-60 minutes), which is then sent as
    `Authorization: Bearer <token>` on all resource calls.

    The resource endpoints below (orders, inventory, stock summaries, items,
    customers, receivers/ASN, warehouses) are MODELED from Extensiv's publicly
    documented resource areas and common API use cases. The full request/response
    reference at developer.extensiv.com is a JavaScript-rendered developer portal
    and is effectively gated, so exact paths, query parameters, and payload
    schemas here are honestly modeled and should be reconciled against the live
    reference. The 3PL Warehouse Manager REST API is a HATEOAS/HAL-style
    hypermedia API; only HTTPS is supported (no plain HTTP).

    NOTE: The SecureWMS / 3PL Warehouse Manager REST API is profiled in more
    detail in the sibling all/3plcentral catalog entry. This description supports
    the Extensiv company/platform entry.
  contact:
    name: Extensiv API Access
    email: api@extensiv.com
    url: https://help.extensiv.com/en_US/rest-api
  license:
    name: Proprietary - Extensiv Terms of Service
    url: https://www.extensiv.com
servers:
- url: https://secure-wms.com
  description: 3PL Warehouse Manager REST API (production, HTTPS only). endpointsConfirmed = auth only; resource endpoints are endpointsModeled.
tags:
- name: Authentication
  description: OAuth2-style token endpoint (endpointsConfirmed).
- name: Orders
  description: Sales/fulfillment orders (endpointsModeled).
- name: Inventory
  description: On-hand inventory and stock summaries (endpointsModeled).
- name: Items
  description: Customer SKU/item master (endpointsModeled).
- name: Customers
  description: Customer/tenant accounts (endpointsModeled).
- name: Receivers
  description: Inbound receivers / ASNs (endpointsModeled).
- name: Warehouses
  description: Physical facilities (endpointsModeled).
paths:
  /AuthServer/api/Token:
    post:
      tags:
      - Authentication
      summary: Obtain an access token (endpointsConfirmed)
      description: >-
        CONFIRMED endpoint. Exchange a Base64-encoded "Client ID:Client Secret"
        Basic authorization header plus a grant_type for a short-lived bearer
        access token. The token is typically valid 30-60 minutes and must be sent
        as `Authorization: Bearer <token>` on all subsequent calls.
      security:
      - basicClientCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: client_credentials
                user_login_id:
                  type: integer
                  description: Optional user login id, when acting on behalf of a specific user.
              required:
              - grant_type
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid client credentials.
  /orders:
    get:
      tags:
      - Orders
      summary: List orders (endpointsModeled)
      parameters:
      - name: pgsiz
        in: query
        description: Page size.
        schema:
          type: integer
      - name: pgnum
        in: query
        description: Page number.
        schema:
          type: integer
      - name: rql
        in: query
        description: Resource Query Language filter (e.g. by customer, status, date).
        schema:
          type: string
      responses:
        '200':
          description: A paged collection of orders.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OrderCollection'
      security:
      - bearerAuth: []
    post:
      tags:
      - Orders
      summary: Create an order (endpointsModeled)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Order created.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Order'
      security:
      - bearerAuth: []
  /orders/{orderId}:
    get:
      tags:
      - Orders
      summary: Retrieve an order (endpointsModeled)
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested order.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found.
      security:
      - bearerAuth: []
    put:
      tags:
      - Orders
      summary: Update an order (endpointsModeled)
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Order updated.
      security:
      - bearerAuth: []
  /inventory:
    get:
      tags:
      - Inventory
      summary: Retrieve inventory (endpointsModeled)
      description: >-
        Retrieve on-hand inventory, optionally filtered by customer, facility, or
        a received-on/before date.
      parameters:
      - name: rql
        in: query
        schema:
          type: string
      - name: pgsiz
        in: query
        schema:
          type: integer
      - name: pgnum
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A collection of inventory records.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/InventoryCollection'
      security:
      - bearerAuth: []
  /inventory/stockSummaries:
    get:
      tags:
      - Inventory
      summary: Retrieve stock summaries (endpointsModeled)
      description: Rolled-up available/on-hand/committed quantities by SKU.
      parameters:
      - name: facilityId
        in: query
        schema:
          type: integer
      - name: customerId
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Stock summary records.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/StockSummaryCollection'
      security:
      - bearerAuth: []
  /customers:
    get:
      tags:
      - Customers
      summary: List customers (endpointsModeled)
      responses:
        '200':
          description: A collection of customers.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CustomerCollection'
      security:
      - bearerAuth: []
  /customers/{customerId}:
    get:
      tags:
      - Customers
      summary: Retrieve a customer (endpointsModeled)
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested customer.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Customer'
      security:
      - bearerAuth: []
  /customers/{customerId}/items:
    get:
      tags:
      - Items
      summary: List a customer's items/SKUs (endpointsModeled)
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: integer
      - name: rql
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A collection of items.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ItemCollection'
      security:
      - bearerAuth: []
  /inventory/receivers:
    get:
      tags:
      - Receivers
      summary: List receivers / ASNs (endpointsModeled)
      responses:
        '200':
          description: A collection of receivers.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ReceiverCollection'
      security:
      - bearerAuth: []
    post:
      tags:
      - Receivers
      summary: Create a receiver / ASN (endpointsModeled)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Receiver'
      responses:
        '201':
          description: Receiver created.
      security:
      - bearerAuth: []
  /inventory/receivers/{receiverId}:
    get:
      tags:
      - Receivers
      summary: Retrieve a receiver / ASN (endpointsModeled)
      parameters:
      - name: receiverId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested receiver.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Receiver'
      security:
      - bearerAuth: []
  /facilities:
    get:
      tags:
      - Warehouses
      summary: List warehouses/facilities (endpointsModeled)
      responses:
        '200':
          description: A collection of facilities.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/FacilityCollection'
      security:
      - bearerAuth: []
components:
  securitySchemes:
    basicClientCredentials:
      type: http
      scheme: basic
      description: Base64-encoded "Client ID:Client Secret" used only against /AuthServer/api/Token.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived bearer access token minted by the auth server.
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Seconds until expiry (typically 1800-3600).
          example: 3600
    Order:
      type: object
      properties:
        orderId:
          type: integer
        customerId:
          type: integer
        referenceNum:
          type: string
        facilityId:
          type: integer
        status:
          type: string
        orderItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        orderItemId:
          type: integer
        itemIdentifier:
          type: string
        qty:
          type: number
    OrderCollection:
      type: object
      properties:
        totalResults:
          type: integer
        _embedded:
          type: object
          properties:
            orders:
              type: array
              items:
                $ref: '#/components/schemas/Order'
    InventoryRecord:
      type: object
      properties:
        itemIdentifier:
          type: string
        customerId:
          type: integer
        facilityId:
          type: integer
        onHand:
          type: number
        available:
          type: number
        receivedDate:
          type: string
          format: date-time
    InventoryCollection:
      type: object
      properties:
        totalResults:
          type: integer
        _embedded:
          type: object
          properties:
            inventory:
              type: array
              items:
                $ref: '#/components/schemas/InventoryRecord'
    StockSummary:
      type: object
      properties:
        sku:
          type: string
        onHand:
          type: number
        available:
          type: number
        committed:
          type: number
    StockSummaryCollection:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            stockSummaries:
              type: array
              items:
                $ref: '#/components/schemas/StockSummary'
    Customer:
      type: object
      properties:
        customerId:
          type: integer
        companyName:
          type: string
    CustomerCollection:
      type: object
      properties:
        totalResults:
          type: integer
        _embedded:
          type: object
          properties:
            customers:
              type: array
              items:
                $ref: '#/components/schemas/Customer'
    Item:
      type: object
      properties:
        itemId:
          type: integer
        sku:
          type: string
        description:
          type: string
    ItemCollection:
      type: object
      properties:
        totalResults:
          type: integer
        _embedded:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Item'
    Receiver:
      type: object
      properties:
        receiverId:
          type: integer
        customerId:
          type: integer
        facilityId:
          type: integer
        referenceNum:
          type: string
        receiveItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    ReceiverCollection:
      type: object
      properties:
        totalResults:
          type: integer
        _embedded:
          type: object
          properties:
            receivers:
              type: array
              items:
                $ref: '#/components/schemas/Receiver'
    Facility:
      type: object
      properties:
        facilityId:
          type: integer
        name:
          type: string
    FacilityCollection:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            facilities:
              type: array
              items:
                $ref: '#/components/schemas/Facility'