NMFTA Document Management API

openapi: 3.2.0
info:
  title: Invoice & Document Document 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. Systems across the economic landscape will leverage this information to bring speed through data availability. Today, EDI and digital document uploads across numerous company specific applications are required for doing business within the logistical sector. Ultimately, this work will include managing a corpus of electronic data values and document file type returns with the focus on the transfer of the Invoice and supporting documents supporting all logistical types.


    Part of the journey is to build an open API to ensure all logistical and banking partners to reach a level of automation that scales with the business demand. With adoption of the FTL council, medium- and long-term value will be achieved for all parties across the economic markets and transportation providers. Teams from DSDC (Digital Standards Development Council) and support from the LTL council have come together for a collective goal to achieve business value for all.


    # The GAP


    Multiple sources and various technology implementations have created an endless landscape for shippers, carriers, and banking institutions that continue to empower antiquated physical documentation or outgrown EDI processes. APIs do not currently have all consistent components to fully operationalize document data transfers and document type dissemination, especially in the areas of "invoice data values", "bill of lading" and "freight bills"


    # Value Proposition


    The Invoice and Documents API will allow for the ability to seamlessly pass specific invoice and related shipment information regardless of transport type to obtain or pass an invoice or related documentation. This will transform the logistics industry by simplification of complex billing processes through accuracy and timeliness in one place will be paramount for all shipments. With a design to handle all complexities for any shipment, a simplified standard source will meet all business needs quickly while providing companies with the needed forecasting for growth.


    ## Carriers


    Providing the ability to pass and create an invoice through details to a Shipper or 3rd Party through standard shipment details. Additional documentation will also be able to be passed for additional proof of payment through supporting document types through shipment criteria. The ease will allow for Carriers to ensure that they avoid being cornered within the market.


    ## Shippers


    Receiving Carrier invoices and supplemental documentation for payment will allow for central standard empowering timely and accurate validation of services while providing the ability to eliminate slower physical or open-source transfers.


    ## 3rd Party


    Ensuring no delay in data validation or accuracy in supplying the appropriate information to support Invoice and supporting documentation for all parties


    # Product Requirements Document (PRD)


    The Product Requirements Document (PRD) for this API can be found [here](https://dsdcapis.github.io/full-truckload/api-prds/API%20Product%20Requirements%20-%20Invoice%20Documents.pdf).

    '
tags:
- name: Document Management
  description: Endpoints for uploading, and managing supporting documents.
paths:
  /documents:
    post:
      operationId: uploadDocument
      summary: Upload Supporting Documents
      description: "## Request\nAs a Carrier, I want to upload supporting documents for an invoice.\n- In a request, the Carrier MUST provide the Invoice Number to associate the document with the correct invoice.\n- In a request, the Carrier MUST designate the document type so that the acceptance of the response can be \n  tracked on the Shipper/3rd Party side. This can range from the Invoice to the supported twenty-four (24) document types.\n- The request MUST include the document file in PDF, TIF, JPEG, or PNG format.\n- The maximum file size MUST not exceed 25 MB.\n- In a request, the Carrier MUST specify the document type so that the \n  acceptance of the response can be tracked on the Shipper/3rd Party side. This \n  can range from the Invoice to the supported twenty-four (24) document types.\n    - Bill of Lading (BOL)\n    - Catalog Page (CAT)\n    - Communications & Correspondence (COMM)\n    - Contract (CON)\n    - Customer Specific Rules Tariff (RULE)\n    - Dimension Certificate (DIM)\n    - Detention Receipt (DTR)\n    - Discount Matrix (DIS)\n    - Freight Bill (FRB)\n    - Fuel Tables (FUEL)\n    - Invoice (INV)\n    - Inspection Certificate (INSP)\n    - Letter of Authority (LOA)\n    - Lumper Receipt (LPR)\n    - Material Safety Data Sheet (MSDS)\n    - Packing Slip (PAC)\n    - Photos (IMG)\n    - Proof of Delivery (POD)\n    - Quote (QUO)\n    - Residential Dispute Support (RESI)\n    - Spec Sheet (SPEC)\n    - Scale (SCL)\n    - Statement Bill (STB)\n    - Weight & Inspection Certificate (W&I)\n\n## Response\n  - In a response, NMFTA MUST provide a response for successful or failure to transfer identification and values.\n  - In a response, the Shipper/3rd Party MUST provide an acceptance or failure of transfer.\n"
      tags:
      - Document Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./schemas/schemas.yaml#/components/schemas/DocumentRequest
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/SuccessMessage
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    get:
      operationId: listDocuments
      summary: List Supporting Documents
      description: 'As a Carrier, I want to list all supporting documents for invoices.

        - The request MAY include optional query parameters such as Invoice Number, DOT Number, MC Number, or documentType to filter the results.

        - All query parameters are optional and can be used individually or in combination to filter results.

        '
      tags:
      - Document Management
      parameters:
      - name: invoiceNumber
        in: query
        description: Invoice number to filter the documents.
        schema:
          type: string
      - name: DOT
        in: query
        schema:
          type: string
          description: Department of Transportation identifier.
      - name: MC
        in: query
        schema:
          type: string
          description: Motor Carrier Identifier.
      - name: documentType
        in: query
        schema:
          type: array
          items:
            $ref: ./schemas/schemas.yaml#/components/schemas/DocumentType
          description: One or more document types to be retrieved (e.g., Invoice, BOL).
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: ./schemas/schemas.yaml#/components/schemas/DocumentResponse
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
  /documents/{invoiceNumber}:
    get:
      operationId: getDocument
      summary: Retrieve Supporting Documents
      description: 'As a Carrier, I want to retrieve supporting documents for an invoice by its Invoice Number.

        - In a request, the Carrier MUST provide the Invoice Number in the path to retrieve the specific documents.

        '
      tags:
      - Document Management
      parameters:
      - name: invoiceNumber
        in: path
        required: true
        description: Invoice number to filter the documents.
        schema:
          type: string
      responses:
        '200':
          description: Document(s) retrieved successfully
          content:
            application/json:
              schema:
                $ref: ./schemas/schemas.yaml#/components/schemas/DocumentResponse
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      operationId: deleteDocument
      summary: Delete Supporting Documents or Files
      description: 'Delete all supporting documents for an invoice, or specific files within the documents.

        - The request MUST provide the Invoice Number in the path to identify the documents to delete.

        - The request MAY include optional fileIds as a query parameter to delete specific files. If omitted, all documents for the invoice will be deleted.

        - The request MAY include optional comments as a query parameter for the deletion.

        '
      tags:
      - Document Management
      parameters:
      - name: invoiceNumber
        in: path
        required: true
        description: Invoice number to identify the documents.
        schema:
          type: string
      - name: fileIds
        in: query
        required: false
        description: List of file IDs to delete. If omitted, all documents for the invoice will be deleted.
        schema:
          type: array
          items:
            type: string
      - name: comments
        in: query
        required: false
        description: Optional comments related to the document deletion.
        schema:
          $ref: ./schemas/schemas.yaml#/components/schemas/Comment
      responses:
        '204':
          description: Document(s) or file(s) 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:
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ResultStatusCode'
  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