naftiko: 1.0.0-alpha2
info:
  label: Pitney Bowes Shipping API
  description: The Pitney Bowes Shipping API enables businesses to integrate shipping, rating, tracking, address validation,
    manifesting, and pickup operations directly into their applications. Authentication uses OAuth 2.0 client credentials.
  tags:
  - Pitney
  - Bowes
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: pitney-bowes
    baseUri: https://shipping-api.pitneybowes.com
    description: Pitney Bowes Shipping API HTTP API.
    authentication:
      type: basic
      username: '{{PITNEY_BOWES_USERNAME}}'
      password: '{{PITNEY_BOWES_PASSWORD}}'
    resources:
    - name: oauth-token
      path: /oauth/token
      operations:
      - name: getoauthtoken
        method: POST
        description: Get OAuth access token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-rates
      path: /shippingservices/v1/rates
      operations:
      - name: rateparcel
        method: POST
        description: Rate a parcel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-shipments
      path: /shippingservices/v1/shipments
      operations:
      - name: createshipment
        method: POST
        description: Create a shipment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-shipments-shipmentid
      path: /shippingservices/v1/shipments/{shipmentId}
      operations:
      - name: reprintshipment
        method: GET
        description: Reprint a shipment label
        inputParameters:
        - name: shipmentId
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: voidshipment
        method: DELETE
        description: Void a shipment
        inputParameters:
        - name: shipmentId
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-manifests
      path: /shippingservices/v1/manifests
      operations:
      - name: createmanifest
        method: POST
        description: Create a manifest
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-tracking-trackingnumber
      path: /shippingservices/v1/tracking/{trackingNumber}
      operations:
      - name: trackparcel
        method: GET
        description: Track a parcel
        inputParameters:
        - name: trackingNumber
          in: path
          type: string
          required: true
        - name: carrier
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-addresses-verify
      path: /shippingservices/v1/addresses/verify
      operations:
      - name: verifyaddress
        method: POST
        description: Validate and suggest addresses
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-pickups
      path: /shippingservices/v1/pickups
      operations:
      - name: schedulepickup
        method: POST
        description: Schedule a pickup
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-pickups-pickupid
      path: /shippingservices/v1/pickups/{pickupId}
      operations:
      - name: cancelpickup
        method: DELETE
        description: Cancel a pickup
        inputParameters:
        - name: pickupId
          in: path
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shippingservices-v1-ledger-transactions-reports
      path: /shippingservices/v1/ledger/transactions/reports
      operations:
      - name: gettransactionreport
        method: GET
        description: Retrieve transaction report
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: pitney-bowes-rest
    description: REST adapter for Pitney Bowes Shipping API.
    resources:
    - path: /oauth/token
      name: getoauthtoken
      operations:
      - method: POST
        name: getoauthtoken
        description: Get OAuth access token
        call: pitney-bowes.getoauthtoken
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/rates
      name: rateparcel
      operations:
      - method: POST
        name: rateparcel
        description: Rate a parcel
        call: pitney-bowes.rateparcel
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/shipments
      name: createshipment
      operations:
      - method: POST
        name: createshipment
        description: Create a shipment
        call: pitney-bowes.createshipment
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/shipments/{shipmentId}
      name: reprintshipment
      operations:
      - method: GET
        name: reprintshipment
        description: Reprint a shipment label
        call: pitney-bowes.reprintshipment
        with:
          shipmentId: rest.shipmentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/shipments/{shipmentId}
      name: voidshipment
      operations:
      - method: DELETE
        name: voidshipment
        description: Void a shipment
        call: pitney-bowes.voidshipment
        with:
          shipmentId: rest.shipmentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/manifests
      name: createmanifest
      operations:
      - method: POST
        name: createmanifest
        description: Create a manifest
        call: pitney-bowes.createmanifest
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/tracking/{trackingNumber}
      name: trackparcel
      operations:
      - method: GET
        name: trackparcel
        description: Track a parcel
        call: pitney-bowes.trackparcel
        with:
          trackingNumber: rest.trackingNumber
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/addresses/verify
      name: verifyaddress
      operations:
      - method: POST
        name: verifyaddress
        description: Validate and suggest addresses
        call: pitney-bowes.verifyaddress
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/pickups
      name: schedulepickup
      operations:
      - method: POST
        name: schedulepickup
        description: Schedule a pickup
        call: pitney-bowes.schedulepickup
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/pickups/{pickupId}
      name: cancelpickup
      operations:
      - method: DELETE
        name: cancelpickup
        description: Cancel a pickup
        call: pitney-bowes.cancelpickup
        with:
          pickupId: rest.pickupId
        outputParameters:
        - type: object
          mapping: $.
    - path: /shippingservices/v1/ledger/transactions/reports
      name: gettransactionreport
      operations:
      - method: GET
        name: gettransactionreport
        description: Retrieve transaction report
        call: pitney-bowes.gettransactionreport
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: pitney-bowes-mcp
    transport: http
    description: MCP adapter for Pitney Bowes Shipping API for AI agent use.
    tools:
    - name: getoauthtoken
      description: Get OAuth access token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.getoauthtoken
      outputParameters:
      - type: object
        mapping: $.
    - name: rateparcel
      description: Rate a parcel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.rateparcel
      outputParameters:
      - type: object
        mapping: $.
    - name: createshipment
      description: Create a shipment
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.createshipment
      outputParameters:
      - type: object
        mapping: $.
    - name: reprintshipment
      description: Reprint a shipment label
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: pitney-bowes.reprintshipment
      with:
        shipmentId: tools.shipmentId
      inputParameters:
      - name: shipmentId
        type: string
        description: shipmentId
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: voidshipment
      description: Void a shipment
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: pitney-bowes.voidshipment
      with:
        shipmentId: tools.shipmentId
      inputParameters:
      - name: shipmentId
        type: string
        description: shipmentId
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: createmanifest
      description: Create a manifest
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.createmanifest
      outputParameters:
      - type: object
        mapping: $.
    - name: trackparcel
      description: Track a parcel
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: pitney-bowes.trackparcel
      with:
        trackingNumber: tools.trackingNumber
        carrier: tools.carrier
      inputParameters:
      - name: trackingNumber
        type: string
        description: trackingNumber
        required: true
      - name: carrier
        type: string
        description: carrier
      outputParameters:
      - type: object
        mapping: $.
    - name: verifyaddress
      description: Validate and suggest addresses
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.verifyaddress
      outputParameters:
      - type: object
        mapping: $.
    - name: schedulepickup
      description: Schedule a pickup
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: pitney-bowes.schedulepickup
      outputParameters:
      - type: object
        mapping: $.
    - name: cancelpickup
      description: Cancel a pickup
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: pitney-bowes.cancelpickup
      with:
        pickupId: tools.pickupId
      inputParameters:
      - name: pickupId
        type: string
        description: pickupId
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: gettransactionreport
      description: Retrieve transaction report
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: pitney-bowes.gettransactionreport
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    PITNEY_BOWES_USERNAME: PITNEY_BOWES_USERNAME
    PITNEY_BOWES_PASSWORD: PITNEY_BOWES_PASSWORD