openai.yaml

openapi: 3.0.3
info:
  title: Teeinblue Print Partner API
  description: |
    Minimal REST API for print partners to sync catalogs and submit orders to Teeinblue.
    Endpoints:
      - GET /catalogs (list)
      - GET /catalogs/{id} (detail)
      - POST /orders (create order)
  version: 1.0.0

servers:
  - url: https://example.com/v1
    description: Base URL

# All endpoints require: Authorization: Bearer <token>
security:
  - bearerAuth: []

tags:
  - name: Catalogs
    description: Endpoints for listing and retrieving catalogs
  - name: Orders
    description: Submit and manage orders

paths:
  /catalogs:
    get:
      tags: [Catalogs]
      summary: List catalogs
      description: Returns a paginated list of catalogs.
      operationId: listCatalogs
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/per_page"
        - $ref: "#/components/parameters/search"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/CatalogListItem"
                  meta:
                    $ref: "#/components/schemas/Meta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /catalogs/{id}:
    get:
      tags: [Catalogs]
      summary: Catalog detail
      description: Returns full catalog details for a given ID.
      operationId: getCatalog
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Catalog"
              example: {"id":8,"name":"Example product","description":"Example product","mockups":[{"name":"Mockup 1","url":"https://example.com/layer-main.png","width":1000,"height":1000,"mockup_layers":[{"url":"https://example.com/layer-background.png"},{"perspective":{"top_left":{"x":145,"y":61},"top_right":{"x":849,"y":56},"bottom_left":{"x":146,"y":726},"bottom_right":{"x":844,"y":729}},"printarea_info":{"name":"front","width":3280,"height":3115}},{"url":"https://example.com/layer-main.png"}]},{"name":"Mockup 2","url":"https://example.com/layer-main.png","width":960,"height":960,"mockup_layers":[{"url":"https://example.com/layer-main.png"},{"top":356,"left":215,"width":554,"height":248,"mask":{"top":0,"left":0,"width":261,"height":248},"printarea_info":{"name":"back","width":2480,"height":1110}},{"top":356,"left":194,"width":552,"height":247,"mask":{"top":0,"left":284,"width":265,"height":247},"printarea_info":{"name":"back","width":2480,"height":1110}}]}],"print_areas":[{"name":"front","display_name":"Front","width":3280,"height":3115,"dpi":300},{"name":"back","display_name":"Back","width":2480,"height":1110,"dpi":300}],"variants":[{"variant_sku":"black-wood-1","size":"Wood LED Base with Cord","color":"Default","color_hex":"#000000","base_cost":19.99,"availability":"in_stock","weight":200,"printareas_info":[{"name":"back","display_name":"Back","width":2480,"height":1110,"dpi":300}]}]}
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /orders:
    post:
      tags: [Orders]
      summary: Create order
      description: This API endpoint creates an order and returns it.
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                [shipping_address, line_items, shipment_notification_url]
              properties:
                reference_order_id:
                  type: string
                  description: External order id in your system.
                  example: "#1001"
                test_order:
                  type: boolean
                  description: Flag to create a test order (no production fulfillment).
                  example: false
                shipment_notification_url:
                  type: string
                  description: A webhook callback URL for shipment updates. If provided, the print provider will send an HTTP POST request to this URL when the order ships, including tracking details (e.g. tracking number, tracking url, tracking company). This allows your system to automatically receive delivery updates without polling the API.
                  example: "https://api.teeinblue.com/api/webhook/print-provider?order-token=7d1e0f01ff56119101046f4f27a88412"
                shipping_address:
                  type: object
                  description: Shipping address
                  required:
                    [
                      first_name,
                      last_name,
                      address1,
                      city,
                      state,
                      zip,
                      country,
                      country_code,
                    ]
                  properties:
                    zip:
                      type: string
                      description: Postal/ZIP code.
                      example: "60089"
                    city:
                      type: string
                      example: "Buffalo Grove"
                    phone:
                      type: string
                    company:
                      type: string
                    country:
                      type: string
                      example: "France"
                    address1:
                      type: string
                      description: Primary street line.
                      example: "1999 Rue Lucie Aubrac"
                    address2:
                      type: string
                      nullable: true
                      description: Secondary address line.
                      example: null
                    province:
                      type: string
                      description: State/Province
                    first_name:
                      type: string
                      example: "John"
                    last_name:
                      type: string
                      example: "Carry"
                    country_code:
                      type: string
                      example: "FR"
                    province_code:
                      type: string

                line_items:
                  type: array
                  description: List of items to fulfill.
                  minItems: 1
                  items:
                    type: object
                    required: [quantity, variant_sku]
                    properties:
                      quantity:
                        type: integer
                        example: 1
                      variant_sku:
                        type: string
                        description: Partner SKU to fulfill.
                        example: "2342"
                      print_areas:
                        type: array
                        description: Artwork per print area.
                        minItems: 1
                        items:
                          type: object
                          required: [key, url]
                          properties:
                            key:
                              type: string
                              description: Print area key.
                              example: "front"
                            url:
                              type: string
                              format: uri
                              description: Public URL to the artwork.
                              example: "https://cdn.teeinblue.com/designs/467f0119-2e8d-4bc8-be90-fd80cbb49f08/467f0119-2e8d-4bc8-be90-fd80cbb49f08-272489.png"
      responses:
        "201":
          description: Order created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: "ord_123456"
                  status:
                    type: string
                    example: "created"
                  reference_order_id:
                    type: string
                    example: "#1001"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          description: Unprocessable Entity (validation error)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <token> # optional, adjust as needed

  parameters:
    id:
      in: path
      name: id
      required: true
      schema:
        type: integer
      description: Resource identifier.
    page:
      in: query
      name: page
      schema:
        type: integer
        description: Page number for pagination.
        default: 1
    per_page:
      in: query
      name: per_page
      schema:
        type: integer
        default: 50
    search:
      in: query
      name: search
      schema:
        type: string
      description: String to search for.

  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
          example:
            error:
              code: invalid_parameter
              message: per_page must be <= 100
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
          example:
            error:
              code: unauthorized
              message: Missing or invalid token
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
          example:
            error:
              code: not_found
              message: Resource not found

  schemas:
    Meta:
      type: object
      properties:
        page:
          type: integer
          description: Current page number.
          example: 1
        per_page:
          type: integer
          description: Number of items per page.
          example: 50
        total:
          type: integer
          description: Total number of items.
          example: 1234
      required: [page, per_page, total]

    Mockup:
      type: object
      properties:
        name:
          type: string
          description: Mockup name
          example: original
        url:
          type: string
          description: Mockup image URL. This should be a high-resolution image that can be used for generating design previews in the design tool.
          example: "https://cdn.teeinblue.com/mockups/467f0119-2e8d-4bc8-be90-fd80cbb49f08-original.jpg"
          format: uri
        mockup_layers:
          type: array
          description: Layers available for this mockup. A layer can be either a print area or an image.
          items:
            $ref: "#/components/schemas/MockupLayer"

      required: [url]

    Point:
      type: object
      properties:
        x:
          type: integer
          description: X coordinate of the point
          example: 100
        y:
          type: integer
          description: Y coordinate of the point
          example: 200
      required: [x, y]

    PrintArea:
      type: object
      properties:
        name:
          type: string
          description: The name of the print area
          example: front
        display_name:
          type: string
          description: Human-friendly name for the print area
          example: Front
        width:
          type: integer
          description: Width of the print area (in pixels)
          example: 4050
        height:
          type: integer
          description: Height of the print area (in pixels)
          example: 3000
        dpi:
          type: integer
          description: DPI (dots per inch) of the print area.
          example: 300
      required: [name, width, height]

    Variant:
      type: object
      properties:
        variant_sku:
          type: string
          description: Partner's unique identifier for this variant. This is required when submitting orders to specify which variant to fulfill.
          example: "2342"
        size:
          type: string
          description: Size of the variant (e.g. S, M, L, XL). The design tool uses this information to auto-enable size options and connect the correct variants to the correct print areas.
          example: M
        color:
          type: string
          description: Color of the variant (e.g. Black, White, Red).
          example: Black
        color_hex:
          type: string
          description: Hex code for the color of the variant.
          example: "#000000"
        base_cost:
          type: number
          description: Base cost of the variant.
          example: 19.99
        availability:
          type: string
          description: Availability status of the variant. The design tool uses this information to determine whether to show or hide the variant as an option in the design tool.
          enum: [in_stock, out_of_stock]
          example: in_stock
        weight:
          type: number
          description: Weight of the variant.
          nullable: true
          example: 200
        printareas_info:
          type: array
          description: Printareas connected to this variant. Teeinblue uses this information to auto-enable `Custom variant's printarea` and connect the printareas to the correct variants.
          items:
            $ref: "#/components/schemas/PrintArea"
      required: [variant_sku, size, color, base_cost, availability]

    CatalogListItem:
      type: object
      properties:
        id:
          type: integer
          description: Catalog ID. This is required when retrieving catalog details or submitting orders.
          example: 7
        name:
          type: string
          description: Name of the catalog.
          example: "Sublimated Sherpa Blanket"
        mockups:
          type: array
          description: List of mockups for this catalog.
          items:
            $ref: "#/components/schemas/Mockup"
      required: [id, name]

    Catalog:
      type: object
      properties:
        id:
          type: integer
          description: Catalog ID. This is required when retrieving catalog details or submitting orders.
          example: 7
        name:
          type: string
          description: Name of the catalog.
          example: "Sublimated Sherpa Blanket"
        description:
          type: string
          description: Description of the catalog.
          example: "A high-quality sublimated sherpa blanket"
        mockups:
          type: array
          items:
            $ref: "#/components/schemas/Mockup"
        print_areas:
          type: array
          items:
            $ref: "#/components/schemas/PrintArea"
        variants:
          type: array
          description: List of variants for this catalog. Each variant represents a specific combination of size and color (e.g. "Size S / Color Black").
          items:
            $ref: "#/components/schemas/Variant"
      required: [id, name, mockups, print_areas, variants]

    MockupLayer:
      type: object
      properties:
        width:
          type: integer
          description: Width of the mockup layer (in pixels). Required if mask is enabled (find out more at [Mockup of Product Base](https://support.teeinblue.com/en/article/mockup-of-product-base-1h4qyj1/)).
          example: 4050
        height:
          type: integer
          description: Height of the mockup layer (in pixels). Required if mask is enabled (find out more at [Mockup of Product Base](https://support.teeinblue.com/en/article/mockup-of-product-base-1h4qyj1/)).
          example: 4650
        top:
          type: integer
          description: Distance from the top edge of the mockup to the top edge of the layer (in pixels)
          example: 1000
        left:
          type: integer
          description: Distance from the left edge of the mockup to the left edge of the layer (in pixels)
          example: 800
        url:
          type: string
          format: uri
          description: URL for this layer on this mockup. Only applicable for image layers. The design tool uses this image to show the layer on the mockup.
          example: "https://cdn.teeinblue.com/designs/467f0119-2e8d-4bc8-be90-fd80cbb49f08/467f0119-2e8d-4bc8-be90-fd80cbb49f08-front-mask.png"
        mask:
          type: object
          description: Mask for this layer on this mockup, used when you want to show only some parts of a printarea. Only applicable for print area layers. The design tool uses this mask to show the layer in the correct shape and position on the mockup. Find out more at [Mockup of Product Base](https://support.teeinblue.com/en/article/mockup-of-product-base-1h4qyj1/).
          properties:
            url:
              type: string
              format: uri
              description: Mask image URL for this print area on this mockup. The design tool uses this mask to show the artwork in the correct shape and position on the mockup.
              example: "https://cdn.teeinblue.com/designs/467f0119-2e8d-4bc8-be90-fd80cbb49f08/467f0119-2e8d-4bc8-be90-fd80cbb49f08-front-mask.png"
            width:
              type: integer
              description: Width of the masked print area on this mockup (in pixels).
              example: 4050
            height:
              type: integer
              description: Height of the masked print area on this mockup (in pixels).
              example: 4650
            top:
              type: integer
              description: Distance from the top edge of the mockup to the top edge of the masked print area (in pixels).
              example: 1000
            left:
              type: integer
              description: Distance from the left edge of the mockup to the left edge of the masked print area (in pixels).
              example: 800
        perspective:
          type: object
          description: Perspective transformation for this layer on this mockup, used when you want to show only some parts of a printarea. Only applicable for print area layers. The design tool uses this information to transform the artwork to fit the perspective of the mockup. Find out more at [Mockup of Product Base](https://support.teeinblue.com/en/article/mockup-of-product-base-1h4qyj1/).
          properties:
            top_left:
              $ref: '#/components/schemas/Point'
              description: Top-left corner of the print area on this mockup.
              example: 
                x: 100
                y: 200
            top_right:
              $ref: '#/components/schemas/Point'
              description: Top-right corner of the print area on this mockup.
              example: 
                x: 500
                y: 200
            bottom_left:
              $ref: '#/components/schemas/Point'
              description: Bottom-left corner of the print area on this mockup.
              example: 
                x: 100
                y: 700
            bottom_right:
              $ref: '#/components/schemas/Point'
              description: Bottom-right corner of the print area on this mockup.
              example: 
                x: 500
                y: 700
        printarea_info:
          type: object
          description: Printarea information for this layer on this mockup. Only applicable for print area layers.
          properties:
            name:
              type: string
              description: Name of the print area.
              example: front
            width:
              type: integer
              description: Width of the print area (in pixels).
              example: 4050
            height:
              type: integer
              description: Height of the print area (in pixels).
              example: 4650

    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A short error code for programmatic handling of errors.
            message:
              type: string
              description: A human-readable message describing the error.
            details:
              type: object
              additionalProperties: true
          required: [code, message]
      required: [error]