openapi: 3.1.0
info:
  title: API Reference
  description: Comprehensive reference for integrating with CargoSprint API endpoints
  version: 0.0.1
  termsOfService: https://cargosprint.com/legal/terms-of-use/sprintpay/
  contact:
    email: support@cargosprint.com
    url: https://cargosprint.com/contact-us/
servers:
  - url: https://{service}-{environment}.cargosprintgroup.com
    variables:
      environment:
        default: ''
        description: application environment (empty for prod)
        enum:
          - staging
          - development
          - (empty for production)
      service:
        default: ''
        description: service host name
        enum:
          - oauth
          - cart
          - invoices
          - facilities
          - payments
paths:
  /oauth2/token:
    post:
      summary: Get authorization token
      description: Get client authorization token for access to backend APIs.
      operationId: getAuthorizationToken
      tags:
        - Oauth
      parameters:
        - $ref: '#/components/parameters/grant_type'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAuthorizationTokenResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/GetAuthorizationTokenResponseExample'
        '400':
          $ref: '#/components/responses/GetAuthorizationBadRequest'
        '401':
          description: Unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/UnauthorizedResponseExample'
  /facilities:
    get:
      summary: Get all facilities
      description: Get facilities by query.
      operationId: getFacilities
      tags:
        - Facilities
      parameters:
        - $ref: '#/components/parameters/x-app-id'
        - $ref: '#/components/parameters/name'
        - $ref: '#/components/parameters/firmsCode'
        - $ref: '#/components/parameters/airportCode'
        - $ref: '#/components/parameters/airlinePrefix'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilitiesResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/GetFacilitiesResponseExample'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/GetFacilitiesBadRequest'
        '401':
          description: Unauthorized.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GenericErrorResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/UnauthorizedResponseExample'
  /payment:
    post:
      summary: Make payment
      description: Make a payment to a facility.
      operationId: makePayment
      tags:
        - Cart
      parameters:
        - $ref: '#/components/parameters/x-app-id'
        - $ref: '#/components/parameters/name'
        - $ref: '#/components/parameters/firmsCode'
        - $ref: '#/components/parameters/airportCode'
        - $ref: '#/components/parameters/airlinePrefix'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/makePaymentRequest'
            examples:
              general_entry:
                $ref: '#/components/examples/makePaymentExample'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFacilitiesResponse'
              examples:
                default_example:
                  $ref: '#/components/examples/GetFacilitiesResponseExample'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/GetFacilitiesBadRequest'
  /external/paymentConfirmation:
    post:
      summary: Get payment confirmation
      description: Download payment confirmation document.
      operationId: getPaymentConfirmation
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/x-app-id'
        - $ref: '#/components/parameters/confirmationId'
      responses:
        '200':
          description: Success.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/GetPaymentConfirmationBadRequest'
        '401':
          $ref: '#/components/responses/GetPaymentConfirmationUnauthorized'
  /external/downloadInvoices:
    post:
      summary: Get invoices
      description: Download invoices.
      operationId: getInvoices
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/x-app-id'
        - $ref: '#/components/parameters/downloadFormat'
        - $ref: '#/components/parameters/confirmationId'
      responses:
        '200':
          description: Success.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/GetInvoicesBadRequest'
        '401':
          $ref: '#/components/responses/GetInvoicesUnauthorized'
