NMFTA Invoice Management API

openapi: 3.2.0
info:
  title: Invoice & Document Invoice Management API
  version: 1.0.0-public-preview
  contact:
    name: DSDC APIs Full Truckload
    url: https://github.com/dsdcapis/full-truckload
  license:
    name: DSDC Repository License
    url: https://github.com/dsdcapis/full-truckload/blob/main/LICENSE.md
  description: '# Overview


    NMFTA is on a journey with logistical and banking institutions to transform the electronic transfer of invoice data and supporting documents through an open-source API.'
tags:
- name: Invoice Management
  description: Endpoints for creating, retrieving, and managing invoices.
paths:
  /invoices:
    post:
      operationId: createInvoice
      summary: Create an Invoice
      description: '## Request

        As a Carrier, I want to Create an Invoice and send shipment information for a particular

        Shipper or 3rd Party.

        - In a request, the Carrier MUST provide a shipmentID provided by the Shipper or

        3rd Party participant.

        - LTL Consideration: Pro Number may be valid for proper tracking to the

        BOL generation process.

        - In a request, the Carrier MUST identify themselves, so the Shipper/3rd Party is

        aware of who is sending the Invoice information

        - Types of universal identifiers: DOT Number or MC number.

        - In a request, the Carrier MUST designate the Invoice Number to properly record

        the instance of payment for the Shipper/3rd party.

        - In a request, the Carrier MUST designate a Date associated with their shipment

        so that proper payment intervals are followed to by the Shipper/3rd party.

        - In a request, the Carrier MUST specify an amount for proper payment tracking

        and agreed upon terms specified in the tender.


        ## Response

        - In a response, NMFTA MUST provide a response for successful or failure

        to transfer identification and values.

        - In a response, the Shipper/3rd Party MUST provide an acceptance or

        failure of transfer.'
      tags:
      - Invoice Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./schemas/schemas.yaml#/components/schemas/Invoice
      responses:
        '200':
          description: Invoice created successfully.
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/SuccessMessage
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: listInvoices
      summary: List Invoices
      description: 'As a Carrier, I want to list all Invoices.

        - The request MAY include optional query parameters to filter the results, such as

        unique ID, shipment ID, DOT Number, MC Number, or invoice number.

        - All query parameters are optional and can be used individually or in combination to filter results.'
      tags:
      - Invoice Management
      parameters:
      - name: uniqueID
        in: query
        description: Unique identifier for the invoice.
        schema:
          type: string
      - name: shipmentID
        in: query
        description: Unique identifier for the shipment associated with the invoice.
        schema:
          type: string
      - name: DOT
        in: query
        description: Department of Transportation identifier
        schema:
          type: string
      - name: MC
        in: query
        description: Motor Carrier Identifier
        schema:
          type: string
      - name: invoiceNumber
        in: query
        description: Invoice number to filter the invoice.
        schema:
          type: string
      responses:
        '200':
          description: Invoices retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: ./schemas/schemas.yaml#/components/schemas/Invoice
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /invoices/{uniqueID}:
    get:
      operationId: getInvoice
      summary: Get an Invoice
      description: 'As a Carrier, I want to retrieve an Invoice by its unique identifier.

        - In a request, the Carrier MUST provide the Unique Identifier in the path to retrieve the specific invoice details.'
      tags:
      - Invoice Management
      parameters:
      - name: uniqueID
        in: path
        required: true
        description: Unique identifier for the invoice to update.
        schema:
          type: string
      responses:
        '200':
          description: Invoice retrieved successfully
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/Invoice
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    put:
      operationId: updateInvoice
      summary: Update (Replace) an Invoice
      description: 'Fully replaces an existing invoice with the provided data.

        - The request MUST provide the Unique Identifier in the path to identify the invoice to update.

        - The request body MUST contain the complete invoice object with all required fields (uniqueID, shipmentID, DOT, MC, invoiceHeader, invoiceCharges).

        - The request MAY include optional comments as a query parameter.'
      tags:
      - Invoice Management
      parameters:
      - name: uniqueID
        in: path
        required: true
        description: Unique identifier for the invoice to update.
        schema:
          type: string
      - name: comments
        in: query
        required: false
        description: Optional comments related to the invoice.
        schema:
          type: array
          items:
            $ref: ./schemas/schemas.yaml#/components/schemas/Comment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./schemas/schemas.yaml#/components/schemas/Invoice
      responses:
        '200':
          description: Invoice updated successfully
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/SuccessMessage
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: deleteInvoice
      summary: Delete an Invoice
      description: 'Deletes an existing invoice by its unique identifier.

        - The request MUST provide the Unique Identifier in the path to identify the invoice to delete.

        - The request MAY include optional comments as a query parameter for the deletion.'
      tags:
      - Invoice Management
      parameters:
      - name: uniqueID
        in: path
        required: true
        description: Unique identifier for the invoice to delete.
        schema:
          type: string
      - name: comments
        in: query
        required: false
        description: Optional comments related to the invoice deletion.
        schema:
          $ref: ./schemas/schemas.yaml#/components/schemas/Comment
      responses:
        '204':
          description: Invoice deleted successfully. No content returned.
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/SuccessMessage
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ResultStatusCode:
      title: Result Status Code
      description: Numerical codes describing any logical status outcomes.  Not all codes apply to this API, but are included to encourage adoption of these standards across API specifications.
      oneOf:
      - const: '100'
        description: Informational General Information
      - const: '200'
        description: Warning Non-Critical Error
      - const: '300'
        description: Failure Data Error
      - const: '400'
        description: Failure Formatting Error
      - const: '500'
        description: Failure Business Logic Error
      - const: '600'
        description: Failure Carrier Specific Error
      - const: '700'
        description: Failure Unknown Reason
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ResultStatusCode'