@epilot/erp-integration-client 0.24.2 → 0.25.0

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.38.0",
+    "version": "0.40.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -2526,31 +2526,18 @@
           }
         }
       },
-      "Integration": {
+      "IntegrationEditableFields": {
         "type": "object",
-        "required": [
-          "id",
-          "orgId",
-          "name",
-          "created_at",
-          "updated_at"
-        ],
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Unique identifier for the integration"
-          },
-          "orgId": {
-            "type": "string",
-            "description": "Organization ID"
-          },
           "name": {
             "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
             "description": "Integration name"
           },
           "description": {
             "type": "string",
+            "maxLength": 1000,
             "description": "Optional description of the integration"
           },
           "access_token_ids": {
@@ -2574,94 +2561,68 @@
             },
             "description": "Configuration defining environment variables needed by this integration. Values are stored in the Environments API."
           },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the integration was created"
-          },
-          "updated_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the integration was last updated"
+          "settings": {
+            "$ref": "#/components/schemas/IntegrationSettings"
           }
         }
       },
-      "CreateIntegrationRequest": {
-        "type": "object",
-        "required": [
-          "name"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Integration name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 1000,
-            "description": "Optional description of the integration"
-          },
-          "access_token_ids": {
-            "type": "array",
-            "description": "List of access token IDs to associate with this integration",
-            "items": {
-              "type": "string"
-            }
-          },
-          "app_ids": {
-            "type": "array",
-            "description": "List of app IDs to associate with this integration",
-            "items": {
-              "type": "string"
+      "Integration": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "id",
+              "orgId",
+              "name",
+              "created_at",
+              "updated_at"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "format": "uuid",
+                "readOnly": true,
+                "description": "Unique identifier for the integration"
+              },
+              "orgId": {
+                "type": "string",
+                "readOnly": true,
+                "description": "Organization ID"
+              },
+              "created_at": {
+                "type": "string",
+                "format": "date-time",
+                "readOnly": true,
+                "description": "ISO-8601 timestamp when the integration was created"
+              },
+              "updated_at": {
+                "type": "string",
+                "format": "date-time",
+                "readOnly": true,
+                "description": "ISO-8601 timestamp when the integration was last updated"
+              }
             }
           },
-          "environment_config": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/EnvironmentFieldConfig"
-            },
-            "description": "Configuration defining environment variables needed by this integration"
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
           }
-        }
+        ]
       },
-      "UpdateIntegrationRequest": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Integration name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 1000,
-            "description": "Optional description of the integration"
-          },
-          "access_token_ids": {
-            "type": "array",
-            "description": "List of access token IDs to associate with this integration",
-            "items": {
-              "type": "string"
-            }
-          },
-          "app_ids": {
-            "type": "array",
-            "description": "List of app IDs to associate with this integration",
-            "items": {
-              "type": "string"
-            }
+      "CreateIntegrationRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
           },
-          "environment_config": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/EnvironmentFieldConfig"
-            },
-            "description": "Configuration defining environment variables needed by this integration"
+          {
+            "type": "object",
+            "required": [
+              "name"
+            ]
           }
-        }
+        ]
+      },
+      "UpdateIntegrationRequest": {
+        "$ref": "#/components/schemas/IntegrationEditableFields"
       },
       "EnvironmentFieldConfig": {
         "type": "object",
@@ -2707,6 +2668,36 @@
           }
         }
       },
