openapi: 3.1.0
info:
  title: Portbase Port Community System CargoManifests API
  description: Portbase is the Dutch Port Community System providing APIs for customs declarations, cargo manifests, vessel call notifications, berth planning, and port logistics coordination at the Port of Rotterdam and Amsterdam, connecting shipping lines, freight forwarders, customs authorities, and terminal operators.
  version: 1.0.0
  contact:
    name: Portbase Support
    url: https://www.portbase.com/en/contact/
  license:
    name: Portbase Terms of Service
    url: https://www.portbase.com/en/about-portbase/terms-and-conditions/
servers:
- url: https://api.portbase.com/v1
  description: Portbase Production API
security:
- oauth2: []
tags:
- name: CargoManifests
  description: Cargo manifest declarations
paths:
  /cargo-manifests:
    post:
      operationId: submitCargoManifest
      summary: Submit cargo manifest
      description: Submits a cargo manifest declaration for a vessel call, listing all cargo on board.
      tags:
      - CargoManifests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CargoManifestCreate'
      responses:
        '201':
          description: Manifest submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CargoManifest'
        '400':
          $ref: '#/components/responses/BadRequest'
  /cargo-manifests/{manifestId}:
    get:
      operationId: getCargoManifest
      summary: Get cargo manifest
      description: Returns a cargo manifest with all cargo lines and customs status.
      tags:
      - CargoManifests
      parameters:
      - name: manifestId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cargo manifest details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CargoManifest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CargoManifestLine:
      type: object
      properties:
        lineNumber:
          type: integer
        containerNumber:
          type: string
        billOfLadingNumber:
          type: string
        cargoDescription:
          type: string
        hsCode:
          type: string
          description: HS tariff code (6 digits)
        grossWeight:
          type: number
          format: double
        grossWeightUnit:
          type: string
          enum:
          - KG
          - MT
        packageCount:
          type: integer
        packageType:
          type: string
        portOfLoading:
          type: string
          description: UN/LOCODE of port of loading
        portOfDischarge:
          type: string
          description: UN/LOCODE of port of discharge
        shipper:
          type: string
        consignee:
          type: string
    CargoManifestCreate:
      type: object
      required:
      - vesselCallId
      - declarantId
      - lines
      properties:
        vesselCallId:
          type: string
        declarantId:
          type: string
        lines:
          type: array
          items:
            $ref: '#/components/schemas/CargoManifestLine'
    CargoManifest:
      type: object
      properties:
        manifestId:
          type: string
        vesselCallId:
          type: string
        declarantId:
          type: string
          description: EORI number of the declarant
        submissionDatetime:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - DRAFT
          - SUBMITTED
          - ACCEPTED
          - REJECTED
          - RELEASED
        lines:
          type: array
          items:
            $ref: '#/components/schemas/CargoManifestLine'
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.portbase.com/oauth2/token
          scopes:
            vessel-calls.read: Read vessel call data
            vessel-calls.write: Submit and update vessel calls
            manifests.write: Submit cargo manifests
            customs.write: Submit customs declarations