API docs by Redocly

Invoice & Document API (1.0.0-public-preview)

Download OpenAPI specification:Download

URL: https://github.com/dsdcapis/full-truckload License: DSDC Repository License

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.

Invoice Management

Endpoints for creating, retrieving, and managing invoices.

Create an Invoice

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.
Request Body schema: application/json
required
uniqueID
required
string

Unique identifier for the invoice.

shipmentID
required
string

Unique identifier for the shipment associated with the invoice.

DOT
required
string

Department of Transportation identifier

MC
required
string

Motor Carrier Identifier

required
object (InvoiceHeader)

Header fields for an invoice including consignor, consignee, billing party, terms, and invoice details.

required
Array of Charge (object) or Item Charge (object) or Handling Unit Charge (object) (InvoiceCharges)

List of all charges on the invoice.

Array of objects (Attribute)

List of attributes associated with the invoice.

Array of objects (Comment)

List of comments associated with the invoice.

Responses

Request samples

Content type
application/json
{
  • "uniqueID": "string",
  • "shipmentID": "string",
  • "DOT": "string",
  • "MC": "string",
  • "invoiceHeader": {
    },
  • "invoiceCharges": [
    ],
  • "attributes": [
    ],
  • "comments": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invoice created successfully"
}

List Invoices

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.
query Parameters
uniqueID
string

Unique identifier for the invoice.

shipmentID
string

Unique identifier for the shipment associated with the invoice.

DOT
string

Department of Transportation identifier

MC
string

Motor Carrier Identifier

invoiceNumber
string

Invoice number to filter the invoice.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an Invoice

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.
path Parameters
uniqueID
required
string

Unique identifier for the invoice to update.

Responses

Response samples

Content type
application/json
{
  • "uniqueID": "string",
  • "shipmentID": "string",
  • "DOT": "string",
  • "MC": "string",
  • "invoiceHeader": {
    },
  • "invoiceCharges": [
    ],
  • "attributes": [
    ],
  • "comments": [
    ]
}

Update (Replace) an Invoice

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.
path Parameters
uniqueID
required
string

Unique identifier for the invoice to update.

query Parameters
Array of objects (Comment)

Optional comments related to the invoice.

Request Body schema: application/json
required
uniqueID
required
string

Unique identifier for the invoice.

shipmentID
required
string

Unique identifier for the shipment associated with the invoice.

DOT
required
string

Department of Transportation identifier

MC
required
string

Motor Carrier Identifier

required
object (InvoiceHeader)

Header fields for an invoice including consignor, consignee, billing party, terms, and invoice details.

required
Array of Charge (object) or Item Charge (object) or Handling Unit Charge (object) (InvoiceCharges)

List of all charges on the invoice.

Array of objects (Attribute)

List of attributes associated with the invoice.

Array of objects (Comment)

List of comments associated with the invoice.

Responses

Request samples

Content type
application/json
{
  • "uniqueID": "string",
  • "shipmentID": "string",
  • "DOT": "string",
  • "MC": "string",
  • "invoiceHeader": {
    },
  • "invoiceCharges": [
    ],
  • "attributes": [
    ],
  • "comments": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invoice created successfully"
}

Delete an Invoice

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.
path Parameters
uniqueID
required
string

Unique identifier for the invoice to delete.

query Parameters
object (Comment)

Optional comments related to the invoice deletion.

Responses

Response samples

Content type
application/json
{
  • "message": "Invoice created successfully"
}

Document Management

Endpoints for uploading, and managing supporting documents.

Upload Supporting Documents

Request

As a Carrier, I want to upload supporting documents for an invoice.

  • In a request, the Carrier MUST provide the Invoice Number to associate the document with the correct invoice.
  • In a request, the Carrier MUST designate the document type so that the acceptance of the response can be tracked on the Shipper/3rd Party side. This can range from the Invoice to the supported twenty-four (24) document types.
  • The request MUST include the document file in PDF, TIF, JPEG, or PNG format.
  • The maximum file size MUST not exceed 25 MB.
  • In a request, the Carrier MUST specify the document type so that the acceptance of the response can be tracked on the Shipper/3rd Party side. This can range from the Invoice to the supported twenty-four (24) document types.
    • Bill of Lading (BOL)
    • Catalog Page (CAT)
    • Communications & Correspondence (COMM)
    • Contract (CON)
    • Customer Specific Rules Tariff (RULE)
    • Dimension Certificate (DIM)
    • Detention Receipt (DTR)
    • Discount Matrix (DIS)
    • Freight Bill (FRB)
    • Fuel Tables (FUEL)
    • Invoice (INV)
    • Inspection Certificate (INSP)
    • Letter of Authority (LOA)
    • Lumper Receipt (LPR)
    • Material Safety Data Sheet (MSDS)
    • Packing Slip (PAC)
    • Photos (IMG)
    • Proof of Delivery (POD)
    • Quote (QUO)
    • Residential Dispute Support (RESI)
    • Spec Sheet (SPEC)
    • Scale (SCL)
    • Statement Bill (STB)
    • Weight & Inspection Certificate (W&I)

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.
Request Body schema: application/json
required
uniqueID
required
string
shipmentID
required
string
DOT
required
string
MC
required
string
invoiceNumber
required
string
invoiceDate
required
string <date>
documentSource
string
Array of objects (Attribute)
Array of objects (Comment)
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "uniqueID": "string",
  • "shipmentID": "string",
  • "DOT": "string",
  • "MC": "string",
  • "invoiceNumber": "string",
  • "invoiceDate": "2019-08-24",
  • "documentSource": "string",
  • "attributes": [
    ],
  • "comments": [
    ],
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invoice created successfully"
}

List Supporting Documents

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.
query Parameters
invoiceNumber
string

Invoice number to filter the documents.

DOT
string

Department of Transportation identifier.

MC
string

Motor Carrier Identifier.

Array of "BOL" (string) or "CAT" (string) or "COMM" (string) or "CON" (string) or "RULE" (string) or "DIM" (string) or "DTR" (string) or "DIS" (string) or "FRB" (string) or "FUEL" (string) or "INV" (string) or "INSP" (string) or "LOA" (string) or "LPR" (string) or "MSDS" (string) or "PAC" (string) or "IMG" (string) or "POD" (string) or "QUO" (string) or "RESI" (string) or "SPEC" (string) or "SCL" (string) or "STB" (string) or "W&I" (string) or "OTHER" (string) (Document Type)
Example: documentType=BOL

One or more document types to be retrieved (e.g., Invoice, BOL).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Supporting Documents

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.
path Parameters
invoiceNumber
required
string

Invoice number to filter the documents.

Responses

Response samples

Content type
application/json
{
  • "uniqueID": "string",
  • "shipmentID": "string",
  • "DOT": "string",
  • "MC": "string",
  • "invoiceNumber": "string",
  • "invoiceDate": "2019-08-24",
  • "documentSource": "string",
  • "attributes": [
    ],
  • "comments": [
    ],
  • "documents": [
    ]
}

Delete Supporting Documents or Files

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.
path Parameters
invoiceNumber
required
string

Invoice number to identify the documents.

query Parameters
fileIds
Array of strings

List of file IDs to delete. If omitted, all documents for the invoice will be deleted.

object (Comment)

Optional comments related to the document deletion.

Responses

Response samples

Content type
application/json
{
  • "message": "Invoice created successfully"
}