+      "IntegrationSettings": {
+        "type": "object",
+        "description": "Settings for the integration",
+        "properties": {
+          "autoRefresh": {
+            "$ref": "#/components/schemas/AutoRefreshSettings"
+          }
+        }
+      },
+      "AutoRefreshSettings": {
+        "type": "object",
+        "description": "Auto-refresh settings for keeping integration data fresh",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether auto-refresh is enabled"
+          },
+          "freshnessThresholdMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum age (in minutes) of data before it is considered stale and eligible for refresh"
+          },
+          "minIntervalBetweenSyncsMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Minimum interval (in minutes) between consecutive sync operations to prevent excessive API calls"
+          }
+        }
+      },
       "SetIntegrationAppMappingRequest": {
         "type": "object",
         "required": [
@@ -2745,23 +2736,419 @@
           },
           "component_id": {
             "type": "string",
-            "format": "uuid",
-            "description": "UUID of the integration app component instance"
+            "format": "uuid",
+            "description": "UUID of the integration app component instance"
+          }
+        }
+      },
+      "IntegrationAppMapping": {
+        "type": "object",
+        "required": [
+          "integration_id"
+        ],
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The integration ID this app/component is mapped to"
+          }
+        }
+      },
+      "IntegrationWithUseCases": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Integration"
+          },
+          {
+            "type": "object",
+            "description": "Integration with embedded use cases for atomic CRUD operations",
+            "required": [
+              "use_cases"
+            ],
+            "properties": {
+              "use_cases": {
+                "type": "array",
+                "description": "All use cases belonging to this integration",
+                "items": {
+                  "$ref": "#/components/schemas/UseCase"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "UpsertIntegrationWithUseCasesRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
+          },
+          {
+            "type": "object",
+            "description": "Request to create or update an integration with embedded use cases (upsert).\nThis is a declarative operation - the request represents the desired state.\n",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "use_cases": {
+                "type": "array",
+                "description": "Full list of use cases (declarative). This replaces ALL existing use cases.\n- Use cases with an `id` field matching an existing use case will be updated\n- Use cases without an `id` or with a non-matching `id` will be created\n- Existing use cases not in this list will be deleted\n",
+                "items": {
+                  "$ref": "#/components/schemas/EmbeddedUseCaseRequest"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "InboundIntegrationEventConfiguration": {
+        "type": "object",
+        "description": "Configuration for inbound use cases (ERP to epilot)",
+        "properties": {
+          "entities": {
+            "type": "array",
+            "description": "Array of entity configurations for this event",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntity"
+            }
+          },
+          "meter_readings": {
+            "type": "array",
+            "description": "Array of meter reading configurations for this event",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationMeterReading"
+            }
+          }
+        }
+      },
+      "OutboundIntegrationEventConfiguration": {
+        "type": "object",
+        "required": [
+          "event_catalog_event",
+          "mappings"
+        ],
+        "description": "Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.",
+        "properties": {
+          "event_catalog_event": {
+            "type": "string",
+            "description": "The Event Catalog event name that triggers this outbound flow",
+            "example": "contract.created"
+          },
+          "mappings": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "#/components/schemas/OutboundMapping"
+            },
+            "description": "List of mappings that transform and deliver the event"
+          }
+        }
+      },
+      "IntegrationEntity": {
+        "type": "object",
+        "required": [
+          "entity_schema",
+          "unique_ids",
+          "fields"
+        ],
+        "properties": {
+          "entity_schema": {
+            "type": "string",
+            "description": "Target entity schema (e.g., 'contact', 'contract')"
+          },
+          "unique_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of attribute names that uniquely identify this entity.\nThe _type hint for repeatable fields (e.g., email, phone) should be specified\non the corresponding field definition in the fields array.\n"
+          },
+          "jsonataExpression": {
+            "type": "string",
+            "description": "Optional JSONata expression to pre-process the event data before field mapping"
+          },
+          "enabled": {
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "Controls whether this entity mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean."
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "upsert",
+              "delete",
+              "purge",
+              "upsert-prune-scope-purge",
+              "upsert-prune-scope-delete"
+            ],
+            "default": "upsert",
+            "description": "Operation mode for entity mapping:\n- 'upsert': Create or update the entity (default)\n- 'delete': Soft delete the entity (marks as deleted)\n- 'purge': Hard delete the entity (permanent removal)\n- 'upsert-prune-scope-purge': Upsert entities from array, then purge entities in scope that weren't upserted\n- 'upsert-prune-scope-delete': Upsert entities from array, then soft delete entities in scope that weren't upserted\n"
+          },
+          "scope": {
+            "$ref": "#/components/schemas/PruneScopeConfig"
+          },
+          "fields": {
+            "type": "array",
+            "description": "Field mapping definitions",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntityField"
+            }
+          }
+        }
+      },
+      "IntegrationMeterReading": {
+        "type": "object",
+        "required": [
+          "meter",
+          "fields"
+        ],
+        "properties": {
+          "jsonataExpression": {
+            "type": "string",
+            "description": "Optional JSONata expression to extract meter reading items from the event data.\nIf not provided, the entire payload is used as the reading data.\nUseful when you need to extract an array of readings from a nested structure (e.g., \"$.readings\").\n"
+          },
+          "reading_matching": {
+            "type": "string",
+            "enum": [
+              "external_id",
+              "strict-date"
+            ],
+            "default": "external_id",
+            "description": "Strategy for matching incoming readings against existing readings.\n- 'external_id': Match readings by external_id attribute (default behavior)\n- 'strict-date': Match by meter_id + counter_id + direction + date (German timezone).\n  Useful when readings originate from ECP and are echoed back by the ERP with truncated timestamps.\n"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "upsert",
+              "delete",
+              "upsert-prune-scope"
+            ],
+            "default": "upsert",
+            "description": "Operation mode for meter reading mapping:\n- 'upsert': Create or update meter readings (default)\n- 'delete': Delete the meter reading\n- 'upsert-prune-scope': Upsert readings from array, then delete all other readings for the same meter+counter that weren't upserted\n"
+          },
+          "scope": {
+            "$ref": "#/components/schemas/MeterReadingPruneScopeConfig"
+          },
+          "meter": {
+            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
+          },
+          "meter_counter": {
+            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
+          },
+          "fields": {
+            "type": "array",
+            "description": "Field mapping definitions for meter reading attributes",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntityField"
+            }
+          }
+        }
+      },
+      "PruneScopeConfig": {
+        "type": "object",
+        "description": "Scope configuration for upsert-prune-scope modes.\nDefines how to find entities that should be pruned if not in the upsert payload.\nThe scope is resolved against the original event payload (not individual array items).\n",
+        "required": [
+          "scope_mode"
+        ],
+        "properties": {
+          "scope_mode": {
+            "type": "string",
+            "enum": [
+              "relations",
+              "query"
+            ],
+            "description": "Scope mode for finding entities to prune:\n- 'relations': Find scope by looking at all entities related to a specific entity (both direct and reverse relations)\n- 'query': Find scope entities directly via query parameters\n"
+          },
+          "schema": {
+            "type": "string",
+            "description": "For 'relations' mode: The schema of the entity to find (e.g., 'billing_account').\nNot used for 'query' mode.\n"
+          },
+          "unique_ids": {
+            "type": "array",
+            "description": "For 'relations' mode: How to identify the scope entity from the payload.\nNot used for 'query' mode.\n",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          },
+          "query": {
+            "type": "array",
+            "description": "For 'query' mode: Direct query parameters to find scope entities.\nNot used for 'relations' or 'reverse-relations' modes.\n",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          }
+        }
+      },
+      "MeterReadingPruneScopeConfig": {
+        "type": "object",
+        "description": "Scope configuration for meter reading upsert-prune-scope mode.\nThe scope is all readings for the same meter + counter.\n",
+        "properties": {
+          "source": {
+            "type": "string",
+            "description": "Optional source filter. When set, only readings with this source\nare eligible for pruning (e.g., 'ERP' to only prune ERP-synced readings).\n"
+          }
+        }
+      },
+      "MeterUniqueIdsConfig": {
+        "type": "object",
+        "required": [
+          "unique_ids"
+        ],
+        "properties": {
+          "unique_ids": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Array of unique identifier field mappings",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          }
+        }
+      },
+      "IntegrationEntityField": {
+        "type": "object",
+        "required": [
+          "attribute"
+        ],
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "Target attribute name"
+          },
+          "field": {
+            "type": "string",
+            "description": "Source field name or JSONPath expression (if starts with $)"
+          },
+          "jsonataExpression": {
+            "type": "string",
+            "description": "JSONata expression for transformation"
+          },
+          "constant": {
+            "description": "Constant value to assign (any type)"
+          },
+          "_type": {
+            "$ref": "#/components/schemas/RepeatableFieldType"
+          },
+          "enabled": {
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "Controls whether this field mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. Defaults to true if omitted."
+          },
+          "relations": {
+            "$ref": "#/components/schemas/RelationConfig"
+          },
+          "relation_refs": {
+            "$ref": "#/components/schemas/RelationRefsConfig"
+          }
+        }
+      },
+      "EmbeddedUseCaseRequest": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedInboundUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
+            "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+          }
+        }
+      },
+      "EmbeddedUseCaseRequestBase": {
+        "type": "object",
+        "required": [
+          "name",
+          "type",
+          "enabled"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional use case ID for update matching.\n- If provided and matches an existing use case, that use case is updated\n- If provided but no match, a new use case with this ID is created\n- If omitted, a new use case with auto-generated ID is created\n"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Use case name"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the use case is enabled"
+          },
+          "change_description": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Optional description of this change (like a commit message)"
           }
         }
       },
