3M Partner and Supplier API

openapi: 3.1.0
info:
  title: 3M Partner and Supplier API
  description: >-
    The 3M Partner and Supplier API provides real-time access to 3M product,
    pricing, order, delivery, and invoice data for partners and suppliers.
    The API supports GET and POST operations for product/price lookups,
    order and delivery tracking, and invoice status queries. Authentication
    uses OAuth 2.0 bearer tokens with client credentials provided during
    onboarding.
  version: '1.0'
servers:
  - url: https://api.3m.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Deliveries
    description: Track delivery status and logistics for partner orders.
  - name: Invoices
    description: Retrieve invoice status and details for billing reconciliation.
  - name: Orders
    description: Submit and track purchase orders with 3M.
  - name: Products
    description: Retrieve product catalog and pricing information.
paths:
  /products:
    get:
      operationId: listProducts
      summary: 3M List Products
      description: >-
        Retrieves a list of 3M products available to partners and suppliers
        with pricing and availability information.
      tags:
        - Products
      parameters:
        - name: category
          in: query
          description: Filter products by product category.
          schema:
            type: string
          example: adhesives
        - name: sku
          in: query
          description: Filter by specific product SKU.
          schema:
            type: string
          example: SKU-12345
      responses:
        '200':
          description: Successful response with product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
              examples:
                ListProducts200Example:
                  summary: Default listProducts 200 response
                  x-microcks-default: true
                  value:
                    products:
                      - productId: PROD-12345
                        name: 3M Scotch Heavy Duty Tape
                        sku: SKU-12345
                        category: adhesives
                        description: Heavy duty packaging tape for industrial use
                        unitPrice: 24.99
                        currency: USD
                        availability: in-stock
        '401':
          description: Unauthorized - invalid or missing bearer token
        '403':
          description: Forbidden - insufficient permissions for this resource
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/{productId}/price:
    get:
      operationId: getProductPrice
      summary: 3M Get Product Price
      description: >-
        Retrieves the current pricing information for a specific 3M product
        based on the partner agreement and negotiated pricing tiers.
      tags:
        - Products
      parameters:
        - name: productId
          in: path
          required: true
          description: The unique product identifier.
          schema:
            type: string
          example: PROD-12345
      responses:
        '200':
          description: Successful response with product pricing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPrice'
              examples:
                GetProductPrice200Example:
                  summary: Default getProductPrice 200 response
                  x-microcks-default: true
                  value:
                    productId: PROD-12345
                    unitPrice: 24.99
                    currency: USD
                    pricingTier: partner
                    effectiveDate: '2025-01-01'
                    expirationDate: '2025-12-31'
        '401':
          description: Unauthorized
        '404':
          description: Product not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /orders:
    get:
      operationId: listOrders
      summary: 3M List Orders
      description: >-
        Retrieves a list of orders placed by the authenticated partner
        or supplier with status and tracking information.
      tags:
        - Orders
      parameters:
        - name: status
          in: query
          description: Filter orders by status (pending, processing, shipped, delivered, cancelled).
          schema:
            type: string
            enum:
              - pending
              - processing
              - shipped
              - delivered
              - cancelled
          example: shipped
        - name: startDate
          in: query
          description: Filter orders from this date.
          schema:
            type: string
            format: date
          example: '2025-01-01'
      responses:
        '200':
          description: Successful response with order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderList'
              examples:
                ListOrders200Example:
                  summary: Default listOrders 200 response
                  x-microcks-default: true
                  value:
                    orders:
                      - orderId: ORD-67890
                        status: shipped
                        createdAt: '2025-03-15T10:30:00Z'
                        totalAmount: 499.95
                        currency: USD
                        items:
                          - productId: PROD-12345
                            quantity: 20
                            unitPrice: 24.99
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

    post:
      operationId: createOrder
      summary: 3M Create an Order
      description: >-
        Submits a new order for 3M products on behalf of the authenticated
        partner or supplier.
      tags:
        - Orders
      requestBody:
        required: true
        description: Order details including line items and shipping address.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              CreateOrderRequestExample:
                summary: Default createOrder request
                x-microcks-default: true
                value:
                  items:
                    - productId: PROD-12345
                      quantity: 20
                  shippingAddress:
                    street: 3M Center
                    city: St. Paul
                    state: MN
                    zip: '55144'
                    country: US
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                CreateOrder201Example:
                  summary: Default createOrder 201 response
                  x-microcks-default: true
                  value:
                    orderId: ORD-67891
                    status: pending
                    createdAt: '2025-03-15T14:30:00Z'
                    totalAmount: 499.80
                    currency: USD
                    items:
                      - productId: PROD-12345
                        quantity: 20
                        unitPrice: 24.99
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /deliveries:
    get:
      operationId: listDeliveries
      summary: 3M List Deliveries
      description: >-
        Retrieves delivery tracking information for orders placed by
        the authenticated partner or supplier.
      tags:
        - Deliveries
      parameters:
        - name: orderId
          in: query
          description: Filter deliveries by order identifier.
          schema:
            type: string
          example: ORD-67890
      responses:
        '200':
          description: Successful response with delivery tracking information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryList'
              examples:
                ListDeliveries200Example:
                  summary: Default listDeliveries 200 response
                  x-microcks-default: true
                  value:
                    deliveries:
                      - deliveryId: DEL-11111
                        orderId: ORD-67890
                        carrier: UPS
                        trackingNumber: 1Z999AA10123456784
                        status: in-transit
                        estimatedDelivery: '2025-03-20'
                        shippedAt: '2025-03-17T08:00:00Z'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /invoices:
    get:
      operationId: listInvoices
      summary: 3M List Invoices
      description: >-
        Retrieves invoice summaries for the authenticated partner
        or supplier with filtering by date range.
      tags:
        - Invoices
      parameters:
        - name: startDate
          in: query
          description: Filter invoices from this date.
          schema:
            type: string
            format: date
          example: '2025-01-01'
        - name: endDate
          in: query
          description: Filter invoices up to this date.
          schema:
            type: string
            format: date
          example: '2025-03-31'
      responses:
        '200':
          description: Successful response with invoice list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceList'
              examples:
                ListInvoices200Example:
                  summary: Default listInvoices 200 response
                  x-microcks-default: true
                  value:
                    invoices:
                      - invoiceId: INV-22222
                        orderId: ORD-67890
                        invoiceDate: '2025-03-18'
                        dueDate: '2025-04-17'
                        totalAmount: 499.95
                        currency: USD
                        status: unpaid
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token obtained through client credentials flow. Provided during onboarding.

  schemas:
    Product:
      type: object
      description: A 3M product available to partners and suppliers
      properties:
        productId:
          type: string
          description: Unique product identifier
          example: PROD-12345
        name:
          type: string
          description: Product display name
          example: 3M Scotch Heavy Duty Tape
        sku:
          type: string
          description: Stock Keeping Unit identifier
          example: SKU-12345
        category:
          type: string
          description: Product category
          example: adhesives
        description:
          type: string
          description: Detailed product description
          example: Heavy duty packaging tape for industrial use
        unitPrice:
          type: number
          description: Unit price for the product
          example: 24.99
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        availability:
          type: string
          description: Product availability status
          enum:
            - in-stock
            - out-of-stock
            - limited
            - discontinued
          example: in-stock

    ProductList:
      type: object
      description: List of 3M products
      properties:
        products:
          type: array
          description: Array of product records
          items:
            $ref: '#/components/schemas/Product'

    ProductPrice:
      type: object
      description: Pricing information for a specific 3M product
      properties:
        productId:
          type: string
          description: Unique product identifier
          example: PROD-12345
        unitPrice:
          type: number
          description: Partner-negotiated unit price
          example: 24.99
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        pricingTier:
          type: string
          description: Pricing tier applied to this partner
          example: partner
        effectiveDate:
          type: string
          format: date
          description: Date when this pricing becomes effective
          example: '2025-01-01'
        expirationDate:
          type: string
          format: date
          description: Date when this pricing expires
          example: '2025-12-31'

    OrderItem:
      type: object
      description: A line item within an order
      properties:
        productId:
          type: string
          description: Product identifier
          example: PROD-12345
        quantity:
          type: integer
          description: Quantity ordered
          example: 20
        unitPrice:
          type: number
          description: Unit price at time of order
          example: 24.99

    Order:
      type: object
      description: A purchase order placed with 3M
      properties:
        orderId:
          type: string
          description: Unique order identifier
          example: ORD-67890
        status:
          type: string
          description: Current order status
          enum:
            - pending
            - processing
            - shipped
            - delivered
            - cancelled
          example: shipped
        createdAt:
          type: string
          format: date-time
          description: Order creation timestamp
          example: '2025-03-15T10:30:00Z'
        totalAmount:
          type: number
          description: Total order value
          example: 499.95
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        items:
          type: array
          description: Line items in the order
          items:
            $ref: '#/components/schemas/OrderItem'

    OrderList:
      type: object
      description: List of orders
      properties:
        orders:
          type: array
          description: Array of order records
          items:
            $ref: '#/components/schemas/Order'

    ShippingAddress:
      type: object
      description: Shipping address for an order
      properties:
        street:
          type: string
          description: Street address
          example: 3M Center
        city:
          type: string
          description: City name
          example: St. Paul
        state:
          type: string
          description: State or province code
          example: MN
        zip:
          type: string
          description: Postal/ZIP code
          example: '55144'
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US

    CreateOrderRequest:
      type: object
      description: Request body for creating a new order
      required:
        - items
        - shippingAddress
      properties:
        items:
          type: array
          description: Line items to order
          items:
            type: object
            properties:
              productId:
                type: string
                description: Product identifier
                example: PROD-12345
              quantity:
                type: integer
                description: Quantity to order
                example: 20
        shippingAddress:
          $ref: '#/components/schemas/ShippingAddress'

    Delivery:
      type: object
      description: Delivery tracking record for an order
      properties:
        deliveryId:
          type: string
          description: Unique delivery identifier
          example: DEL-11111
        orderId:
          type: string
          description: Associated order identifier
          example: ORD-67890
        carrier:
          type: string
          description: Shipping carrier name
          example: UPS
        trackingNumber:
          type: string
          description: Carrier tracking number
          example: 1Z999AA10123456784
        status:
          type: string
          description: Current delivery status
          enum:
            - pending
            - in-transit
            - out-for-delivery
            - delivered
            - exception
          example: in-transit
        estimatedDelivery:
          type: string
          format: date
          description: Estimated delivery date
          example: '2025-03-20'
        shippedAt:
          type: string
          format: date-time
          description: Timestamp when the shipment was dispatched
          example: '2025-03-17T08:00:00Z'

    DeliveryList:
      type: object
      description: List of delivery records
      properties:
        deliveries:
          type: array
          description: Array of delivery records
          items:
            $ref: '#/components/schemas/Delivery'

    Invoice:
      type: object
      description: An invoice issued by 3M for an order
      properties:
        invoiceId:
          type: string
          description: Unique invoice identifier
          example: INV-22222
        orderId:
          type: string
          description: Associated order identifier
          example: ORD-67890
        invoiceDate:
          type: string
          format: date
          description: Date the invoice was issued
          example: '2025-03-18'
        dueDate:
          type: string
          format: date
          description: Payment due date
          example: '2025-04-17'
        totalAmount:
          type: number
          description: Total invoice amount
          example: 499.95
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: USD
        status:
          type: string
          description: Invoice payment status
          enum:
            - unpaid
            - paid
            - overdue
            - disputed
          example: unpaid

    InvoiceList:
      type: object
      description: List of invoices
      properties:
        invoices:
          type: array
          description: Array of invoice records
          items:
            $ref: '#/components/schemas/Invoice'