API : Invoice List (reseller overview of their customer invoices)

Introduction

This request will return a list of invoices that was created for a resellers customer(s) within a given period. This endpoint can be used by the reseller to create invoices in an accounting system, or download their customers' invoices to a CSV file. The resulting documents will contain both the end customers' prices and the reseller's wholesale prices.

Request

URL	https://api.telecomx.dk/invoice
Method	GET
Access level	RESELLER, RESELLER_ADMIN, ADMIN.
Query	fromDate	The invoice date to return invoices for, unless toDate is also set, then it is the first date to return invoices for, e.g. 2015-01-01.
	toDate	`[optional]` The last invoice date to return invoices for.
	customer	`[optional]` If invoices should only be returned for a given customer, this is the id of that customer.
	reseller	`[optional]` Id of the reseller whose customers invoices should be returned for (RESELLER and above only).
	offset	`[optional]` Index of the first product to return, default 0.
	limit	`[optional]` The number of products to return, default 500, min 1, max 500.
	expand	`[optional]` If true, full customer data (name, address, invoicing e-mail address) is included in the reply. Subtotals will also be calculated for all invoices.
	format	`[optional]` Can be “csv” or “json”. If not given, defaults to json. If none of the headers below are given, then they are all included in the CSV.
	groupInvoiceLines	`[optional]` Whether the invoice lines will be grouped by product and period, making the invoices shorter. Can be true or false. Only relevant if format equals csv.
	spaceBetweenLines	`[optional]` Adds empty lines between lines, used for making the format easier to read. Can be true or false. Only relevant if format equals csv and group.
	customerName	`[optional]` If format is CSV - adds this column to the csv file.
	vatNumber	`[optional]` If format is CSV - adds this column to the csv file.
	productCode	`[optional]` If format is CSV - adds this column to the csv file.
	amount	`[optional]` If format is CSV - adds this column to the csv file.
	wholesalePrice	`[optional]` If format is CSV - adds this column to the csv file.
	customerPrice	`[optional]` If format is CSV - adds this column to the csv file.
	name	`[optional]` If format is CSV - adds this column to the csv file.
	description	`[optional]` If format is CSV - adds this column to the csv file.
	customerId	`[optional]` If format is CSV - adds this column to the csv file.

Query examples

https://api.telecomx.dk/invoice?fromDate=2015-01-01
https://api.telecomx.dk/invoice?fromDate=2015-01-01&toDate=2015-06-01
https://api.telecomx.dk/invoice?fromDate=2015-01-01&toDate=2015-06-01&offset=100&limit=250
https://api.telecomx.dk/invoice?fromDate=2014-01-01&toDate=2014-12-31&customer=1234567890ABCDEF12345678

Response

JSON object
offset	Index of the first invoice returned.
limit	Number of invoices to return. Note that the actual number of invoices returned may be lower.
total	Number of invoices that can be returned when offset and limit is not considered. This is to be used for paging through the data.
invoices	Array of invoices, see definition below.

Invoice object (JSON)
_id	Id	Unique invoice id.
customer	Id	Id of customer invoice is for.
sent	Boolean	True if invoice has been sent to the customer.
invoiceNumber	String	Invoice number. If it is -1, then it is waiting to be set by the accounting system.
period	Boolean	True if this is a monthly period invoice.
invoiceDate	Date	The invoice date.
dueDate	Date	The payment date.
paid	Boolean	True if payment has been received - set by accounting system.
headline	String	Optional headline for the invoice. For description, tracking id, reference number etc.
lines	Array	Array of invoice lines - see below:
lines[item].product	ObjectID	Id of product used.
lines[item].productCode	String	Product code, e.g. 'IN4010'.
lines[item].name	String	Product name, e.g. 'Internet VDSL 40/10Mbit'.
lines[item].description	String	Optional descriptive text, e.g. 'for perioden 1/1 - 31/1-2014'.
lines[item].units	Number	Number of units (to be multiplied by the unit price).
lines[item].type	String	Type of units: MIN, MB, UNITS, HOURS, KM, MONTHS.
lines[item].unitCost	Number	Cost pr. unit (ADMIN only).
lines[item].unitWholesale	Number	Reseller price pr. unit (RESELLER/RESELLER_ADMIN only).
lines[item].unitPrice	Number	Sales prices pr. unit
lines[item].vatExempt	Boolean	True if this is exempt from VAT
subTotalCost	Number	Total cost before tax (ADMIN only).
subTotalWholesale	Number	Total wholesale cost before tax (RESELLER/RESELLER_ADMIN only).
subTotal	Number	Total price before tax.
vat	Double	Value added tax.
vatCost	Double	Value added tax on cost (ADMIN only).
vatWholesale	Double	Value added tax on wholesale (RESELLER/RESELLER_ADMIN only).
total	Double	Sales price including VAT.

