{ "openapi": "3.1.0", "info": { "title": "ChargeBridge Clearing Platform API", "version": "1.1.0", "description": "Financial clearing, settlement, invoicing, payment, and reconciliation API for the ChargeBridge EV Roaming Hub. Schema bodies are generated from the runtime Zod schemas (zod-to-json-schema); operations carry `x-consumer` (hub-ops | partner | internal | public) for scope-filtered client generation. `x-unvalidated: true` marks handlers that do not runtime-parse yet.", "contact": { "name": "ChargeBridge Engineering" } }, "servers": [ { "url": "http://localhost:3001", "description": "Local development" }, { "url": "https://api.dev.egridium.com", "description": "Development environment" } ], "tags": [ { "name": "Health", "description": "Service health and readiness" }, { "name": "Settlement", "description": "Settlement window operations" }, { "name": "Invoices", "description": "Invoice lifecycle" }, { "name": "Reconciliation", "description": "Reconciliation lifecycle" }, { "name": "Payments", "description": "Payment recording" }, { "name": "Billing", "description": "Billing configuration + credit notes" }, { "name": "Compliance", "description": "GDPR + appeals" }, { "name": "FX", "description": "Exchange rates" }, { "name": "Operations", "description": "Terminals, anomalies" }, { "name": "Governance", "description": "Internal governance/admin surface" } ], "paths": { "/health": { "get": { "tags": ["Health"], "summary": "Service health", "x-consumer": "public", "responses": { "200": { "description": "Service is healthy", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "healthy" } } } }, "503": { "description": "Service is degraded", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/ready": { "get": { "tags": ["Health"], "summary": "Readiness probe", "x-consumer": "public", "responses": { "200": { "description": "Service is ready", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Service is not ready", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/settlements/windows/{windowId}/close": { "post": { "tags": ["Settlement"], "summary": "Close a settlement window (operator fast-forward)", "x-consumer": "hub-ops", "parameters": [ { "name": "windowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "closedBy": "ops:alice" } } } }, "responses": { "200": { "description": "Window closed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "windowType": { "type": "string" }, "status": { "type": "string" }, "region": { "type": "string", "nullable": true }, "partyCountryCode": { "type": "string", "nullable": true }, "partyId": { "type": "string", "nullable": true }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "gracePeriodEnd": { "type": "string" } }, "required": ["start", "end", "gracePeriodEnd"], "additionalProperties": false }, "aggregates": { "type": "object", "additionalProperties": {}, "nullable": true }, "previousWindowId": { "type": "string", "nullable": true }, "windowHash": { "type": "string", "nullable": true }, "timestamps": { "type": "object", "properties": { "openedAt": { "type": "string" }, "graceStartedAt": { "type": "string", "nullable": true }, "reconciliationStartedAt": { "type": "string", "nullable": true }, "closedAt": { "type": "string", "nullable": true }, "closedBy": { "type": "string", "nullable": true } }, "required": ["openedAt"], "additionalProperties": false }, "version": { "type": "number" } }, "required": [ "id", "windowType", "status", "period", "timestamps", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Invalid state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Invalid state" } } } } } } }, "/api/v1/settlement/windows/current": { "get": { "tags": ["Settlement"], "summary": "Current settlement window", "x-consumer": "hub-ops", "responses": { "200": { "description": "Current settlement window", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "windowType": { "type": "string" }, "status": { "type": "string" }, "region": { "type": "string", "nullable": true }, "partyCountryCode": { "type": "string", "nullable": true }, "partyId": { "type": "string", "nullable": true }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "gracePeriodEnd": { "type": "string" } }, "required": ["start", "end", "gracePeriodEnd"], "additionalProperties": false }, "aggregates": { "type": "object", "additionalProperties": {}, "nullable": true }, "previousWindowId": { "type": "string", "nullable": true }, "windowHash": { "type": "string", "nullable": true }, "timestamps": { "type": "object", "properties": { "openedAt": { "type": "string" }, "graceStartedAt": { "type": "string", "nullable": true }, "reconciliationStartedAt": { "type": "string", "nullable": true }, "closedAt": { "type": "string", "nullable": true }, "closedBy": { "type": "string", "nullable": true } }, "required": ["openedAt"], "additionalProperties": false }, "version": { "type": "number" } }, "required": [ "id", "windowType", "status", "period", "timestamps", "version" ], "additionalProperties": false } }, "required": ["data"] } } } } } } }, "/api/v1/partners/{countryCode}/{partyId}/commission/quote": { "post": { "tags": ["Settlement"], "summary": "Quote the partner commission a CPO would pay on given gross amounts (estimate; the statement is authoritative)", "x-consumer": "partner", "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "counterparty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 32 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "value": { "type": "string", "maxLength": 24, "pattern": "^\\d+(?:\\.\\d{1,4})?$" } }, "required": ["ref", "currency", "value"], "additionalProperties": false }, "minItems": 1, "maxItems": 16 } }, "required": ["counterparty", "items"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Commission quote (APPLIED | NONE | NO_AGREEMENT)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["APPLIED"] }, "agreementId": { "type": "string" }, "agreementVersion": { "type": "integer" }, "agreementOrigin": { "type": "string", "enum": ["NEGOTIATED", "TRANSITION_DEFAULT"] }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "vatMode": { "type": "string", "enum": ["INCLUSIVE", "EXCLUSIVE"] }, "treatment": { "type": "string", "enum": ["SERVICE_FEE", "DISCOUNT"] }, "basis": { "type": "string", "enum": ["ITEM_CURRENCY_VAT_EXCLUSIVE"] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "currency": { "type": "string" }, "gross": { "type": "string" }, "commission": { "type": "string" }, "net": { "type": "string" } }, "required": [ "ref", "currency", "gross", "commission", "net" ], "additionalProperties": false } } }, "required": [ "status", "agreementId", "agreementVersion", "agreementOrigin", "bps", "vatMode", "treatment", "basis", "lines" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["NONE"] }, "agreementId": { "type": "string" }, "agreementVersion": { "type": "integer" }, "agreementOrigin": { "type": "string", "enum": ["NEGOTIATED", "TRANSITION_DEFAULT"] }, "basis": { "type": "string", "enum": ["ITEM_CURRENCY_VAT_EXCLUSIVE"] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "currency": { "type": "string" }, "gross": { "type": "string" }, "commission": { "type": "string" }, "net": { "type": "string" } }, "required": [ "ref", "currency", "gross", "commission", "net" ], "additionalProperties": false } } }, "required": [ "status", "agreementId", "agreementVersion", "agreementOrigin", "basis", "lines" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["NO_AGREEMENT"] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "currency": { "type": "string" }, "gross": { "type": "string" }, "commission": { "type": "string" }, "net": { "type": "string" } }, "required": [ "ref", "currency", "gross", "commission", "net" ], "additionalProperties": false }, "minItems": 0, "maxItems": 0 } }, "required": ["status", "lines"], "additionalProperties": false } ] } }, "required": ["data"] } } } }, "400": { "description": "Validation error / invalid amount", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation error / invalid amount" } } } }, "404": { "description": "Party not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Party not accessible" } } } }, "422": { "description": "Rate missing for CPO / overflow", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Rate missing for CPO / overflow" } } } } } } }, "/api/v1/invoices": { "post": { "tags": ["Invoices"], "summary": "Generate an invoice for a window + party pair", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "windowId": { "type": "string", "minLength": 1 }, "ourParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "partnerParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "reconciliationId": { "type": "string", "minLength": 1 } }, "required": [ "windowId", "ourParty", "partnerParty", "reconciliationId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Invoice generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string" }, "windowId": { "type": "string" }, "status": { "type": "string" }, "fromParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "toParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "totals": { "type": "object", "additionalProperties": {} }, "ledgerSnapshot": { "type": "object", "properties": { "windowId": { "type": "string" }, "entryCount": { "type": "number" }, "firstEntryId": { "type": "string", "format": "uuid" }, "lastEntryId": { "type": "string", "format": "uuid" }, "merkleRoot": { "type": "string" }, "generatedAt": { "type": "string" } }, "required": [ "windowId", "entryCount", "firstEntryId", "lastEntryId", "merkleRoot", "generatedAt" ], "additionalProperties": false }, "reconciliationSummary": { "type": "object", "properties": { "reconciliationId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "discrepancyCount": { "type": "number" }, "discrepancyAmount": { "type": "number" }, "reconciledAt": { "type": "string" } }, "required": [ "reconciliationId", "status", "discrepancyCount", "reconciledAt" ], "additionalProperties": false }, "documentHashes": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "hash": { "type": "string" }, "generatedAt": { "type": "string" } }, "required": ["format", "hash", "generatedAt"], "additionalProperties": false } }, "timestamps": { "type": "object", "properties": { "createdAt": { "type": "string" }, "issuedAt": { "type": "string", "nullable": true }, "voidedAt": { "type": "string", "nullable": true }, "voidReason": { "type": "string", "nullable": true } }, "required": ["createdAt"], "additionalProperties": false }, "version": { "type": "number" } }, "required": [ "id", "invoiceNumber", "windowId", "status", "fromParty", "toParty", "totals", "ledgerSnapshot", "reconciliationSummary", "documentHashes", "timestamps", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/reconciliation": { "post": { "tags": ["Reconciliation"], "summary": "Create a reconciliation record", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "windowId": { "type": "string", "minLength": 1 }, "ourParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "partnerParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "ourSummary": { "type": "object", "properties": { "totalSessions": { "type": "integer", "minimum": 0 }, "totalCdrs": { "type": "integer", "minimum": 0 }, "totalKwh": { "type": "number", "minimum": 0 }, "totalAmount": { "type": "number" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "reportHash": { "type": "string" } }, "required": [ "totalSessions", "totalCdrs", "totalKwh", "totalAmount", "currency" ], "additionalProperties": false } }, "required": [ "windowId", "ourParty", "partnerParty", "ourSummary" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Reconciliation created", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/anomalies/critical": { "get": { "tags": ["Operations"], "summary": "Critical anomalies", "x-consumer": "hub-ops", "responses": { "200": { "description": "List of critical anomalies", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": [] } } } } } }, "/api/v1/payments": { "post": { "tags": ["Payments"], "summary": "Record a manual payment against an invoice", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "payerParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "payeeParty": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "method": { "type": "string", "enum": [ "BANK_TRANSFER", "SEPA", "CREDIT_CARD", "NETTING", "DIRECT_DEBIT" ] }, "amount": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "externalReference": { "type": "string", "maxLength": 255 }, "notes": { "type": "string", "maxLength": 2000 }, "recordedBy": { "type": "string", "minLength": 1 } }, "required": [ "invoiceId", "payerParty", "payeeParty", "method", "amount", "currency", "recordedBy" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Payment recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string" }, "payerParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "payeeParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "status": { "type": "string" }, "method": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "externalReference": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "confirmedAt": { "type": "string", "nullable": true }, "failedAt": { "type": "string", "nullable": true }, "reversedAt": { "type": "string", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "reversalReason": { "type": "string", "nullable": true }, "recordedBy": { "type": "string", "nullable": true }, "version": { "type": "number" } }, "required": [ "id", "invoiceId", "invoiceNumber", "payerParty", "payeeParty", "status", "method", "amount", "currency", "createdAt", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/credit-notes": { "post": { "tags": ["Billing"], "summary": "Create a credit note", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "BILLING_ERROR", "CDR_CORRECTION", "TARIFF_DISPUTE", "SERVICE_COMPLAINT", "PARTIAL_REFUND", "FULL_REVERSAL", "REGULATORY" ] }, "description": { "type": "string", "minLength": 5, "maxLength": 2000 }, "totalAmount": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "unitAmount": { "type": "number", "minimum": 0 }, "totalAmount": { "type": "number", "minimum": 0 }, "relatedLedgerEntryId": { "type": "string", "format": "uuid" } }, "required": [ "description", "quantity", "unitAmount", "totalAmount" ], "additionalProperties": false }, "minItems": 1 }, "createdBy": { "type": "string", "minLength": 1 } }, "required": [ "invoiceId", "reason", "description", "totalAmount", "lineItems", "createdBy" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Credit note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creditNoteNumber": { "type": "string" }, "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string" }, "windowId": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" }, "description": { "type": "string", "nullable": true }, "fromParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "toParty": { "type": "object", "properties": { "countryCode": { "type": "string" }, "partyId": { "type": "string" } }, "required": ["countryCode", "partyId"], "additionalProperties": false }, "totalAmount": { "type": "number" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "nullable": true }, "reversalLedgerEntryIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true }, "timestamps": { "type": "object", "properties": { "createdAt": { "type": "string" }, "issuedAt": { "type": "string", "nullable": true }, "appliedAt": { "type": "string", "nullable": true } }, "required": ["createdAt"], "additionalProperties": false }, "createdBy": { "type": "string", "nullable": true }, "version": { "type": "number" } }, "required": [ "id", "creditNoteNumber", "invoiceId", "invoiceNumber", "windowId", "status", "reason", "fromParty", "toParty", "totalAmount", "currency", "timestamps", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/billing-configs": { "post": { "tags": ["Billing"], "summary": "Create billing configuration", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partyCountryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "partyId": { "type": "string", "minLength": 1, "maxLength": 3 }, "paymentTerms": { "type": "string", "enum": ["NET_15", "NET_30", "NET_45", "NET_60"] }, "billingCycle": { "type": "string", "enum": ["MONTHLY", "BI_WEEKLY", "WEEKLY"] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "billingContact": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "department": { "type": "string" } }, "required": ["name", "email"], "additionalProperties": false }, "vatRegistration": { "type": "object", "properties": { "vatNumber": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "isReverseCharge": { "type": "boolean" } }, "required": ["vatNumber", "countryCode", "isReverseCharge"], "additionalProperties": false }, "feeOverrides": { "type": "array", "items": { "type": "object", "properties": { "feeType": { "type": "string", "minLength": 1 }, "ratePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "flatAmount": { "type": "number", "minimum": 0 }, "minAmount": { "type": "number", "minimum": 0 }, "maxAmount": { "type": "number", "minimum": 0 } }, "required": ["feeType"], "additionalProperties": false }, "default": [] }, "autoInvoice": { "type": "boolean", "default": false }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "partyCountryCode", "partyId", "paymentTerms", "billingCycle", "currency", "billingContact" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Config created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partyCountryCode": { "type": "string" }, "partyId": { "type": "string" }, "paymentTerms": { "type": "string" }, "billingCycle": { "type": "string" }, "currency": { "type": "string" }, "billingContact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true } }, "required": ["name", "email"], "additionalProperties": false, "nullable": true }, "vatRegistration": { "type": "object", "properties": { "vatNumber": { "type": "string" }, "countryCode": { "type": "string" }, "isReverseCharge": { "type": "boolean" } }, "required": [ "vatNumber", "countryCode", "isReverseCharge" ], "additionalProperties": false, "nullable": true }, "feeOverrides": { "type": "array", "items": { "type": "object", "properties": { "feeType": { "type": "string" }, "ratePercent": { "type": "number" }, "flatAmount": { "type": "number" }, "minAmount": { "type": "number" }, "maxAmount": { "type": "number" } }, "required": ["feeType"], "additionalProperties": false }, "nullable": true }, "autoInvoice": { "type": "boolean" }, "notes": { "type": "string", "nullable": true }, "timestamps": { "type": "object", "properties": { "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": ["createdAt", "updatedAt"], "additionalProperties": false }, "version": { "type": "number" } }, "required": [ "id", "partyCountryCode", "partyId", "paymentTerms", "billingCycle", "currency", "autoInvoice", "timestamps", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } }, "get": { "tags": ["Billing"], "summary": "List billing configurations", "x-consumer": "hub-ops", "responses": { "200": { "description": "List of billing configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "partyCountryCode": { "type": "string" }, "partyId": { "type": "string" }, "paymentTerms": { "type": "string" }, "billingCycle": { "type": "string" }, "currency": { "type": "string" }, "billingContact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true } }, "required": ["name", "email"], "additionalProperties": false, "nullable": true }, "autoInvoice": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "partyCountryCode", "partyId", "paymentTerms", "billingCycle", "currency", "autoInvoice", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": ["total"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false } } } } } } }, "/api/v1/gdpr/requests": { "post": { "tags": ["Compliance"], "summary": "Submit a GDPR request", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestType": { "type": "string", "enum": ["DSAR", "ERASURE", "RECTIFICATION", "PORTABILITY"] }, "subjectIdentifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EMAIL", "PHONE", "OCPI_TOKEN", "RFID_UID", "CONTRACT_ID" ] }, "value": { "type": "string", "minLength": 1 } }, "required": ["type", "value"], "additionalProperties": false }, "minItems": 1 }, "requestedBy": { "type": "string", "minLength": 1 }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "requestType", "subjectIdentifiers", "requestedBy" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Request submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestType": { "type": "string" }, "status": { "type": "string" }, "subjectIdentifiers": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "requestedBy": { "type": "string" }, "timestamps": { "type": "object", "properties": { "requestedAt": { "type": "string" }, "dueDate": { "type": "string" }, "identityVerifiedAt": { "type": "string", "nullable": true }, "processingStartedAt": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "nullable": true }, "rejectedAt": { "type": "string", "nullable": true } }, "required": [ "requestedAt", "dueDate", "identityVerifiedAt", "processingStartedAt", "completedAt", "rejectedAt" ], "additionalProperties": false }, "rejectionReason": { "type": "string", "nullable": true }, "serviceResults": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "status": { "type": "string" }, "recordsFound": { "type": "number" }, "recordsAnonymized": { "type": "number" }, "error": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "nullable": true } }, "required": ["service", "status"], "additionalProperties": false } }, "auditLog": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "performedBy": { "type": "string" }, "performedAt": { "type": "string" }, "details": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "action", "performedBy", "performedAt" ], "additionalProperties": false } }, "notes": { "type": "string", "nullable": true }, "version": { "type": "number" } }, "required": [ "id", "requestType", "status", "subjectIdentifiers", "requestedBy", "timestamps", "serviceResults", "auditLog", "version" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } }, "get": { "tags": ["Compliance"], "summary": "List GDPR requests", "x-consumer": "hub-ops", "responses": { "200": { "description": "List of GDPR requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestType": { "type": "string" }, "status": { "type": "string" }, "requestedBy": { "type": "string" }, "requestedAt": { "type": "string" }, "dueDate": { "type": "string" }, "completedAt": { "type": "string", "nullable": true }, "rejectedAt": { "type": "string", "nullable": true }, "subjectIdentifierCount": { "type": "number" }, "serviceResultCount": { "type": "number" } }, "required": [ "id", "requestType", "status", "requestedBy", "requestedAt", "dueDate", "completedAt", "rejectedAt", "subjectIdentifierCount", "serviceResultCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": ["total"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false } } } } } } }, "/api/v1/appeals": { "get": { "tags": ["Compliance"], "summary": "List enforcement appeals", "x-consumer": "hub-ops", "responses": { "200": { "description": "List of appeals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enforcement_action_id": { "type": "string", "format": "uuid" }, "appellant_party_id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string" }, "assigned_reviewer": { "type": "string", "nullable": true }, "sla_deadline": { "type": "string", "nullable": true }, "is_sla_breached": { "type": "boolean" }, "decision": { "type": "string", "nullable": true } }, "required": [ "id", "enforcement_action_id", "appellant_party_id", "status", "submitted_at", "is_sla_breached" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": ["total"], "additionalProperties": false } }, "required": ["data", "pagination"], "additionalProperties": false } } } } } }, "post": { "tags": ["Compliance"], "summary": "Submit an enforcement appeal", "x-consumer": "hub-ops", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enforcement_action_id": { "type": "string", "minLength": 1 }, "appellant_party_id": { "type": "string", "minLength": 1 }, "appellant_type": { "type": "string", "enum": ["DRIVER", "CPO", "EMSP", "THIRD_PARTY"] }, "appeal_category": { "type": "string", "enum": [ "MISTAKEN_IDENTITY", "TECHNICAL_ERROR", "DISPUTED_EVIDENCE", "MITIGATING_CIRCUMSTANCES", "PROCEDURAL_VIOLATION", "POLICY_CHANGE", "OTHER" ], "default": "OTHER" }, "grounds": { "type": "string", "minLength": 10, "maxLength": 2000 }, "initial_evidence": { "type": "string", "maxLength": 5000 }, "contact_email": { "type": "string", "format": "email" } }, "required": [ "enforcement_action_id", "appellant_party_id", "appellant_type", "grounds" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Appeal submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enforcement_action_id": { "type": "string", "format": "uuid" }, "appellant_party_id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string" }, "assigned_reviewer": { "type": "string", "nullable": true }, "sla_deadline": { "type": "string", "nullable": true }, "is_sla_breached": { "type": "boolean" }, "decision": { "type": "string", "nullable": true }, "grounds": { "type": "string", "nullable": true }, "assigned_at": { "type": "string", "nullable": true }, "decision_reasoning": { "type": "string", "nullable": true }, "decided_at": { "type": "string", "nullable": true }, "decided_by": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "enforcement_action_id", "appellant_party_id", "status", "submitted_at", "is_sla_breached", "updated_at" ], "additionalProperties": false } }, "required": ["data"] } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/exchange-rates": { "get": { "tags": ["FX"], "summary": "List exchange rates", "x-consumer": "hub-ops", "responses": { "200": { "description": "List of exchange rates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sourceCurrency": { "type": "string" }, "targetCurrency": { "type": "string" }, "rate": { "type": "number" }, "inverseRate": { "type": "number" }, "effectiveDate": { "type": "string" }, "source": { "type": "string" } }, "required": [ "sourceCurrency", "targetCurrency", "rate", "inverseRate", "effectiveDate", "source" ], "additionalProperties": false } }, "total": { "type": "number" }, "timestamp": { "type": "string" } }, "required": ["data", "total", "timestamp"], "additionalProperties": false } } } } } }, "post": { "tags": ["FX"], "summary": "Create an exchange rate", "x-consumer": "hub-ops", "requestBody": { "required": true, "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "baseCurrency": "EUR", "quoteCurrency": "TRY", "rate": "47.5000" } } } }, "responses": { "201": { "description": "Exchange rate created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sourceCurrency": { "type": "string" }, "targetCurrency": { "type": "string" }, "rate": { "type": "number" }, "inverseRate": { "type": "number" }, "effectiveDate": { "type": "string" }, "source": { "type": "string" } }, "required": [ "sourceCurrency", "targetCurrency", "rate", "inverseRate", "effectiveDate", "source" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": ["data", "timestamp"], "additionalProperties": false } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Validation failed" } } } } } } }, "/api/v1/admin/payment-evidence/{evidenceId}/chain-proof": { "get": { "tags": ["Governance"], "summary": "Verify payment evidence chain proof", "x-consumer": "internal", "parameters": [ { "name": "evidenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chain proof result", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Evidence not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Evidence not found" } } } } } } }, "/api/v1/admin/payment-obligations/{obligationId}/advance": { "post": { "tags": ["Governance"], "summary": "Advance a payment obligation", "x-consumer": "internal", "parameters": [ { "name": "obligationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "actor": "admin:ops" } } } }, "responses": { "200": { "description": "Advance outcome", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Obligation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Obligation not found" } } } } } } }, "/api/v1/admin/payment-obligations/{obligationId}/evidence/{evidenceId}/replay": { "post": { "tags": ["Governance"], "summary": "Replay a payment evidence webhook", "x-consumer": "internal", "parameters": [ { "name": "obligationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evidenceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replay outcome", "x-unvalidated": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Evidence not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } }, "example": { "error": "BAD_REQUEST", "message": "Evidence not found" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Portal JWT (hub_operator) veya INTERNAL_SERVICE_TOKEN. `x-consumer: internal` uçları yalnız servis token'ı kabul eder." } }, "schemas": {} }, "security": [ { "bearerAuth": [] } ] }