-      "IntegrationAppMapping": {
-        "type": "object",
-        "required": [
-          "integration_id"
-        ],
-        "properties": {
-          "integration_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "The integration ID this app/component is mapped to"
+      "EmbeddedInboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            }
           }
-        }
+        ]
+      },
+      "EmbeddedOutboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
       },
       "UseCaseBase": {
         "type": "object",
@@ -2793,7 +3180,8 @@
             "type": "string",
             "enum": [
               "inbound",
-              "outbound"
+              "outbound",
+              "file_proxy"
             ],
             "description": "Use case type"
           },
@@ -2867,6 +3255,31 @@
           }
         ]
       },
+      "FileProxyUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
       "UseCase": {
         "oneOf": [
           {
@@ -2874,13 +3287,17 @@
           },
           {
             "$ref": "#/components/schemas/OutboundUseCase"
+          },
+          {
+            "$ref": "#/components/schemas/FileProxyUseCase"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
             "inbound": "#/components/schemas/InboundUseCase",
-            "outbound": "#/components/schemas/OutboundUseCase"
+            "outbound": "#/components/schemas/OutboundUseCase",
+            "file_proxy": "#/components/schemas/FileProxyUseCase"
           }
         }
       },
@@ -2891,13 +3308,17 @@
           },
           {
             "$ref": "#/components/schemas/CreateOutboundUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/CreateFileProxyUseCaseRequest"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
             "inbound": "#/components/schemas/CreateInboundUseCaseRequest",
-            "outbound": "#/components/schemas/CreateOutboundUseCaseRequest"
+            "outbound": "#/components/schemas/CreateOutboundUseCaseRequest",
+            "file_proxy": "#/components/schemas/CreateFileProxyUseCaseRequest"
           }
         }
       },
