openapi: 3.1.0
info:
  title: Air Waybill (AWB)
  description: |
    Closes the current open order/box and generates an AWB (Air Waybill) document for all international parcels in that Deutsche Post box.

    **How it works:**
    1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box_number).
    2. When the box is full or you're ready to ship, call this endpoint to finalize the box.
    3. The finalization process:
       - Generates a single AWB label that is shared by all parcels in the finalized box
       - Attaches the AWB label to all parcels in the box
       - Increments the box_number, automatically starting a new box for subsequent parcels
    4. You can create and finalize multiple boxes throughout the day as needed.

    **Important notes:**
    - Each box has its own unique AWB label
    - All parcels within a single box share the same AWB label
    - The AWB document can be retrieved from any parcel that was in the finalized box
    - New parcels created after finalization will be added to the new box
  version: 2.0.0
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
tags:
  - name: Air Waybill (AWB)
paths:
  /box/finalize:
    post:
      summary: Finalize a Deutsche Post order
      tags:
        - Air Waybill
      operationId: sc-public-v2-scp-post-finalize_box
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      description: Finalize a Deutsche Post order by closing the current open box and generating an AWB (Air Waybill) document for all parcels in that box.
      x-mint:
        href: /api/v2/air-waybill/finalizing-a-box
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>

          This endpoint closes the current open order/box and generates an AWB (Air Waybill) document for all parcels in that box.

          **How it works:**
          1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box_number).
          2. When the box is full or you're ready to ship, call this endpoint to finalize the box.
          3. The finalization process generates a single AWB label that is shared by all parcels in the finalized box and increments the box_number, automatically starting a new box for subsequent parcels.
          4. You can create and finalize multiple boxes throughout the day as needed.

          **Parameters:**
          - `copy_count`: Specify how many AWB copies you need (1-99). Use this if the parcels are split over multiple physical boxes or pallets.

          **Response:**
          When the request is successful, a `200` code will be returned with the `copy_count` requested. The AWB is generated and you can retrieve the AWB label from any parcel that was in the finalized box, as the AWB label is identical for all parcels included in the box.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwbCopies'
              examples:
                AWBCopiesQuantity:
                  summary: AWB copies quantity
                  value:
                    copy_count: 10
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                      request:
                        type: string
                      message:
                        type: string
              examples:
                CopyLessThanMinimum:
                  summary: Copy count falls short than minimum
                  value:
                    error:
                      code: 400
                      request: api/v2/box/finalize
                      message: 'copy_count: "Ensure this value is greater than or equal to 1."'
                CountExceedsMaximum:
                  summary: Copy count exceeds maximum
                  value:
                    error:
                      code: 400
                      request: api/v2/box/finalize
                      message: 'copy_count: "Ensure this value is less than or equal to 99."'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwbCopies'
components:
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: Basic Authentication using API key and secrets is currently the main authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.
  schemas:
    AwbCopies:
      type: object
      properties:
        copy_count:
          type: integer
          format: int64
          default: 1
          minimum: 1
          maximum: 99
      description: Specify how many AWB copies you need
      title: AWB Copies Object