@epilot/pricing-client 3.35.0 → 3.35.1-alpha.0

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Pricing API",
-    "description": "The `pricing-api` hub sets the foundations for the following Pricing APIs:\n\n### Order API\nThis api enables the management of orders in epilot 360, providing features such as:\n - Automatic calculation of totals and price breakdowns for taxes on the Order entity\n - Product and pricing data validation\n\n### Shopping Cart API\nUsed to interact with a cart during a customer's checkout session, providing:\n - An unified data model to model a Shopping Cart\n - Product and pricing data validation\n - Checkout a cart into an order or quote\n\n### Catalog API\nProvides a way to query the entire catalog of products and prices.\n\n### Availability API\nProvides endpoints for querying products availability by a set of predefined dimensions.\n\n### External Integrations API\nProvides endpoints for external integrations (e.g. Enet / GetAG).\n",
+    "description": "The `pricing-api` hub sets the foundations for the following Pricing APIs:\n\n### Order API\nThis api enables the management of orders in epilot 360, providing features such as:\n - Automatic calculation of totals and price breakdowns for taxes on the Order entity\n - Product and pricing data validation\n\n### Shopping Cart API\nUsed to interact with a cart during a customer's checkout session, providing:\n - An unified data model to model a Shopping Cart\n - Product and pricing data validation\n - Checkout a cart into an order or quote\n\n### Catalog API\nProvides a way to query the entire catalog of products and prices.\n\n### Availability API\nProvides endpoints for querying products availability by a set of predefined dimensions.\n\n### External Integrations API\nProvides endpoints for external integrations.\n",
     "version": "1.0.0",
     "termsOfService": "https://epilot.cloud/agb",
     "contact": {
@@ -30,7 +30,7 @@
     },
     {
       "name": "External Integrations API",
-      "description": "Provides endpoints for external integrations (e.g. Enet / GetAG).\n"
+      "description": "Provides endpoints for external integrations.\n"
     },
     {
       "name": "Deprecated Endpoints",
@@ -867,7 +867,6 @@
         "operationId": "$availabilityCheck",
         "summary": "availabilityCheck",
         "security": [
-          {},
           {
             "EpilotPublicAuth": []
           }
@@ -1063,6 +1062,81 @@
         }
       }
     },