Note that properties holding no value may be omitted from the object.

If expand = true

Invoice object (JSON)
_id	Id	Unique invoice id.
customer	Object	Customer object
customer._id	Id	Id of customer invoice is for.
customer.name	String	Customer name
customer.address	Object	Customer address object
customer.address.address	String	Street name/address
customer.address.alternativeName	String	Name for the specific address
customer.address.city	String	City name
customer.address.country	String	2-letter ISO country code
customer.address.zip	String	City ZIP code
customer.finance	Object	Customer's finance properties
customer.finance.accountingSystemId	String	Accounting system ID. Can be used to link the customer to an external accounting system.
customer.finance.emailAddress	String	Accounting e-mail
customer.finance.invoiceMethod	String	Invoice method of the customer
customer.finance.vatNumber	String	Customer's vat number
sent	Boolean	True if invoice has been sent to the customer.
invoiceNumber	String	Invoice number. If it is -1, then it is waiting to be set by the accounting system.
period	Boolean	True if this is a monthly period invoice.
invoiceDate	Date	The invoice date.
dueDate	Date	The payment date.
paid	Boolean	True if payment has been received - set by accounting system.
headline	String	Optional headline for the invoice. For description, tracking id, reference number etc.
lines	Array	Array of invoice lines - see below:
lines[item].product	ObjectID	Id of product used.
lines[item].productCode	String	Product code, e.g. 'IN4010'.
lines[item].name	String	Product name, e.g. 'Internet VDSL 40/10Mbit'.
lines[item].description	String	Optional descriptive text, e.g. 'for perioden 1/1 - 31/1-2014'.
lines[item].units	Number	Number of units (to be multiplied by the unit price).
lines[item].type	String	Type of units: MIN, MB, UNITS, HOURS, KM, MONTHS.
lines[item].unitCost	Number	Cost pr. unit (ADMIN only).
lines[item].unitWholesale	Number	Reseller price pr. unit (RESELLER/RESELLER_ADMIN only).
lines[item].unitPrice	Number	Sales prices pr. unit
lines[item].vatExempt	Boolean	True if this is exempt from VAT
subTotalCost	Number	Total cost before tax (ADMIN only).
subTotalWholesale	Number	Total wholesale cost before tax (RESELLER/RESELLER_ADMIN only).
subTotal	Number	Total price before tax.
vat	Double	Value added tax.
vatCost	Double	Value added tax on cost (ADMIN only).
vatWholesale	Double	Value added tax on wholesale (RESELLER/RESELLER_ADMIN only).
total	Double	Sales price including VAT.

Response examples

Normal condensed

