API : Invoice Create

Introduction

This request will create a new invoice.

An invoice can be created with a number of lines to invoice or it can be created from current invoice lines which are not recurring or locked.

Request

URL	https://api.telecomx.dk/invoice
Method	POST
Access level	RESELLER if customer belongs to the reseller. ADMIN.
Body	customer	Id	Id of the customer the invoice should be added to.
	reseller	Id	`[optional]` Id of the reseller (ADMIN only).
	sent	Boolean	True if the invoice should be marked as 'sent to customer'.
	invoiceNumber	String	`[optional]` Invoice number. Omit if TelecomX is to auto-set it or if it will be set by an accounting system later.
	invoiceDate	Date	`[optional]` The invoice date. If not set it will be set to today.
	dueDate	Date	`[optional]` The last payment date. If not set, it should be set later by an accounting system.
	paid	Boolean	`[optional]` True if the invoice has been paid.
	headline	String	`[optional]` Headline for the invoice, e.g. 'Vedr. ordrenr. 123 - afd. Kastrup'.
	lines	Array	`[optional]` List of products/service to invoice, can be empty if currentInvoices are specified instead.
	lines[].product	Id	Id of the product to use.
	lines[].name	String	`[optional]` Name of the product. Overrides product.
	lines[].description	String	`[optional]` Description of the the product/service. Overrides product.
	lines[].units	Number	Number of units to invoice, can be fractional and can be negative to credit instead of invoicing.
	lines[].unitCost	Number	`[optional]` Cost price pr. unit. Overrides product price (ADMIN only).
	lines[].unitWholesale	Number	`[optional]` Wholesale price pr. unit. Overrides product price. (ADMIN only).
	lines[].unitPrice	Number	`[optional]` Price pr. unit. Overrides product price.
	lines[].vatExempt	Boolean	`[optional]` True if product should be vat exempt. Overrides product.
	lines[item].from	Date	From date for this line.
	lines[item].to	Date	To date for this line.
	currentInvoices	Array	`[optional]` Array of current invoice ids to add to the invoice and remove from current invoices.

Request body examples

{
  customer: '123457890ABCDEF12345678',
  reseller: '123457890ABCDEF12345679',
  sent: false,
  invoiceNumber: '12345',
  invoiceDate: '2015-01-01T00:00:00+0100',
  dueDate: '2015-01-14T00:00:00+0100',
  paid: false,
  headline: 'Vedr. ordrenr. 123 - afd. Kastrup',
  lines:
  [
    {
      product: '1234567890ABCDEF12345677',
      description: 'Nummer: 70305050',
      units: 1
    },
    {
      ...
    }
  ],
  currentInvoices: ['1234567890ABCDEF12345670','1234567890ABCDEF12345671']
}

Response

The response will be the newly created invoice, if no errors occurred.

JSON object
_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/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/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/ADMIN only).
total	Double	Sales price including VAT.

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

Example

{
  "_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": "1234567890ABCDEF12345677",
      "productCode": "NUM01",
      "name": "Køb af nummer",
      "description": "Nummer: 70305050",
      "units": 1,
      "type": "UNITS",
      "unitWholesale": 100,
      "unitPrice": 200,
      "vatExempt": false
    },
    {
      "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
    }
  ],
  "subTotalWholesale": 499.81,
  "subTotal": 920.76,
  "vatWholesale": 124.95,
  "vat": 230.19,
  "total": 1150.95
}

Errors

Error code	Message	Description
404	customer	Customer not found
404	reseller	Reseller not found
422	invoiceDate	Invoice date is invalid
422	dueDate	Due date is invalid or in the past
422	headline	Headline is invalid
404	lines[x].product	Product not found
422	lines[x].units	Units is invalid
422	lines[x].unitCost	Unit cost is invalid
422	lines[x].unitWholesale	Unit wholesale is invalid
422	lines[x].unitPrice	Unit price is invalid
404	lines[x].product	Product not found or not valid for use
404	currentInvoices	Some or all items were not found
422	currentInvoices[x]	Current invoice item cannot be included due to recurrence
422	lines	Nothing to invoice
403	access_denied	Access denied
500	internal_error	<Unspecified>

WIKI

Table of Contents