@@ -2971,6 +3392,31 @@
           }
         ]
       },
+      "CreateFileProxyUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
       "UpdateUseCaseRequest": {
         "oneOf": [
           {
@@ -2978,13 +3424,17 @@
           },
           {
             "$ref": "#/components/schemas/UpdateOutboundUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateFileProxyUseCaseRequest"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
             "inbound": "#/components/schemas/UpdateInboundUseCaseRequest",
-            "outbound": "#/components/schemas/UpdateOutboundUseCaseRequest"
+            "outbound": "#/components/schemas/UpdateOutboundUseCaseRequest",
+            "file_proxy": "#/components/schemas/UpdateFileProxyUseCaseRequest"
           }
         }
       },
@@ -3052,6 +3502,28 @@
           }
         ]
       },
+      "UpdateFileProxyUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
       "UseCaseHistoryEntry": {
         "oneOf": [
           {
@@ -3059,13 +3531,17 @@
           },
           {
             "$ref": "#/components/schemas/OutboundUseCaseHistoryEntry"
+          },
+          {
+            "$ref": "#/components/schemas/FileProxyUseCaseHistoryEntry"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
             "inbound": "#/components/schemas/InboundUseCaseHistoryEntry",
-            "outbound": "#/components/schemas/OutboundUseCaseHistoryEntry"
+            "outbound": "#/components/schemas/OutboundUseCaseHistoryEntry",
+            "file_proxy": "#/components/schemas/FileProxyUseCaseHistoryEntry"
           }
         }
       },
@@ -3175,7 +3651,193 @@
               }
             }
           }
