Skip to content

Dunning API v3 (Alpha)

Configs

Configs that can be used inside the CEL expressions of the dunning service. Conceptually, this is a time-sliced key-value store. Configs are independent of the dunning process version. Each Config has a list of Parameters.

ListConfigs

List Configs

Input: ListConfigsRequest

Field Type Rules Description
*parent string The parent resource name.
page_size int32 The maximum number of items to return. 0 for default.
page_token string The next_page_token value returned from a previous List request, if any.
filter string Filter to apply to the list.
e.g. display_name = "Global"
order_by string Comma separated list of fields to order by. Use - for descending order, e.g. "-created_time".

Output: ListConfigsResponse

Field Type Rules Description
configs Config repeated The list of configs.
total_size int64 Count of items contained in the list.
next_page_token string The token to retrieve the next page of results.

GetConfig

Get a single config

Input: GetConfigRequest

Field Type Rules Description
*name string Name of the config to retrieve.

Output: Config

Field Type Rules Description
name string Name of the config
display_name string Display Name of the config
parameters Parameter repeated The parameters of the config.
create_time google.protobuf.Timestamp output only The creation time of the config.
update_time google.protobuf.Timestamp output only The last update time of the config.

CreateConfig

Create a new config

Input: CreateConfigRequest

Field Type Rules Description
*parent string The parent resource (i.e. the tenant)
*config Config The config to create.
config_id string The ID to use for the config, which will become the final component of the process's resource name.
If not specified, a system generated id will be used.

Output: Config

Field Type Rules Description
name string Name of the config
display_name string Display Name of the config
parameters Parameter repeated The parameters of the config.
create_time google.protobuf.Timestamp output only The creation time of the config.
update_time google.protobuf.Timestamp output only The last update time of the config.

UpdateConfig

Update a config

Input: UpdateConfigRequest

Field Type Rules Description
*config Config The config to update.
*update_mask google.protobuf.FieldMask The update mask applies to the resource. For the FieldMask definition,
see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

Output: Config

Field Type Rules Description
name string Name of the config
display_name string Display Name of the config
parameters Parameter repeated The parameters of the config.
create_time google.protobuf.Timestamp output only The creation time of the config.
update_time google.protobuf.Timestamp output only The last update time of the config.

Parameter

Field Type Rules Description
*display_name string Display Name of the parameter, the name must be unique within the config.
*values Value repeated The values of the parameter, this must be a list of non-overlapping date ranges.

Value

Field Type Rules Description
validity_range enpowerx.types.v3.DateRange The validity range of the value
null_value google.protobuf.NullValue Represents a null value.
number_value double Represents a double value.
string_value string Represents a string value.
bool_value bool Represents a boolean value.
int_value int64 Represents a int64 value.
decimal_value enpowerx.types.v3.Decimal Represents a decimal value.

FailedPreconditionExpressionCompilationError

Field Type Rules Description
details FailedPreconditionExpressionCompilationError.Detail repeated The details of the compilation error.
expression string The expression that failed to compile.

FailedPreconditionExpressionCompilationError.Detail

Field Type Rules Description
line int32 The line number of the error.
column int32 The column number of the error.
message string The error message.
formatted_message string formatted error message

FailedPreconditionExpressionRuntimeError

Field Type Rules Description
message string The error message.
expression string The expression that failed to evaluate.

FailedPreconditionIllegalStateError

Field Type Rules Description
allowed_states Instance.State output only
repeated		 Allowed states for the attempted operation.

FailedPreconditionInstructionNotRetryableError

Field Type Rules Description
instruction Instance.Step.Instruction The instruction that was attempted to be retried.

FailedPreconditionInterruptHandlerMissingError

Field Type Rules Description
process string Name of the process.

FailedPreconditionInvalidJumpInstructionError

Field Type Rules Description
jump_target_level int32 The level that was attempted to be jumped to.

InvalidArgumentPauseEndBeforeNowError

Field Type Rules Description
reference_time google.protobuf.Timestamp The current system time.

InvalidArgumentPrematureInvocationError

Field Type Rules Description
next_scheduled_invocation_time google.protobuf.Timestamp The next scheduled invocation time.

Instances

Manage dunning process instances

ListInstances

List process instances.

Input: ListInstancesRequest

Field Type Rules Description
*parent string The parent resource name.
page_size int32 The maximum number of items to return. 0 for default.
page_token string The next_page_token value returned from a previous List request, if any.
filter string Filter to apply to the list.
e.g. contract = "contracts/1234"
order_by string Comma separated list of fields to order by. Use - for descending order, e.g. "-created_time".

Output: ListInstancesResponse

Field Type Rules Description
instances Instance repeated The list of processes instances.
total_size int64 Count of items contained in the list.
next_page_token string The token to retrieve the next page of results.

GetInstance

Get a single process instance.

Input: GetInstanceRequest

Field Type Rules Description
*name string Name of the process instance to retrieve.

Output: Instance

Field Type Rules Description
name string Name of the instance
state Instance.State output only The state of the instance
*contract string The contract the instance is running for
steps Instance.Step output only
repeated		 Step history of the instance. Each step represents any changes that occurred to the instance.
interrupts Instance.Interrupt output only
repeated		 Interrupts that were scheduled for the instance.
*payload google.protobuf.Struct The payload of the instance. Arbitrary data that is passed to the process.
end_reason Instance.EndReason output only The reason why the instance ended.
next_scheduled_invocation_time google.protobuf.Timestamp Earliest time this instance can be invoked again.
When creating a new instance this can be used to schedule the instance for a later time.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
create_time google.protobuf.Timestamp output only The creation time of the process.

CreateInstance

Create a new process instance, the process will be determined automatically based on the payload.

Input: CreateInstanceRequest

Field Type Rules Description
*parent string The parent resource
*instance Instance The Instance to be created.
instance_id string The ID to use for the instance, which will become the final component of the instance's resource name.
If not specified, a system generated id will be used.

Output: Instance

Field Type Rules Description
name string Name of the instance
state Instance.State output only The state of the instance
*contract string The contract the instance is running for
steps Instance.Step output only
repeated		 Step history of the instance. Each step represents any changes that occurred to the instance.
interrupts Instance.Interrupt output only
repeated		 Interrupts that were scheduled for the instance.
*payload google.protobuf.Struct The payload of the instance. Arbitrary data that is passed to the process.
end_reason Instance.EndReason output only The reason why the instance ended.
next_scheduled_invocation_time google.protobuf.Timestamp Earliest time this instance can be invoked again.
When creating a new instance this can be used to schedule the instance for a later time.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
create_time google.protobuf.Timestamp output only The creation time of the process.

CancelInstance

Cancel a running process instance.

Input: CancelInstanceRequest

Field Type Rules Description
*name string Name of the process instance to cancel.

Output: CancelInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was cancelled.

RetryInstance

Retry a failed process instance. This action retries the last failed step action.

Input: RetryInstanceRequest

Field Type Rules Description
*name string Name of the process instance to retry.
reference_time google.protobuf.Timestamp The system time to use as reference for the retry. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: RetryInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was retried.

InvokeInstance

Invoke executes the next step of the instance.

Input: InvokeInstanceRequest

Field Type Rules Description
*name string Name of the process instance to invoke.
reference_time google.protobuf.Timestamp The system time to use as reference for the invocation. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: InvokeInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was invoked.

PauseInstance

Pause the instance until the given resume_time.

Input: PauseInstanceRequest

Field Type Rules Description
*name string Name of the process instance to pause.
*resume_time google.protobuf.Timestamp The time to automatically resume the instance.
reference_time google.protobuf.Timestamp The system time to use as reference for the resume. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: PauseInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was paused.

ResumeInstance

Resume the instance. This will resume the instance at the beginning of the current level.

Input: ResumeInstanceRequest

Field Type Rules Description
*name string Name of the process instance to pause.
reference_time google.protobuf.Timestamp The system time to use as reference for the resume. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: ResumeInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was resumed.

InterruptInstance

Interrupt the instance with the given payload. This will invoke the interrupt handler of the process.
If the process has no interrupt handler, the API will return an error.

Input: InterruptInstanceRequest

Field Type Rules Description
*name string Name of the process instance to cancel.
*payload google.protobuf.Struct The payload of the interrupt.
reference_time google.protobuf.Timestamp The system time to use as reference for the invocation. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: InterruptInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was interrupted.

CompleteInstance

Complete a running process instance.

Input: CompleteInstanceRequest

Field Type Rules Description
*name string Name of the process instance to cancel.
*end_reason Instance.EndReason end reason
reference_time google.protobuf.Timestamp The system time to use as reference for the invocation. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: CompleteInstanceResponse

Field Type Rules Description
instance Instance output only The instance that was completed.

JumpLevel

Set the current level of the instance. This will set the current level of the instance to the given level.
It is only possible to set the level to a level less or equal to the current level.
The target level will be executed immediately.

Input: JumpLevelRequest

Field Type Rules Description
*name string Name of the process instance to cancel.
*target_level int32 The target level to set the instance to.
reference_time google.protobuf.Timestamp The system time to use as reference for the invocation. If not specified, the current time will be used.
This functionality might be disabled on production systems and will lead to an UNIMPLEMENTED error in that case.
Furthermore the client is required to have the appropriate permissions to use this field or PERMISSION_DENIED will be returned.

Output: JumpLevelResponse

Field Type Rules Description
instance Instance output only The instance for which the level was set.

Instance.Interrupt