+    "/v1/public/integration/{integrationId}/external-catalog": {
+      "post": {
+        "description": "Returns the list of available products (including computed prices) based on a given context.",
+        "operationId": "$searchExternalCatalog",
+        "security": [
+          {},
+          {
+            "EpilotPublicAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "integrationId",
+            "description": "The integration identifier",
+            "schema": {
+              "$ref": "#/components/schemas/IntegrationId"
+            },
+            "required": true,
+            "example": "ikom"
+          }
+        ],
+        "summary": "searchExternalCatalog",
+        "tags": [
+          "External Integrations API"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchExternalCatalogParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The available products response payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SearchExternalCatalogResult"
+                },
+                "examples": {
+                  "External products": {
+                    "$ref": "#/components/examples/external-catalog-sample-1"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden, no credentials found for the given integration / organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/public/integration/{integrationId}/providers:search": {
       "post": {
         "description": "Returns the list of providers available based on a given location",
@@ -1566,8 +1640,8 @@
       "IntegrationId": {
         "type": "string",
         "enum": [
-          "enet",
-          "getag"
+          "getag",
+          "ikom"
         ]
       },
       "Error": {
@@ -3108,6 +3182,11 @@
             "description": "The password",
             "type": "string",
             "example": "123456"
+          },
+          "base_url": {
+            "description": "The Base API URL",
+            "type": "string",
+            "example": "https://api.example.com"
           }
         },
         "required": [
@@ -5127,6 +5206,482 @@
           "amount_tax",
           "unit_amount_decimal"
         ]
+      },
+      "SearchExternalCatalogParams": {
+        "type": "object",
+        "properties": {
+          "context": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/JourneyContext"
+              }
+            ]
+          }
+        },
+        "additionalProperties": false,
+        "required": [
+          "context"
+        ]
+      },
+      "JourneyContext": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "journey_id": {
+            "type": "string",
+            "description": "The ID of the journey.",
+            "example": "8d0a2235-97ce-42d0-88a3-e374634ca44e"
+          },
+          "journey_name": {
+            "type": "string",
+            "description": "The name of the journey.",
+            "example": "journey name"
+          },
+          "current_step_name": {
+            "description": "The name of the step where the products selection is happening.",
+            "type": "string",
+            "example": "step name"
+          },
+          "current_block_name": {
+            "type": "string",
+            "example": "block name",
+            "description": "The name of the block where the products selection is happening."
+          },
+          "steps_data": {
+            "type": "array",
+            "description": "The steps of the journey.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "step_name": {
+                  "type": "string",
+                  "description": "The name of the step."
+                },
+                "step_index": {
+                  "type": "integer",
+                  "description": "The index of the step."
+                },
+                "blocks": {
+                  "type": "object",
+                  "description": "The data of the blocks.",
+                  "additionalProperties": true,
+                  "example": {
+                    "Adresse": {
+                      "countryCode": "DE",
+                      "city": "Koblenz",
+                      "zipCode": "56068",
+                      "streetName": "Am Alten Hospital",
+                      "houseNumber": "123"
+                    }
+                  }
+                }
+              },
+              "additionalProperties": false,
+              "required": [
+                "step_name",
+                "step_index",
+                "blocks"
+              ]
+            }
+          }
+        },
+        "required": [
+          "journey_id",
+          "journey_name",
+          "current_step_name",
+          "current_block_name",
+          "steps_Data"
+        ]
+      },
+      "SearchExternalCatalogResult": {
+        "type": "object",
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExternalProduct"
+            }
+          }
+        },
+        "required": [
+          "results"
+        ]
+      },
+      "ExternalProduct": {
+        "type": "object",
+        "description": "An external product & price information (already computed) from an external catalog.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The ID of the product in the external catalog."
+          },
+          "name": {
+            "type": "string",
+            "description": "The name of the product."
+          },
+          "description": {
+            "type": "string",
+            "description": "A description of the product."
+          },
+          "features": {
+            "type": "array",
+            "description": "A list of features of the product.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "product_image_urls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of image URLs of the product. RECOMMENDED: Store files in Epilot for advantages such as resizing, versioning, easy access, and maintenance.\n"
+          },
+          "product_downloads_urls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of file/attachment URLs of the product RECOMMENDED: Store files in Epilot for advantages such as resizing, versioning, easy access, and maintenance.\n"
+          },
+          "legal_footnotes": {
+            "type": "string",
+            "description": "Legal footnotes for the product."
+          },
+          "additional_notes": {
+            "type": "array",
+            "description": "Additional notes for the product.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "recommendation_settings": {
+            "type": "object",
+            "description": "Recommendation settings for the product.",
+            "properties": {
+              "is_recommended": {
+                "type": "boolean",
+                "description": "Flag to enable or disable the recommendation for this product."
+              },
+              "recommended_label": {
+                "type": "string",
+                "description": "Label to display when the product is recommended."
+              }
+            },
+            "example": {
+              "is_recommended": true,
+              "recommended_label": "Best Value"
+            }
+          },
+          "price": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ExternalSimplePrice"
+              },
+              {
+                "$ref": "#/components/schemas/ExternalCompositePrice"
+              }
+            ]
+          }
+        },
+        "required": [
+          "price",
+          "name",
+          "id"
+        ]
+      },
+      "ExternalBasePrice": {
+        "type": "object",
+        "properties": {
+          "variable_price": {
+            "type": "boolean",
+            "description": "A flag to indicate if the price is variable.\n"
+          },
+          "unit": {
+            "description": "The unit of measurement used for display purposes and possibly for calculations when the price is variable.",
+            "type": "string",
+            "example": "kWh"
+          },
+          "currency": {
+            "type": "string",
+            "description": "The currency of the price. ISO 4217 currency code. E.g. EUR.",
+            "default": "EUR",
+            "example": "EUR"
+          },
+          "type": {
+            "type": "string",
+            "description": "The price type.",
+            "enum": [
+              "one_time",
+              "recurring"
+            ]
+          },
+          "billing_period": {
+            "$ref": "#/components/schemas/BillingPeriod",
+            "description": "The billing period of the price."
+          },
+          "unit_amount_gross_decimal": {
+            "type": "string",
+            "example": "1.19",
+            "description": "The unit gross amount value, as a string with all the decimal places."
+          },
+          "unit_amount_net_decimal": {
+            "type": "string",
+            "description": "The unit net amount value, as a string with all the decimal places.",
+            "example": "1.00"
+          },
+          "amount_subtotal_decimal": {
+            "type": "string",
+            "description": "Total of all items before discounts or taxes, as a string with all the decimal places.",
+            "example": "1.00"
+          },
+          "amount_total_decimal": {
+            "type": "string",
+            "description": "Total of all items after discounts and taxes, as a string with all the decimal places.",
+            "example": "1.19"
+          },
+          "tax": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "The tax name.",
+                "example": "VAT"
+              },
+              "description": {
+                "type": "string",
+                "description": "The tax description.",
+                "example": "Value Added Tax"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "VAT",
+                  "GST",
+                  "Custom"
+                ],
+                "description": "The type of the tax.",
+                "example": "VAT"
+              },
+              "rate": {
+                "type": "number",
+                "description": "The tax rate applied.",
+                "example": 19
+              },
+              "region": {
+                "type": "string",
+                "description": "The region code of the tax.",
+                "example": "DE"
+              },
+              "region_label": {
+                "type": "string",
+                "description": "The region label of the tax.",
+                "example": "Germany"
+              }
+            },
+            "required": [
+              "rate"
+            ]
+          },
+          "price_display_in_journeys": {
+            "type": "string",
+            "enum": [
+              "show_price",
+              "show_as_starting_price",
+              "show_as_on_request"
+            ],
+            "description": "The way the price should be displayed in the journeys."
+          },
+          "is_tax_inclusive": {
+            "type": "boolean",
+            "description": "A flag to indicate if the price is tax inclusive."
+          },
+          "fees": {
+            "type": "object",
+            "description": "Fees structure with static and variable amounts",
+            "properties": {
+              "billing_period": {
+                "$ref": "#/components/schemas/BillingPeriod",
+                "description": "The billing period of the fee values (e.g. monthly)."
+              },
+              "amount_total_decimal": {
+                "type": "string",
+                "example": "1.00"
+              },
+              "amount_static_decimal": {
+                "type": "string",
+                "example": "1.00"
+              },
+              "amount_variable_decimal": {
+                "type": "string",
+                "example": "1.00"
+              },
+              "breakdown": {
+                "type": "object",
+                "description": "Breakdown of the fee values",
+                "properties": {
+                  "static": {
+                    "type": "object",
+                    "description": "Static breakdown of fees",
+                    "additionalProperties": {
+                      "type": "object",
+                      "properties": {
+                        "amount_decimal": {
+                          "type": "string",
+                          "description": "The amount of the fee, as a string with all the decimal places.",
+                          "example": "1.00"
+                        }
+                      }
+                    },
+                    "required": [
+                      "amount_decimal"
+                    ]
+                  },
+                  "variable": {
+                    "type": "object",
+                    "description": "Variable breakdown of fees",
+                    "additionalProperties": {
+                      "type": "object",
+                      "properties": {
+                        "amount_decimal": {
+                          "type": "string",
+                          "example": "1.00"
+                        },
+                        "unit": {
+                          "type": "string",
+                          "description": "The unit of the fee (e.g. kWh) if applicable."
+                        }
+                      },
+                      "required": [
+                        "amount_decimal"
+                      ]
+                    }
+                  }
+                }
+              }
+            },
+            "required": [
+              "billing_period",
+              "amount_total_decimal",
+              "amount_static_decimal",
+              "amount_variable_decimal",
+              "breakdown"
+            ]
+          }
+        },
+        "required": [
+          "type",
+          "unit_amount_decimal",
+          "unit_amount_gross_decimal",
+          "unit_amount_net_decimal",
+          "amount_subtotal_decimal",
+          "amount_total_decimal"
+        ]
+      },
+      "ExternalSimplePrice": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/ExternalBasePrice"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "is_composite_price": {
+                "type": "boolean",
+                "enum": [
+                  false
+                ]
+              }
+            },
+            "required": [
+              "is_composite_price"
+            ]
+          }
+        ]
+      },
+      "ExternalCompositePrice": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/ExternalBasePrice"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "is_composite_price": {
+                "type": "boolean",
+                "enum": [
+                  true
+                ]
+              },
+              "price_components": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/ExternalSimplePrice"
+                }
+              },
+              "total_details": {
+                "$ref": "#/components/schemas/ExternalPriceTotalDetails"
+              }
+            },
+            "required": [
+              "is_composite_price",
+              "price_components",
+              "total_details"
+            ]
+          }
+        ]
+      },
+      "ExternalPriceTotalDetails": {
+        "type": "object",
+        "description": "Details of the total price including shipping and tax amounts.",
+        "properties": {
+          "breakdown": {
+            "type": "object",
+            "description": "A breakdown of the recurrences of amounts.",
+            "properties": {
+              "recurrences": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "description": "Recurrence details including subtotal, total, and tax amounts.",
+                  "properties": {
+                    "amount_subtotal_decimal": {
+                      "type": "string",
+                      "description": "Total of all items before discounts or taxes, as a string with all the decimal places.",
+                      "example": "1.00"
+                    },
+                    "amount_total_decimal": {
+                      "type": "string",
+                      "description": "Total of all items after discounts and taxes, as a string with all the decimal places.",
+                      "example": "1.19"
+                    },
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "one_time",
+                        "recurring"
+                      ],
+                      "description": "The price type.",
+                      "example": "one_time"
+                    },
+                    "billing_period": {
+                      "$ref": "#/components/schemas/BillingPeriod",
+                      "description": "The billing period of the price."
+                    }
+                  },
+                  "required": [
+                    "amount_subtotal_decimal",
+                    "amount_total_decimal",
+                    "type"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "breakdown"
+        ]
       }
     },
     "examples": {
@@ -6635,6 +7190,181 @@
             "_title": "Cool box"
           }
         }