-        ]
+        ]
+      },
+      "FileProxyUseCaseHistoryEntry": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "FileProxyUseCaseConfiguration": {
+        "type": "object",
+        "required": [
+          "steps",
+          "response"
+        ],
+        "description": "Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.\n\nThe file proxy download URL always requires `orgId`, `integrationId`, and `useCaseId` as query parameters.\nThe `orgId` is included in the signed URL to establish organization context without requiring authentication.\nAdditional use-case-specific parameters are declared in the `params` array.\n",
+        "properties": {
+          "requires_vpc": {
+            "type": "boolean",
+            "description": "Whether requests require VPC routing for IP allowlisting",
+            "default": false
+          },
+          "auth": {
+            "$ref": "#/components/schemas/FileProxyAuth"
+          },
+          "params": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FileProxyParam"
+            },
+            "description": "Additional use-case-specific parameters expected in the download URL query string (beyond the required orgId, integrationId, useCaseId)"
+          },
+          "steps": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "#/components/schemas/FileProxyStep"
+            },
+            "description": "Ordered list of HTTP steps to execute to retrieve the file"
+          },
+          "response": {
+            "$ref": "#/components/schemas/FileProxyResponseConfig"
+          }
+        }
+      },
+      "FileProxyAuth": {
+        "type": "object",
+        "required": [
+          "type",
+          "token_url",
+          "client_id",
+          "client_secret"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "oauth2_client_credentials"
+            ],
+            "description": "Authentication type"
+          },
+          "token_url": {
+            "type": "string",
+            "description": "Handlebars template for the OAuth2 token endpoint URL"
+          },
+          "client_id": {
+            "type": "string",
+            "description": "Handlebars template for the OAuth2 client ID"
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "Handlebars template for the OAuth2 client secret"
+          },
+          "scope": {
+            "type": "string",
+            "description": "Optional OAuth2 scope"
+          }
+        }
+      },
+      "FileProxyParam": {
+        "type": "object",
+        "required": [
+          "name",
+          "required"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Parameter name as it appears in the query string"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Whether this parameter is required"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of the parameter"
+          }
+        }
+      },
+      "FileProxyStep": {
+        "type": "object",
+        "required": [
+          "url",
+          "method",
+          "response_type"
+        ],
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Handlebars template for the request URL"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST"
+            ],
+            "description": "HTTP method"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Handlebars templates for request headers"
+          },
+          "body": {
+            "type": "string",
+            "description": "Handlebars template for the request body (POST only)"
+          },
+          "response_type": {
+            "type": "string",
+            "enum": [
+              "json",
+              "binary"
+            ],
+            "description": "Expected response type"
+          }
+        }
+      },
+      "FileProxyResponseConfig": {
+        "type": "object",
+        "required": [
+          "body",
+          "encoding"
+        ],
+        "properties": {
+          "body": {
+            "type": "string",
+            "description": "JSONata expression to extract file content from step results"
+          },
+          "encoding": {
+            "type": "string",
+            "enum": [
+              "base64",
+              "binary"
+            ],
+            "description": "Encoding of the extracted body"
+          },
+          "filename": {
+            "type": "string",
+            "description": "JSONata expression to extract the filename"
+          },
+          "content_type": {
+            "type": "string",
+            "description": "JSONata expression to extract the content type"
+          }
+        }
       },
       "MappingSimulationRequest": {
         "type": "object",
@@ -3468,49 +4130,6 @@
           }
         }
       },
-      "InboundIntegrationEventConfiguration": {
-        "type": "object",
-        "description": "Configuration for inbound use cases (ERP to epilot)",
-        "properties": {
-          "entities": {
-            "type": "array",
-            "description": "Array of entity configurations for this event",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationEntity"
-            }
-          },
-          "meter_readings": {
-            "type": "array",
-            "description": "Array of meter reading configurations for this event",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationMeterReading"
-            }
-          }
-        }
-      },
-      "OutboundIntegrationEventConfiguration": {
-        "type": "object",
-        "required": [
-          "event_catalog_event",
-          "mappings"
-        ],
-        "description": "Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.",
-        "properties": {
-          "event_catalog_event": {
-            "type": "string",
-            "description": "The Event Catalog event name that triggers this outbound flow",
-            "example": "contract.created"
-          },
-          "mappings": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-              "$ref": "#/components/schemas/OutboundMapping"
-            },
-            "description": "List of mappings that transform and deliver the event"
-          }
-        }
-      },
       "OutboundMapping": {
         "type": "object",
         "required": [
@@ -3638,279 +4257,69 @@
               "$ref": "#/components/schemas/WebhookStatus"
             }
           },
