API : Finance Report List

Introduction

This request will return a list of all finance report for a specific reseller, in a specific time period. The purpose of this endpoint is for resellers to get a better overview on costs and revenue for a specific period.

This endpoint is different from just getting the customers invoices for that month, in that it gives all the lines regarding the specific period. E.g an invoice made on July 1st will cover usage from June, but subscriptions/products from July and onwards, because subscriptions are billed ahead.

This endpoint also supports “accrual accounting” of invoice lines. As an example, a line can have the period 01-07-2024 - 31-09-2024, which would amount to a unit price times three months. If a finance report is fetched for the period 01-07-2024 - 31-07-2024, then that line will only have one unit, because the line has been “split”.

In short, this finance report allows viewing the usage and subscriptions that only covers the specific period.

Request

URL	https://api.telecomx.dk/financeReport
Method	GET
Access level	RESELLER RESELLER_ADMIN ADMIN.
Query	resellerId	`[optional]` Reseller's customer ID (24 hex-char string).
	from	From date in YYYY-MM format, always defaults to the first day of the month.
	to	`[optional]` To date in YYYY-MM format. If not set, it will be set to a month after the “from” date
	format	`[optional]` Format to get the data in. Allowed values are CSV and JSON. Defaults to JSON.

Query example

https://api.telecomx.dk/financeReport?from=2024-06
https://api.telecomx.dk/financeReport?from=2024-06&reseller=1234567890ABCDEF12345678
https://api.telecomx.dk/financeReport?from=2024-06&to=2024-07&reseller=1234567890ABCDEF12345678
https://api.telecomx.dk/financeReport?from=2024-06&to=2024-07

Response

JSON object
total	number	Total amount of finance reports
offset	number	Index of the first finance report returned
limit	number	Number of finance reports to return. Note that the actual number of finance reports returned may be lower.
total	number	Number of finance reports that can be returned when offset and limit is not considered. This is to be used for paging through the data.
subTotalCost	Number	Total cost before tax (ADMIN/RESELLER_ADMIN only). This is calculated based on all finance reports in the given timeframe, and not only the ones fetched.
subTotalWholesale	Number	Total wholesale cost before tax (ADMIN/RESELLER_ADMIN/RESELLER only). This is calculated based on all finance reports in the given timeframe, and not only the ones fetched.
subTotal	Number	Total price before tax. This is calculated based on all finance reports in the given timeframe, and not only the ones fetched.
docs	FinanceReport[]	List of finance reports, see definition below

FinanceReport object
customer	Id	Id of customer report is for.
customerName	String	Name of customer
customerIsDeleted	Boolean	True if the customer was deleted
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
lines[item].from	Date	From date for this line.
lines[item].to	Date	To date for this line.
subTotalCost	Number	Total cost before tax (ADMIN/RESELLER_ADMIN only).
subTotalWholesale	Number	Total wholesale cost before tax (ADMIN/RESELLER_ADMIN/RESELLER only).
subTotal	Number	Total price before tax.
vat	Double	Value added tax.
vatCost	Double	Value added tax on cost (ADMIN/RESELLER_ADMIN only).
vatWholesale	Double	Value added tax on wholesale (ADMIN/RESELLER_ADMIN/RESELLER only).
total	Double	Sales price including VAT.

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

Example

{
  "offset": 0,
  "limit": 50,
  "total": 78,
  "subTotalCost": 90000,
  "subTotalWholesale": 90550.15,
  "subTotal": 150391.35
  "docs": [
    {
      "customer": "1234567890ABCD1234567890",
      "customerName": "Hans Hansens Biler ApS",
      "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
    },
    {
      ...
    }
  ]
}

Example (CSV) lang=da

"Kundenavn";"KundeNummer/CVR";"Varenummer";"Produktnavn";"BeskrivelseUdenPeriode";"Fra";"Til";"Antal";"Forhandlerpris";"Pris"
"Hans Hansens Cykler ApS";"12345123";"Nummerleje";"1 numre";"2014-11-01";"2014-11-30";5;"MONTHS";20;25
...

Example (CSV) lang=en

"CustomerName";"AccountingSystemId";"ProductCode";"ProduktName";"DescriptionWithoutPeriod";"From";"To";"Amount";"ResellerPrice";"Price"
"Hans Hansens Cykler ApS";"12345123";"Nummerleje";"1 numre";"2014-11-01";"2014-11-30";5;"MONTHS";20;25
...

Errors

Error code	Message	Description
404	reseller	Reseller not found
404	from	From date not found
422	from	Date is not valid
422	to	Date is not valid
422	to	Date cannot be before from
422	to	Date cannot be later than 2 years from the from-date
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents