Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/integrations/core-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ See the [API Changelog](/api/changelog) for the full history of additions and ch

Events follow a consistent structure with common metadata fields and event-specific payloads. Each event may include hydrated entity data from the entity graph.

An entity node is either a single object or a list. A contact can have several billing accounts and accounts, and a ticket can link several billing accounts. Events that start from a contact or a ticket therefore carry `billing_accounts` (and `CustomerDetailsUpdated` also carries `accounts`) with every related entity. The single `billing_account` and `account` fields stay for compatibility, but hold an arbitrary one of them when there are several, so read the list when your integration acts per billing account.

### Common Event Fields

All events include these fields:
Expand Down
11 changes: 10 additions & 1 deletion static/events/BillingAccountConnectionRemoved.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"event_name": "BillingAccountConnectionRemoved",
"event_title": "Disassociate Billing Account",
"event_description": "Customer request to disassociate a billing account from a contact",
"event_version": "1.0",
"event_version": "1.1",
"event_tags": [
"builtin",
"erp",
Expand Down Expand Up @@ -35,6 +35,11 @@
"id": "billing_account",
"schema": "billing_account",
"cardinality": "one"
},
{
"id": "billing_accounts",
"schema": "billing_account",
"cardinality": "many"
}
],
"edges": [
Expand All @@ -49,6 +54,10 @@
{
"from": "ticket",
"to": "billing_account"
},
{
"from": "ticket",
"to": "billing_accounts"
}
]
},
Expand Down
121 changes: 119 additions & 2 deletions static/events/BillingAccountConnectionRemoved.sample.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"_event_time": "1970-01-01T00:00:00.000Z",
"_event_id": "string",
"_event_name": "BillingAccountConnectionRemoved",
"_event_version": "1.0",
"_event_version": "1.1",
"_event_source": "string",
"_ack_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"_trigger_source_type": "api",
Expand Down Expand Up @@ -448,5 +448,122 @@
},
"_created_at": "1970-01-01T00:00:00.000Z",
"_updated_at": "1970-01-01T00:00:00.000Z"
}
},
"billing_accounts": [
{
"_schema": "billing_account",
"_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"_org": "123",
"_title": "John Doe",
"_tags": [
"family:label"
],
"billing_account_number": "string",
"balance_currency": "EUR",
"balance_decimal": "123.45",
"balance": 0,
"billing_contact": {
"$relation": [
{
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"_tags": [
"example"
]
}
]
},
"billing_address": {
"_tags": [
"billing"
],
"street": "Hauptstraße",
"street_number": "123",
"postal_code": "50668",
"city": "Cologne",
"country": "DE",
"additional_info": "string",
"company_name": "string",
"first_name": "string",
"last_name": "string",
"salutation": "string",
"title": "string",
"coordinates": "50.948484, 6.943147",
"plot_of_land": "string",
"plot_area": "string",
"start_date": "1970-01-01",
"end_date": "1970-01-01"
},
"payment_method": [
{
"type": "payment_sepa",
"data": {
"bank_name": "Deutsche Bank",
"iban": "DE89370400440532013000",
"bic_number": "DEUTDEFF",
"fullname": "John Doe"
}
}
],
"contracts": {
"$relation": [
{
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"_tags": [
"example"
]
}
]
},
"external_id": "string",
"workflows": {
"primary": {
"id": "string",
"definition_id": "string",
"name": "string",
"status": "STARTED",
"assignees": [
"string"
],
"progress": 0,
"phases_in_progress": [
{
"phase_id": "string",
"phase_name": "string",
"phase_progress": 0
}
],
"last_update_time": "1970-01-01T00:00:00.000Z",
"upcoming_tasks_assignees": [
"string"
],
"task_id": "string",
"task_name": "string",
"task_assignees": [
"string"
],
"task_duedate": "1970-01-01T00:00:00.000Z",
"task_execution_type": "MANUAL",
"task_status": "UNASSIGNED",
"phase_id": "string",
"phase_name": "string",
"phase_assignees": [
"string"
],
"phase_progress": 0
}
},
"_files": {
"$relation": [
{
"entity_id": "123e4567-e89b-12d3-a456-426614174000",
"_tags": [
"example"
]
}
]
},
"_created_at": "1970-01-01T00:00:00.000Z",
"_updated_at": "1970-01-01T00:00:00.000Z"
}
]
}
147 changes: 146 additions & 1 deletion static/events/BillingAccountConnectionRemoved.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
"_event_version": {
"type": "string",
"description": "Schema version number",
"example": "1.0"
"example": "1.1"
},
"_event_source": {
"type": "string",
Expand Down Expand Up @@ -759,6 +759,151 @@
}
},
"description": "billing_account entity (hydrated from entity graph)"
},
"billing_accounts": {
"type": "array",
"description": "Array of billing_account entities (hydrated from entity graph)",
"items": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"_schema"
],
"properties": {
"_schema": {
"readOnly": true,
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"example": "billing_account",
"description": "URL-friendly identifier for the entity schema"
},
"_id": {
"readOnly": true,
"type": "string",
"format": "uuid",
"example": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "Unique identifier for the entity"
},
"_org": {
"type": "string",
"description": "Organization Id the entity belongs to",
"readOnly": true,
"example": "123"
},
"_title": {
"readOnly": true,
"type": "string",
"nullable": true,
"example": "John Doe",
"description": "Generated title for the entity based on schema title_template"
},
"_tags": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"example": [
"family:label"
],
"description": "Entity Labels"
},
"billing_account_number": {
"type": "string",
"description": "Billing Account Number"
},
"balance_currency": {
"type": "string",
"description": "Three-letter ISO currency code, in lowercase. Must be a supported currency.",
"example": "EUR"
},
"balance_decimal": {
"type": "string",
"description": "The currency value as a decimal string",
"example": "123.45"
},
"balance": {
"type": "number",
"description": "Account Balance"
},
"billing_contact": {
"$ref": "#/definitions/BaseRelation",
"description": "Billing Contact"
},
"billing_address": {
"$ref": "#/definitions/AddressAttribute",
"description": "Billing Address"
},
"payment_method": {
"type": "array",
"items": {
"type": "object",
"description": "Payment method details",
"properties": {
"type": {
"type": "string",
"enum": [
"payment_sepa",
"payment_invoice",
"payment_cash"
],
"example": "payment_sepa"
},
"data": {
"type": "object",
"properties": {
"bank_name": {
"type": "string",
"example": "Deutsche Bank"
},
"iban": {
"type": "string",
"example": "DE89370400440532013000"
},
"bic_number": {
"type": "string",
"example": "DEUTDEFF"
},
"fullname": {
"type": "string",
"example": "John Doe"
}
}
}
}
},
"description": "Payment Method"
},
"contracts": {
"$ref": "#/definitions/BaseRelation",
"description": "Contracts"
},
"external_id": {
"type": "string",
"description": "External ID"
},
"workflows": {
"$ref": "#/definitions/WorkflowOverview"
},
"_files": {
"$ref": "#/definitions/BaseRelation"
},
"_created_at": {
"readOnly": true,
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of entity creation"
},
"_updated_at": {
"readOnly": true,
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of entity last update"
}
}
}
}
},
"required": [
Expand Down
11 changes: 10 additions & 1 deletion static/events/ContractWithdrawalRequested.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"event_name": "ContractWithdrawalRequested",
"event_title": "Contract Withdrawal Request",
"event_description": "A customer withdrew from a contract (Widerruf), e.g. through the withdrawal function required by § 356a BGB. Explicitly triggered by Automation once the withdrawal ticket is complete.",
"event_version": "1.0",
"event_version": "1.1",
"event_tags": [
"builtin",
"erp",
Expand Down Expand Up @@ -57,6 +57,11 @@
"id": "billing_account",
"schema": "billing_account",
"cardinality": "one"
},
{
"id": "billing_accounts",
"schema": "billing_account",
"cardinality": "many"
}
],
"edges": [
Expand All @@ -79,6 +84,10 @@
{
"from": "ticket",
"to": "billing_account"
},
{
"from": "ticket",
"to": "billing_accounts"
}
]
},
Expand Down
Loading
Loading