components:
  parameters:
    x-app-id:
      name: x-app-id
      in: header
      description: Encoded customer identifier.
      schema:
        type: string
        example: 2ZMEEX2otslHtRRgzQC0tPVwbasC23455vx0k=
    grant_type:
      name: grant_type
      in: query
      description: Method of authorization. Defaults to client_credentials.
      schema:
        type: string
        example: client_credentials
    confirmationId:
      name: confirmationId
      in: query
      description: Payment confirmation id.
      schema:
        type: string
        example: kevsdkxb
    downloadFormat:
      name: downloadFormat
      in: query
      description: Format to download in (e.g. PDF, XLSX).
      schema:
        type: string
        example: XLSX
    name:
      name: name
      in: query
      description: Facility name. Can be truncated.
      schema:
        type: string
        example: Test Cargo
    firmsCode:
      name: firmsCode
      in: query
      description: Facilities Information and Resources Management System (FIRMS) code.
      schema:
        type: string
        example: L247
    airportCode:
      name: airportCode
      in: query
      description: Facility airport code.
      schema:
        type: string
        example: JFK
    airlinePrefix:
      name: airlinePrefix
      in: query
      description: Three digit prefix that identifies the airline transporting the cargo.
      schema:
        type: string
        example: '871'
  schemas:
    access_token:
      description: Authorization token used to access backend APIs.
      type: string
      example: >-
        eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
    scope:
      description: Roles that the client has access to.
      type: string
      example: api.cart:read
    token_type:
      description: Type of token administered.
      type: string
      example: Bearer
    expires_in:
      description: Token time to live (ttl) in seconds.
      type: integer
      example: 3600
    GetAuthorizationTokenResponse:
      description: Details of a client's authorization token.
      type: object
      properties:
        access_token:
          $ref: '#/components/schemas/access_token'
        scope:
          $ref: '#/components/schemas/scope'
        token_type:
          $ref: '#/components/schemas/token_type'
        expires_in:
          $ref: '#/components/schemas/expires_in'
      required:
        - access_token
        - scope
        - token_type
        - expires_in
    paymentRequestDetail:
      type: object
      properties:
        awb:
          type: string
          description: AWB number
          example: 111-11111111
        hawb:
          type: string
          description: HAWB number
          example: '845448'
        amount:
          type: number
          description: Amount being paid to facility
          example: 3234.12
        customerReference:
          type: string
          description: Customer reference details used by facility
          example: customer reference details
        facility:
          type: object
          description: Details about the facility to associate payment
          properties:
            id:
              type: integer
              description: Facility identifier number
              example: 36
        paymentType:
          type: string
          description: Type of payment being paid for
          enum:
            - Delivery
            - ISC
            - Storage
          example: Delivery
        notificationEmail:
          type: string
          description: User notification email for payment confirmation
          example: test@test.com
    makePaymentRequest:
      description: Payment request details.
      type: array
      items:
        $ref: '#/components/schemas/paymentRequestDetail'
    facilityDetails:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          description: facility name
          example: test facility
        airportCode:
          type: string
          description: facility airport code
          example: ATL
        prefixes:
          type: string
          description: all possible airline prefixes
          example: 160,34
        prefix:
          type: string
          description: selected airline prefix
          example: '34'
        awbFieldType:
          type: string
          example: AWB
        awbFieldLabel:
          type: string
          example: AWB Number
        hawbFieldLabel:
          type: string
          description: Input label for hawb field
          example: 'Add one or more Hawb #'
        addressDTO:
          type: object
          properties:
            addressLine1:
              type: string
              example: 973 Barry Rd, South Building D
            city:
              type: string
              example: Atlanta
            state:
              type: string
              example: GA
            zip:
              type: string
              example: '30320'
    content:
      type: array
      items:
        $ref: '#/components/schemas/facilityDetails'
    sort:
      type: object
      properties:
        unsorted:
          type: boolean
          example: true
        sorted:
          type: boolean
          example: false
        empty:
          type: boolean
          example: true
    pageable:
      type: object
      items:
        properties:
          sort:
            $ref: '#/components/schemas/sort'
          pageSize:
            type: integer
            example: 10
          pageNumber:
            type: integer
            example: 0
          offset:
            type: integer
            example: 0
          paged:
            type: boolean
            example: true
          unpaged:
            type: boolean
            example: false
    Unauthorized:
      description: Unauthorized.
      $ref: '#/components/schemas/GenericErrorResponse'
    GetFacilitiesResponse:
      description: Lists all facilities that fit the query criteria.
      type: object
      properties:
        content:
          $ref: '#/components/schemas/content'
        pageable:
          $ref: '#/components/schemas/pageable'
        totalPages:
          type: integer
          example: 4
        last:
          type: boolean
          example: false
        totalElements:
          type: integer
          example: 37
        first:
          type: boolean
          example: true
        sort:
          $ref: '#/components/schemas/sort'
        numberOfElements:
          type: integer
          example: 10
        size:
          type: integer
          example: 10
        number:
          type: integer
          example: 0
        empty:
          type: boolean
          example: false
    AuthErrorResponse:
      type: object
      properties:
        error_description:
          type: string
          example: 'OAuth 2.0 Parameter: grant_type'
        error:
          type: string
          example: unsupported_grant_type
        error_uri:
          type: string
          example: https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
    GenericErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
            example: An error occured
    EmptyResponse:
      type: object
  examples:
    makePaymentExample:
      summary: Make payment to facility details request example
      value:
        - awb: 111-11111111
          hawb: '342523'
          amount: 326.23
          customerReference: Customer reference details
          facility:
            id: 36
          paymentType: Delivery
          notificationEmail: test@test.com
    GetFacilitiesResponseExample:
      summary: Get facilities' details response example
      value:
        content:
          - id: 1
            name: test facility 1
            airportCode: ATL
            prefixes: 319,34
            prefix: '319'
            awbFieldType: AWB
            awbFieldLabel: AWB Number
            hawbFieldLabel: 'Add one or more Hawb #'
            addressDTO:
              addressLine1: ATL Intl Airport Cargo Bldg 23
              city: Atlanta
              state: GA
              zip: '30320'
          - id: 2
            name: test facility 2
            airportCode: LAX
            prefixes: '320'
            awbFieldType: AWB
            awbFieldLabel: AWB Number
            hawbFieldLabel: 'Add one or more Hawb #'
            addressDTO:
              addressLine1: LAX Intl Airport Cargo Bldg 24
              city: Los Angeles
              state: CA
              zip: '90001'
        pageable:
          sort:
            unsorted: true
            sorted: false
            empty: true
          pageSize: 10
          pageNumber: 0
          offset: 0
          paged: true
          unpaged: false
        totalPages: 4
        last: false
        totalElements: 37
        first: true
        sort:
          unsorted: true
          sorted: false
          empty: true
        numberOfElements: 10
        size: 10
        number: 0
        empty: false
    UnauthorizedResponseExample:
      summary: Unauthorized response example
      value:
        errors:
          - An error occurred while attempting to decode the Jwt
    GetAuthorizationTokenResponseExample:
      summary: Get authorization token response example
      value:
        access_token: >-
          eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        scope: api.cart:read
        token_type: Bearer
        expires_in: 3600
  responses:
    GetAuthorizationBadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/AuthErrorResponse'
    GetFacilitiesBadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    GetInvoicesBadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    GetPaymentConfirmationBadRequest:
      description: Bad request.
    GetPaymentConfirmationUnauthorized:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    GetInvoicesUnauthorized:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    NotFound:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    NoContent:
      description: No content found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/EmptyResponse'
