Table of Contents

API : Finance Report Get

Introduction

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

This endpoint is different from just getting the customer's invoice 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/CUSTOMER_ID
Method GET
Access level RESELLER if customer belongs to the reseller.
RESELLER_ADMIN
ADMIN.
Param CUSTOMER_ID Id of the customer (24 hex-char string)
Query 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.
groupLines [optional] Boolean. When true, lines that share product and period are grouped into one line, the response also contains the customer's reseller id, and groups are separated by empty objects in the lines array. Default false.
lang [optional] Language of the CSV column headers: da (default) or en.
showIncludedProducts [optional] Boolean. When true, invoice lines bundled into another product are kept in the report, default false.

Query example

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

Response

JSON object
customer Id Id of customer report is for.
reseller Id Id of the customer's reseller. Only present when groupLines=true.
lines Array Array of invoice lines. A line carries all fields of the stored invoice line (see API : Invoice Get) with units, from, to and description adjusted to the part of the line inside the report period. Key fields 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 (RESELLER_ADMIN/ADMIN only).
lines[item].unitWholesale Number Reseller price pr. unit.
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.
lines[item].accountName String Name of the account the line concerns, when set (may be null).
lines[item].isIncluded Boolean True when the line is bundled into another product. Such lines are only returned when showIncludedProducts=true.
subTotalCost Number Total cost before tax (RESELLER_ADMIN/ADMIN only).
subTotalWholesale Number Total wholesale cost before tax.
subTotal Number Total price before tax.
vat Double Value added tax.
vatCost Double Value added tax on cost (RESELLER_ADMIN/ADMIN only).
vatWholesale Double Value added tax on wholesale.
total Double Sales price including VAT.

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

Example (JSON)

{
  "customer": "650000000000000000000001",
  "lines": [
    {
      "product": "650000000000000000000002",
      "productCode": "NUM01",
      "name": "Nummerleje",
      "description": "1 numre - Periode: 01-06-2024 - 30-06-2024",
      "units": 1,
      "type": "MONTHS",
      "unitWholesale": 20,
      "unitPrice": 25,
      "vatExempt": false,
      "from": "2024-05-31T22:00:00.000Z",
      "to": "2024-06-30T22:00:00.000Z"
    },
    {
      "product": "650000000000000000000003",
      "productCode": "FORBRUG1",
      "name": "Samtaler",
      "description": "SIP konto: Hovedkonto - kald: 42 - tid: 03:12:05 - periode: 01-06-2024 - 30-06-2024",
      "units": 1,
      "type": "UNITS",
      "unitWholesale": 398.18,
      "unitPrice": 792.22,
      "vatExempt": false,
      "from": "2024-05-31T22:00:00.000Z",
      "to": "2024-06-30T22:00:00.000Z"
    }
  ],
  "subTotalWholesale": 418.18,
  "subTotal": 817.22,
  "vatWholesale": 104.55,
  "vat": 204.31,
  "total": 1021.53
}

Example (CSV) lang=da

Varenummer;Produktnavn;BeskrivelseUdenPeriode;Fra;Til;Antal;Forhandlerpris;Pris
NUM01;Nummerleje;1 numre;2024-06-01;2024-06-30;1;20;25
FORBRUG1;Samtaler;SIP konto: Hovedkonto - kald: 42 - tid: 03:12:05;2024-06-01;2024-06-30;1;398,18;792,22

Example (CSV) lang=en

ProductCode;ProductName;DescriptionWithoutPeriod;From;To;Amount;ResellerPrice;Price
NUM01;Nummerleje;1 numre;2024-06-01;2024-06-30;1;20;25
FORBRUG1;Samtaler;SIP konto: Hovedkonto - kald: 42 - tid: 03:12:05;2024-06-01;2024-06-30;1;398,18;792,22

Errors

Error code Message Description
422 id Customer id is not valid
422 from Date is not valid
422 to Date is not valid
422 to To-date has to be higher than the from-date
422 to Date cannot be later than 2 years from the from-date
403 access_denied Insufficient access level, or the customer does not exist or is outside your scope
404 customer Customer not found (can only occur with groupLines=true)
500 internal_error <Unspecified>