PMAPI-1829: add buckslips docs

lob-api-public.yml

@@ -100,6 +100,18 @@ tags:
       resource API section to learn more about how to access the Billing Groups API.
       <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
 
+  - name: Buckslip Orders
+    description: |
+      The buckslip orders endpoint allows you to easily create buckslip orders for existing buckslips.
+      The API provides endpoints for creating buckslip orders and listing buckslip orders for a given buckslip.
+      <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
+
+  - name: Buckslips
+    description: |
+      The buckslips endpoint allows you to easily create buckslips that can later be affixed to Letters.
+      The API provides endpoints for creating buckslips, retrieving individual buckslips, creating buckslip orders, and retrieving a list of buckslips.
+      <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
+
   - name: Bulk Intl Verifications
     description: |
       Verify a list of non-US addresses.
@@ -2434,6 +2446,8 @@ x-tagGroups:
   - name: Special Features
     tags:
       - Billing Groups
+      - Buckslips
+      - Buckslip Orders
       - Cards
       - Card Orders
 
@@ -2514,6 +2528,15 @@ paths:
   /campaigns/{cmp_id}/send:
     $ref: resources/campaigns/send.yml
 
+  /buckslips:
+    $ref: resources/buckslips/buckslips.yml
+
+  /buckslips/{buckslip_id}:
+    $ref: resources/buckslips/buckslip.yml
+
+  /buckslips/{buckslip_id}/orders:
+    $ref: resources/buckslips/buckslip_orders/buckslip_orders.yml
+
   /cards:
     $ref: resources/cards/cards.yml
 

resources/buckslips/attributes/buckslip_description.yml

@@ -0,0 +1,4 @@
+type: string
+description: Description of the buckslip.
+maxLength: 255
+nullable: true

resources/buckslips/buckslip.yml

@@ -0,0 +1,115 @@
+parameters:
+  - in: path
+    name: buckslip_id
+    description: id of the buckslip
+    required: true
+    schema:
+      $ref: "../../shared/attributes/model_ids/buckslip_id.yml"
+
+get:
+  operationId: buckslip_retrieve
+
+  summary: Retrieve
+
+  description: >-
+    Retrieves the details of an existing buckslip. You need only supply
+    the unique customer identifier that was returned upon buckslip creation.
+
+  tags:
+    - Buckslips
+
+  responses:
+    "200":
+      description: Returns a buckslip object
+      content:
+        $ref: "responses/buckslip.yml"
+
+    default:
+      $ref: "../../shared/responses/buckslip_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
+          -u <YOUR API KEY>:
+      label: CURL
+
+patch:
+  operationId: buckslip_update
+
+  summary: Update
+
+  description: >-
+    Update the details of an existing buckslip. You need only supply
+    the unique identifier that was returned upon buckslip creation.
+
+  tags:
+    - Buckslips
+
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "models/buckslip_updatable.yml"
+        example:
+          description: Test buckslip
+          auto_reorder: true
+
+      application/x-www-form-urlencoded:
+        schema:
+          $ref: "models/buckslip_updatable.yml"
+        example:
+          description: Test buckslip
+          auto_reorder: true
+
+      multipart/form-data:
+        schema:
+          $ref: "models/buckslip_updatable.yml"
+        example:
+          description: Test buckslip
+          auto_reorder: true
+
+  responses:
+    "200":
+      description: Returns a buckslip object
+      content:
+        $ref: "responses/buckslip.yml"
+
+    default:
+      $ref: "../../shared/responses/buckslip_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl -X PATCH https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
+          -u <YOUR API KEY>: \
+          -d "description=Awesome buckslip" \
+          -d "auto_reorder=true"
+      label: CURL
+
+delete:
+  operationId: buckslip_delete
+
+  summary: Delete
+
+  description: >-
+    Delete an existing buckslip. You need only supply
+    the unique identifier that was returned upon buckslip creation.
+
+  tags:
+    - Buckslips
+
+  responses:
+    "200":
+      $ref: "../../shared/responses/buckslip_deleted.yml"
+
+    default:
+      $ref: "../../shared/responses/buckslip_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
+          -u <YOUR API KEY>:
+      label: CURL

resources/buckslips/buckslip_orders/buckslip_orders.yml