{
  offset: 0,
  limit: 500,
  total: 822,
  invoices:
  [
    {
      "_id": "54a978806d30733986cfa817",
      "customer": "54463ed73fc6ea53780080cf",
      "sent": false,
      "invoiceNumber": -1,
      "period": true,
      "invoiceDate": "2014-12-31T23:00:00.000Z",
      "dueDate": "2015-01-07T23:00:00.000Z",
      "paid": false,
      "headline": "Periode faktura",
      "lines":
      [
        {
          "product": "548ecd936b34cd1826f3ff2b",
          "productCode": "NUM01",
          "name": "Nummerleje",
          "description": "1 numre - Periode: 01-11-2014 - 31-03-2015",
          "units": 5,
          "type": "MONTHS",
          "unitWholesale": 20,
          "unitPrice": 25,
          "vatExempt": false
        },
        {
          "product": "54917e9940c67b6c3dd05a8c",
          "productCode": "FORBRUG1",
          "name": "Samtaler",
          "description": "SIP konto: Hovedkonto - kald: 544 - tid: 25:34:05 - periode: 01-12-2014 - 31-12-2014",
          "units": 1,
          "type": "UNITS",
          "unitWholesale": 398.18,
          "unitPrice": 792.22,
          "vatExempt": false
        },
        {
          "product": "54917e9940c67b6c3dd05a8c",
          "productCode": "FORBRUG1",
          "name": "Samtaler",
          "description": "SIP konto: Fax - kald: 15 - tid: 00:11:47 - periode: 01-12-2014 - 31-12-2014",
          "units": 1,
          "type": "UNITS",
          "unitWholesale": 1.63,
          "unitPrice": 3.54,
          "vatExempt": false
        }
      ],
      "subTotalWholesale": 499.81,
      "subTotal": 920.76,
      "vatWholesale": 124.95,
      "vat": 230.19,
      "total": 1150.95
    },
    {
      ...
    }
  ]
}

If expand = true

{
  offset: 0,
  limit: 500,
  total: 822,
  subTotalCost: 281.5,
  subTotalWholesale: 716.2,
  subTotal: 1082.2,
  invoices:
  [
    {
      "_id": "54a978806d34133986cfa817",
      "customer": {
        "_id": "1234567890ABCD1234567890",
        "name": "Ducktales & Co.",
        "address": {
           "address": "ABC-vej 15"
           "alternativeName": "Hovedkontoret"
           "city": "Kalundborg"
           "country": "DK"
           "zip": "4400"
      },
      "finance": {
        "accountingSystemId": "35722"
        "emailAddress": "invoice@andeby.dk"
        "invoiceMethod": "EMAIL"
        "vatNumber": "19552942"
      },
      "sent": false,
      "invoiceNumber": -1,
      "period": true,
      "invoiceDate": "2014-12-31T23:00:00.000Z",
      "dueDate": "2015-01-07T23:00:00.000Z",
      "paid": false,
      "headline": "Periode faktura",
      "lines":
      [
        {
          "product": "548ecd936b34cd1826f3ff2b",
          "productCode": "NUM01",
          "name": "Nummerleje",
          "description": "1 numre - Periode: 01-11-2014 - 31-03-2015",
          "units": 5,
          "type": "MONTHS",
          "unitWholesale": 20,
          "unitPrice": 25,
          "vatExempt": false
        },
        {
          "product": "54917e9940c67b6c3dd05a8c",
          "productCode": "FORBRUG1",
          "name": "Samtaler",
          "description": "SIP konto: Hovedkonto - kald: 544 - tid: 25:34:05 - periode: 01-12-2014 - 31-12-2014",
          "units": 1,
          "type": "UNITS",
          "unitWholesale": 398.18,
          "unitPrice": 792.22,
          "vatExempt": false
        },
        {
          "product": "54917e9940c67b6c3dd05a8c",
          "productCode": "FORBRUG1",
          "name": "Samtaler",
          "description": "SIP konto: Fax - kald: 15 - tid: 00:11:47 - periode: 01-12-2014 - 31-12-2014",
          "units": 1,
          "type": "UNITS",
          "unitWholesale": 1.63,
          "unitPrice": 3.54,
          "vatExempt": false
        }
      ],
      "subTotalWholesale": 499.81,
      "subTotal": 920.76,
      "vatWholesale": 124.95,
      "vat": 230.19,
      "total": 1150.95
    },
    {
      ...
    }
  ]
}

Errors

Error code	Message	Description
422	fromDate	Date is not valid
422	toDate	Date is not valid
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents

API : Invoice List (reseller overview of their customer invoices)

Introduction

Request

Query examples

Response

If expand = true

Response examples

Normal condensed

If expand = true

Errors