Usage Monitoring Service

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:*.

Usage

The Usage Monitoring Service enables callers to obtain statistics about the usage of Socrate Business Services. For example, you can view how many times a particular query or mutation of a particular service was called.

Note that the Usage Monitoring Service is a tenant-level service, and, consequently, it returns statistics only for other tenant-level services. Tenant-level services are those that require a tenant-level service access key from callers in order to be accessed.

To see which services require a tenant-level access key, check the “Access Info” section provided in the API reference of each service.

Queries

calls

Returns the count of queries or mutations that were run for a particular service, or for all services.

Arguments

Argument Type Description
filter CallsFilter! Provides filtering options to the query.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
CallsFilter input
Attribute Type Description
from DateTime! Mandatory. The date and time starting with which statistics will be fetched.
to DateTime Optional. The date and time up to which statistics will be fetched, for example, 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 Optional. The service code specifies the service for which you would like to collect statistics. You can obtain the service code from the endpoint URL of each service, by extracting from the URL the string part after https:// and before .socrate. For example, if the URL is https://account-api.socrate.xyz/graphql, then the service code is account-api.
operationType OperationType Optional. Specifies the operation type for which statistics should be returned. Valid values: query, mutation.
field Field Optional. Specifies the name of the query or mutation for which statistics should be returned.

Result

CallsResult type
Attribute Type Description
items [CallsValue] The statistics data that matches the filtering options, as an array of items of type CallsValue.
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.
CallsValue type
Attribute Type Description
service ServiceCode The service code indicates specifies the service for which statistics have been retrieved.
operationType OperationType Specifies the operation type for which statistics have been returned. Valid values: query, mutation.
field Field Specifies the name of the query or mutation for which statistics have been retrieved.
count Float The actual count of calls (queries or mutations) that took place.

Example

The following call returns the count of runs for the sendMessage mutation of the Email Service starting from the 1st of July 2023 up to the current date and time:

query calls ($filter:CallsFilter!){
  calls(filter:$filter) {
    items {
      service
      operationType
      field
      count
    }
  }
}

{
  "filter": {
    "from": "2023-07-01",
    "service": "email-api",
    "field": "sendMessage"
  }
}

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
  • Online Banking Service
  • Tax Declarations 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. You can obtain the service code from the endpoint URL of each service, by extracting from the URL the string part after https:// and before .socrate. For example, if the URL is https://ro-efactura-api.socrate.xyz/graphql, then the service code is ro-efactura-api.
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 ro-efactura-api or tax-declaration-api. It enables filtering usage counters by the object that caused usage. Valid values are: an invoice ID (if service is ro-efactura-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 e-Factura and Tax Declarations services only). This is the ID of the object that caused usage. In case of tax declarations service, this is a tax declaration process ID. In case of e-Factura, this is the ID of an inbound invoice.

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. You can obtain the service code from the endpoint URL of each service, by extracting from the URL the string part after https:// and before .socrate. For example, if the URL is https://tax-declarations-api.socrate.xyz/graphql, then the service code is tax-declarations-api.

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