Field Type Rules Description
payload google.protobuf.Struct output only The payload of the interrupt
processed_time google.protobuf.Timestamp output only Time when the interrupt was processed.

Instance.Step

Step represents any changes that occurred to the instance.

Field Type Rules Description
active_level int32 output only The active level of the instance.
state Instance.State output only The state of the instance
payload google.protobuf.Struct output only The payload of the instance.
invoked_action int32 output only
optional		 The action of the level that was invoked.
error string output only The error that occurred during the step invocation.
instruction Instance.Step.Instruction output only The instruction that was executed.
jump_target_level int32 output only
optional		 The level the instance is jumping to in the next invocation.
invoked_hook int32 output only
optional		 The hook that was invoked.
interrupt_payload google.protobuf.Struct output only The payload of the interrupt, only available for INTERRUPT instructions.
details Instance.Step.Details output only Details of the step.
start_time google.protobuf.Timestamp output only The time the step invocation started.
end_time google.protobuf.Timestamp output only The time the step invocation ended.

Instance.Step.Details

Field Type Rules Description
balances Instance.Step.Details.Balances output only The balances of the account
records Instance.Step.Details.Record output only
repeated		 Business records which compose the claim (DE: Einzel-Belege)

Instance.Step.Details.Balances

Balance Breakdown (DE: Salden)

Field Type Rules Description
principal_claim google.type.Money output only Principal balance (DE: Hauptforderungen)
secondary_claim google.type.Money output only Secondary claim amount (DE: Nebenforderungen)
installments google.type.Money output only Installments (DE: Abschläge)
down_payments google.type.Money output only Down payments (DE: Raten)
sum_claims google.type.Money output only Total amount of claims (DE: Summe Forderungen)
deposit google.type.Money output only Deposits (DE: Zahlungen Guthaben)
balance google.type.Money output only Balance (DE: Saldo)

Instance.Step.Details.Record

Business record (DE: Beleg)

Field Type Rules Description
type string output only type of the record (DE: SAP-Kurzbezeichnung)
description string output only Description of the record (DE: Belegart)
number string output only fica number (DE: FICA-Belegnummer)
reference string output only Reference (DE: Druckbeleg/Rechnungsnummer)
date google.type.Date output only date of the record (DE: Belegdatum)
due_date google.type.Date output only due date of the record (DE: Fälligkeitsdatum)
amount google.type.Money output only Amount of the record (DE: Amount)

Instance.EndReason

The reason why the instance ended.

Name Number Description
END_REASON_UNSPECIFIED 0 The end reason is unspecified
PAYMENT_EXPENSED 1 The instance ended because a in-payment was expensed (DE: Zahlungseingang gebucht)
REVERSAL_EXPENSED 2 A reversal was expensed (DE: Storno gebucht)
INSTALLMENT_PLAN_CREATED 3 A installment plan was created (DE: Ratenplan angelegt)
DEFERRAL_CREATED 4 A deferral was created (DE: Stundung angelegt)
INVOICE_CREATED 5 A Invoice was created (DE: Rechnung angelegt)
BILLING_DOCUMENT_CREATED 6 A billing document was created (DE: Fakturabeleg storniert)
COMPLETED_MANUALLY_CUSTOMER_CONTACT 7 Instance was completed manually after a customer contact
COMPLETED_MANUALLY_PROCESS_ERROR 8 Instance was completed manually due to a process error
COMPLETED_MANUALLY_OTHER 9 Instance was completed manually for another reason

Instance.State

Name Number Description
STATE_UNSPECIFIED 0 The state is unspecified
INITIALIZING 1 The instance has been created and is waiting for the scheduler to start it.
WAITING 2 The instance is waiting until wait_duration_workdays have elapsed.
RUNNING 3 The instance currently being executed.
PAUSED 4 The instance has been paused manually.
COMPLETED 5 The instance is completed.
CANCELLED 6 The instance is cancelled.
FAILED 7 The instance failed due to an error

Instance.Step.Instruction

Name Number Description
INSTRUCTION_UNSPECIFIED 0 The instruction is unspecified
ACTIVATE_LEVEL 1 The level was activated
REFRESH_PAYLOAD 2 Payload was refreshed
INVOKE_LEVEL 3 Level was invoked
INVOKE_ACTION 4 Action was invoked
COMPLETE_INSTANCE 5 The instance was completed
CANCEL_MANUALLY 6 The instance was cancelled manually.
INVOKE_HOOK 7 A hook was invoked.
PAUSE_MANUALLY 8 The instance was paused manually.
FORCE_RESUME 9 The instance was forced to resume.
COMPLETE_MANUALLY 10 The instance was completed manually.
JUMP_MANUALLY 11 A manual jump was performed.

Processes

Manage dunning process definitions

ListProcesses

List process definitions.

Input: ListProcessesRequest

