Invoicing

The External API (XAPI) provides two method types for adding or modifying invoice-related data - single-transaction, and independent-transaction.
Tags:
Categories:

Single-Transaction

The single-transaction endpoints provide a single method for submitting all of the necessary data to create an invoice in one call. To accomplish this, the endpoint accepts a special type of payload that allows the user to set both the invoice header and all of the child tables in a single JSON payload.

The single-transaction type of method has the following behaviors:

  • Atomicity: Invoice additions are prevented (rolled back) if any of the child tables fail in their ability to meet integrity checks or encounter an unexpected error.
  • Speed: Reducing the number of calls to the API results in using a single authentication check rather than several, as well as it makes use of a shared database connection to ensure the fastest possible database performance is achieved.

Independent Transactions

The independent-transaction endpoints allow for the creation or modification of an invoice in small isolated transactions. For example, one endpoint could be used to create an invoice header, and another endpoint could be used to add each item or miscellaneous charge. This style of interacting with an invoice is best suited for situations when individual parts of an existing invoice need to be modified.

The single-transaction type of method has the following behaviors:

  • Flexibility: This type of endpoint allows for the individual addition or modification of any of the individual invoice components. This is useful for situations where the invoice exists and additional information such as comments needs to be added.
  • Reduced Speed: Each invoice components' web method validates the session, establishes a database connection, and initializes any objects; all of which takes time.

Object Design

The following objects and matching endpoints are available.

Object Description Endpoint
Invoice The invoice header contains important information about the invoice, such as the invoice number, date, customer billing and shipping information, and Job Status. /invoicing/invoice/add
/invoicing/invoice/edit
/invoicing/invoice/add/getrequest
/invoicing/invoice/getschema
InvoiceModel InvoiceModel represents a model added to an invoice. In EPASS, a model is a product that a customer can purchase, such as a stove or a dishwasher. /invoicing/invoice/model/add
InvoiceItem InvoiceItem represents an item added to an invoice. In EPASS, items are parts or accessories sold to customers or used by service technicians. /invoicing/invoice/item/add
InvoicePackage InvoicePackage contains details of a ‘“package”’ (a collection of models, items, warranties, or charges sold at a single price). /invoicing/invoice/package/add
InvoiceMisc InvoiceMisc represents a miscellaneous charge, credit, or promotion that is added to an invoice. Examples of miscellaneous items are delivery charges, instant rebates, and ‘“price matching”’ discounts. /invoicing/invoice/misc/add
/invoicing/invoice/misc/add/getrequest
/invoicing/invoice/misc/getschema
InvoiceWarranty InvoiceWarranty represents an extended warranty product added to an invoice. /invoicing/invoice/warranty/add
InvoiceLabor InvoiceLabour represents a labor fee that can be added to an invoice. Labor fees are usually the selling price of a product installation. /invoicing/invoice/labor/add
InvoiceComment InvoiceComment represents a comment added to an invoice. Comments are reusable pieces of text that are printed on invoices and typically include important or noteworthy information for store staff or the customer. Examples would be a store’s return policy for special orders or notes on extended warranty. /invoicing/invoice/comment/add
/invoicing/invoice/comment/add/getrequest
/invoicing/invoice/comment/getschema
InvoicePayment InvoicePayment represents a payment made on an invoice. Examples of payment methods are cash, check, and credit cards. /invoicing/invoice/payment/add
/invoicing/invoice/payment/add/getrequest
/invoicing/invoice/payment/getschema
InvoiceNote InvoiceNote object represents a note that can be added to an invoice. Notes are added to an invoice’s “Notepad” section and are intended for internal use only. /invoicing/invoice/note/add

Invoicing ER Diagram

The following diagram of the Invoicing Model details the relationship between the Invoice header and Invoice detail lines.

InvoiceAddress

InvoiceAddress is an associative table that resolves the relationships between the tables for the Invoice header and the objects that are added to an invoice, such as a model, item, or price. It is also commonly used as a “lookup” to quickly retrieve all of the various detail objects (models, items, etc.) for one invoice.

The InvoiceAddress structure is as follows:
PK DateStamp date
PK InvoiceCode varchar(20)
PK LineTimeStamp varchar(21)
Code varcahr(20)
LocationCode varcahr(5)
ParentDateStamp date
ParentLineTimeStamp varchar(12)

When an object is added to an invoice, it not only adds a record to the appropriate table (InvoiceModel, InvoiceItem, etc.) but it adds an InvoiceAddress record as well.

The InvoiceAddress record ID is returned in a successful response message.

Example:

{
    "success": true,
    "warning": false,
    "httpStatusCode": 201,
    "generalMessage": null,
    "exceptionMessage": null,
    "keys": [
        {
            "table": "InvoiceAddress",
            "keys": [
                {
                    "key": "ID",
                    "fields": [
                        {
                            "fieldName": "ID",
                            "fieldValue": 7054758
                        }
                    ]
                }
            ]
        },
    ],
    "messages": [],
    "warnings": []
}