@@ -0,0 +1,87 @@
+parameters:
+  - in: path
+    name: buckslip_id
+    description: The ID of the buckslip to which the buckslip orders belong.
+    required: true
+    schema:
+      $ref: "../../../shared/attributes/model_ids/buckslip_id.yml"
+
+get:
+  operationId: buckslip_orders_retrieve
+
+  summary: Retrieve
+
+  description: >-
+    Retrieves the buckslip orders associated with the given buckslip id.
+
+  tags:
+    - Buckslip Orders
+
+  parameters:
+    - $ref: "../../../shared/parameters/limit.yml"
+    - $ref: "../../../shared/parameters/offset.yml"
+
+  responses:
+    "200":
+      description: Returns the buckslip orders associated with the given buckslip id
+      content:
+        $ref: "responses/all_buckslip_orders.yml"
+
+    default:
+      $ref: "../../../shared/responses/buckslip_order_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \
+          -u <YOUR API KEY>:
+      label: CURL
+
+post:
+  operationId: buckslip_order_create
+
+  summary: Create
+
+  description: >-
+    Creates a new buckslip order given information
+
+  tags:
+    - Buckslip Orders
+
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "models/buckslip_order_editable.yml"
+        example:
+          quantity: 10000
+
+      application/x-www-form-urlencoded:
+        schema:
+          $ref: "models/buckslip_order_editable.yml"
+        example:
+          quantity: 10000
+
+      multipart/form-data:
+        schema:
+          $ref: "models/buckslip_order_editable.yml"
+        example:
+          quantity: 10000
+
+  responses:
+    "200":
+      description: Buckslip order created successfully
+      content:
+        $ref: "responses/buckslip_order.yml"
+
+    default:
+      $ref: "../../../shared/responses/buckslip_error.yml"
+
+  x-codeSamples:
+    - lang: Shell
+      source: |
+        curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders \
+          -u <YOUR API KEY>: \
+          -d "quantity=10000"
+      label: CURL

resources/buckslips/buckslip_orders/models/buckslip_order.yml

@@ -0,0 +1,36 @@
+allOf:
+  - $ref: "../../../../shared/models/lob_base.yml"
+  - type: object
+    properties:
+      id:
+        $ref: "../../../../shared/attributes/model_ids/bo_id.yml"
+      buckslip_id:
+        $ref: "../../../../shared/attributes/model_ids/buckslip_id.yml"
+      status:
+        description: The status of the buckslip order.
+        enum:
+          - pending
+          - printing
+          - available
+          - cancelled
+          - depleted
+        type: string
+      quantity_ordered:
+        description: The quantity of buckslips ordered
+        type: number
+        default: 0
+      unit_price:
+        description: The unit price for the buckslip order.
+        type: number
+        default: 0
+      cancelled_reason:
+        description: The reason for cancellation.
+        type: string
+      availability_date:
+        type: string
+        format: date-time
+        description: A timestamp in ISO 8601 format of the date the resource was created.
+      expected_availability_date:
+        type: string
+        format: date-time
+        description: The fixed deadline for the buckslips to be printed.

resources/buckslips/buckslip_orders/models/buckslip_order_editable.yml

@@ -0,0 +1,11 @@
+type: object
+
+required:
+  - quantity
+
+properties:
+  quantity:
+    type: integer
+    description: The quantity of buckslips in the order (minimum 5,000).
+    minimum: 5000
+    maximum: 10000000

resources/buckslips/buckslip_orders/responses/all_buckslip_orders.yml

@@ -0,0 +1,28 @@
+application/json:
+  schema:
+    allOf:
+      - $ref: "../../../../shared/models/list.yml"
+      - type: object
+        properties:
+          data:
+            type: array
+            description: List of buckslip orders
+            items:
+              $ref: "../models/buckslip_order.yml"
+  example:
+    data:
+      - id: "bo_e0f8a0562a06bea7f"
+        buckslip_id: "bck_6afffd19045076c"
+        status: "available"
+        quantity_ordered: 5000
+        unit_price: 0.75
+        cancelled_reason: "No longer needed"
+        availability_date: "2021-10-12T21:41:48.326Z"
+        expected_availability_date: "2021-11-04T21:03:18.871Z"
+        date_created: "2021-10-07T21:03:18.871Z"
+        date_modified: "2021-10-16T01:00:30.144Z"
+        object: "buckslip_order"
+    object: list
+    next_url: null
+    previous_url: null
+    count: 1

resources/buckslips/buckslip_orders/responses/buckslip_order.yml

@@ -0,0 +1,18 @@
+application/json:
+  schema:
+    $ref: "../models/buckslip_order.yml"
+
+  examples:
+    basic:
+      value:
+        id: "bo_e0f8a0562a06bea7f"
+        buckslip_id: "bck_6afffd19045076c"
+        status: "available"
+        quantity_ordered: 10000
+        unit_price: 0.75
+        cancelled_reason: "No longer needed"
+        availability_date: "2021-10-12T21:41:48.326Z"
+        expected_availability_date: "2021-11-04T21:03:18.871Z"
+        date_created: "2021-10-07T21:03:18.871Z"
+        date_modified: "2021-10-16T01:00:30.144Z"
+        object: "buckslip_order"