Field Type Rules Description
*parent string The parent resource name.
page_size int32 The maximum number of items to return. 0 for default.
page_token string The next_page_token value returned from a previous List request, if any.
filter string Filter to apply to the list.
e.g. category IN ('meter', 'device')
order_by string Comma separated list of fields to order by. Use - for descending order, e.g. "-created_time".

Output: ListProcessesResponse

Field Type Rules Description
processes Process repeated The list of processes.
total_size int64 Count of items contained in the list.
next_page_token string The token to retrieve the next page of results.

GetProcess

Get a single process.

Input: GetProcessRequest

Field Type Rules Description
*name string Name of the process to retrieve.
Example: tenants/stadtwerkex/processes/dunning-swx-b2b

In order to retrieve a previous revision of the process, also provide
the revision ID.
Example: tenants/stadtwerkex/processes/dunning-swx-b2b@v1

Output: Process

Field Type Rules Description
name string Name of the process
*display_name string Human readable name of the process.
enabled bool Indicates whether the process is enabled.
match_condition string A CEL expression which must evaluate to a boolean. If the expression evaluates to true, the process is activated.
If multiple processes match a given payload, a random process is selected.
levels Process.Level repeated The levels of the process. Each step is equal to a dunning level. The order of the steps defines their dunning level.
First step is the first dunning level, second step is the second dunning level, etc.
hooks Process.Hook repeated The hooks to invoke during the process lifecycle.
details_extractor string A CEL expression which extracts enpowerx.dunning.v3.Instance.Step.Details from the payload.
If not provided details are not extracted.
revision_id string immutable
output only		 The revision ID of the process. A new revision is created each time the process is updated.
revision_create_time google.protobuf.Timestamp output only The timestamp that the revision was created.
create_time google.protobuf.Timestamp output only The creation time of the process.

ListProcessRevisions

List revisions of a process.

Input: ListProcessRevisionsRequest

Field Type Rules Description
*name string Name of the process to retrieve.
page_size int32 The maximum number of revisions to return per page.
page_token string The page token, received from a previous ListProcessRevisions call.
Provide this to retrieve the subsequent page.

Output: ListProcessRevisionsResponse

Field Type Rules Description
processes Process repeated The list of processes.
total_size int64 Count of items contained in the list.
next_page_token string The token to retrieve the next page of results.

CreateProcess

Create a new process

Input: CreateProcessRequest

Field Type Rules Description
*parent string The parent resource (i.e. the tenant)
*process Process The Process to be created.
process_id string The ID to use for the process, which will become the final component of the process's resource name.
If not specified, a system generated id will be used.

Output: Process

Field Type Rules Description
name string Name of the process
*display_name string Human readable name of the process.
enabled bool Indicates whether the process is enabled.
match_condition string A CEL expression which must evaluate to a boolean. If the expression evaluates to true, the process is activated.
If multiple processes match a given payload, a random process is selected.
levels Process.Level repeated The levels of the process. Each step is equal to a dunning level. The order of the steps defines their dunning level.
First step is the first dunning level, second step is the second dunning level, etc.
hooks Process.Hook repeated The hooks to invoke during the process lifecycle.
details_extractor string A CEL expression which extracts enpowerx.dunning.v3.Instance.Step.Details from the payload.
If not provided details are not extracted.
revision_id string immutable
output only		 The revision ID of the process. A new revision is created each time the process is updated.
revision_create_time google.protobuf.Timestamp output only The timestamp that the revision was created.
create_time google.protobuf.Timestamp output only The creation time of the process.

UpdateProcess

Update an existing process

Input: UpdateProcessRequest

Field Type Rules Description
*process Process The process to update.
*update_mask google.protobuf.FieldMask The update mask applies to the resource. For the FieldMask definition,
see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

Output: Process

Field Type Rules Description
name string Name of the process
*display_name string Human readable name of the process.
enabled bool Indicates whether the process is enabled.
match_condition string A CEL expression which must evaluate to a boolean. If the expression evaluates to true, the process is activated.
If multiple processes match a given payload, a random process is selected.
levels Process.Level repeated The levels of the process. Each step is equal to a dunning level. The order of the steps defines their dunning level.
First step is the first dunning level, second step is the second dunning level, etc.
hooks Process.Hook repeated The hooks to invoke during the process lifecycle.
details_extractor string A CEL expression which extracts enpowerx.dunning.v3.Instance.Step.Details from the payload.
If not provided details are not extracted.
revision_id string immutable
output only		 The revision ID of the process. A new revision is created each time the process is updated.
revision_create_time google.protobuf.Timestamp output only The timestamp that the revision was created.
create_time google.protobuf.Timestamp output only The creation time of the process.

Process.Hook

Field Type Rules Description
*type Process.Hook.Type The type of the hook.
*hook string The CEL expression to invoke.

Process.Level

Level defines a single step in the process. A step is equal to a dunning level.