-          "status": {
-            "type": "string",
-            "enum": [
-              "ok",
-              "conflict",
-              "disabled"
-            ],
-            "description": "Overall status of the use case:\n- 'ok': Use case is enabled and all dependencies are properly configured\n- 'conflict': Use case has configuration issues (disabled events/webhooks while enabled)\n- 'disabled': Use case is disabled\n"
-          },
-          "conflicts": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/OutboundConflict"
-            },
-            "description": "List of detected conflicts, if any"
-          }
-        }
-      },
-      "WebhookStatus": {
-        "type": "object",
-        "required": [
-          "webhookId"
-        ],
-        "properties": {
-          "webhookId": {
-            "type": "string",
-            "description": "Unique identifier for the webhook"
-          },
-          "webhookName": {
-            "type": "string",
-            "description": "Human-readable name of the webhook"
-          },
-          "enabled": {
-            "type": "boolean",
-            "nullable": true,
-            "description": "Whether the webhook is enabled. Null if the API is unreachable."
-          }
-        }
-      },
-      "OutboundConflict": {
-        "type": "object",
-        "required": [
-          "type",
-          "message"
-        ],
-        "properties": {
-          "type": {
-            "type": "string",
-            "enum": [
-              "event_disabled",
-              "all_webhooks_disabled",
-              "event_enabled_while_disabled",
-              "webhook_enabled_while_disabled"
-            ],
-            "description": "Type of conflict:\n- 'event_disabled': Event catalog event is disabled while use case is enabled\n- 'all_webhooks_disabled': All webhooks are disabled while use case is enabled\n- 'event_enabled_while_disabled': Event is enabled while use case is disabled\n- 'webhook_enabled_while_disabled': A webhook is enabled while use case is disabled\n"
-          },
-          "webhookId": {
-            "type": "string",
-            "description": "Webhook ID (only present for webhook_enabled_while_disabled conflicts)"
-          },
-          "message": {
-            "type": "string",
-            "description": "Human-readable description of the conflict"
-          }
-        }
-      },
-      "IntegrationEntity": {
-        "type": "object",
-        "required": [
-          "entity_schema",
-          "unique_ids",
-          "fields"
-        ],
-        "properties": {
-          "entity_schema": {
-            "type": "string",
-            "description": "Target entity schema (e.g., 'contact', 'contract')"
-          },
-          "unique_ids": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Array of attribute names that uniquely identify this entity.\nThe _type hint for repeatable fields (e.g., email, phone) should be specified\non the corresponding field definition in the fields array.\n"
-          },
-          "jsonataExpression": {
-            "type": "string",
-            "description": "Optional JSONata expression to pre-process the event data before field mapping"
-          },
-          "enabled": {
-            "oneOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "string"
-              }
-            ],
-            "description": "Controls whether this entity mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean."
-          },
-          "mode": {
-            "type": "string",
-            "enum": [
-              "upsert",
-              "delete",
-              "purge",
-              "upsert-prune-scope-purge",
-              "upsert-prune-scope-delete"
-            ],
-            "default": "upsert",
-            "description": "Operation mode for entity mapping:\n- 'upsert': Create or update the entity (default)\n- 'delete': Soft delete the entity (marks as deleted)\n- 'purge': Hard delete the entity (permanent removal)\n- 'upsert-prune-scope-purge': Upsert entities from array, then purge entities in scope that weren't upserted\n- 'upsert-prune-scope-delete': Upsert entities from array, then soft delete entities in scope that weren't upserted\n"
-          },
-          "scope": {
-            "$ref": "#/components/schemas/PruneScopeConfig"
-          },
-          "fields": {
-            "type": "array",
-            "description": "Field mapping definitions",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationEntityField"
-            }
-          }
-        }
-      },
-      "PruneScopeConfig": {
-        "type": "object",
-        "description": "Scope configuration for upsert-prune-scope modes.\nDefines how to find entities that should be pruned if not in the upsert payload.\nThe scope is resolved against the original event payload (not individual array items).\n",
-        "required": [
-          "scope_mode"
-        ],
-        "properties": {
-          "scope_mode": {
-            "type": "string",
-            "enum": [
-              "relations",
-              "query"
-            ],
-            "description": "Scope mode for finding entities to prune:\n- 'relations': Find scope by looking at all entities related to a specific entity (both direct and reverse relations)\n- 'query': Find scope entities directly via query parameters\n"
-          },
-          "schema": {
-            "type": "string",
-            "description": "For 'relations' mode: The schema of the entity to find (e.g., 'billing_account').\nNot used for 'query' mode.\n"
-          },
-          "unique_ids": {
-            "type": "array",
-            "description": "For 'relations' mode: How to identify the scope entity from the payload.\nNot used for 'query' mode.\n",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
-          },
-          "query": {
-            "type": "array",
-            "description": "For 'query' mode: Direct query parameters to find scope entities.\nNot used for 'relations' or 'reverse-relations' modes.\n",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
-          }
-        }
-      },
-      "MeterReadingPruneScopeConfig": {
-        "type": "object",
-        "description": "Scope configuration for meter reading upsert-prune-scope mode.\nThe scope is all readings for the same meter + counter.\n",
-        "properties": {
-          "source": {
-            "type": "string",
-            "description": "Optional source filter. When set, only readings with this source\nare eligible for pruning (e.g., 'ERP' to only prune ERP-synced readings).\n"
-          }
-        }
-      },
-      "IntegrationMeterReading": {
-        "type": "object",
-        "required": [
-          "meter",
-          "fields"
-        ],
-        "properties": {
-          "jsonataExpression": {
-            "type": "string",
-            "description": "Optional JSONata expression to extract meter reading items from the event data.\nIf not provided, the entire payload is used as the reading data.\nUseful when you need to extract an array of readings from a nested structure (e.g., \"$.readings\").\n"
-          },
-          "reading_matching": {
-            "type": "string",
-            "enum": [
-              "external_id",
-              "strict-date"
-            ],
-            "default": "external_id",
-            "description": "Strategy for matching incoming readings against existing readings.\n- 'external_id': Match readings by external_id attribute (default behavior)\n- 'strict-date': Match by meter_id + counter_id + direction + date (German timezone).\n  Useful when readings originate from ECP and are echoed back by the ERP with truncated timestamps.\n"
-          },
-          "mode": {
-            "type": "string",
-            "enum": [
-              "upsert",
-              "delete",
-              "upsert-prune-scope"
-            ],
-            "default": "upsert",
-            "description": "Operation mode for meter reading mapping:\n- 'upsert': Create or update meter readings (default)\n- 'delete': Delete the meter reading\n- 'upsert-prune-scope': Upsert readings from array, then delete all other readings for the same meter+counter that weren't upserted\n"
-          },
-          "scope": {
-            "$ref": "#/components/schemas/MeterReadingPruneScopeConfig"
-          },
-          "meter": {
-            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
-          },
-          "meter_counter": {
-            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
-          },
-          "fields": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict",
+              "disabled"
+            ],
+            "description": "Overall status of the use case:\n- 'ok': Use case is enabled and all dependencies are properly configured\n- 'conflict': Use case has configuration issues (disabled events/webhooks while enabled)\n- 'disabled': Use case is disabled\n"
+          },
+          "conflicts": {
             "type": "array",
-            "description": "Field mapping definitions for meter reading attributes",
             "items": {
-              "$ref": "#/components/schemas/IntegrationEntityField"
-            }
+              "$ref": "#/components/schemas/OutboundConflict"
+            },
+            "description": "List of detected conflicts, if any"
           }
         }
       },
