openapi: 3.0.1
info:
  title: Bulksplit API
  version: '1.0'
servers:
  - url: https://api.bring.com/bulksplit/v1

security:
  - mybringApiUid: []
    mybringApiKey: []

paths:
  /bulk-shipment-ids:
    post:
      summary: Reserve a bulk shipment id
      parameters:
        - in: header
          name: X-Bring-Test-Indicator
          schema:
            type: string
          required: false
          description: >
            No effect on this endpoint at the current time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReserveBulkShipmentIdRequestDto'
            examples:
              this:
                summary: Reserve bulk shipment id
                value:
                  customerNumber: 1234567890
                  senderParty:
                    name: Bulky Sender
                    addressLine1: Sender street 42
                    postalCode: 1234
                    city: Copenhagen
                    countryCode: DK
                  terminalId: NO_OSLO_4

      responses:
        '201':
          description: Successfully reserved a bulk shipment ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReserveBulkShipmentIdResponseDto'
              examples:
                this:
                  summary: Success
                  value:
                    bulkShipmentId: CS059102945NO

  /bulk-shipments/{bulk-shipment-id}/routing-labels:
    post:
      summary: Reserve a routing label id and produce label
      parameters:
        - in: path
          name: bulk-shipment-id
          schema:
            type: string
          required: true
          description: Bulk shipment ID
        - in: header
          name: X-Bring-Test-Indicator
          schema:
            type: string
          required: false
          description: >
            No effect on this endpoint at the current time.

      responses:
        '201':
          description: Successfully reserved a routing number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReserveRoutingIdResponseDto'
              examples:
                this:
                  summary: Success
                  value:
                    bulkShipmentId: CS059102945NO
                    routingNumber: CS128103952NO
                    routingLabelUrl: https://api.bring.com/labels/id/6eaeab58-da7e-4ce4-a1ce-b07607245e07.pdf

  /bulk-shipments/{bulk-shipment-id}:
    post:
      summary: Register bulk shipment for reserved shipment-id
      parameters:
        - in: path
          name: bulk-shipment-id
          schema:
            type: string
          required: true
          description: Bulk shipment ID
        - in: header
          name: X-Bring-Test-Indicator
          schema:
            type: string
          required: false
          description: >
            If set to "true" indicates that this request is a test, otherwise the request is treated as real. If set all
            validations will be performed and labels will be generated but the booking will not be sent to the
            underlying systems.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterBulkShipmentRequestDto'
            examples:
              onlyRequired:
                summary: Only required fields
                value:
                  shippingDateTime: 2025-10-10T13:00:00+02:00
                  pallets:
                    - totalWeightKg: 200
                      palletType: EUR_PALLETS
                      services:
                        - "0342"
                        - "0345"
              withRoutingNumber:
                summary: With routing number
                value:
                  shippingDateTime: 2025-10-10T13:00:00+02:00
                  pallets:
                    - routingNumber: CS128103952NO
                      totalWeightKg: 200
                      palletType: EUR_PALLETS
                      services:
                        - "0342"
                        - "0345"
              allFields:
                summary: All fields
                value:
                  shippingDateTime: 2025-10-10T13:00:00+02:00
                  waybillType: NONE
                  routingLabelsType: NONE
                  pallets:
                    - routingNumber: CS128103952NO
                      totalWeightKg: 200
                      palletType: EUR_PALLETS
                      services:
                        - "0342"
                        - "0345"
                  customsDocuments:
                    numInvoices: 3
                    numExportNotifications: 3
                    numEurCertifications: 2
      responses:
        '200':
          description: Successfully booked bulk shipment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterBulkShipmentResponseDto'
              examples:
                success:
                  summary: Success
                  value:
                    bulkShipmentId: CS059102945NO
                    waybillUrl: https://api.bring.com/labels/id/c1c65ccc-99fe-4aad-90a3-08546d99e3b8.pdf
                    routingLabelsUrl: https://api.bring.com/labels/id/6eaeab58-da7e-4ce4-a1ce-b07607245e07.pdf

  /terminals:
    get:
      summary: List available terminals
      responses:
        '200':
          description: Successfully list all terminals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTerminalsResponseDto'
              examples:
                allTerminals:
                  summary: All terminals
                  value:
                    terminals:
                      - id: NO_OSLO_4
                        name: Logistikksenter Oslo
                        addressLine1: Alfasetvegen 24
                        addressLine2:
                        postalCode: 0024
                        city: Oslo
                        countryCode: "NO"
                      - id: SE_JONKOPING_24
                        name: Bring
                        addressLine1: Södra Stigamovägen 9A
                        addressLine2:
                        postalCode: 55650
                        city: Jönköping
                        countryCode: SE

