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. 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: Invoice Management description: Endpoints for creating, retrieving, and managing invoices. paths: /invoices: post: operationId: createInvoice summary: Create an Invoice description: "## Request \nAs a Carrier, I want to Create an Invoice and send shipment information for a particular \nShipper or 3rd Party. \n- In a request, the Carrier MUST provide a shipmentID provided by the Shipper or \n 3rd Party participant. \n - LTL Consideration: Pro Number may be valid for proper tracking to the \n BOL generation process. \n- In a request, the Carrier MUST identify themselves, so the Shipper/3rd Party is \n aware of who is sending the Invoice information\n - Types of universal identifiers: DOT Number or MC number.\n- In a request, the Carrier MUST designate the Invoice Number to properly record \n the instance of payment for the Shipper/3rd party.\n- In a request, the Carrier MUST designate a Date associated with their shipment\n so that proper payment intervals are followed to by the Shipper/3rd party.\n- In a request, the Carrier MUST specify an amount for proper payment tracking \n and agreed upon terms specified in the tender. \n\n## Response \n- In a response, NMFTA MUST provide a response for successful or failure \n to transfer identification and values.\n- In a response, the Shipper/3rd Party MUST provide an acceptance or \n failure of transfer.\n" 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.\n- The request MAY include optional query parameters to filter the results, such as \n unique ID, shipment ID, DOT Number, MC Number, or invoice number.\n- All query parameters are optional and can be used individually or in combination to filter results.\n" 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: 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