-      "MeterUniqueIdsConfig": {
+      "WebhookStatus": {
         "type": "object",
         "required": [
-          "unique_ids"
+          "webhookId"
         ],
         "properties": {
-          "unique_ids": {
-            "type": "array",
-            "minItems": 1,
-            "description": "Array of unique identifier field mappings",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
+          "webhookId": {
+            "type": "string",
+            "description": "Unique identifier for the webhook"
+          },
+          "webhookName": {
+            "type": "string",
+            "description": "Human-readable name of the webhook"
+          },
+          "enabled": {
+            "type": "boolean",
+            "nullable": true,
+            "description": "Whether the webhook is enabled. Null if the API is unreachable."
           }
         }
       },
-      "IntegrationEntityField": {
+      "OutboundConflict": {
         "type": "object",
         "required": [
-          "attribute"
+          "type",
+          "message"
         ],
         "properties": {
-          "attribute": {
+          "type": {
             "type": "string",
-            "description": "Target attribute name"
+            "enum": [
+              "event_disabled",
+              "all_webhooks_disabled",
+              "event_enabled_while_disabled",
+              "webhook_enabled_while_disabled"
+            ],
+            "description": "Type of conflict:\n- 'event_disabled': Event catalog event is disabled while use case is enabled\n- 'all_webhooks_disabled': All webhooks are disabled while use case is enabled\n- 'event_enabled_while_disabled': Event is enabled while use case is disabled\n- 'webhook_enabled_while_disabled': A webhook is enabled while use case is disabled\n"
           },
-          "field": {
+          "webhookId": {
             "type": "string",
-            "description": "Source field name or JSONPath expression (if starts with $)"
+            "description": "Webhook ID (only present for webhook_enabled_while_disabled conflicts)"
           },
-          "jsonataExpression": {
+          "message": {
             "type": "string",
-            "description": "JSONata expression for transformation"
-          },
-          "constant": {
-            "description": "Constant value to assign (any type)"
-          },
-          "_type": {
-            "$ref": "#/components/schemas/RepeatableFieldType"
-          },
-          "enabled": {
-            "oneOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "string"
-              }
-            ],
-            "description": "Controls whether this field mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. Defaults to true if omitted."
-          },
-          "relations": {
-            "$ref": "#/components/schemas/RelationConfig"
-          },
-          "relation_refs": {
-            "$ref": "#/components/schemas/RelationRefsConfig"
+            "description": "Human-readable description of the conflict"
           }
         }
       },
@@ -4095,192 +4504,6 @@
         ],
         "description": "Type hint for repeatable fields that require special search handling.\nThese fields are stored as arrays of objects (e.g., email: [{ email: \"value\" }]).\n"
       },
-      "IntegrationWithUseCases": {
-        "type": "object",
-        "description": "Integration with embedded use cases for atomic CRUD operations",
-        "required": [
-          "id",
-          "orgId",
-          "name",
-          "use_cases",
-          "created_at",
-          "updated_at"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Unique identifier for the integration"
-          },
-          "orgId": {
-            "type": "string",
-            "description": "Organization ID"
-          },
-          "name": {
-            "type": "string",
-            "description": "Integration name"
-          },
-          "description": {
-            "type": "string",
-            "description": "Optional description of the integration"
-          },
-          "access_token_ids": {
-            "type": "array",
-            "description": "List of access token IDs associated with this integration",
-            "items": {
-              "type": "string"
-            }
-          },
-          "use_cases": {
-            "type": "array",
-            "description": "All use cases belonging to this integration",
-            "items": {
-              "$ref": "#/components/schemas/UseCase"
-            }
-          },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the integration was created"
-          },
-          "updated_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the integration was last updated"
-          }
-        }
-      },
-      "UpsertIntegrationWithUseCasesRequest": {
-        "type": "object",
-        "description": "Request to create or update an integration with embedded use cases (upsert).\nThis is a declarative operation - the request represents the desired state.\n",
-        "required": [
-          "name"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Integration name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 1000,
-            "description": "Optional description of the integration"
-          },
-          "access_token_ids": {
-            "type": "array",
-            "description": "List of access token IDs to associate with this integration",
-            "items": {
-              "type": "string"
-            }
-          },
-          "use_cases": {
-            "type": "array",
-            "description": "Full list of use cases (declarative). This replaces ALL existing use cases.\n- Use cases with an `id` field matching an existing use case will be updated\n- Use cases without an `id` or with a non-matching `id` will be created\n- Existing use cases not in this list will be deleted\n",
-            "items": {
-              "$ref": "#/components/schemas/EmbeddedUseCaseRequest"
-            }
-          }
-        }
-      },
-      "EmbeddedUseCaseRequest": {
-        "oneOf": [
-          {
-            "$ref": "#/components/schemas/EmbeddedInboundUseCaseRequest"
-          },
-          {
-            "$ref": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
-          }
-        ],
-        "discriminator": {
-          "propertyName": "type",
-          "mapping": {
-            "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
-            "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
-          }
-        }
-      },
-      "EmbeddedUseCaseRequestBase": {
-        "type": "object",
-        "required": [
-          "name",
-          "type",
-          "enabled"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Optional use case ID for update matching.\n- If provided and matches an existing use case, that use case is updated\n- If provided but no match, a new use case with this ID is created\n- If omitted, a new use case with auto-generated ID is created\n"
-          },
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Use case name"
-          },
-          "enabled": {
-            "type": "boolean",
-            "description": "Whether the use case is enabled"
-          },
-          "change_description": {
-            "type": "string",
-            "maxLength": 2000,
-            "description": "Optional description of this change (like a commit message)"
-          }
-        }
-      },
-      "EmbeddedInboundUseCaseRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
-          },
-          {
-            "type": "object",
-            "required": [
-              "type"
-            ],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "inbound"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
-              }
-            }
-          }
-        ]
-      },
-      "EmbeddedOutboundUseCaseRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
-          },
-          {
-            "type": "object",
-            "required": [
-              "type"
-            ],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "outbound"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
-              }
-            }
-          }
-        ]
-      },
       "ReplayEventsRequest": {
         "type": "object",
         "required": [