Field Type Rules Description
*display_name string Human readable name of the step, e.g. "Mahnstufe 1"
payload_refresh_hook string The payload refresh hook is a CEL expression. The expression is invoked when the step is activated.
The expression can be used to refresh the payload of the associated Instance.
This expression is invoked after wait_duration_workdays are elapsed.
For example: If level 0 has a wait duration of 8 days, the activation condition of level 0 is invoked 8 days
activation_hook string The activation_hook is invoked immediately after the payload refresh hook has been invoked.
Within the activation hook it is possible to control the instance execution.
For example it is possible to use cancel() to cancel the execution of the instance.
If no hook is defined, the instance continues its execution.
*wait_duration_workdays string The wait duration before the step's actions are invoked in workdays.
This is a CEL expression that must evaluate to an integer.
You can use the global config store here to fetch the wait duration from the configuration.
For example: dunning.parameter("water", "Zahlungserinnerung - Mahnrhythmus")
The process will fail if the wait duration is not a positive integer in [1, 65535].
actions Process.Level.Action repeated The actions to execute when the step is activated. The actions are executed in the order they are defined.

Process.Level.Action

Field Type Rules Description
*display_name string Human readable name of the action, e.g. "Mahnschreiben an Kunden versenden"
*commands string repeated Command to execute, this is a CEL expression. The expression is invoked, when the step is activated.
retry_max_elapsed_duration google.protobuf.Duration Total time for retries; If none of the retries succeeds the associated Instance is moved to FAILED state.
The command is retried using an exponential backoff strategy (See https://en.wikipedia.org/wiki/Exponential_backoff).
If not set, a default of 5 minutes is used.

Process.Hook.Type

Available hook types.

Name Number Description
TYPE_UNSPECIFIED 0 The type is unspecified.
AFTER_INITIALIZATION 1 Invoked after the process has been initialized by the scheduler.
INTERRUPT_HANDLER 2 Invoked when the process receives an interrupt signal
AFTER_CANCELLATION 3 Invoked when the process was cancelled.
AFTER_COMPLETION 4 Invoked when the process was completed.

Shared Types

Amount

Field Type Rules Description
unit string The unit of the amount. E.g.'kWh' or 'PCS' for pieces.
units int64 The whole units of the amount.
For example if unit is "PCS", then 1 unit is one piece.
nanos int32 Number of nano (10^-9) units of the amount.
The value must be between -999,999,999 and +999,999,999 inclusive.
If units is positive, nanos must be positive or zero.
If units is zero, nanos can be positive, zero, or negative.
If units is negative, nanos must be negative or zero.
For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

BankAccount

Information about a bank account.

Field Type Rules Description
*iban string The International Bank Account Number.
bic string The Bank Identifier Code.
account_holder string The name of the account holder.
bank string The name of the bank.

CustomerType

Represents the kind of the customer.

Name Number Description
CUSTOMER_TYPE_UNSPECIFIED 0 The customer type is unspecified.
PRIVATE 1 The customer type is private.
BUSINESS 2 The customer type is business.
BOTH 3 The customer type is private and business.

DateRange

Represents a range of dates.

Field Type Rules Description
*start google.type.Date The inclusive start date.
end google.type.Date The inclusive end date.
end_exclusive google.type.Date The exclusive end date.
time_zone string The time zone of the date range (defaults to Europe/Berlin).

DateTimeRange

Represents a range of date times.

Field Type Rules Description
*start google.protobuf.Timestamp The inclusive start date.
end google.protobuf.Timestamp The inclusive end date.

Decimal

Field Type Rules Description
units int64 The whole units of the amount.
nanos int32 Number of nano (10^-9) units of the amount.
The value must be between -999,999,999 and +999,999,999 inclusive.
If units is positive, nanos must be positive or zero.
If units is zero, nanos can be positive, zero, or negative.
If units is negative, nanos must be negative or zero.
For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

Billing

Billing details.

Field Type Rules Description
*contact Contact The contact to send invoices to.
*payment_method PaymentMethod The payment method method.
bank_account BankAccount The bank account used if payment_method is DIRECT_DEBIT.

CommunicationChannel

Communication channel.

Name Number Description
COMMUNICATION_CHANNEL_UNSPECIFIED 0 Channel not specified.
LETTER 1 Send messages via letter.
EMAIL 2 Send messages via email.
SMS 3 Send messages via SMS.
MESSENGER 4 Send messages via messenger apps like WhatsApp.
PHONE 5 Communicate via telephone.

Contact

Contact details (postal, phone, etc.).

Field Type Rules Description
*person Person Information on how to address the contact.
postal_address PostalAddress The contact's postal address.
phone_number string The phone number of the contact.
Values are normalized into the form +123456789.
email string The email address of the contact.
careof Person A person that may receive communication in the name of the actual recipient (e.g. a "C/O" line added to the postal address).

Reading

Information about a reading.

Field Type Rules Description
*date google.type.Date The date when the reading was taken.
channel Reading.Channel How the reading was reported.
This is value is ignored when submitting via AddMine.
*values Reading.ValuesEntry repeated A map of values to submit with OBIS codes as the key.
ignore_plausibility_check_reason google.protobuf.StringValue If set the meter reading(s) will be saved, even if they're not plausible.
Specifies the reason why the plausibility check is to be ignored.

Reading.ValuesEntry

Field Type Rules Description
key string
value double

Reading.Channel

Name Number Description
CHANNEL_UNSPECIFIED 0 No channel specified.
PORTAL 1 Reported via end-user portal.
EMAIL 2 Reported via email.
LETTER 3 Reported via letter.
PHONE 4 Reported via phone call.
MSCONS 5 Reported via Metered Services Consumption report message.

Relocation

Information about the relocation of an contract.

Field Type Rules Description
*contract string The contract's ID this request is targeting.
*moveout_date google.type.Date The move-out date.
*movein_date google.type.Date The move-in date.
*delivery EnergyDelivery Which kind and amount of energy is to be delivered to where.
*use_new_address Relocation.UseNewAddress Use the new address as postal and billing address.
*meter string The ID of the meter at the new consumption point.
last_reading Reading The last reading at the old consumption point.
old_meter string The ID of the meter at the old consumption point.
Optional, must be set if a last reading is provided.

Relocation.UseNewAddress

Name Number Description
USE_NEW_ADDRESS_UNSPECIFIED 0 Use unspecified.
NO 1 Use not desired.
IMMEDIATELY 2 Use immediately desired.
ON_MOVE_IN 3 Use on moving in desired.

SalesInfo

Information on how a sale was made.

Field Type Rules Description
sales_partner_code string Direct sales partner code.
sales_partner_code_second string Second direct sales partner code.
campaign string Optional override for the default campaign.

ScheduledRequest

Reference to an entity with an optional scheduled starting date.

Field Type Rules Description
*id string The ID referencing the entity.
scheduled_date google.type.Date The scheduled starting date (earliest possible if unset).

TransitionType

Specifies modalities of a contract transition.

Name Number Description
TRANSITION_TYPE_UNSPECIFIED 0 The transition type is unspecified
MANUAL_TERMINATION 1 The customer terminates the prior contract.
VENDOR_TERMINATION 2 The vendor terminates the prior contract.
RELOCATION 3 The customer is going to or has recently moved to the new address.

Duration

Represents a coarse time duration (e.g., 2 months).

Field Type Rules Description
*units int32 The number of time units.
*type google.type.CalendarPeriod The type the units refer to (days, months, etc.).

EnergyDelivery

Describes which kind and amount of energy is to be delivered to where.

Field Type Rules Description
*energy_type EnergyType The kind of the energy.
*customer_type CustomerType The kind of the customer.
*address PostalAddress The address to deliver energy to.
annual_usage int32 The estimated power usage in kWh per year.
usage_type EnergyDelivery.UsageType The usage type for the delivered energy.
annual_usage_nt int32 The estimated off-peak power usage in kWh per year (DE: Niedertarifverbrauch).

EnergyDelivery.UsageType

Name Number Description
USAGE_TYPE_UNSPECIFIED 0 The consumption type is unspecified.
HOUSEHOLD_ELECTRICITY 1 The energy is used for household.
CHARGING_CURRENT 2 The energy is used for charging.
STORAGE_HEATER 3 The energy is used for a storage heater.
HEAT_PUMP 4 The energy is used for a heat pump.
HOUSEHOLD_ELECTRICITY_AND_STORAGE_HEATER 5 The energy is used for household with storage heater.
HOUSEHOLD_ELECTRICITY_AND_HEAT_PUMP 6 The energy is used for household with heat pump.

EnergyType

Represents the kind of the energy.

Name Number Description
ENERGY_TYPE_UNSPECIFIED 0 The energy type is unspecified.
ELECTRICITY 1 The energy type is electricity.
GAS 2 The energy type is gas.

FileContent

Field Type Rules Description
*mime_type string The media type / content type of the document.
*content bytes The raw data of the document.

AnnotationFilter

AnnotationFilter provides filter semantics for annotations.

Field Type Rules Description
*field string The annotation field path is a symbolic field path to target an annotation's field, for example:

"invoice.id", "is_consumption_based", ...
value google.protobuf.Value The value to match the annotation field's value.

DateFilter

DateFilter provides match semantics for date fields.

Field Type Rules Description
*date google.type.Date The date to filter for.
match_mode DateFilter.MatchMode The match mode to use. The default is EQUAL.

DateRangeFilter

DateTimeRangeFilter provides match semantics for date fields. The filter treats the start and end date as inclusive.

Field Type Rules Description
*start_date google.type.Date The start date to filter for.
*end_date google.type.Date The end date to filter for.

DateTimeFilter

DateTimeFilter provides match semantics for date time fields.

Field Type Rules Description
*time google.protobuf.Timestamp The date time to filter for.
match_mode DateTimeFilter.MatchMode The match mode to use. The default is EQUAL.

DateTimeRangeFilter

DateTimeRangeFilter provides match semantics for date time fields.

Field Type Rules Description
*start_time google.protobuf.Timestamp The start date time to filter for.
*end_time google.protobuf.Timestamp The end date time to filter for.

StringListFilter

Strings filter x IN and x NOT IN semantics.

Field Type Rules Description
*values string repeated The value to filter for.
negate bool If true the expression is negated.

StringScalarFilter

StringFilter provides match semantics for strings fields.

Field Type Rules Description
*value string The value to filter for.
match_mode StringScalarFilter.MatchMode The match mode to use.
negate bool If true the expression is negated.

DateFilter.MatchMode

Name Number Description
MATCH_MODE_UNSPECIFIED 0 The match mode is unspecified.
EQUAL 1 Filter only matches if the date is equal to the provided date.
BEFORE 2 Filter matches all dates that are before the provided date.
AFTER 3 Filter matches all dates that are after the provided date.
BEFORE_OR_EQUAL 4 Filter matches all dates that are before or equal to the provided date.
AFTER_OR_EQUAL 5 Filter matches all dates that are after or equal to the provided date.

DateTimeFilter.MatchMode

Name Number Description
MATCH_MODE_UNSPECIFIED 0 The match mode is unspecified.
EQUAL 1 Filter only matches if the date is equal to the provided date.
BEFORE 2 Filter matches all dates that are before the provided date.
AFTER 3 Filter matches all dates that are after the provided date.
BEFORE_OR_EQUAL 4 Filter matches all dates that are before or equal to the provided date.
AFTER_OR_EQUAL 5 Filter matches all dates that are after or equal to the provided date.

StringScalarFilter.MatchMode

Name Number Description
MATCH_MODE_UNSPECIFIED 0 The match mode is unspecified.
EXACT 1 Filter only matches if the field contains exactly the expected value.
PREFIX 2 Filter matches all fields that are prefixed with the given value.
SUFFIX 3 Filter matches all fields that are suffixed with the given value.
SUBSTRING 4 Filter matches all fields that contain the given value.

LetterAddress

Combines a name and a postal address.

Field Type Rules Description
*person Person The person being addressed.
careof string A person that may receive letters in the name of the actual recipient (e.g. a "C/O" line added to the postal address).
*postal_address PostalAddress The postal address.

MonthOfYear

Represents a month of a year.

Field Type Rules Description
month int32 Month of the year.
year int32 Year.

PaymentMethod

Possible methods for paying invoices.

Name Number Description
PAYMENT_METHOD_UNSPECIFIED 0 The payment method method is unspecified.
DIRECT_DEBIT 1 Money is automatically withdrawn from the specified bank account.
MANUAL_TRANSFER 2 The customer pays bills manually using money transfers.

Period

A period of time with inclusive start and inclusive and exclusive end time. If both (inclusive and exclusive) ends are specified, they must be consistent. If no end is specified, the period is considered unbounded on the end. If the time is unspecified it is considered to be 00:00:00.000000000 for the start (and exclusive end) and 23:59:59.999999999 for the inclusive end.

The following example represents a period of time from 2006-01-01 to 2006-01-31: { start_time: { hours: 0 minutes: 0 seconds: 0 nanos: 0 } start_date: { year: 2006 month: 1 day: 1 } end_time: { hours: 23 minutes: 59 seconds: 59 nanos: 999999999 } end_date: { year: 2006 month: 1 day: 31 } end_date_exclusive: { year: 2006 month: 2 day: 1 } end_time_exclusive: { hours: 0 minutes: 0 seconds: 0 nanos: 0 } }

Field Type Rules Description
start_time google.type.TimeOfDay The start time of the period (inclusive).
end_time google.type.TimeOfDay The end time of the period (inclusive).
start_date google.type.Date The start date of the period (inclusive).
end_date google.type.Date The end date of the period (inclusive).
end_time_exclusive google.type.TimeOfDay The end time of the period (exclusive).
end_date_exclusive google.type.Date The end date of the period (exclusive).
time_zone string The time zone of the period (defaults to Europe/Berlin).

Person

Information on how to address a person. A person can be either a natural person or a company with an optional contact Natural Person: Must provide firstname, lastname Company: Must provide company

Field Type Rules Description
salutation Person.SalutationForm The salutation of the person.
title string The title of the person.
firstname string The first name of the person.
lastname string The last name of the person.
birthday google.type.Date The birthday of the person.
company string The company name.

Person.SalutationForm

Name Number Description
SALUTATION_FORM_UNSPECIFIED 0 The salutation form is unspecified.
MRS 1 The salutation form is Mrs..
MR 2 The salutation form is Mr..
DIVERSE 3 The salutation form is Diverse.
FAMILY 4 The salutation form is Family.

PostalAddress

Represents a postal address, e.g. for postal delivery or payments addresses.

Field Type Rules Description
*region string The region the address is located in as a CLDR region code.
Example: DE for Germany
*postal_code string A postal code of the city (a city may have more than one).
Example: 76131 for Karlsruhe inner city
*city string The canonical name of the city (there may be more than one per postal code).
Example: Karlsruhe
street string The canonical name of the street.
Example: Kaiserstr.
house_number string The house number.
Examples: 32, 32a, 32/1
postbox_number string Postbox number in case address is a postbox.
district string Administrative division (i.e. Stadtteil).
additional_address_lines string repeated Additional address lines
Example: Appartment 104, Care of etc.

Price

Represents a price before and after taxes.

Field Type Rules Description
*net google.type.Money The price without VAT.
*gross google.type.Money The price including VAT.
unit string The unit the price is related to (e.g "kWh", "PCS", "month", etc.)

Quantity

Field Type Rules Description
unit string The unit of the quantity. E.g.'kWh' or 'PCS' for pieces.
units int64 The whole units of the quantity.
For example if unit is "PCS", then 1 unit is one piece.
nanos int32 Number of nano (10^-9) units of the quantity.
The value must be between -999,999,999 and +999,999,999 inclusive.
If units is positive, nanos must be positive or zero.
If units is zero, nanos can be positive, zero, or negative.
If units is negative, nanos must be negative or zero.
For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

RecurringCost

Represents a price/cost that repeats at a fixed interval.

Field Type Rules Description
*price Price The price per interval.
*interval google.type.CalendarPeriod The interval at which the cost occurs (per day, month, etc.).

TenantScopedListRequest

Field Type Rules Description
*tenant string The tenant the list belongs to.
page_size int32 The maximum number of items to return. 0 for default.
page_token string The next_page_token value returned from a previous List request, if any.

TenantScopedResource

A tenant scoped resource.

Field Type Rules Description
*tenant string The tenant the resource belongs to.
*id string The ID of the resource.

TimeRange

A range of time with inclusive start, inclusive and exclusive end time. If both (inclusive and exclusive) ends are specified, they must be consistent. If no end is specified, the period is considered unbounded on the end.

Field Type Rules Description
start google.protobuf.Timestamp The inclusive start.
end google.protobuf.Timestamp The inclusive end.
end_exclusive google.protobuf.Timestamp The exclusive end.

File-level Extensions

Extension Type Base Number Description
throws string .google.protobuf.MethodOptions 76131 throws is used to document error messages that the method might return in status.details.

CalendarPeriod

A CalendarPeriod represents the abstract concept of a time period that has a canonical start. Grammatically, "the start of the current CalendarPeriod." All calendar times begin at midnight UTC.

Name Number Description
CALENDAR_PERIOD_UNSPECIFIED 0 Undefined period, raises an error.
DAY 1 A day.
WEEK 2 A week. Weeks begin on Monday, following
ISO 8601.
FORTNIGHT 3 A fortnight. The first calendar fortnight of the year begins at the start
of week 1 according to
ISO 8601.
MONTH 4 A month.
QUARTER 5 A quarter. Quarters start on dates 1-Jan, 1-Apr, 1-Jul, and 1-Oct of each
year.
HALF 6 A half-year. Half-years start on dates 1-Jan and 1-Jul.
YEAR 7 A year.

Date

Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following:

  • A full date, with non-zero year, month, and day values
  • A month and day value, with a zero year, such as an anniversary
  • A year on its own, with zero month and day values
  • A year and month value, with a zero day, such as a credit card expiration date

Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and google.protobuf.Timestamp.

Field Type Rules Description
year int32 Year of the date. Must be from 1 to 9999, or 0 to specify a date without
a year.
month int32 Month of a year. Must be from 1 to 12, or 0 to specify a year without a
month and day.
day int32 Day of a month. Must be from 1 to 31 and valid for the year and month, or 0
to specify a year by itself or a year and month where the day isn't
significant.

Money

Represents an amount of money with its currency type.

Field Type Rules Description
currency_code string The three-letter currency code defined in ISO 4217.
units int64 The whole units of the amount.
For example if currencyCode is "USD", then 1 unit is one US dollar.
nanos int32 Number of nano (10^-9) units of the amount.
The value must be between -999,999,999 and +999,999,999 inclusive.
If units is positive, nanos must be positive or zero.
If units is zero, nanos can be positive, zero, or negative.
If units is negative, nanos must be negative or zero.
For example $-1.75 is represented as units=-1 and nanos=-750,000,000.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)

Legend

*) required