openapi: 3.2.0
info:
  description: The body fields to generate the labels.
  title: Labeler Generate labels API
  version: 3.0.0
servers:
- url: https://api.paack.io/v3
  description: Production environment
- url: https://api.staging.paack.io/v3
  description: Staging environment
security:
- Bearer: []
tags:
- name: Generate labels
paths:
  /labels:
    post:
      description: 'Generates labels for an order.


        The body of the call to the Labeler API uses a structured JSON format with mandatory and optional fields. The JSON must be properly structured to be accepted and mandatory fields must be populated. Each property in the request has a specific data type for the value; all values must conform to the required data type.


        The number of generated PDF labels depends on the number of objects in the `parcels` array. `barcode` identifies a label and is the only required field within the object.'
      operationId: CreateLabelRequestPDF
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLabelRequestJson'
            example:
              customer:
                first_name: Martín
                last_name: Fierro
              delivery_address:
                city: Barcelona
                country: ES
                line1: Via Augusta
                line2: 17, Principal
                post_code: 08006
              expected_delivery_ts:
                start:
                  date: '2022-04-28'
                  time: '10:00:00'
              order_details: null
              external_id: 5cef0f5-1a0-44-b0f-96faa0
              parcels:
              - barcode: 034724878233029420
                height: 28.2
                length: 38.1
                width: 48.3
                weight: 12.1
              - barcode: 034724878233029499
                height: 19
                length: 12.33
                width: 33.1
                weight: 18.3
              - barcode: 034724878233029437
                height: 18.5
                length: 9.3
                width: 13.33
                weight: 2.5
              pick_up_address:
                city: Barcelona
                country: ES
                line1: Avinguda Diagonal, 1234
                line2: null
                post_code: 08021
              service_type: NT4
        description: Request to generate labels (for PDF, as many labels as objects in the parcels[] array; for ZPL, first parcel in the parcels[] array or parcel indicated by the parcel_number value).
      responses:
        '200':
          $ref: '#/components/responses/Response200'
        '206':
          $ref: '#/components/responses/Response206'
        '400':
          $ref: '#/components/responses/Response400'
        '401':
          $ref: '#/components/responses/Response401'
      tags:
      - Generate labels
      summary: Create label request PDF
      x-summary-source: derived