components:
  securitySchemes:
    mybringApiUid:
      type: apiKey
      in: header
      name: X-MyBring-API-Uid
    mybringApiKey:
      type: apiKey
      in: header
      name: X-MyBring-API-Key
  schemas:
    ReserveBulkShipmentIdRequestDto:
      type: object
      properties:
        customerNumber:
          type: string
          description: Customer number
        senderParty:
          $ref: '#/components/schemas/SenderPartyDto'
        terminalId:
          type: string
          description: Recipient terminal ID
      required:
        - customerNumber
        - senderParty
        - terminalId

    ReserveBulkShipmentIdResponseDto:
      type: object
      properties:
        bulkShipmentId:
          type: string
          description: Reserved bulk shipment ID
      required:
        - bulkShipmentId

    ReserveRoutingIdResponseDto:
      type: object
      properties:
        bulkShipmentId:
          type: string
          description: Reserved bulk shipment ID
        routingLabelId:
          type: string
          description: The routing number represented on the label
        routingLabelUrl:
          type: string
          format: uri
          description: URL to the routing label
      required:
        - bulkShipmentId
        - routingLabelId
        - routingLabelUrl

    RegisterBulkShipmentRequestDto:
      type: object
      properties:
        shippingDateTime:
          type: string
          format: date-time
          description: Scheduled pickup date
        waybillType:
          type: string
          description: Type of waybill to produce for the shipment. CMR or NONE, defaults to CMR.
        routingLabelsType:
          type: string
          description: Indication of whether to produce routing labels at this time or not. ROUTING or NONE, defaults to ROUTING.
        customsDocuments:
          $ref: '#/components/schemas/CustomsDocumentsDto'
        pallets:
          type: array
          items:
            $ref: '#/components/schemas/RegisterBulkShipmentPalletRequestDto'
      required:
        - shippingDateTime
        - pallets

    RegisterBulkShipmentResponseDto:
      type: object
      properties:
        bulkShipmentId:
          type: string
          description: Bulk shipment ID
        waybillUrl:
          type: string
          format: uri
          description: URL to the waybill document
        routingLabelsUrl:
          type: string
          format: uri
          description: URL to the routing labels
      required:
        - bulkShipmentId

    CustomsDocumentsDto:
      description: Required if shipment is crossing customs border
      type: object
      properties:
        numInvoices:
          type: integer
          description: Number of invoices
        numExportNotifications:
          type: integer
          description: Number of export notifications
        numEurCertificates:
          type: integer
          description: Number of EUR certificates
      required:
        - numInvoices
        - numExportNotifications
        - numEurCertificates

    SenderPartyDto:
      type: object
      description: Required if not using pre-reserved shipment number
      properties:
        name:
          type: string
          description: Sender's name
        addressLine1:
          type: string
          description: Sender's address line 1
        addressLine2:
          type: string
          description: Sender's address line 2
          nullable: true
        postalCode:
          type: string
          description: Sender's postal code
        city:
          type: string
          description: Sender's city
        countryCode:
          type: string
          description: Sender's country code
        senderReference:
          type: string
          description: Sender's reference
          nullable: true
      required:
        - name
        - addressLine1
        - postalCode
        - city
        - countryCode

    RegisterBulkShipmentPalletRequestDto:
      type: object
      properties:
        routingNumber:
          type: string
          description: Routing number of the pallet
        totalWeightKg:
          type: integer
          description: Total weight of the pallet in kilograms
        palletType:
          type: string
          description: Type of pallet
        services:
          type: array
          items:
            type: string
          description: List of services
      required:
        - totalWeightKg
        - palletType
        - services

    ListTerminalsResponseDto:
      type: object
      properties:
        terminals:
          type: array
          items:
            $ref: '#/components/schemas/TerminalDto'
      required:
        - terminals

    TerminalDto:
      type: object
      properties:
        id:
          type: string
          description: Terminal Id for use when registering bulk shipment
        name:
          type: string
          description: Name of the terminal
        addressLine1:
          type: string
          description: First address line of the terminal
        addressLine2:
          type: string
          description: Second address line of the terminal
        postalCode:
          type: string
          description: Terminal post code
        city:
          type: string
          description: Terminal city
        countryCode:
          type: string
          description: Terminal country
      required:
        - id
        - name
        - addressLine1
        - addressLine2
        - postalCode
        - city
        - countryCode