tags:
  - name: Oauth
    description: >
      The SprintPay API uses Authorization Tokens to authenticate requests.
      <br><br>SprintPay’s OAuth system that uses a access token that  is private
      and reserved for specific official partnerships. To get set up with access
      please inquire directly with your SprintPay relationship manager.
      <br><br>This API enables partners to register their own systems or
      authorized third-party systems to be able to execute actions.
  - name: Facilities
    description: >-
      API reference for facilities endpoints and webhooks. <br><br>The
      /get/facilities is an endpoint that allow you to retrieve facilities
      contacts information on file including Facility Name, Airport Code, Firms
      Code, Phone, Address, City and Delivery.
  - name: Cart
    description: >-
      API reference for cart endpoints and webhooks. <br><br>The /post/payments
      is an endpoint that allow you to manage the end user’s cart, initiate and
      process the payments to the facilities.
  - name: Invoices
    description: >-
      API reference for invoices endpoints and webhooks. <br><br>The
      /post/external/downloadinvoices is an endpoint that allow you to retrieve
      and manage open and paid invoices. This will be retrieved as an Excel file
      with information such as Cargo Payment Created Date, Email, Airport Code, 
      Cargo Payment&#58; Payment Reference &#35;, Cargo Facility&#58; Airline
      Cargo Facility Name, Airline AWB &#35;, Customer Reference &#35;, Cargo
      Payment&#58; Amount and Total Invoice Amount.
  - name: Payments
    description: >-
      API reference for payments endpoints and webhooks. <br><br>The
      /post/external/paymentConfirmation is an endpoint that allows you to
      retrieve and manage electronic payment confirmations. This will be
      retrieved as a PDF file or a ZIP with multiple PDF files containing
      information such as Cargo Payment Created Date, Email, Facility Branch, 
      Cargo Payment&#58; Payment Reference &#35;, Cargo Facility&#58; Airline
      Cargo Facility Name, Airline AWB &#35;, Customer Reference &#35;, Cargo
      Payment&#58; Amount and Total Invoice Amount.
security:
  - MuseumPlaceholderAuth: []