components:
  responses:
    Response206:
      content:
        '*/*':
          schema:
            properties: {}
            type: object
          example: See Labeler API > Examples.
      description: 'In case of an `HTTP 206` response, the Labeler API returns partial content, in the format specified in the `template_id` field of the request body. This occurs due to exceeding the character field length or due to unsupported characters.<br /><br />- Response body: The label in the specified format is returned but the displayed information is incomplete: names can be truncated and unsupported characters converted into question marks (``?``).<br /><br />'
    Response200:
      content:
        '*/*':
          schema:
            properties: {}
            type: object
          example: See Labeler API > Examples.
      description: In case of an `HTTP 200` response, the Labeler API returns the file in the format specified in the `template_id` field in the request body. The default file format is PDF.
    Response401:
      content:
        application/json:
          schema:
            properties:
              code:
                description: HTTP response code.
                type: number
                enum:
                - 401
              message:
                description: Error details.
                type: string
                enum:
                - Jwt is missing
                - Jwt is expired
            type: object
          example:
            code: 401
            message: Jwt is missing
      description: Communicates a missing or expired access token for authorization.
    Response400:
      content:
        text/plain:
          schema:
            properties:
              error:
                $ref: '#/components/schemas/ErrorSchema'
            type: object
          example:
            error:
              code: SYS001
              message: 'field delivery_address: required'
      description: If the information you provided is invalid, the HTTP code of the response is 400. For instance, you didn't use the specified data type or missed required fields.<br />- Response body as described here.<br /><br />Learn more in Labeler API > Troubleshooting.
  schemas:
    WindowObject:
      description: Contains the objects `start` and `end` indicating the order delivery's timeslot.
      properties:
        end:
          $ref: '#/components/schemas/WindowDatetime'
        start:
          $ref: '#/components/schemas/WindowDatetime'
      required:
      - start
      - end
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJsonTemplateId:
      description: Defines the format of the label. `1` is for a single ZPL label, `2` is for printing multiple ZPL labels at once; `null` or  missing property returns a PDF.
      enum:
      - 1
      type: integer
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJsonCustomer:
      description: 'Contains the properties `first_name` and `last_name`.


        **PDF Display limits**:

        * `first_name` and `last_name` combined can take up to 45 characters (2 graphic lines).

        * A max. of approx. 23 characters can be displayed for `last_name`.


        **ZPL Display limits**:

        * `first_name` and `last_name` combined can take up to 29 characters (1 graphic line).

        * A max. of approx. 23 characters can be displayed for `last_name`.

        '
      properties:
        first_name:
          description: Specifies your customer's first name.
          maxLength: 45
          minLength: 1
          type: string
          x-go-name: FirstName
        last_name:
          description: Specifies your customer's last name.
          maxLength: 23
          type: string
          x-go-name: LastName
      required:
      - first_name
      - last_name
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    AddressDelivery:
      description: 'Specifies the address of the delivery.


        **Display limits**:

        * `city` can take up to 58 characters.

        * A max. of approx. 60 characters (2 graphic lines) can be displayed for `line1` and `line2` combined.

        * A max. of approx. 30 characters can be displayed for `line2`.'
      properties:
        city:
          description: Specifies the city.
          maxLength: 58
          minLength: 1
          type: string
          x-go-name: City
        country:
          description: Specifies, in ISO 3166 alpha 2 format, the country.
          maxLength: 2
          minLength: 2
          type: string
          x-go-name: Country
        line1:
          description: Specifies the primary address.
          maxLength: 60
          minLength: 1
          type: string
          x-go-name: Line1
        line2:
          description: Specifies additional address information.
          maxLength: 30
          type: string
          x-go-name: Line2
        post_code:
          description: Specifies the ZIP code.
          maxLength: 10
          minLength: 4
          type: string
          x-go-name: PostCode
      required:
      - city
      - country
      - line1
      - post_code
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJson:
      properties:
        customer:
          $ref: '#/components/schemas/CreateLabelRequestJsonCustomer'
        delivery_address:
          $ref: '#/components/schemas/AddressDelivery'
        delivery_type:
          description: 'Identifies a direct of reverse order. Example: reverse.'
          type: string
        expected_delivery_ts:
          $ref: '#/components/schemas/WindowObject'
        external_id:
          description: Uniquely identifies the order within the retailer.
          maxLength: 30
          minLength: 1
          type: string
          x-go-name: ExternalId
        order_details:
          description: Specifies custom information on the order.
          items:
            $ref: '#/components/schemas/CreateLabelRequestJsonOrderDetails'
          type: array
        parcel_number:
          $ref: '#/components/schemas/CreateLabelRequestJsonParcelNumber'
        parcels:
          description: 'Defines the parcels included in the order. Each object included in this array corresponds to one parcel identified by its barcode.


            **Display limits**:

            * The dimensions are not displayed if all three values are 0.'
          items:
            $ref: '#/components/schemas/CreateLabelRequestJsonParcelsElem'
          type: array
          x-go-name: Parcels
        pick_up_address:
          $ref: '#/components/schemas/AddressPickup'
        retailer_name:
          description: 'Specifies the retailer name.


            **Display limits**:

            * `retailer_name` can take up to 60 characters.'
          maxLength: 60
          minLength: 1
          type: string
        service_type:
          description: Defines the code that identifies the delivery day type, timeslot type, and available slot length.
          type: string
          enum:
          - ST2
          - ST4
          - STZ
          - SF2
          - SF4
          - SFZ
          - NT2
          - NT4
          - NTH
          - NTZ
          - NF2
          - NF4
          - NFA
          - XF4
          - NFZ
          - PT2
          - PT4
          - PTH
          - PTA
          - PTZ
          - PF2
          - PF4
          - PFA
          - PFZ
          - CT2
          - CT4
          - CTH
          - CTZ
          - XFZ
          - CF2
          - CF4
          - CFA
          - CFZ
          - WT2
          - WT4
          - WTH
          - WTZ
          - WF2
          - WF4
          - WFA
          - WFZ
          - XTZ
          - XF2
          - ST3
          - DDD
          - ND
          - SD
          - UNK
          - RFA
          - RT2
          - RT4
        template_id:
          $ref: '#/components/schemas/CreateLabelRequestJsonTemplateId'
      required:
      - customer
      - delivery_address
      - expected_delivery_ts
      - external_id
      - parcels
      - service_type
      title: Defines the request to generate labels.
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJsonOrderDetails:
      description: 'Contains the properties `name`, `type`, and `value`. Specifies custom information on the order. In case of `"name": "sale_number"` and `"type": "string"`, the `value` appears on the label instead of the `external_id`.'
      properties:
        name:
          default: sale_number
          description: Specifies the name of the custom field.
          minLength: 1
          type: string
        type:
          description: Specifies the type of the custom field.
          enum:
          - string
          - currency
          - country
          - number
          - boolean
          - uuid
          - uri
          - date
          - time
          - object
          - array
          - null
          minLength: 1
          type: string
        value:
          default: ''
          description: Specifies the value of the custom field.
          type: string
      required:
      - name
      - type
      - value
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    ErrorSchema:
      description: Contains the properties `code` and `message`.
      properties:
        code:
          description: Error code.
          type: string
          enum:
          - SYS001
        message:
          description: Error details.
          type: string
      type: object
    WindowDatetime:
      description: Contains the properties `date` and `time`.
      properties:
        date:
          description: Specifies the date in `YYYY-MM-DD` format.
          maxLength: 10
          minLength: 10
          type: string
          x-go-name: Date
        time:
          description: Specifies the UTC time in `hh:mm:ss` format.
          maxLength: 8
          minLength: 8
          type: string
          x-go-name: Time
      required:
      - date
      - time
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    AddressPickup:
      description: 'Specifies the pickup address.


        **Display limits**:

        * `city` can take up to 43 characters.

        * A max. of approx. 43 characters (2 graphic lines) can be displayed for `line1` and `line2` combined.

        * A max. of approx. 22 characters can be displayed for `line2`.'
      properties:
        city:
          description: Specifies the city.
          maxLength: 43
          minLength: 1
          type: string
          x-go-name: City
        country:
          description: Specifies, in ISO 3166 alpha 2 format, the country.
          maxLength: 2
          minLength: 2
          type: string
          x-go-name: Country
        line1:
          description: Specifies the primary address.
          maxLength: 43
          minLength: 1
          type: string
          x-go-name: Line1
        line2:
          description: Specifies additional address information.
          maxLength: 22
          type: string
          x-go-name: Line2
        post_code:
          description: Specifies the ZIP code.
          maxLength: 10
          minLength: 4
          type: string
          x-go-name: PostCode
      required:
      - city
      - country
      - line1
      - post_code
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJsonParcelsElem:
      description: 'Defines the parcels included in the order. Each object included in this array corresponds to one parcel identified by its `barcode`.


        **Display limits**:

        * The dimensions are not displayed if all three values are 0.'
      properties:
        barcode:
          description: Identifies the parcel. For ZPL labels, the maximum number of permitted characters is 25. For PDF labels, the maximum number of permitted characters is 33.
          maxLength: 33
          minLength: 1
          type: string
          x-go-name: Barcode
        height:
          description: Specifies the parcel's height in cm.
          format: double
          minimum: 0
          type: number
          x-go-name: Height
        length:
          description: Specifies the parcel's length in cm.
          format: double
          minimum: 0
          type: number
          x-go-name: Length
        weight:
          description: Specifies the parcel's weight in kg.
          format: double
          maximum: 30
          minimum: 0
          type: number
          x-go-name: Weight
        sku:
          description: Specifies the retailer barcode.
          format: string
          minimum: 0
          maximum: 33
          type: string
        width:
          description: Specifies the parcel's width in cm.
          format: double
          minimum: 0
          type: number
          x-go-name: Width
      required:
      - barcode
      type: object
      x-go-package: github.com/PaackEng/lms-backend/infra/http
    CreateLabelRequestJsonParcelNumber:
      description: For ZPL labels, (`template_id` = `1` or `template_id` = `2`), specifies either the first parcel or all parcels from the `parcels[]` array to return. For PDF labels, all parcels from the `parcels[]` array are returned in the response.
      type: integer
      x-go-package: github.com/PaackEng/lms-backend/infra/http
  securitySchemes:
    Bearer:
      in: header
      name: Authorization
      type: apiKey
x-provenance:
  method: searched
  source: https://paack.readme.io/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://paack.readme.io/reference/labels.md
  merge:
    pages: 1
    deduped: 0
    conflicts_kept_first: 0