+      },
+      "external-catalog-sample-1": {
+        "value": [
+          {
+            "id": "73f857a4-0fbc-4aa6-983f-87c0d6d410a6",
+            "name": "Home Energy Package",
+            "description": "Composite home energy solution with solar panels and battery",
+            "features": [
+              "4kW solar system",
+              "10kWh battery storage",
+              "Smart energy management"
+            ],
+            "product_image_urls": [
+              "https://example.com/images/home-energy-package.jpg"
+            ],
+            "legal_footnotes": "Installation and permitting fees may vary by location.",
+            "price": {
+              "is_composite_price": true,
+              "currency": "EUR",
+              "amount_subtotal_decimal": "419.110616246297",
+              "amount_total_decimal": "498.741633333333",
+              "price_display_in_journeys": "show_price",
+              "price_components": [
+                {
+                  "type": "recurring",
+                  "billing_period": "monthly",
+                  "is_tax_inclusive": true,
+                  "variable_price": true,
+                  "price_display_in_journeys": "show_price",
+                  "unit": "kWh",
+                  "amount_subtotal_decimal": "11.244355742297",
+                  "amount_total_decimal": "13.380783333333",
+                  "unit_amount_net_decimal": "11.24",
+                  "unit_amount_gross_decimal": "13.38",
+                  "currency": "EUR",
+                  "tax": {
+                    "name": "tax",
+                    "type": "VAT",
+                    "rate": 19,
+                    "region": "DE"
+                  }
+                },
+                {
+                  "price_display_in_journeys": "show_price",
+                  "variable_price": true,
+                  "type": "recurring",
+                  "billing_period": "monthly",
+                  "is_tax_inclusive": true,
+                  "unit": "kWh",
+                  "amount_subtotal_decimal": "407.866260504",
+                  "amount_total_decimal": "485.36085",
+                  "unit_amount_net_decimal": "14",
+                  "unit_amount_gross_decimal": "16",
+                  "currency": "EUR",
+                  "tax": {
+                    "name": "VAT",
+                    "type": "VAT",
+                    "rate": 19,
+                    "region": "DE"
+                  }
+                }
+              ],
+              "fees": {
+                "amount_total_decimal": "410.84",
+                "amount_variable_decimal": "356.58",
+                "billing_period": "yearly",
+                "breakdown": {
+                  "static": {
+                    "basic_fee": {
+                      "amount_decimal": "19.21"
+                    },
+                    "maintenance_fee": {
+                      "amount_decimal": "35.05"
+                    }
+                  },
+                  "variable": {
+                    "offshore_liability_fee": {
+                      "amount_decimal": "2.4",
+                      "unit": "kWh"
+                    },
+                    "interruptible_load": {
+                      "amount_decimal": "0"
+                    },
+                    "extra_charge": {
+                      "amount_decimal": "22.68"
+                    },
+                    "chp": {
+                      "amount_decimal": "26.7"
+                    },
+                    "power_kwh": {
+                      "amount_decimal": "161.4"
+                    },
+                    "concession": {
+                      "amount_decimal": "143.4"
+                    }
+                  }
+                }
+              },
+              "total_details": {
+                "breakdown": {
+                  "recurrences": [
+                    {
+                      "type": "recurring",
+                      "billing_period": "monthly",
+                      "amount_subtotal_decimal": "419.110616246297",
+                      "amount_total_decimal": "498.741633333333"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "id": "73f857a4-0fbc-4aa6-983f-87c0d6d410a6",
+            "name": "Solar Panel X1",
+            "description": "High-efficiency solar panel for residential use",
+            "additional_notes": [
+              "Includes mounting hardware",
+              "Professional installation recommended"
+            ],
+            "price": {
+              "is_composite_price": true,
+              "currency": "EUR",
+              "amount_subtotal_decimal": "99",
+              "amount_total_decimal": "99",
+              "price_components": [
+                {
+                  "type": "one_time",
+                  "unit_amount_net_decimal": "99",
+                  "unit_amount_gross_decimal": "99",
+                  "amount_subtotal_decimal": "99",
+                  "amount_total_decimal": "99",
+                  "is_tax_inclusive": true,
+                  "currency": "EUR"
+                }
+              ],
+              "total_details": {
+                "breakdown": {
+                  "recurrences": [
+                    {
+                      "type": "one_time",
+                      "amount_subtotal_decimal": "99",
+                      "amount_total_decimal": "99"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "id": "73f857a4-0fbc-4aa6-983f-87c0d6d410a6",
+            "name": "Solar Panel X2",
+            "recommendation_settings": {
+              "is_recommended": true,
+              "recommended_label": "Best Value"
+            },
+            "price": {
+              "is_composite_price": false,
+              "currency": "EUR",
+              "price_display_in_journeys": "show_price",
+              "type": "one_time",
+              "unit_amount_net_decimal": "25",
+              "unit_amount_gross_decimal": "25",
+              "amount_subtotal_decimal": "25",
+              "amount_total_decimal": "25",
+              "is_tax_inclusive": true,
+              "tax": {
+                "name": "no-tax",
+                "type": "VAT",
+                "rate": 0,
+                "region": "DE"
+              }
+            }
+          }
+        ]
       }
     }
   }