Table of Contents

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 reseller [optional] Reseller's customer ID (24 hex-char string). Only honored for RESELLER_ADMIN/ADMIN callers; RESELLER callers always get their own customers.
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.
offset [optional] Index of the first finance report to return, default 0. Capped at 500 for RESELLER callers.
limit [optional] The number of finance reports to return, default 100, min 1, max 500.
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?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
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. 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
accountingSystemId String The customer's accounting system id (CVR / customer number), when set.
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 (ADMIN/RESELLER_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 (ADMIN/RESELLER_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

{
  "offset": 0,
  "limit": 100,
  "total": 78,
  "subTotalWholesale": 90550.15,
  "subTotal": 150391.35,
  "docs": [
    {
      "customer": "650000000000000000000001",
      "customerName": "Eksempel ApS",
      "accountingSystemId": "12345678",
      "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

Kundenavn;CVR/KundeNummer;Varenummer;Produktnavn;BeskrivelseUdenPeriode;Fra;Til;Antal;Forhandlerpris;Pris
Eksempel ApS;12345678;NUM01;Nummerleje;1 numre;2024-06-01;2024-06-30;1;20;25
Eksempel ApS;12345678;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

CustomerName;AccountingSystemId;ProductCode;ProductName;DescriptionWithoutPeriod;From;To;Amount;ResellerPrice;Price
Eksempel ApS;12345678;NUM01;Nummerleje;1 numre;2024-06-01;2024-06-30;1;20;25
Eksempel ApS;12345678;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
404 reseller Reseller not found
422 reseller Reseller 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 reseller does not exist or is outside your scope
500 internal_error <Unspecified>