openapi: 3.0.3
info:
  title: 3PL Warehouse Manager (SecureWMS) REST Authentication Receivers API
  description: 'REST API for 3PL Warehouse Manager, the cloud warehouse management system (WMS) for third-party logistics providers, sold under Extensiv and historically known as "3PL Central". The public integration surface is the SecureWMS REST API served from https://secure-wms.com. It is used to create and retrieve orders, manage SKU items and inventory, read stock summaries and stock details, submit and track inbound receivers (Advance Ship Notices), and enumerate customers, warehouses/facilities, and locations.


    Authentication is OAuth 2.0 client-credentials. Base64-encode "clientId:clientSecret" and POST it as a Basic Authorization header to /AuthServer/api/Token with a JSON body of {"grant_type":"client_credentials","user_login_id":<id>} (a user_login or user_login_id provided by the warehouse for auditing). The returned bearer access token is short-lived - typically valid 30 to 60 minutes - and should be refreshed at least every 30 minutes. All traffic must use HTTPS; plain HTTP is not supported.


    Collection endpoints are paged with pgnum (page number) and pgsiz (page size) query parameters and can be filtered with Resource Query Language (RQL, http://api.3plcentral.com/rels/rql) via the rql parameter and ordered with sort. Responses are HAL-style JSON where list payloads carry records under a ResourceList (or Summaries for stock summaries) property.


    Endpoint provenance: read (GET) endpoints for customers, items, inventory, stock details, stock summaries, facility locations, and orders are CONFIRMED against the public developer portal and the open-source singer-io tap-3plcentral extractor. Order creation, receiver (ASN) create/list/get, and the facilities and order-packages resources are documented in the 3PL Warehouse Manager developer portal; request/response shapes that are gated behind the authenticated developer portal are MODELED here honestly and marked per-operation with x-endpoint-status.'
  version: '1.0'
  contact:
    name: Extensiv - 3PL Warehouse Manager Developer Community
    url: https://developer.3plcentral.com/
  license:
    name: Proprietary
    url: https://www.extensiv.com/legal
servers:
- url: https://secure-wms.com
  description: 3PL Warehouse Manager (SecureWMS) production
security:
- bearerAuth: []
tags:
- name: Receivers
  description: Inbound receivers (Advance Ship Notices).
paths:
  /inventory/receivers:
    get:
      operationId: listReceivers
      tags:
      - Receivers
      summary: List receivers (ASN)
      description: Lists inbound receivers (Advance Ship Notices). A receiver can be looked up by tracking/reference number via rql. DOCUMENTED (GET /inventory/receivers); response is MODELED here.
      x-endpoint-status: modeled
      parameters:
      - $ref: '#/components/parameters/pgnum'
      - $ref: '#/components/parameters/pgsiz'
      - $ref: '#/components/parameters/rql'
      responses:
        '200':
          description: A page of receivers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createReceiver
      tags:
      - Receivers
      summary: Create a receiver (ASN)
      description: Creates an inbound receiver (Advance Ship Notice) the warehouse will receive goods against. DOCUMENTED (POST /inventory/receivers); request body is MODELED here.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiverCreate'
      responses:
        '201':
          description: The created receiver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receiver'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /inventory/receivers/{receiverId}:
    get:
      operationId: getReceiver
      tags:
      - Receivers
      summary: Retrieve a receiver (ASN)
      description: Retrieves a single inbound receiver by id. DOCUMENTED (GET /inventory/receivers/{id}); response is MODELED here.
      x-endpoint-status: modeled
      parameters:
      - $ref: '#/components/parameters/receiverId'
      responses:
        '200':
          description: The receiver.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receiver'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ReceiverCreate:
      type: object
      required:
      - CustomerIdentifier
      properties:
        CustomerIdentifier:
          $ref: '#/components/schemas/CustomerIdentifier'
        FacilityIdentifier:
          $ref: '#/components/schemas/FacilityIdentifier'
        ReferenceNum:
          type: string
        PoNum:
          type: string
        ExpectedDate:
          type: string
          format: date-time
        ReceiveItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    Receiver:
      allOf:
      - $ref: '#/components/schemas/ReceiverCreate'
      - type: object
        properties:
          ReceiverId:
            type: integer
          ReadOnly:
            type: object
            additionalProperties: true
    CustomerIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
    FacilityIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
    ItemIdentifier:
      type: object
      properties:
        Id:
          type: integer
        Sku:
          type: string
    ResourceListResponse:
      type: object
      description: HAL-style list payload. Records are carried under ResourceList.
      properties:
        TotalResults:
          type: integer
        ResourceList:
          type: array
          items:
            type: object
            additionalProperties: true
        _links:
          type: object
          additionalProperties: true
    OrderItem:
      type: object
      properties:
        ItemIdentifier:
          $ref: '#/components/schemas/ItemIdentifier'
        Qty:
          type: number
        SecondaryQty:
          type: number
  parameters:
    pgnum:
      name: pgnum
      in: query
      description: Page number (1-based).
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    pgsiz:
      name: pgsiz
      in: query
      description: Page size (records per page).
      required: false
      schema:
        type: integer
        minimum: 1
        default: 100
    receiverId:
      name: receiverId
      in: path
      required: true
      description: The receiver (ASN) identifier.
      schema:
        type: integer
    rql:
      name: rql
      in: query
      description: Resource Query Language filter, e.g. "readonly.lastModifiedDate=ge=2024-01-01". Reference http://api.3plcentral.com/rels/rql.
      required: false
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or expired access token.
    BadRequest:
      description: The request payload failed validation.
    NotFound:
      description: The requested resource was not found.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived access token from POST /AuthServer/api/Token.
    basicAuth:
      type: http
      scheme: basic
      description: Base64-encoded "clientId:clientSecret" used only to obtain a token.