Usage Monitoring Service

The Usage Monitoring Service enables callers to obtain statistics about the usage of Socrate Business Services. Usage is expressed in so-called “usage measurement types”, or simply counters. The list of counters is different for each service. For example, the counter INBOUND_MESSAGES of the Email Service tracks how many email messages have been received within the reported period. To obtain the counters available for each service, run the usageMeasurementTypes query.

This is a tenant-level service, and, consequently, it returns statistics only for other tenant-level services. To obtain the list of all tenant-level services, run the services query.

Access info
Endpoint https://usage-monitoring-api.socrate.io/graphql
Required access keys Tenant-level service access key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to usage-monitoring-api:query:* usage-monitoring-api:mutation:*.

Queries

organizations

Returns a list of active organizations defined in the Organizations Service. This is a convenience query used to obtain the list of organizations in Usage Monitoring Service without having to query the Organizations Service separately.

Result

The result is an array of Organization. Note this is a simplified type compared to the Organization type from the Organizations Service, and contains only the fields relevant for the Usage Monitoring Service.

Organization type
Attribute Type Description
id ID! Specifies the organization’s unique identifier.
name String Specifies the organization’s name.
tin String Specifies the organization’s tax identification number (TIN) (in Romanian, CIF - cod de identificare fiscală) issued by ANAF (in Romanian, ANAF - Agenția Națională de Administrare Fiscală).
regNo String Specifies the organization’s registration number issued by the National Trade Registration Office (in Romanian, ONRC - Oficiul National al Registrului Comerțului).
country CountryCode Enum value that identifies the ISO 3166-2 two-letter country code.
createdAt DateTime The date and time when the organization record was created in SBS.

services

Returns a list of all services exposed by the Socrate Business Services API. This query is useful when you need to find out the service code of a particular service, for example, when querying usage.

Arguments

None.

Result

An array of service codes.

Example

query services {
  services 
}

usage

Returns information about usage of SBS services. Querying usage is meaningful only for those services that have usage measurement types (counters). Currently, the following services have counters:

  • e-Factura Service
  • e-Transport Service
  • Email Service
  • Intrastat Service
  • Online Banking Service
  • Tax Declarations Service
  • VAT Validator Service
  • Websockets Service

Arguments

Attribute Type Description
filter UsageMeasurementFilter! Mandatory. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the UsageMeasurementResult type.
UsageMeasurementFilter type
Attribute Type Description
from DateTime! Mandatory. When provided, the call will return usage beginning with this date and time.
to DateTime Optional. When provided, the call will return usage up to this date and time only. Example values: 2024-07-16, 2024-07-15T06:59:59, 2024-07-16T11:30:53.983Z. Note that, if you specify only a date value without time, then the time is considered to be 00:00:00.
service ServiceCode! Mandatory. The service code specifies the service for which you would like to collect usage. To obtain all available service codes, run the services query.
type TypeCode! Mandatory. Specifies the usage measurement type. Valid values depend on the service argument. Run the usageMeasurementTypes query to obtain usage measurement types applicable for each service.
organizationId ID Optional. This filter may be used to filter the usage counters by organization, and is applicable only for those services that segregate data by organization (such as e-Factura, Tax Declarations).
environment Environment Optional. The SBS environment where usage took place (TEST or PRODUCTION). Supplying this filter is meaningful only for services that have test and production environments (currently, ro-efactura-api, ro-etransport-api, and online-banking-api).
objectId ID Optional. This filter is meaningful only if the service argument is email-api, ro-efactura-api, ro-etransport-api, ro-intrastat-api, or tax-declaration-api. It enables filtering usage counters by the object that caused usage. Valid values are: an email ID (if service is email-api), an invoice ID (if service is ro-efactura-api), a shipment ID (if service is ro-etransport-api), an Intrastat declaration process (if service is ro-intrastat-api), a tax declaration process ID (if service is tax-declarations-api)

Result

The result is an object of type UsageMeasurementResult.

UsageMeasurementResult type
Attribute Type Description
items [MeasurementValue] The array of MeasurementValue objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
MeasurementValue type
Attribute Type Description
value String The value of the statistic.
date Date The date relevant to this statistic.
organizationId ID (Applicable only for services that segregate data by organization, such as e-Factura Service or Tax Declarations Service.) This value specifies the organization to which this statistic applies.
environment Environment The environment where usage took place (TEST or PRODUCTION). This value is meaningful only for services that have test and production environments (currently, ro-efactura-api, ro-etransport-api, and online-banking-api).
objectId ID (Applicable for the Email, e-Factura, e-Transport, Intrastat, and Tax Declarations services only). This is the SBS ID of the object that caused usage. In the case of the Email Service, this is the email ID. In the case of the Tax Declarations Service, this is a tax declaration process ID. In the case of e-Factura, this is the ID of an inbound or outbound invoice. In the case of e-Transport, this is the ID of an e-transport declaration (shipment). In the case of the Intrastat Service, this is the ID of an Intrastat declaration’s process.

Example

The following call returns the count of CSV lines processed by the Tax Declarations Service from the 15th of March 2023 up to and including the 16th of March 2023 for the organization with ID 76c268a0-e5ce-11ee-9f95-db6d42e82b92:

query usage ($filter:UsageMeasurementFilter!){
  usage(filter:$filter) {
    items {
      value
      date
      organizationId
    }
  }
}

{
  "filter": {
    "from": "2023-03-15 00:00:00",
    "to": "2023-03-16 23:59:59",
    "service": "tax-declarations-api",
    "organizationId": "76c268a0-e5ce-11ee-9f95-db6d42e82b92",
    "type": "CSV_FILE_LINES"
  }
}

usageMeasurementTypes

Returns the measurement types (names of usage counters) supported by a given service. This is useful for those services that have usage counters, such as ro-efactura-api, ro-etransport-api, and others.

Arguments

Attribute Type Description
service ServiceCode! Mandatory. The code of the service for which you are requesting measurement types. To obtain all available service codes, run the services query.

Result

An array of type codes. Each type code is the name of the measurement type. For example, if the service supplied as input is tax-declarations-api, the returned type code is CSV_FILE_LINES.

Example

The following query returns the usage measurement types available for the Tax Declarations Service:

query UsageMeasurementTypes($service:ServiceCode!) {
  usageMeasurementTypes(service:$service) 
}

{
  "service": "tax-declarations-api"
}

version

Returns the API version.

Read more

RO Tax Declarations Service User Management Service