{
	"openapi": "3.0.3",
	"info": {
		"title": "Billyou Invoice Management API",
		"description": "# Billyou Invoice Management API\n\nInvoice management for Romanian businesses with complete VAT compliance and E-Factura integration.\n\n## Core Features\n\n- **Invoices** - Create, view, update, cancel, and delete invoices with PDF generation\n- **Clients** - Manage client database with CUI/CNP validation\n- **Payments** - Track payments and monitor invoice status\n- **Series** - Configure invoice numbering and formatting\n\n## Authentication\n\nAll endpoints require API key authentication.\n\nRequests should include:\n```\nX-API-Key: your-api-key-here\n```\n\n## Rate Limits\n\n- **60 requests/minute per organization** (default)\n- The budget is per ORGANIZATION, not per key — every API key issued to an\n  organization draws on the same budget\n- Sliding 60-second window; there is **no burst allowance**\n- `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` are\n  returned on rate-limited responses. `X-RateLimit-Limit` is authoritative:\n  it reflects any custom limit configured for your organization, which the\n  default above does not\n- On refusal: `429` with `errorCode: \"RATE_LIMIT_EXCEEDED\"` and\n  `retryAfterSeconds`\n\nNeed a higher limit? Contact support — limits are raised per organization.\n\n## Response Format\n\n```json\n{\n  \"success\": true|false,\n  \"data\": { ... },\n  \"meta\": { ... },\n  \"errorCode\": \"ERROR_CODE\" // Only on errors\n}\n```",
		"version": "1.0.27",
		"contact": {
			"name": "Billyou Development Team",
			"email": "dev@billyou.ro"
		},
		"license": {
			"name": "Proprietary"
		}
	},
	"components": {
		"securitySchemes": {
			"ApiKeyAuth": {
				"type": "apiKey",
				"in": "header",
				"name": "X-API-Key",
				"description": "API key authentication. Enter your API key without any prefix (e.g., bk_user_...)"
			}
		},
		"schemas": {
			"ErrorResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"example": false
					},
					"errorCode": {
						"type": "string",
						"example": "VALIDATION_ERROR"
					},
					"message": {
						"type": "string",
						"example": "The provided data is invalid."
					}
				},
				"required": [
					"success",
					"errorCode",
					"message"
				]
			},
			"SuccessResponse": {
				"type": "object",
				"properties": {
					"success": {
						"type": "boolean",
						"example": true
					},
					"data": {
						"type": "object",
						"description": "Response data payload"
					},
					"meta": {
						"type": "object",
						"description": "Additional metadata (pagination, etc.)"
					}
				},
				"required": [
					"success"
				]
			}
		}
	},
	"paths": {
		"/api-keys/": {
			"get": {
				"summary": "List API keys",
				"tags": [
					"API Keys"
				],
				"description": "Retrieve a list of API keys for your organization.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 25,
							"example": 25
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Maximum number of items to return (1-100)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "starting_after",
						"required": false,
						"description": "Resource ID to paginate after (returns items created after this ID)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "ending_before",
						"required": false,
						"description": "Resource ID to paginate before (returns items created before this ID)"
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"production",
								"sandbox"
							]
						},
						"in": "query",
						"name": "environment",
						"required": false,
						"description": "Filter by environment"
					}
				],
				"x-internal": true,
				"responses": {
					"200": {
						"description": "API keys retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "API keys retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"data": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "API key unique identifier",
																"example": "60f7b1b9c9e7b4a1e8d1c2b3"
															},
															"name": {
																"type": "string",
																"description": "Human-readable name for the API key",
																"example": "Production Integration Key"
															},
															"key_prefix": {
																"type": "string",
																"description": "Masked key prefix for identification (the full key is only shown once on creation)",
																"example": "bk_user_a1b2..."
															},
															"environment": {
																"type": "string",
																"enum": [
																	"production",
																	"sandbox"
																],
																"description": "Environment this key is scoped to",
																"example": "production"
															},
															"api_version": {
																"type": "string",
																"description": "API version this key uses",
																"example": "2026-01-01"
															},
															"is_active": {
																"type": "boolean",
																"description": "Whether the API key is active",
																"example": true
															},
															"expires_at": {
																"type": "string",
																"format": "date-time",
																"nullable": true,
																"description": "Expiration timestamp, or null if the key never expires",
																"example": "2027-01-15T10:00:00Z"
															},
															"last_used_at": {
																"type": "string",
																"format": "date-time",
																"nullable": true,
																"description": "When the key was last used for authentication",
																"example": "2026-02-28T14:30:00Z"
															},
															"created_at": {
																"type": "string",
																"format": "date-time",
																"description": "Creation timestamp",
																"example": "2026-01-15T10:00:00Z"
															},
															"updated_at": {
																"type": "string",
																"format": "date-time",
																"description": "Last update timestamp",
																"example": "2026-01-15T10:00:00Z"
															}
														}
													}
												},
												"has_more": {
													"type": "boolean",
													"description": "Whether there are more items available after this page",
													"example": true
												},
												"total_count": {
													"type": "integer",
													"description": "Total number of matching resources",
													"example": 42
												}
											},
											"required": [
												"data",
												"has_more",
												"total_count"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"post": {
				"summary": "Create an API key",
				"tags": [
					"API Keys"
				],
				"description": "Create a new API key. The key secret is returned only once — store it securely.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"name": {
										"type": "string",
										"minLength": 1,
										"maxLength": 100,
										"description": "A human-readable name for the API key",
										"example": "Production Integration Key"
									},
									"expiresInDays": {
										"type": "string",
										"description": "Number of days until the key expires, or \"never\" for no expiration",
										"default": "never",
										"example": "90"
									},
									"environment": {
										"type": "string",
										"enum": [
											"production",
											"sandbox"
										],
										"description": "Environment to scope this key to",
										"default": "sandbox",
										"example": "sandbox"
									}
								},
								"required": [
									"name"
								],
								"additionalProperties": false
							}
						}
					}
				},
				"x-internal": true,
				"responses": {
					"201": {
						"description": "API key created successfully. The secret is only returned once.",
						"content": {
							"application/json": {
								"schema": {
									"description": "API key created successfully. The secret is only returned once.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "API key unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"name": {
													"type": "string",
													"description": "Human-readable name for the API key",
													"example": "Production Integration Key"
												},
												"key_prefix": {
													"type": "string",
													"description": "Masked key prefix for identification (the full key is only shown once on creation)",
													"example": "bk_user_a1b2..."
												},
												"environment": {
													"type": "string",
													"enum": [
														"production",
														"sandbox"
													],
													"description": "Environment this key is scoped to",
													"example": "production"
												},
												"api_version": {
													"type": "string",
													"description": "API version this key uses",
													"example": "2026-01-01"
												},
												"is_active": {
													"type": "boolean",
													"description": "Whether the API key is active",
													"example": true
												},
												"expires_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true,
													"description": "Expiration timestamp, or null if the key never expires",
													"example": "2027-01-15T10:00:00Z"
												},
												"last_used_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true,
													"description": "When the key was last used for authentication",
													"example": "2026-02-28T14:30:00Z"
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"secret": {
													"type": "string",
													"description": "The full API key secret. Only returned on creation and rotation — store it securely.",
													"example": "bk_user_a1b2c3d4e5f6..."
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/api-keys/{id}": {
			"delete": {
				"summary": "Delete an API key",
				"tags": [
					"API Keys"
				],
				"description": "Permanently delete an API key. This cannot be undone.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"x-internal": true,
				"responses": {
					"200": {
						"description": "API key deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "API key deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$"
												},
												"deleted": {
													"type": "boolean",
													"enum": [
														true
													]
												}
											},
											"required": [
												"id",
												"deleted"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/api-keys/{id}/rotate": {
			"post": {
				"summary": "Rotate an API key",
				"tags": [
					"API Keys"
				],
				"description": "Rotate an existing API key. The old key is deactivated and a new key is created with the same settings. The new secret is returned only once.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"x-internal": true,
				"responses": {
					"200": {
						"description": "API key rotated successfully. The new secret is only returned once.",
						"content": {
							"application/json": {
								"schema": {
									"description": "API key rotated successfully. The new secret is only returned once.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "API key unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"name": {
													"type": "string",
													"description": "Human-readable name for the API key",
													"example": "Production Integration Key"
												},
												"key_prefix": {
													"type": "string",
													"description": "Masked key prefix for identification (the full key is only shown once on creation)",
													"example": "bk_user_a1b2..."
												},
												"environment": {
													"type": "string",
													"enum": [
														"production",
														"sandbox"
													],
													"description": "Environment this key is scoped to",
													"example": "production"
												},
												"api_version": {
													"type": "string",
													"description": "API version this key uses",
													"example": "2026-01-01"
												},
												"is_active": {
													"type": "boolean",
													"description": "Whether the API key is active",
													"example": true
												},
												"expires_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true,
													"description": "Expiration timestamp, or null if the key never expires",
													"example": "2027-01-15T10:00:00Z"
												},
												"last_used_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true,
													"description": "When the key was last used for authentication",
													"example": "2026-02-28T14:30:00Z"
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"secret": {
													"type": "string",
													"description": "The full API key secret. Only returned on creation and rotation — store it securely.",
													"example": "bk_user_a1b2c3d4e5f6..."
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/clients/": {
			"post": {
				"summary": "Create a new client",
				"tags": [
					"Clients"
				],
				"description": "Add a new business client to your organization with contact and address information.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"name": {
										"type": "string",
										"minLength": 1,
										"maxLength": 200,
										"description": "Client business name"
									},
									"taxId": {
										"type": "string",
										"minLength": 1,
										"maxLength": 50,
										"description": "Tax identification number (Romanian CUI/CNP, US EIN, or EU VAT ID)"
									},
									"tradeRegistryNumber": {
										"type": "string",
										"maxLength": 50,
										"description": "Trade registry number (e.g., J40/1234/2020)"
									},
									"address": {
										"type": "object",
										"properties": {
											"street": {
												"type": "string",
												"maxLength": 200,
												"description": "Street address"
											},
											"city": {
												"type": "string",
												"minLength": 1,
												"maxLength": 100,
												"description": "City"
											},
											"county": {
												"type": "string",
												"minLength": 1,
												"maxLength": 100,
												"description": "Romanian county (județ): its name, any case, with or without diacritics (\"Iași\", \"IASI\"), or its ISO 3166-2 code (\"IS\", \"RO-IS\") — not a city or village. Published invoices for a Romanian client whose county is not recognised are refused with 400 EFACTURA_INVALID_COUNTY. Free text for non-Romanian addresses."
											},
											"postalCode": {
												"type": "string",
												"maxLength": 20,
												"description": "Postal code"
											},
											"sector": {
												"type": "string",
												"maxLength": 10,
												"description": "București sector, e.g. \"Sectorul 3\" or \"3\" (1-6). Required for București addresses (ANAF e-Factura rule BR-RO-100)."
											},
											"country": {
												"type": "string",
												"minLength": 1,
												"maxLength": 100,
												"description": "Country",
												"default": "România"
											}
										},
										"required": [
											"city",
											"county",
											"country"
										],
										"additionalProperties": false,
										"description": "Client address information"
									},
									"IBAN": {
										"type": "string",
										"maxLength": 50,
										"description": "Bank account IBAN"
									},
									"contactEmails": {
										"type": "array",
										"items": {
											"type": "string",
											"format": "email"
										},
										"description": "Contact email addresses"
									},
									"contact": {
										"type": "string",
										"maxLength": 200,
										"description": "Contact person name"
									},
									"phone": {
										"type": "string",
										"maxLength": 50,
										"description": "Contact phone number"
									},
									"bank": {
										"type": "string",
										"maxLength": 200,
										"description": "Bank name"
									},
									"swift": {
										"type": "string",
										"maxLength": 11,
										"description": "SWIFT/BIC code (ISO 9362, 8 or 11 chars). Optional; used for international payments and shown on the invoice PDF when present."
									},
									"hasSelfBillingContract": {
										"type": "boolean",
										"description": "Indicates whether this client has a contract that allows self-billing (Autofacturare)"
									}
								},
								"required": [
									"name",
									"taxId",
									"address"
								],
								"additionalProperties": false,
								"example": {
									"name": "SC Example SRL",
									"taxId": "12345678",
									"tradeRegistryNumber": "J40/1234/2020",
									"address": {
										"street": "Strada Exemplu nr. 123",
										"city": "București",
										"county": "București",
										"postalCode": "010101",
										"sector": "Sectorul 1",
										"country": "România"
									},
									"IBAN": "RO49AAAA1B31007593840000",
									"swift": "BTRLRO22",
									"contactEmails": [
										"contact@example.ro"
									],
									"phone": "+40123456789"
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Client created successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client created successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List clients with search",
				"tags": [
					"Clients"
				],
				"description": "Retrieve a paginated list of clients with optional search by name, email, or registration number.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					},
					{
						"schema": {
							"type": "string",
							"maxLength": 200
						},
						"in": "query",
						"name": "search",
						"required": false,
						"description": "Search term for client name, email, or registration number"
					}
				],
				"responses": {
					"200": {
						"description": "Clients retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Clients retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/clients/{id}": {
			"put": {
				"summary": "Update client information",
				"tags": [
					"Clients"
				],
				"description": "Update an existing client's information. All fields are optional.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"name": {
										"type": "string",
										"minLength": 1,
										"maxLength": 200,
										"description": "Client business name"
									},
									"taxId": {
										"type": "string",
										"maxLength": 50,
										"description": "Tax identification number (CUI/CNP)"
									},
									"tradeRegistryNumber": {
										"type": "string",
										"maxLength": 50,
										"description": "Trade registry number"
									},
									"address": {
										"type": "object",
										"description": "Address information",
										"properties": {
											"street": {
												"type": "string",
												"maxLength": 200,
												"description": "Street name and number"
											},
											"city": {
												"type": "string",
												"maxLength": 100,
												"description": "City"
											},
											"county": {
												"type": "string",
												"maxLength": 100,
												"description": "Romanian county (județ): its name, any case, with or without diacritics (\"Iași\", \"IASI\"), or its ISO 3166-2 code (\"IS\", \"RO-IS\") — not a city or village. Published invoices for a Romanian client whose county is not recognised are refused with 400 EFACTURA_INVALID_COUNTY. Free text for non-Romanian addresses."
											},
											"postalCode": {
												"type": "string",
												"maxLength": 20,
												"description": "Postal code"
											},
											"sector": {
												"type": "string",
												"maxLength": 10,
												"description": "București sector, e.g. \"Sectorul 3\" or \"3\" (1-6). Required for București addresses (ANAF e-Factura rule BR-RO-100)."
											},
											"country": {
												"type": "string",
												"maxLength": 100,
												"description": "Country"
											}
										},
										"additionalProperties": false
									},
									"IBAN": {
										"type": "string",
										"maxLength": 50,
										"description": "Bank account IBAN"
									},
									"contactEmails": {
										"type": "array",
										"items": {
											"type": "string",
											"format": "email"
										},
										"description": "Contact email addresses"
									},
									"contact": {
										"type": "string",
										"maxLength": 200,
										"description": "Contact person name"
									},
									"phone": {
										"type": "string",
										"maxLength": 50,
										"description": "Contact phone number"
									},
									"bank": {
										"type": "string",
										"maxLength": 200,
										"description": "Bank name"
									},
									"swift": {
										"type": "string",
										"maxLength": 11,
										"description": "SWIFT/BIC code (ISO 9362, 8 or 11 chars). Optional; used for international payments and shown on the invoice PDF when present."
									},
									"hasSelfBillingContract": {
										"type": "boolean",
										"description": "Indicates whether this client has a contract that allows self-billing (Autofacturare)"
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Client updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client updated successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "Get client by ID",
				"tags": [
					"Clients"
				],
				"description": "Retrieve a single client's information by their ID.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Client retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"delete": {
				"summary": "Delete a client",
				"tags": [
					"Clients"
				],
				"description": "Delete a client. Clients with existing invoices cannot be deleted - delete or cancel all invoices first.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Client deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"deleted": {
													"type": "boolean",
													"example": true
												},
												"clientId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2b4"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "CLIENT_HAS_INVOICES",
										"message": "Cannot delete a client with existing invoices. Delete or cancel all invoices first."
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/received": {
			"get": {
				"summary": "List received E-Factura invoices",
				"tags": [
					"E-Factura"
				],
				"description": "Retrieve a paginated list of invoices received via the E-Factura system (SPV inbox).",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"pending",
								"saved",
								"failed"
							]
						},
						"in": "query",
						"name": "status",
						"required": false,
						"description": "Filter by processing status"
					}
				],
				"responses": {
					"200": {
						"description": "Received invoices retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Received invoices retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"uploadIndex": {
														"type": "string",
														"description": "ANAF upload index"
													},
													"downloadId": {
														"type": "string",
														"description": "ANAF download ID"
													},
													"invoiceNumber": {
														"type": "string",
														"description": "Invoice number from the XML"
													},
													"vendorCIF": {
														"type": "string",
														"description": "Vendor tax identification number (CIF)"
													},
													"issueDate": {
														"type": "string",
														"description": "Invoice issue date"
													},
													"paymentDueDate": {
														"type": "string",
														"description": "Payment due date"
													},
													"valueWithoutVAT": {
														"type": "number",
														"description": "Total value without VAT"
													},
													"VATValue": {
														"type": "number",
														"description": "Total VAT amount"
													},
													"totalValue": {
														"type": "number",
														"description": "Total value including VAT"
													},
													"currency": {
														"type": "string",
														"description": "Currency code (RON, EUR, etc.)"
													},
													"status": {
														"type": "string",
														"enum": [
															"pending",
															"saved",
															"failed"
														],
														"description": "Processing status of the received invoice"
													}
												}
											}
										},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/received/{id}": {
			"get": {
				"summary": "Get received E-Factura invoice",
				"tags": [
					"E-Factura"
				],
				"description": "Retrieve a specific received E-Factura invoice by its download ID.",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Download ID of the received invoice"
					}
				],
				"responses": {
					"200": {
						"description": "Received invoice retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Received invoice retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"uploadIndex": {
													"type": "string"
												},
												"downloadId": {
													"type": "string"
												},
												"invoiceNumber": {
													"type": "string"
												},
												"vendorCIF": {
													"type": "string"
												},
												"issueDate": {
													"type": "string"
												},
												"paymentDueDate": {
													"type": "string"
												},
												"valueWithoutVAT": {
													"type": "number"
												},
												"VATValue": {
													"type": "number"
												},
												"totalValue": {
													"type": "number"
												},
												"currency": {
													"type": "string"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"saved",
														"failed"
													]
												},
												"stats": {
													"type": "object",
													"properties": {
														"queuedAt": {
															"type": "string"
														},
														"processStartedAt": {
															"type": "string"
														},
														"processedAt": {
															"type": "string"
														}
													}
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/received/{id}/xml": {
			"get": {
				"summary": "Download received E-Factura XML",
				"tags": [
					"E-Factura"
				],
				"description": "Get a presigned download URL for the raw XML of a received E-Factura invoice.",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Download ID of the received invoice"
					}
				],
				"responses": {
					"200": {
						"description": "Presigned download URL for the XML file",
						"content": {
							"application/json": {
								"schema": {
									"description": "Presigned download URL for the XML file",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"downloadUrl": {
													"type": "string",
													"format": "uri",
													"description": "Presigned S3 URL to download the XML (valid for 1 hour)"
												},
												"invoiceNumber": {
													"type": "string",
													"description": "Invoice number for the filename"
												},
												"filename": {
													"type": "string",
													"description": "Suggested filename for the download"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/submissions/{id}": {
			"get": {
				"summary": "Get E-Factura submission status",
				"tags": [
					"E-Factura"
				],
				"description": "Get status by Invoice ID (acting as Submission ID currently)",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Submission ID (currently maps to Invoice ID)"
					}
				],
				"responses": {
					"200": {
						"description": "Default Response",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"invoiceId": {
													"type": "string"
												},
												"uploadIndex": {
													"type": "string"
												},
												"downloadId": {
													"type": "string"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"processing",
														"uploaded",
														"validated",
														"rejected",
														"failed"
													]
												},
												"createdAt": {
													"type": "string"
												},
												"updatedAt": {
													"type": "string"
												},
												"error": {
													"type": "object",
													"properties": {
														"code": {
															"type": "string"
														},
														"message": {
															"type": "string"
														},
														"details": {
															"type": "object",
															"properties": {
																"errorCode": {
																	"type": "string"
																},
																"anafErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"properties": {
																			"code": {
																				"type": "string"
																			},
																			"message": {
																				"type": "string"
																			}
																		}
																	}
																},
																"translatedErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"additionalProperties": true
																	}
																}
															}
														}
													}
												}
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/submissions/{id}/retry": {
			"post": {
				"summary": "Retry a failed E-Factura submission",
				"tags": [
					"E-Factura"
				],
				"description": "Retry a previously failed E-Factura submission. Only submissions with retryable statuses (`upload-failed`, `nok-retryable`, `failed`) can be retried.",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Submission ID (currently maps to Invoice ID)"
					}
				],
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"202": {
						"description": "Retry accepted for processing",
						"content": {
							"application/json": {
								"schema": {
									"description": "Retry accepted for processing",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"invoiceId": {
													"type": "string"
												},
												"uploadIndex": {
													"type": "string"
												},
												"downloadId": {
													"type": "string"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"processing",
														"uploaded",
														"validated",
														"rejected",
														"failed"
													]
												},
												"createdAt": {
													"type": "string"
												},
												"updatedAt": {
													"type": "string"
												},
												"error": {
													"type": "object",
													"properties": {
														"code": {
															"type": "string"
														},
														"message": {
															"type": "string"
														},
														"details": {
															"type": "object",
															"properties": {
																"errorCode": {
																	"type": "string"
																},
																"anafErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"properties": {
																			"code": {
																				"type": "string"
																			},
																			"message": {
																				"type": "string"
																			}
																		}
																	}
																},
																"translatedErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"additionalProperties": true
																	}
																}
															}
														}
													}
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/efactura/submissions/{id}/xml": {
			"get": {
				"summary": "Download issued E-Factura XML",
				"tags": [
					"E-Factura"
				],
				"description": "Get a presigned download URL for the e-Factura UBL XML of an issued invoice (submission) — the same XML that is submitted to ANAF. This is the issued-invoice counterpart of `GET /efactura/received/{id}/xml`.\n\nThe submission ID is the invoice ID. The XML is available as soon as the invoice exists — no e-Factura submission is required; it is generated on demand and cached on first request.\n\nThe presigned URL is valid for 10 minutes (600 seconds).",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Submission ID (currently equals the Invoice ID)"
					}
				],
				"responses": {
					"200": {
						"description": "XML download URL retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "XML download URL retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"downloadUrl": {
													"type": "string",
													"format": "uri",
													"description": "Presigned S3 URL to download the e-Factura UBL XML directly",
													"example": "https://s3.eu-central-1.amazonaws.com/bucket/efactura/invoice.xml?X-Amz-..."
												},
												"invoiceNumber": {
													"type": "string",
													"description": "Invoice number, used in the suggested filename",
													"example": "FACT-00123"
												},
												"filename": {
													"type": "string",
													"description": "Suggested filename for the download",
													"example": "efactura_FACT-00123.xml"
												},
												"expiresIn": {
													"type": "number",
													"description": "Time in seconds until the download URL expires",
													"example": 600
												}
											},
											"required": [
												"downloadUrl",
												"invoiceNumber",
												"filename",
												"expiresIn"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/etransport/declarations/": {
			"post": {
				"summary": "Submit transport declaration",
				"tags": [
					"E-Transport"
				],
				"description": "Submit a new e-Transport declaration to ANAF. Performs pre-flight validation before the real submission. Returns immediately with declarationId; poll GET /:id or await webhook for final UIT code.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": [
									"declarationType",
									"declarationData"
								],
								"properties": {
									"declarationType": {
										"type": "string",
										"enum": [
											"NOTIFICATION",
											"CONFIRMATION",
											"DELETION"
										],
										"description": "Type of transport declaration"
									},
									"declarationData": {
										"type": "object",
										"anyOf": [
											{
												"required": [
													"declarantTaxId"
												]
											},
											{
												"required": [
													"declarantCode"
												]
											}
										],
										"properties": {
											"declarantTaxId": {
												"type": "string",
												"minLength": 1,
												"description": "Romanian CUI of the declarant (with or without the 'RO' prefix, e.g. 'RO12345678' or '12345678'). Automatically normalized to declarantCode before forwarding to ANAF."
											},
											"declarantCode": {
												"type": "string",
												"minLength": 1,
												"description": "Digits-only ANAF codDeclarant (e.g. '12345678'). Takes precedence over declarantTaxId when both are provided."
											}
										},
										"additionalProperties": true,
										"description": "Full declaration input per @billyou/etransport spec"
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"202": {
						"description": "Declaration accepted and uploaded to ANAF",
						"content": {
							"application/json": {
								"schema": {
									"description": "Declaration accepted and uploaded to ANAF",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"description": "Declaration ID"
												},
												"declarationType": {
													"type": "string",
													"enum": [
														"NOTIFICATION",
														"CONFIRMATION",
														"DELETION"
													]
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"uploaded",
														"processed",
														"rejected",
														"failed"
													]
												},
												"uploadIndex": {
													"type": "string"
												},
												"uitCode": {
													"type": "string"
												},
												"createdAt": {
													"type": "string",
													"format": "date-time"
												},
												"updatedAt": {
													"type": "string",
													"format": "date-time"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List transport declarations",
				"tags": [
					"E-Transport"
				],
				"description": "Return all e-Transport declarations for the authenticated organization.",
				"responses": {
					"200": {
						"description": "Declarations retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Declarations retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Declaration ID"
													},
													"declarationType": {
														"type": "string",
														"enum": [
															"NOTIFICATION",
															"CONFIRMATION",
															"DELETION"
														]
													},
													"status": {
														"type": "string",
														"enum": [
															"pending",
															"uploaded",
															"processed",
															"rejected",
															"failed"
														]
													},
													"uploadIndex": {
														"type": "string"
													},
													"uitCode": {
														"type": "string"
													},
													"createdAt": {
														"type": "string",
														"format": "date-time"
													},
													"updatedAt": {
														"type": "string",
														"format": "date-time"
													}
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/etransport/declarations/validate": {
			"post": {
				"summary": "Validate transport declaration",
				"tags": [
					"E-Transport"
				],
				"description": "Validate a declaration against ANAF business rules without creating a record. Uses ANAF testMode=1. Use this before submitting to catch errors early.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": [
									"declarationType",
									"declarationData"
								],
								"properties": {
									"declarationType": {
										"type": "string",
										"enum": [
											"NOTIFICATION",
											"CONFIRMATION",
											"DELETION"
										],
										"description": "Type of transport declaration"
									},
									"declarationData": {
										"type": "object",
										"anyOf": [
											{
												"required": [
													"declarantTaxId"
												]
											},
											{
												"required": [
													"declarantCode"
												]
											}
										],
										"properties": {
											"declarantTaxId": {
												"type": "string",
												"minLength": 1,
												"description": "Romanian CUI of the declarant (with or without the 'RO' prefix, e.g. 'RO12345678' or '12345678'). Automatically normalized to declarantCode before forwarding to ANAF."
											},
											"declarantCode": {
												"type": "string",
												"minLength": 1,
												"description": "Digits-only ANAF codDeclarant (e.g. '12345678'). Takes precedence over declarantTaxId when both are provided."
											}
										},
										"additionalProperties": true,
										"description": "Full declaration input per @billyou/etransport spec"
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Validation result",
						"content": {
							"application/json": {
								"schema": {
									"description": "Validation result",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"valid": {
													"type": "boolean"
												},
												"errors": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"code": {
																"type": "string"
															},
															"field": {
																"type": "string"
															},
															"message": {
																"type": "string"
															}
														}
													}
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/etransport/declarations/{id}": {
			"get": {
				"summary": "Get transport declaration",
				"tags": [
					"E-Transport"
				],
				"description": "Get a single e-Transport declaration by ID. Returns current status and UIT code once ANAF has processed the declaration.",
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Declaration ID"
					}
				],
				"responses": {
					"200": {
						"description": "Declaration retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Declaration retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"description": "Declaration ID"
												},
												"declarationType": {
													"type": "string",
													"enum": [
														"NOTIFICATION",
														"CONFIRMATION",
														"DELETION"
													]
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"uploaded",
														"processed",
														"rejected",
														"failed"
													]
												},
												"uploadIndex": {
													"type": "string"
												},
												"uitCode": {
													"type": "string"
												},
												"createdAt": {
													"type": "string",
													"format": "date-time"
												},
												"updatedAt": {
													"type": "string",
													"format": "date-time"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/": {
			"post": {
				"summary": "Create a new invoice or draft",
				"tags": [
					"Invoices"
				],
				"description": "Create a new invoice or draft for a client with specified services.\n\n**Before Testing**:\n1. Get your client ID: Use GET /api/clients to list clients\n2. Get your series ID: Use GET /api/series to list invoice series (OR provide a custom serial number)\n3. Replace the example `clientId` and `seriesId` with your actual values\n\n**Serial Number Options** (mutually exclusive):\n- `seriesId`: Auto-generates next invoice number from series (e.g., \"INV-2025-00001\")\n- `customSerialNumber`: User-defined invoice number (e.g., \"CUSTOM-INV-2025-001\")\n\n**Draft Mode**: Set `draft: true` to create a draft invoice that can be edited before publishing.\n\n**Language**: Specify \"ro\" for Romanian (default) or \"en\" for English PDF generation.\n\n**Romanian county (e-Factura)**: a published (non-draft, non-proforma) invoice is refused with `400` when a Romanian party's county is not one ANAF can code — `EFACTURA_INVALID_COUNTY` for the client (fix the client record) or `EFACTURA_INVALID_VENDOR_COUNTY` for your company address; `details` carries `field` and `value`. Accepted: a county name in any case, with or without diacritics (\"Iași\", \"IASI\"), or its ISO 3166-2 code (\"IS\", \"RO-IS\"); a city or village (\"Purcareni\") is not a county. București addresses take the code from the city. A blank county is not refused here.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"clientId": {
										"type": "string",
										"pattern": "^[0-9a-fA-F]{24}$",
										"description": "MongoDB ObjectId of the client",
										"example": "60f7b1b9c9e7b4a1e8d1c2b4"
									},
									"seriesId": {
										"type": "string",
										"pattern": "^[0-9a-fA-F]{24}$",
										"description": "Invoice series ID (MongoDB ObjectId). Get available series from GET /api/series endpoint. Mutually exclusive with customSerialNumber.",
										"example": "60f7b1b9c9e7b4a1e8d1c2b5"
									},
									"customSerialNumber": {
										"type": "string",
										"pattern": "^[A-Za-z0-9-_]+$",
										"minLength": 1,
										"maxLength": 50,
										"description": "Custom invoice number (alphanumeric, hyphens, underscores only). Mutually exclusive with seriesId.",
										"example": "CUSTOM-INV-2025-001"
									},
									"draft": {
										"type": "boolean",
										"default": false,
										"description": "If true, creates a draft invoice that can be edited before publishing. Drafts do not consume series numbers until published.",
										"example": false
									},
									"issueDate": {
										"type": "string",
										"format": "date",
										"description": "Invoice issue date (ISO 8601 format)",
										"example": "2024-01-15"
									},
									"dueDate": {
										"type": "string",
										"format": "date",
										"description": "Payment due date (ISO 8601 format)",
										"example": "2024-02-14"
									},
									"deliveryDate": {
										"type": "string",
										"format": "date",
										"description": "Actual delivery / supply date (e-Factura BT-72, ISO 8601 format). When provided, the e-Factura XML emits cac:Delivery/cac:ActualDeliveryDate.",
										"example": "2024-01-14"
									},
									"currency": {
										"type": "string",
										"pattern": "^[A-Za-z]{3}$",
										"default": "RON",
										"description": "ISO 4217 currency code the invoice is priced in (e.g. RON, EUR, USD). Defaults to RON. Item prices and totals are expressed in this currency.",
										"example": "EUR"
									},
									"exchangeRate": {
										"type": "number",
										"exclusiveMinimum": 0,
										"description": "Exchange rate as RON per 1 unit of `currency`. Required when currency is not RON; ignored (forced to 1) for RON. The app uses it to compute the RON total (total × exchangeRate) and e-factura emits the mandatory RON tax total from it (ANAF rule BR-53).",
										"example": 4.9772
									},
									"services": {
										"type": "array",
										"minItems": 1,
										"maxItems": 50,
										"description": "List of services/products on the invoice",
										"items": {
											"type": "object",
											"properties": {
												"description": {
													"type": "string",
													"minLength": 1,
													"maxLength": 100,
													"description": "Item/service name. Maximum 100 characters (ANAF e-factura rule BR-RO-L100)."
												},
												"quantity": {
													"type": "number",
													"minimum": 0.01
												},
												"unitPrice": {
													"type": "number",
													"minimum": 0
												},
												"vatRate": {
													"type": "number",
													"description": "VAT rate percentage (e.g., 21 for 21%). For Romanian clients, this must be one of [0, 9, 11, 21] (Romanian VAT, Law 141/2025). For an ordinary sale this is all you need — the tax category is inferred as 'S' (standard). A 0% line requires an explicit taxCategory (see below)."
												},
												"unitOfMeasure": {
													"type": "string",
													"maxLength": 10,
													"description": "Unit of measure (default: 'buc' - pieces)",
													"example": "buc"
												},
												"taxCategory": {
													"type": "string",
													"enum": [
														"S",
														"AE",
														"Z",
														"E",
														"O"
													],
													"description": "EN 16931 VAT category (v2026-08-01+). OPTIONAL — omit for ordinary sales (inferred 'S'). Use to disambiguate a 0% line: 'S' standard, 'AE' reverse charge (taxare inversă), 'Z' zero-rated, 'E' exempt (also send vatExemptionCode), 'O' outside scope of VAT."
												},
												"vatExemptionCode": {
													"type": "string",
													"description": "EN 16931 exemption reason code (VATEX-EU-*). Required when taxCategory is 'E'. Examples: 'VATEX-EU-132' (intra-community supply), 'VATEX-EU-G' (export outside EU), 'VATEX-EU-D' (travel-agent margin), 'VATEX-EU-F' (second-hand margin)."
												},
												"discount": {
													"type": "object",
													"description": "Optional per-line discount, applied to the net BEFORE VAT (v2026-08-01+).",
													"properties": {
														"type": {
															"type": "string",
															"enum": [
																"percentage",
																"amount"
															],
															"description": "'percentage' (0–100) or a fixed 'amount' in the invoice currency."
														},
														"value": {
															"type": "number",
															"minimum": 0
														}
													},
													"required": [
														"type",
														"value"
													],
													"additionalProperties": false
												}
											},
											"required": [
												"description",
												"quantity",
												"unitPrice",
												"vatRate"
											],
											"additionalProperties": false
										}
									},
									"notes": {
										"type": "string",
										"maxLength": 1000,
										"description": "Additional notes or payment terms",
										"example": "Payment due in 30 days"
									},
									"language": {
										"type": "string",
										"enum": [
											"ro",
											"en"
										],
										"default": "ro",
										"description": "Invoice PDF language (ro=Romanian, en=English)",
										"example": "en"
									},
									"documentType": {
										"type": "string",
										"enum": [
											"invoice",
											"proforma"
										],
										"default": "invoice",
										"description": "Document type. Use \"proforma\" to create a non-fiscal proforma invoice (FACTURĂ PROFORMĂ). Use POST /:id/finalize to convert it to a fiscal invoice. Defaults to \"invoice\".",
										"example": "invoice"
									},
									"isSelfBilling": {
										"type": "boolean",
										"description": "If true, creates an autofacturare (self-billing) invoice where the organization is the buyer and the client is the seller.",
										"default": false
									},
									"selfBillingDetails": {
										"type": "object",
										"description": "Required if isSelfBilling is true. Contains the contract details for self-billing.",
										"properties": {
											"contractNumber": {
												"type": "string",
												"description": "The number of the self-billing contract."
											},
											"contractDate": {
												"type": "string",
												"format": "date",
												"description": "The date of the self-billing contract (ISO 8601 format)."
											}
										},
										"required": [
											"contractNumber",
											"contractDate"
										],
										"additionalProperties": false
									}
								},
								"required": [
									"clientId",
									"issueDate",
									"services"
								],
								"additionalProperties": false,
								"example": {
									"clientId": "60f7b1b9c9e7b4a1e8d1c2b4",
									"seriesId": "60f7b1b9c9e7b4a1e8d1c2b5",
									"issueDate": "2025-01-15",
									"dueDate": "2025-02-14",
									"services": [
										{
											"description": "Web Development Services",
											"quantity": 8,
											"unitPrice": 150,
											"unitOfMeasure": "hours",
											"vatRate": 21
										},
										{
											"description": "Project Management",
											"quantity": 4,
											"unitPrice": 100,
											"unitOfMeasure": "hours",
											"vatRate": 21
										}
									],
									"notes": "Payment due in 30 days. Bank transfer preferred.",
									"language": "ro"
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"201": {
						"description": "Invoice created successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invoice created successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"invoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1",
													"description": "Identifier of the created resource. For published invoices this is the invoice ObjectId; for drafts it is the draft ObjectId."
												},
												"serialNumber": {
													"type": "string",
													"example": "FACT-00123",
													"description": "Generated invoice serial number. Drafts have no finalized serial yet and return \"DRAFT\"."
												},
												"isDraft": {
													"type": "boolean",
													"example": false,
													"description": "True when the created resource is a draft (not yet finalized). Published invoices return false."
												},
												"filename": {
													"type": "string",
													"example": "draft-60f7b1b9c9e7b4a1e8d1c2c1.json",
													"description": "Storage filename of the draft. Present only on the draft path."
												},
												"createdAt": {
													"type": "string",
													"format": "date-time",
													"example": "2025-01-15T10:30:00.000Z",
													"description": "Creation timestamp of the draft. Present only on the draft path."
												}
											}
										}
									},
									"example": {
										"success": true,
										"data": {
											"invoiceId": "60f7b1b9c9e7b4a1e8d1c2c1",
											"serialNumber": "FACT-00123",
											"isDraft": false
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List invoices with filtering",
				"tags": [
					"Invoices"
				],
				"description": "Retrieve a paginated list of invoices with optional filtering by date range, payment status, and client.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "startDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "endDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"unpaid",
								"paid",
								"partial",
								"canceled"
							],
							"example": "paid"
						},
						"in": "query",
						"name": "paymentStatus",
						"required": false,
						"description": "Filter by payment status: 'unpaid' (no payments), 'paid' (fully paid), 'partial' (partially paid), or 'canceled'."
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b4"
						},
						"in": "query",
						"name": "clientId",
						"required": false,
						"description": "Filter by specific client ID"
					}
				],
				"responses": {
					"200": {
						"description": "Invoices retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invoices retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"invoices": {
													"type": "array",
													"description": "Array of invoice objects",
													"items": {
														"type": "object",
														"additionalProperties": false,
														"properties": {
															"_id": {
																"type": "string"
															},
															"invoiceId": {
																"type": "string"
															},
															"filename": {
																"type": "string"
															},
															"createdAt": {
																"type": "string"
															},
															"paymentStatus": {
																"type": "string",
																"enum": [
																	"unpaid",
																	"paid",
																	"partial",
																	"canceled"
																]
															},
															"spvLifecycleState": {
																"type": "string"
															},
															"data": {
																"type": "object",
																"additionalProperties": true
															},
															"payments": {
																"type": "array",
																"items": {
																	"type": "object",
																	"additionalProperties": true
																}
															},
															"stornoInvoiceId": {
																"type": "string"
															}
														}
													}
												},
												"pagination": {
													"type": "object",
													"properties": {
														"total": {
															"type": "number",
															"example": 2
														},
														"page": {
															"type": "number",
															"example": 1
														},
														"limit": {
															"type": "number",
															"example": 20
														},
														"pages": {
															"type": "number",
															"example": 1
														}
													}
												}
											}
										}
									},
									"example": {
										"success": true,
										"data": {
											"invoices": [
												{
													"_id": "60f7b1b9c9e7b4a1e8d1c2c1",
													"invoiceId": "fdd6976e-9c10-48de-b890-882160f814f1",
													"filename": "a7ac356d-c952-411c-bbc6-41914ae160e4.pdf",
													"createdAt": "2025-01-15T10:30:00.000Z",
													"paymentStatus": "unpaid",
													"data": {
														"serialNumber": "FACT-00123",
														"invoiceDate": "2025-01-15",
														"paymentDueDate": "2025-02-14",
														"totals": {
															"totalWithoutVAT": 1600,
															"totalVAT": 304,
															"totalWithVAT": 1904
														},
														"client": {
															"name": "SC Example SRL",
															"taxId": "12345678"
														},
														"vendor": {
															"name": "Your Company SRL",
															"taxIdentificationNumber": "98765432"
														}
													}
												}
											],
											"pagination": {
												"total": 15,
												"page": 1,
												"limit": 20,
												"pages": 1
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/branding-preview": {
			"post": {
				"summary": "Render a branding-preview invoice PDF",
				"tags": [
					"Invoices"
				],
				"description": "Render a **sample** invoice PDF with the supplied partner branding theme applied.\n\nThe invoice content is a fixed, hardcoded Romanian sample — it contains NO real customer data and reads nothing from your account. Only the branding theme (preset, accent colour, logo placement, footer) is taken from the request body. Omit `theme` to render the default Billyou branding.\n\nThe response is the PDF binary (`Content-Type: application/pdf`), served inline for embedding in a live preview.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"additionalProperties": false,
								"properties": {
									"theme": {
										"type": "object",
										"additionalProperties": false,
										"properties": {
											"schemaVersion": {
												"type": "integer",
												"enum": [
													1
												]
											},
											"preset": {
												"type": "string",
												"enum": [
													"classic",
													"modern"
												]
											},
											"accentColor": {
												"type": "string",
												"maxLength": 7,
												"description": "Hex accent colour, e.g. '#2563eb'."
											},
											"logoPlacement": {
												"type": "string",
												"enum": [
													"top-left",
													"top-center"
												]
											},
											"footer": {
												"type": "object",
												"additionalProperties": false,
												"properties": {
													"mode": {
														"type": "string",
														"enum": [
															"billyou",
															"none",
															"partner"
														]
													},
													"text": {
														"type": "string",
														"maxLength": 120
													},
													"url": {
														"type": "string",
														"maxLength": 2048
													}
												},
												"required": [
													"mode"
												]
											}
										},
										"required": [
											"schemaVersion",
											"preset",
											"footer"
										]
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Rendered sample invoice PDF (binary)",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rendered sample invoice PDF (binary)",
									"type": "string",
									"format": "binary"
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/saga": {
			"get": {
				"summary": "Export issued invoices of a period for Saga",
				"tags": [
					"Invoices"
				],
				"description": "Issued invoices in the **Saga C** import format (Saga → Diverse → Import date). The company is the supplier (<FurnizorCIF>), so Saga files them under **Ieșiri**. Storno invoices are included (negative quantities); proformas, drafts and cancelled invoices are not.\n\nDates are taken on the Romanian (Europe/Bucharest) calendar. Amounts are in the invoice currency; for foreign-currency invoices the BNR rate is stated in FacturaInformatiiSuplimentare. See also the app's \"Export Saga\" button, which produces the same file.\n\nThe period is inclusive and at most 366 days.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
						},
						"in": "query",
						"name": "startDate",
						"required": true,
						"description": "First invoice date (YYYY-MM-DD)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
						},
						"in": "query",
						"name": "endDate",
						"required": true,
						"description": "Last invoice date (YYYY-MM-DD)"
					},
					{
						"schema": {
							"type": "boolean",
							"default": false
						},
						"in": "query",
						"name": "download",
						"required": false,
						"description": "true: respond with the XML file (Content-Disposition attachment) instead of JSON"
					}
				],
				"responses": {
					"200": {
						"description": "Saga XML. With download=true the body is the XML file itself (application/xml) instead of this JSON.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Saga XML. With download=true the body is the XML file itself (application/xml) instead of this JSON.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"fileName": {
													"type": "string",
													"description": "The file name Saga's import screen requires: F_<CIF>_<number-or-period>_<dd.mm.yyyy>.xml. Save the content under exactly this name.",
													"example": "F_44540371_IESIRI-2026-09-01-2026-09-30_04.10.2026.xml"
												},
												"contentType": {
													"type": "string",
													"example": "application/xml"
												},
												"content": {
													"type": "string",
													"description": "The Saga XML (UTF-8)"
												},
												"exported": {
													"type": "integer",
													"description": "Invoices in the file"
												},
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													},
													"description": "Invoices of the period left out, and why"
												},
												"truncated": {
													"type": "boolean",
													"description": "true when the period held more than 20,000 invoices and the export was capped"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"422": {
						"description": "Nothing exportable in the period, or the organization has no fiscal code",
						"content": {
							"application/json": {
								"schema": {
									"description": "Nothing exportable in the period, or the organization has no fiscal code",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"type": "object",
											"properties": {
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													}
												},
												"skippedReasons": {
													"type": "string"
												}
											}
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					},
					"504": {
						"description": "The export took too long",
						"content": {
							"application/json": {
								"schema": {
									"description": "The export took too long",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"type": "object",
											"properties": {
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													}
												},
												"skippedReasons": {
													"type": "string"
												}
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}": {
			"get": {
				"summary": "Get invoice details",
				"tags": [
					"Invoices"
				],
				"description": "Retrieve detailed information for a specific invoice by its ID.\n\n**Testing**: Replace the example invoice ID with an actual invoice ID from your account. You can get invoice IDs by:\n1. Creating a new invoice with POST /api/invoices\n2. Listing invoices with GET /api/invoices",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Invoice retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invoice retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"_id": {
													"type": "string"
												},
												"invoiceId": {
													"type": "string"
												},
												"filename": {
													"type": "string"
												},
												"createdAt": {
													"type": "string"
												},
												"paymentStatus": {
													"type": "string",
													"enum": [
														"unpaid",
														"paid",
														"partial",
														"canceled"
													]
												},
												"spvLifecycleState": {
													"type": "string"
												},
												"data": {
													"type": "object",
													"additionalProperties": true
												},
												"payments": {
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												"stornoInvoiceId": {
													"type": "string"
												}
											}
										}
									},
									"example": {
										"success": true,
										"data": {
											"_id": "60f7b1b9c9e7b4a1e8d1c2c1",
											"invoiceId": "fdd6976e-9c10-48de-b890-882160f814f1",
											"filename": "a7ac356d-c952-411c-bbc6-41914ae160e4.pdf",
											"createdAt": "2025-01-15T10:30:00.000Z",
											"paymentStatus": "unpaid",
											"data": {
												"isVAT": true,
												"currency": "RON",
												"exchangeRate": 1,
												"invoiceDate": "2025-01-15",
												"paymentDueDate": "2025-02-14",
												"paymentDueOption": "custom",
												"items": [
													{
														"description": "Web Development Services",
														"quantity": 8,
														"unitPrice": 150,
														"unitOfMeasure": "hours",
														"VATRate": 21,
														"currency": "RON",
														"exchangeRate": 1,
														"totalWithoutVAT": 1200,
														"VATValue": 252
													},
													{
														"description": "Project Management",
														"quantity": 4,
														"unitPrice": 100,
														"unitOfMeasure": "hours",
														"VATRate": 21,
														"currency": "RON",
														"exchangeRate": 1,
														"totalWithoutVAT": 400,
														"VATValue": 84
													}
												],
												"totals": {
													"totalWithoutVAT": 1600,
													"totalVAT": 336,
													"totalWithVAT": 1936
												},
												"client": {
													"_id": "60f7b1b9c9e7b4a1e8d1c2b4",
													"name": "SC Example SRL",
													"taxId": "12345678",
													"tradeRegistryNumber": "J40/1234/2020",
													"contactEmails": [
														"contact@example.ro"
													],
													"address": "Strada Exemplu nr. 123",
													"city": "București",
													"county": "București",
													"postalCode": "010101",
													"country": "România",
													"IBAN": "RO49AAAA1B31007593840000",
													"phone": "+40123456789"
												},
												"vendor": {
													"_id": "60f7b1b9c9e7b4a1e8d1c2b3",
													"name": "Your Company SRL",
													"taxIdentificationNumber": "98765432",
													"tradeRegistryNumber": "J40/5678/2020"
												},
												"additionalNotes": "Payment due in 30 days. Bank transfer preferred.",
												"language": "ro",
												"serialNumber": "FACT-00123"
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"delete": {
				"summary": "Delete an invoice",
				"tags": [
					"Invoices"
				],
				"description": "Delete an invoice. Only the last invoice in a series can be deleted. Invoices with payments or submitted to E-Factura cannot be deleted.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Invoice deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invoice deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"deleted": {
													"type": "boolean",
													"example": true
												},
												"invoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_LAST_IN_SERIES",
										"message": "Only the last invoice in series can be deleted. Use cancellation for other invoices."
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/cancel": {
			"post": {
				"summary": "Cancel an invoice",
				"tags": [
					"Invoices"
				],
				"description": "Cancel an invoice. This creates a cancellation document and marks the invoice as cancelled.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Invoice cancelled successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invoice cancelled successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"cancelled": {
													"type": "boolean",
													"example": true
												},
												"invoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"409": {
						"description": "The document is a proforma, which is not a fiscal document and cannot be cancelled (delete it instead)",
						"content": {
							"application/json": {
								"schema": {
									"description": "The document is a proforma, which is not a fiscal document and cannot be cancelled (delete it instead)",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": false
										},
										"errorCode": {
											"type": "string",
											"example": "PROFORMA_NOT_CANCELABLE"
										},
										"message": {
											"type": "string"
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/efactura/submissions": {
			"post": {
				"summary": "Submit invoice to ANAF E-Factura system",
				"tags": [
					"E-Factura"
				],
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Simulation completed (sandbox smart_mock) or success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Simulation completed (sandbox smart_mock) or success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"invoiceId": {
													"type": "string"
												},
												"uploadIndex": {
													"type": "string"
												},
												"downloadId": {
													"type": "string"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"processing",
														"uploaded",
														"validated",
														"rejected",
														"failed"
													]
												},
												"createdAt": {
													"type": "string"
												},
												"updatedAt": {
													"type": "string"
												},
												"error": {
													"type": "object",
													"properties": {
														"code": {
															"type": "string"
														},
														"message": {
															"type": "string"
														},
														"details": {
															"type": "object",
															"properties": {
																"errorCode": {
																	"type": "string"
																},
																"anafErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"properties": {
																			"code": {
																				"type": "string"
																			},
																			"message": {
																				"type": "string"
																			}
																		}
																	}
																},
																"translatedErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"additionalProperties": true
																	}
																}
															}
														}
													}
												},
												"simulation": {
													"type": "boolean"
												},
												"validationErrors": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"code": {
																"type": "string"
															},
															"message": {
																"type": "string"
															},
															"severity": {
																"type": "string"
															}
														}
													}
												}
											}
										}
									}
								}
							}
						}
					},
					"202": {
						"description": "E-Factura submission accepted for processing",
						"content": {
							"application/json": {
								"schema": {
									"description": "E-Factura submission accepted for processing",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"invoiceId": {
													"type": "string"
												},
												"uploadIndex": {
													"type": "string"
												},
												"downloadId": {
													"type": "string"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"processing",
														"uploaded",
														"validated",
														"rejected",
														"failed"
													]
												},
												"createdAt": {
													"type": "string"
												},
												"updatedAt": {
													"type": "string"
												},
												"error": {
													"type": "object",
													"properties": {
														"code": {
															"type": "string"
														},
														"message": {
															"type": "string"
														},
														"details": {
															"type": "object",
															"properties": {
																"errorCode": {
																	"type": "string"
																},
																"anafErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"properties": {
																			"code": {
																				"type": "string"
																			},
																			"message": {
																				"type": "string"
																			}
																		}
																	}
																},
																"translatedErrors": {
																	"type": "array",
																	"items": {
																		"type": "object",
																		"additionalProperties": true
																	}
																}
															}
														}
													}
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/email": {
			"post": {
				"summary": "Send invoice by email",
				"tags": [
					"Invoices"
				],
				"description": "Send an invoice access link to a specified email address with custom subject and message. The recipient must be authorized in the client's contact list.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"to": {
										"type": "string",
										"format": "email",
										"description": "Recipient email address",
										"example": "client@example.ro"
									},
									"subject": {
										"type": "string",
										"minLength": 1,
										"maxLength": 200,
										"description": "Email subject line",
										"example": "Factura FACT125 - SC Example SRL"
									},
									"body": {
										"type": "string",
										"minLength": 1,
										"maxLength": 2000,
										"description": "Email message body",
										"example": "Vă transmitem factura în anexă. Mulțumim!"
									},
									"language": {
										"type": "string",
										"enum": [
											"ro",
											"en"
										],
										"default": "ro",
										"description": "Email language",
										"example": "ro"
									},
									"addToContacts": {
										"type": "boolean",
										"description": "Add recipient email to client contact list if not present",
										"default": false,
										"example": false
									}
								},
								"required": [
									"to",
									"subject",
									"body"
								],
								"additionalProperties": false
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Email sent successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Email sent successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/finalize": {
			"post": {
				"summary": "Convert a proforma invoice to a fiscal invoice",
				"tags": [
					"Invoices"
				],
				"description": "Convert a proforma invoice (FACTURĂ PROFORMĂ) into a binding fiscal invoice on a separate fiscal series.\n\nThe proforma is NOT deleted — it is marked with the resulting fiscal invoice ID. The fiscal invoice will include a note referencing the proforma serial number.\n\n**Serial Number Options** (mutually exclusive, one required):\n- `seriesId`: Auto-generates next number from a fiscal invoice series\n- `customSerialNumber`: User-defined fiscal invoice number",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"seriesId": {
										"type": "string",
										"pattern": "^[0-9a-fA-F]{24}$",
										"description": "Fiscal invoice series ID. Mutually exclusive with customSerialNumber.",
										"example": "60f7b1b9c9e7b4a1e8d1c2b5"
									},
									"customSerialNumber": {
										"type": "string",
										"pattern": "^[A-Za-z0-9-_]+$",
										"minLength": 1,
										"maxLength": 50,
										"description": "Custom fiscal invoice number. Mutually exclusive with seriesId.",
										"example": "FACT-2025-001"
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Proforma invoice ID (MongoDB ObjectId)"
					}
				],
				"responses": {
					"201": {
						"description": "Fiscal invoice created successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Fiscal invoice created successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"invoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1"
												},
												"serialNumber": {
													"type": "string",
													"example": "FACT-00123"
												},
												"isDraft": {
													"type": "boolean",
													"example": false
												},
												"originProformaId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2b9"
												},
												"originProformaSerialNumber": {
													"type": "string",
													"example": "PROF-0001"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Validation error (not a proforma, missing series config)",
						"content": {
							"application/json": {
								"schema": {
									"description": "Validation error (not a proforma, missing series config)",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										}
									}
								}
							}
						}
					},
					"409": {
						"description": "Proforma already converted",
						"content": {
							"application/json": {
								"schema": {
									"description": "Proforma already converted",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/payments": {
			"post": {
				"summary": "Record a new payment",
				"tags": [
					"Payments"
				],
				"description": "Record a payment for an invoice. The payment amount will be added to the invoice's total paid amount.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"amount": {
										"type": "number",
										"minimum": 0.01,
										"description": "Payment amount",
										"example": 500
									},
									"paymentDate": {
										"type": "string",
										"format": "date-time",
										"description": "Date when payment was made (accepts both date and datetime formats)",
										"example": "2024-01-20T10:30:00.000Z"
									},
									"paymentMethod": {
										"type": "string",
										"enum": [
											"cash",
											"bank_transfer",
											"card",
											"check",
											"other"
										],
										"description": "Method of payment",
										"example": "bank_transfer"
									},
									"currency": {
										"type": "string",
										"default": "RON",
										"description": "Payment currency (defaults to RON)",
										"example": "RON"
									},
									"exchangeRate": {
										"type": "number",
										"minimum": 0,
										"description": "Exchange rate to RON (required for non-RON currencies)",
										"example": 4.97
									},
									"reference": {
										"type": "string",
										"maxLength": 200,
										"description": "Payment reference (e.g. transaction ID, check number)",
										"example": "TXN123456"
									},
									"notes": {
										"type": "string",
										"maxLength": 500,
										"description": "Additional payment notes",
										"example": "Transfer bancar - ref: TXN123456"
									}
								},
								"required": [
									"amount",
									"paymentDate"
								],
								"additionalProperties": false,
								"example": {
									"amount": 500,
									"paymentDate": "2024-01-20",
									"paymentMethod": "bank_transfer",
									"currency": "EUR",
									"exchangeRate": 4.97,
									"reference": "TXN123456",
									"notes": "Transfer bancar - ref: TXN123456"
								}
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"201": {
						"description": "Payment recorded successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payment recorded successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"invoiceId": {
													"type": "string",
													"description": "The invoice this payment was applied to",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1"
												},
												"amount": {
													"type": "number",
													"description": "Payment amount (in payment currency)",
													"example": 500
												},
												"paymentMethod": {
													"type": "string",
													"description": "Method used for payment",
													"example": "bank_transfer"
												},
												"paymentDate": {
													"type": "string",
													"description": "Date/datetime the payment was made",
													"example": "2024-01-20T10:30:00.000Z"
												},
												"paymentStatus": {
													"type": "string",
													"enum": [
														"unpaid",
														"paid",
														"partial"
													],
													"description": "The invoice's new payment status after this payment",
													"example": "paid"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List payments with filtering",
				"tags": [
					"Payments"
				],
				"description": "Retrieve a paginated list of payments with optional filtering by date range and invoice.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "startDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "endDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "invoiceId",
						"required": false,
						"description": "Filter payments for specific invoice"
					},
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Payments retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payments retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/payments/{paymentId}": {
			"delete": {
				"summary": "Delete a payment",
				"tags": [
					"Payments"
				],
				"description": "Delete a payment by its ID. The system will find the invoice containing this payment and recalculate the invoice status after the payment is removed.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"example": "68dcd51b9746176fdc513710"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Payment ID to delete (or invoice ID for the nested /invoices/:id/payments/:paymentId route)"
					},
					{
						"schema": {
							"type": "string",
							"example": "68dcd51b9746176fdc513710"
						},
						"in": "path",
						"name": "paymentId",
						"required": true,
						"description": "Payment ID to delete (nested /invoices/:id/payments/:paymentId route)"
					}
				],
				"responses": {
					"200": {
						"description": "Payment deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payment deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/paymentstatus": {
			"get": {
				"summary": "Get invoice payment status",
				"tags": [
					"Invoices"
				],
				"description": "Retrieve detailed payment information for an invoice including amounts paid, remaining balance, and payment history.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Payment status retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payment status retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/pdf": {
			"get": {
				"summary": "Get invoice PDF download URL",
				"tags": [
					"Invoices"
				],
				"description": "Get a presigned download URL for the invoice PDF.\n\nThe response contains a presigned S3 URL that can be used directly to download the PDF file.\n\nThe URL is valid for 10 minutes (600 seconds).",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "PDF download URL retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "PDF download URL retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"downloadUrl": {
													"type": "string",
													"description": "Presigned S3 URL to download the PDF directly",
													"example": "https://s3.eu-central-1.amazonaws.com/bucket/vizualizare/invoice.pdf?X-Amz-..."
												},
												"filename": {
													"type": "string",
													"description": "Formatted filename for download",
													"example": "factura_FACT-00123.pdf"
												},
												"expiresIn": {
													"type": "number",
													"description": "Time in seconds until the download URL expires",
													"example": 600
												}
											},
											"required": [
												"downloadUrl",
												"filename",
												"expiresIn"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/saga": {
			"get": {
				"summary": "Export one issued invoice for Saga",
				"tags": [
					"Invoices"
				],
				"description": "Issued invoices in the **Saga C** import format (Saga → Diverse → Import date). The company is the supplier (<FurnizorCIF>), so Saga files them under **Ieșiri**. Storno invoices are included (negative quantities); proformas, drafts and cancelled invoices are not.\n\nDates are taken on the Romanian (Europe/Bucharest) calendar. Amounts are in the invoice currency; for foreign-currency invoices the BNR rate is stated in FacturaInformatiiSuplimentare. See also the app's \"Export Saga\" button, which produces the same file.\n\nThe file holds this one invoice and is named F_<CIF>_<invoice number>_<invoice date>.xml, as Saga's manual names single invoices.",
				"parameters": [
					{
						"schema": {
							"type": "boolean",
							"default": false
						},
						"in": "query",
						"name": "download",
						"required": false,
						"description": "true: respond with the XML file (Content-Disposition attachment) instead of JSON"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Saga XML. With download=true the body is the XML file itself (application/xml) instead of this JSON.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Saga XML. With download=true the body is the XML file itself (application/xml) instead of this JSON.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"fileName": {
													"type": "string",
													"description": "The file name Saga's import screen requires: F_<CIF>_<number-or-period>_<dd.mm.yyyy>.xml. Save the content under exactly this name.",
													"example": "F_44540371_IESIRI-2026-09-01-2026-09-30_04.10.2026.xml"
												},
												"contentType": {
													"type": "string",
													"example": "application/xml"
												},
												"content": {
													"type": "string",
													"description": "The Saga XML (UTF-8)"
												},
												"exported": {
													"type": "integer",
													"description": "Invoices in the file"
												},
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													},
													"description": "Invoices of the period left out, and why"
												},
												"truncated": {
													"type": "boolean",
													"description": "true when the period held more than 20,000 invoices and the export was capped"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"422": {
						"description": "The invoice cannot be exported to Saga (proforma, cancelled, inconsistent) or the organization has no fiscal code",
						"content": {
							"application/json": {
								"schema": {
									"description": "The invoice cannot be exported to Saga (proforma, cancelled, inconsistent) or the organization has no fiscal code",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"type": "object",
											"properties": {
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													}
												},
												"skippedReasons": {
													"type": "string"
												}
											}
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					},
					"504": {
						"description": "The export took too long",
						"content": {
							"application/json": {
								"schema": {
									"description": "The export took too long",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"type": "object",
											"properties": {
												"skipped": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Invoice ID"
															},
															"number": {
																"type": "string",
																"description": "Invoice number"
															},
															"reason": {
																"type": "string",
																"description": "Why it was left out: CANCELED, MISSING_NUMBER, MISSING_DATE, NO_LINES, LINE_VAT_MISMATCH, PROFORMA (single-invoice export only)"
															}
														}
													}
												},
												"skippedReasons": {
													"type": "string"
												}
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/storno": {
			"post": {
				"summary": "Issue a storno (reversal) of an invoice",
				"tags": [
					"Invoices"
				],
				"description": "Creates a storno: a fiscal reversal that is the exact negative of the original invoice and references it. The server computes the negation — send only the original invoice id plus optional issueDate / seriesId / customSerialNumber / reason. Create-only: submit the storno to e-Factura separately.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"additionalProperties": false,
								"properties": {
									"issueDate": {
										"type": "string",
										"format": "date",
										"description": "Reversal date (YYYY-MM-DD). Defaults to today."
									},
									"seriesId": {
										"type": "string",
										"pattern": "^[0-9a-fA-F]{24}$",
										"description": "Series for the storno. Defaults to the original invoice's series. Mutually exclusive with customSerialNumber."
									},
									"customSerialNumber": {
										"type": "string",
										"minLength": 1,
										"maxLength": 50,
										"description": "Explicit serial number for the storno. Mutually exclusive with seriesId."
									},
									"reason": {
										"type": "string",
										"maxLength": 500,
										"description": "Optional free-text reason, recorded on the storno."
									}
								}
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"201": {
						"description": "Storno issued successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Storno issued successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"invoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c9"
												},
												"serialNumber": {
													"type": "string",
													"example": "FACT-00126"
												},
												"originalInvoiceId": {
													"type": "string",
													"example": "60f7b1b9c9e7b4a1e8d1c2c1"
												},
												"isDraft": {
													"type": "boolean",
													"example": false
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"409": {
						"description": "The invoice has already been reversed",
						"content": {
							"application/json": {
								"schema": {
									"description": "The invoice has already been reversed",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": false
										},
										"errorCode": {
											"type": "string",
											"example": "STORNO_ALREADY_EXISTS"
										},
										"message": {
											"type": "string"
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/invoices/{id}/xml": {
			"get": {
				"summary": "Get issued invoice e-Factura XML download URL",
				"tags": [
					"Invoices"
				],
				"description": "Get a presigned download URL for the e-Factura UBL XML of an issued invoice — the same XML that is submitted to ANAF.\n\nThe response contains a presigned S3 URL that can be used directly to download the XML file. The URL is valid for 10 minutes (600 seconds).\n\nThe XML is available as soon as the invoice exists — no e-Factura submission is required. If it has not been generated yet it is generated on demand and cached, so the first call may take slightly longer.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "XML download URL retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "XML download URL retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"downloadUrl": {
													"type": "string",
													"format": "uri",
													"description": "Presigned S3 URL to download the e-Factura UBL XML directly",
													"example": "https://s3.eu-central-1.amazonaws.com/bucket/efactura/invoice.xml?X-Amz-..."
												},
												"invoiceNumber": {
													"type": "string",
													"description": "Invoice number, used in the suggested filename",
													"example": "FACT-00123"
												},
												"filename": {
													"type": "string",
													"description": "Suggested filename for the download",
													"example": "efactura_FACT-00123.xml"
												},
												"expiresIn": {
													"type": "number",
													"description": "Time in seconds until the download URL expires",
													"example": 600
												}
											},
											"required": [
												"downloadUrl",
												"invoiceNumber",
												"filename",
												"expiresIn"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/oauth/clients": {
			"get": {
				"summary": "List your OAuth clients",
				"tags": [
					"OAuth"
				],
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1
						},
						"in": "query",
						"name": "page",
						"required": false
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"in": "query",
						"name": "limit",
						"required": false
					}
				],
				"responses": {
					"200": {
						"description": "List of clients (no secrets)",
						"content": {
							"application/json": {
								"schema": {
									"description": "List of clients (no secrets)",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"clients": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"description": "Internal client record id"
															},
															"client_id": {
																"type": "string",
																"description": "Public client identifier (bk_id_…)",
																"example": "bk_id_a1b2c3d4e5f6a1b2c3d4e5f6"
															},
															"name": {
																"type": "string",
																"example": "Acme Integration"
															},
															"is_active": {
																"type": "boolean",
																"example": true
															},
															"last_used_at": {
																"type": "string",
																"format": "date-time",
																"nullable": true
															},
															"created_at": {
																"type": "string",
																"format": "date-time"
															},
															"updated_at": {
																"type": "string",
																"format": "date-time"
															}
														}
													}
												},
												"pagination": {
													"type": "object",
													"additionalProperties": true
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"post": {
				"summary": "Create an OAuth client",
				"tags": [
					"OAuth"
				],
				"description": "Creates a client_id + client_secret scoped to your organization. The client_secret is returned exactly once.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": [
									"name"
								],
								"properties": {
									"name": {
										"type": "string",
										"minLength": 1,
										"maxLength": 256
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"201": {
						"description": "Client created (client_secret shown once)",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client created (client_secret shown once)",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"description": "Internal client record id"
												},
												"client_id": {
													"type": "string",
													"description": "Public client identifier (bk_id_…)",
													"example": "bk_id_a1b2c3d4e5f6a1b2c3d4e5f6"
												},
												"name": {
													"type": "string",
													"example": "Acme Integration"
												},
												"is_active": {
													"type": "boolean",
													"example": true
												},
												"last_used_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true
												},
												"created_at": {
													"type": "string",
													"format": "date-time"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time"
												},
												"client_secret": {
													"type": "string",
													"description": "Shown once — store it securely",
													"example": "bk_cs_…"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/oauth/clients/{clientId}": {
			"delete": {
				"summary": "Delete an OAuth client (revokes its live tokens)",
				"tags": [
					"OAuth"
				],
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "clientId",
						"required": true,
						"description": "Public client_id (bk_id_…)"
					}
				],
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"description": "Success",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/oauth/clients/{clientId}/rotate": {
			"post": {
				"summary": "Rotate an OAuth client secret",
				"tags": [
					"OAuth"
				],
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "clientId",
						"required": true,
						"description": "Public client_id (bk_id_…)"
					}
				],
				"responses": {
					"200": {
						"description": "New client_secret issued (shown once)",
						"content": {
							"application/json": {
								"schema": {
									"description": "New client_secret issued (shown once)",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"description": "Internal client record id"
												},
												"client_id": {
													"type": "string",
													"description": "Public client identifier (bk_id_…)",
													"example": "bk_id_a1b2c3d4e5f6a1b2c3d4e5f6"
												},
												"name": {
													"type": "string",
													"example": "Acme Integration"
												},
												"is_active": {
													"type": "boolean",
													"example": true
												},
												"last_used_at": {
													"type": "string",
													"format": "date-time",
													"nullable": true
												},
												"created_at": {
													"type": "string",
													"format": "date-time"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time"
												},
												"client_secret": {
													"type": "string",
													"example": "bk_cs_…"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/oauth/clients/{clientId}/usage": {
			"get": {
				"summary": "Usage analytics for an OAuth client",
				"tags": [
					"OAuth"
				],
				"parameters": [
					{
						"schema": {
							"type": "string",
							"format": "date-time"
						},
						"in": "query",
						"name": "startDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"format": "date-time"
						},
						"in": "query",
						"name": "endDate",
						"required": false
					},
					{
						"schema": {
							"type": "string"
						},
						"in": "path",
						"name": "clientId",
						"required": true,
						"description": "Public client_id (bk_id_…)"
					}
				],
				"responses": {
					"200": {
						"description": "Aggregated usage for the client",
						"content": {
							"application/json": {
								"schema": {
									"description": "Aggregated usage for the client",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"data": {
											"type": "object",
											"additionalProperties": true
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/oauth/token": {
			"post": {
				"summary": "OAuth 2.0 token endpoint (client credentials grant)",
				"tags": [
					"OAuth"
				],
				"description": "Exchanges a client_id + client_secret for a short-lived Bearer access token. Accepts application/x-www-form-urlencoded or application/json. Public endpoint.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"grant_type": {
										"type": "string"
									},
									"client_id": {
										"type": "string"
									},
									"client_secret": {
										"type": "string"
									}
								}
							}
						}
					}
				},
				"security": [],
				"responses": {
					"200": {
						"description": "Access token issued",
						"content": {
							"application/json": {
								"schema": {
									"description": "Access token issued",
									"type": "object",
									"properties": {
										"access_token": {
											"type": "string",
											"example": "bk_at_…"
										},
										"token_type": {
											"type": "string",
											"example": "Bearer"
										},
										"expires_in": {
											"type": "integer",
											"example": 3600
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Invalid request (RFC 6749 error)",
						"content": {
							"application/json": {
								"schema": {
									"description": "Invalid request (RFC 6749 error)",
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"example": "unsupported_grant_type"
										},
										"error_description": {
											"type": "string"
										}
									}
								}
							}
						}
					},
					"401": {
						"description": "Client authentication failed (RFC 6749 error)",
						"content": {
							"application/json": {
								"schema": {
									"description": "Client authentication failed (RFC 6749 error)",
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"example": "invalid_client"
										},
										"error_description": {
											"type": "string"
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/partner/accounts": {
			"post": {
				"summary": "Provision an end-customer account",
				"tags": [
					"Partner"
				],
				"description": "Provision a new trial end-customer account on behalf of your partner organization. Provide either a CUI (for companies) or a CNP (for individuals), but not both. Returns the new organization ID and a production API key scoped to that account.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"additionalProperties": false,
								"properties": {
									"email": {
										"type": "string",
										"format": "email",
										"maxLength": 320,
										"description": "Email of the account owner. The invite is sent here.",
										"example": "owner@example.com"
									},
									"firstName": {
										"type": "string",
										"minLength": 1,
										"maxLength": 200,
										"example": "Ion"
									},
									"lastName": {
										"type": "string",
										"minLength": 1,
										"maxLength": 200,
										"example": "Popescu"
									},
									"cui": {
										"type": "string",
										"maxLength": 20,
										"description": "Romanian CUI for company accounts. Mutually exclusive with cnp.",
										"example": "RO12345678"
									},
									"cnp": {
										"type": "string",
										"maxLength": 20,
										"description": "Romanian CNP for individual accounts. Mutually exclusive with cui.",
										"example": "1900101221144"
									},
									"companyName": {
										"type": "string",
										"maxLength": 200,
										"description": "Company name. Required for company (cui) accounts.",
										"example": "Example SRL"
									},
									"tradeRegistryNumber": {
										"type": "string",
										"maxLength": 50,
										"description": "Optional trade registry number (J number) for companies.",
										"example": "J40/1234/2020"
									},
									"address": {
										"type": "object",
										"description": "Postal address of the end-customer. Required.",
										"additionalProperties": false,
										"properties": {
											"street": {
												"type": "string",
												"maxLength": 200,
												"example": "Strada Exemplu"
											},
											"number": {
												"type": "string",
												"maxLength": 200,
												"example": "10"
											},
											"city": {
												"type": "string",
												"maxLength": 200,
												"example": "Bucuresti"
											},
											"county": {
												"type": "string",
												"maxLength": 200,
												"example": "Bucuresti"
											},
											"postalCode": {
												"type": "string",
												"maxLength": 200,
												"example": "010101"
											},
											"completeAddress": {
												"type": "string",
												"minLength": 1,
												"maxLength": 200,
												"description": "Free-form full address. Required — the structured fields above are optional.",
												"example": "Strada Exemplu 10, Bucuresti"
											}
										},
										"required": [
											"completeAddress"
										]
									},
									"phone": {
										"type": "string",
										"maxLength": 40,
										"example": "+40712345678"
									},
									"locale": {
										"type": "string",
										"enum": [
											"ro",
											"en"
										],
										"default": "ro",
										"description": "Preferred language for the account owner (invite + UI)."
									}
								},
								"required": [
									"email",
									"firstName",
									"lastName",
									"address"
								],
								"oneOf": [
									{
										"required": [
											"cui"
										]
									},
									{
										"required": [
											"cnp"
										]
									}
								],
								"example": {
									"email": "owner@example.com",
									"firstName": "Ion",
									"lastName": "Popescu",
									"cui": "RO12345678",
									"companyName": "Example SRL",
									"address": {
										"city": "Bucuresti",
										"county": "Bucuresti",
										"completeAddress": "Strada Exemplu 10, Bucuresti"
									},
									"locale": "ro"
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Account provisioned successfully.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Account provisioned successfully.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"organizationId": {
													"type": "string",
													"description": "The newly provisioned organization ID.",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"apiKey": {
													"type": "string",
													"description": "Production API key for the new account. Returned only once — store it securely.",
													"example": "bk_user_live_a1b2c3..."
												},
												"activationStatus": {
													"type": "string",
													"description": "Activation state of the account.",
													"example": "invite_sent"
												}
											},
											"required": [
												"organizationId",
												"apiKey",
												"activationStatus"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"409": {
						"description": "Conflict",
						"content": {
							"application/json": {
								"schema": {
									"description": "Conflict",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "ORG_EXISTS",
										"message": "An organization with this tax ID already exists."
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					},
					"503": {
						"description": "Provisioning timed out (safe to retry, tax-id idempotent).",
						"content": {
							"application/json": {
								"schema": {
									"description": "Provisioning timed out (safe to retry, tax-id idempotent).",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "PROVISIONING_TIMEOUT",
										"message": "The provisioning request timed out but may still have succeeded. It is safe to retry — accounts are de-duplicated by tax ID."
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List provisioned accounts",
				"tags": [
					"Partner"
				],
				"description": "Retrieve a paginated list of the end-customer accounts your partner organization has provisioned.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					}
				],
				"responses": {
					"200": {
						"description": "Provisioned accounts retrieved successfully.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Provisioned accounts retrieved successfully.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"organizationId": {
														"type": "string",
														"description": "The provisioned end-customer organization ID.",
														"example": "60f7b1b9c9e7b4a1e8d1c2b3"
													},
													"name": {
														"type": "string",
														"nullable": true,
														"description": "Company name (company accounts)."
													},
													"cui": {
														"type": "string",
														"nullable": true,
														"description": "Romanian CUI (company accounts)."
													},
													"cnp": {
														"type": "string",
														"nullable": true,
														"description": "Romanian CNP (individual accounts)."
													},
													"firstName": {
														"type": "string",
														"nullable": true
													},
													"lastName": {
														"type": "string",
														"nullable": true
													},
													"accountType": {
														"type": "string",
														"nullable": true,
														"enum": [
															"company",
															"individual",
															null
														],
														"description": "Whether the account is a company or an individual."
													},
													"provisionedByPartnerOrgId": {
														"type": "string",
														"nullable": true,
														"description": "The partner org that provisioned this account (always your org)."
													},
													"createdVia": {
														"type": "string",
														"nullable": true,
														"description": "How the account was created (PARTNER_API for partner-provisioned accounts)."
													},
													"createdAt": {
														"type": "string",
														"nullable": true,
														"format": "date-time"
													}
												}
											}
										},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer",
													"example": 42
												},
												"page": {
													"type": "integer",
													"example": 1
												},
												"limit": {
													"type": "integer",
													"example": 20
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/partner/accounts/{id}": {
			"get": {
				"summary": "Get a provisioned account",
				"tags": [
					"Partner"
				],
				"description": "Retrieve a single end-customer account your partner organization provisioned, by its organization ID.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "The provisioned organization ID."
					}
				],
				"responses": {
					"200": {
						"description": "Provisioned account retrieved successfully.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Provisioned account retrieved successfully.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"organizationId": {
													"type": "string",
													"description": "The provisioned end-customer organization ID.",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"name": {
													"type": "string",
													"nullable": true,
													"description": "Company name (company accounts)."
												},
												"cui": {
													"type": "string",
													"nullable": true,
													"description": "Romanian CUI (company accounts)."
												},
												"cnp": {
													"type": "string",
													"nullable": true,
													"description": "Romanian CNP (individual accounts)."
												},
												"firstName": {
													"type": "string",
													"nullable": true
												},
												"lastName": {
													"type": "string",
													"nullable": true
												},
												"accountType": {
													"type": "string",
													"nullable": true,
													"enum": [
														"company",
														"individual",
														null
													],
													"description": "Whether the account is a company or an individual."
												},
												"provisionedByPartnerOrgId": {
													"type": "string",
													"nullable": true,
													"description": "The partner org that provisioned this account (always your org)."
												},
												"createdVia": {
													"type": "string",
													"nullable": true,
													"description": "How the account was created (PARTNER_API for partner-provisioned accounts)."
												},
												"createdAt": {
													"type": "string",
													"nullable": true,
													"format": "date-time"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/partner/efactura/auth-sessions": {
			"post": {
				"summary": "Start a white-label ANAF e-Factura authorization session",
				"tags": [
					"Partner"
				],
				"description": "Returns a one-time authorizeUrl to redirect the end-user's browser to. The end-user authorizes on ANAF and is returned to your registered returnUri with a status. Requires the target organization to be one you provisioned, and returnUri to be in your connect.anafReturnUris allow-list.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"additionalProperties": false,
								"required": [
									"organizationId",
									"returnUri"
								],
								"properties": {
									"organizationId": {
										"type": "string",
										"pattern": "^[0-9a-fA-F]{24}$",
										"description": "A child organization you provisioned."
									},
									"returnUri": {
										"type": "string",
										"format": "uri",
										"description": "Partner-owned https URL to return to (must exactly match a connect.anafReturnUris entry)."
									}
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Authorization session created",
						"content": {
							"application/json": {
								"schema": {
									"description": "Authorization session created",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"additionalProperties": false,
											"properties": {
												"authorizeUrl": {
													"type": "string",
													"example": "https://api.billyou.ro/api/partner/efactura/authorize?session=…"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/payments/": {
			"get": {
				"summary": "List payments with filtering",
				"tags": [
					"Payments"
				],
				"description": "Retrieve a paginated list of payments with optional filtering by date range and invoice.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"default": 1,
							"example": 1
						},
						"in": "query",
						"name": "page",
						"required": false,
						"description": "Page number for pagination"
					},
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20,
							"example": 20
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Number of items per page"
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "startDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"format": "date"
						},
						"in": "query",
						"name": "endDate",
						"required": false
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "invoiceId",
						"required": false,
						"description": "Filter payments for specific invoice"
					}
				],
				"responses": {
					"200": {
						"description": "Payments retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payments retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/payments/{id}": {
			"delete": {
				"summary": "Delete a payment",
				"tags": [
					"Payments"
				],
				"description": "Delete a payment by its ID. The system will find the invoice containing this payment and recalculate the invoice status after the payment is removed.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"example": "68dcd51b9746176fdc513710"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Payment ID to delete (or invoice ID for the nested /invoices/:id/payments/:paymentId route)"
					},
					{
						"schema": {
							"type": "string",
							"example": "68dcd51b9746176fdc513710"
						},
						"in": "path",
						"name": "paymentId",
						"required": true,
						"description": "Payment ID to delete (nested /invoices/:id/payments/:paymentId route)"
					}
				],
				"responses": {
					"200": {
						"description": "Payment deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Payment deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {},
										"meta": {
											"type": "object",
											"properties": {
												"total": {
													"type": "integer"
												},
												"page": {
													"type": "integer"
												},
												"limit": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/plans/": {
			"get": {
				"summary": "List plans available to your partner organization",
				"tags": [
					"Partner"
				],
				"description": "Retrieve the subscription plans your partner organization is allowed to offer end-customers. The catalog is curated by your partner_config.allowedPlans — if it is empty (not yet configured), no plans are returned.",
				"responses": {
					"200": {
						"description": "Allowed plans retrieved successfully.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Allowed plans retrieved successfully.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Stripe product ID of the plan.",
														"example": "prod_ABC123"
													},
													"name": {
														"type": "string",
														"example": "Pro"
													},
													"prices": {
														"type": "array",
														"items": {
															"type": "object",
															"properties": {
																"id": {
																	"type": "string",
																	"example": "price_ABC123"
																},
																"currency": {
																	"type": "string",
																	"example": "ron"
																},
																"interval": {
																	"type": "string",
																	"nullable": true,
																	"example": "month"
																}
															}
														}
													}
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/series/": {
			"get": {
				"summary": "Get series configuration",
				"tags": [
					"Series"
				],
				"description": "Retrieve the invoice series configuration for the organization",
				"responses": {
					"200": {
						"description": "Series configuration retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Series configuration retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"_id": {
														"type": "string",
														"description": "Unique series identifier",
														"example": "507f1f77bcf86cd799439011"
													},
													"prefix": {
														"type": "string",
														"description": "Serie prefix (e.g., 'INV', 'FACT')",
														"example": "FACT"
													},
													"suffix": {
														"type": "string",
														"description": "Serie suffix (optional)",
														"example": ""
													},
													"currentNumber": {
														"type": "number",
														"minimum": 1,
														"description": "Current number in sequence",
														"example": 125
													},
													"year": {
														"type": "number",
														"minimum": 2020,
														"maximum": 2099,
														"description": "Year for the series",
														"example": 2024
													},
													"type": {
														"type": "string",
														"enum": [
															"invoice",
															"receipt",
															"proforma"
														],
														"description": "Type of document series",
														"example": "invoice"
													}
												},
												"required": [
													"_id",
													"prefix",
													"currentNumber",
													"year",
													"type"
												]
											},
											"example": [
												{
													"_id": "507f1f77bcf86cd799439011",
													"prefix": "FACT",
													"suffix": "",
													"currentNumber": 125,
													"year": 2024,
													"type": "invoice"
												},
												{
													"_id": "507f1f77bcf86cd799439012",
													"prefix": "CHIT",
													"suffix": "",
													"currentNumber": 45,
													"year": 2024,
													"type": "receipt"
												}
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"post": {
				"summary": "Create new series",
				"tags": [
					"Series"
				],
				"description": "Create a new invoice/receipt series configuration",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"prefix": {
										"type": "string",
										"minLength": 1,
										"maxLength": 20,
										"description": "Series prefix (e.g., 'FACT', 'INV')",
										"example": "FACT"
									},
									"suffix": {
										"type": "string",
										"maxLength": 20,
										"description": "Optional series suffix",
										"example": ""
									},
									"year": {
										"type": "number",
										"minimum": 2020,
										"maximum": 2099,
										"description": "Year for the series",
										"example": 2025
									},
									"type": {
										"type": "string",
										"enum": [
											"invoice",
											"receipt",
											"proforma"
										],
										"description": "Type of document series",
										"example": "invoice"
									},
									"startNumber": {
										"type": "number",
										"minimum": 0,
										"description": "Starting number for the series (default: 0)",
										"example": 0
									}
								},
								"required": [
									"prefix",
									"year",
									"type"
								],
								"additionalProperties": false
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Series created successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Series created successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"_id": {
													"type": "string",
													"description": "Unique series identifier",
													"example": "507f1f77bcf86cd799439011"
												},
												"prefix": {
													"type": "string",
													"description": "Serie prefix (e.g., 'INV', 'FACT')",
													"example": "FACT"
												},
												"suffix": {
													"type": "string",
													"description": "Serie suffix (optional)",
													"example": ""
												},
												"currentNumber": {
													"type": "number",
													"minimum": 1,
													"description": "Current number in sequence",
													"example": 125
												},
												"year": {
													"type": "number",
													"minimum": 2020,
													"maximum": 2099,
													"description": "Year for the series",
													"example": 2024
												},
												"type": {
													"type": "string",
													"enum": [
														"invoice",
														"receipt",
														"proforma"
													],
													"description": "Type of document series",
													"example": "invoice"
												}
											},
											"required": [
												"_id",
												"prefix",
												"currentNumber",
												"year",
												"type"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/series/{id}": {
			"get": {
				"summary": "Get series by ID",
				"tags": [
					"Series"
				],
				"description": "Retrieve a specific invoice series configuration by its ID",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"example": "507f1f77bcf86cd799439011"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Series ID to retrieve"
					}
				],
				"responses": {
					"200": {
						"description": "Series configuration retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Series configuration retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"_id": {
													"type": "string",
													"description": "Unique series identifier",
													"example": "507f1f77bcf86cd799439011"
												},
												"prefix": {
													"type": "string",
													"description": "Serie prefix (e.g., 'INV', 'FACT')",
													"example": "FACT"
												},
												"suffix": {
													"type": "string",
													"description": "Serie suffix (optional)",
													"example": ""
												},
												"currentNumber": {
													"type": "number",
													"minimum": 1,
													"description": "Current number in sequence",
													"example": 125
												},
												"year": {
													"type": "number",
													"minimum": 2020,
													"maximum": 2099,
													"description": "Year for the series",
													"example": 2024
												},
												"type": {
													"type": "string",
													"enum": [
														"invoice",
														"receipt",
														"proforma"
													],
													"description": "Type of document series",
													"example": "invoice"
												}
											},
											"required": [
												"_id",
												"prefix",
												"currentNumber",
												"year",
												"type"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"delete": {
				"summary": "Delete series",
				"tags": [
					"Series"
				],
				"description": "Delete an invoice/receipt series. Series can only be deleted if no invoices are using it.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"example": "507f1f77bcf86cd799439011"
						},
						"in": "path",
						"name": "id",
						"required": true,
						"description": "Series ID to delete"
					}
				],
				"responses": {
					"200": {
						"description": "Series deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Series deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"example": true
										},
										"data": {
											"type": "object",
											"properties": {
												"message": {
													"type": "string",
													"example": "Series successfully deleted"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/deliveries": {
			"get": {
				"summary": "List all webhook deliveries",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve a paginated list of all webhook deliveries across all endpoints for your organization.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 10,
							"example": 25
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Maximum number of items to return (1-100)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "starting_after",
						"required": false,
						"description": "Resource ID to paginate after (returns items created after this ID)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "ending_before",
						"required": false,
						"description": "Resource ID to paginate before (returns items created before this ID)"
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"pending",
								"success",
								"failed"
							]
						},
						"in": "query",
						"name": "status",
						"required": false,
						"description": "Filter deliveries by status"
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"production",
								"sandbox"
							]
						},
						"in": "query",
						"name": "environment",
						"required": false,
						"description": "Filter deliveries by environment"
					}
				],
				"x-internal": true,
				"responses": {
					"200": {
						"description": "Webhook deliveries retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook deliveries retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"data": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "Delivery unique identifier",
																"example": "60f7b1b9c9e7b4a1e8d1c2b4"
															},
															"endpoint_id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "The endpoint this delivery was sent to"
															},
															"event_type": {
																"type": "string",
																"description": "The event type that triggered this delivery",
																"example": "invoice.issued"
															},
															"status": {
																"type": "string",
																"enum": [
																	"pending",
																	"success",
																	"failed"
																],
																"description": "Delivery status",
																"example": "success"
															},
															"status_code": {
																"type": "integer",
																"description": "HTTP response status code from the endpoint",
																"example": 200
															},
															"request_body": {
																"type": "object",
																"description": "The payload that was sent to the endpoint"
															},
															"response_body": {
																"type": "string",
																"description": "The response body from the endpoint (truncated to 1KB)"
															},
															"response_time_ms": {
																"type": "integer",
																"description": "Response time in milliseconds",
																"example": 250
															},
															"attempt_count": {
																"type": "integer",
																"description": "Number of delivery attempts",
																"example": 1
															},
															"next_retry_at": {
																"type": "string",
																"format": "date-time",
																"description": "When the next retry will be attempted (if applicable)"
															},
															"created_at": {
																"type": "string",
																"format": "date-time",
																"description": "Creation timestamp",
																"example": "2026-01-15T10:00:00Z"
															},
															"updated_at": {
																"type": "string",
																"format": "date-time",
																"description": "Last update timestamp",
																"example": "2026-01-15T10:00:00Z"
															}
														}
													}
												},
												"has_more": {
													"type": "boolean",
													"description": "Whether there are more items available after this page",
													"example": true
												},
												"total_count": {
													"type": "integer",
													"description": "Total number of matching resources",
													"example": 42
												}
											},
											"required": [
												"data",
												"has_more",
												"total_count"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/deliveries/{id}/retry": {
			"post": {
				"summary": "Retry webhook delivery",
				"tags": [
					"Webhooks"
				],
				"description": "Retry a failed webhook delivery. The delivery will be re-queued for immediate delivery.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Delivery retry queued successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Delivery retry queued successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "Delivery unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b4"
												},
												"endpoint_id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "The endpoint this delivery was sent to"
												},
												"event_type": {
													"type": "string",
													"description": "The event type that triggered this delivery",
													"example": "invoice.issued"
												},
												"status": {
													"type": "string",
													"enum": [
														"pending",
														"success",
														"failed"
													],
													"description": "Delivery status",
													"example": "success"
												},
												"status_code": {
													"type": "integer",
													"description": "HTTP response status code from the endpoint",
													"example": 200
												},
												"request_body": {
													"type": "object",
													"description": "The payload that was sent to the endpoint"
												},
												"response_body": {
													"type": "string",
													"description": "The response body from the endpoint (truncated to 1KB)"
												},
												"response_time_ms": {
													"type": "integer",
													"description": "Response time in milliseconds",
													"example": 250
												},
												"attempt_count": {
													"type": "integer",
													"description": "Number of delivery attempts",
													"example": 1
												},
												"next_retry_at": {
													"type": "string",
													"format": "date-time",
													"description": "When the next retry will be attempted (if applicable)"
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/endpoints": {
			"post": {
				"summary": "Create a webhook endpoint",
				"tags": [
					"Webhooks"
				],
				"description": "Create a new webhook endpoint to receive event notifications. The signing secret is returned only once on creation — store it securely.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"url": {
										"type": "string",
										"format": "uri",
										"description": "The URL that will receive webhook event POST requests. Must be HTTPS.",
										"example": "https://example.com/webhooks/billyou"
									},
									"description": {
										"type": "string",
										"maxLength": 500,
										"description": "An optional description for the endpoint",
										"example": "Production webhook endpoint"
									},
									"events": {
										"type": "array",
										"items": {
											"type": "string",
											"enum": [
												"invoice.issued",
												"invoice.paid",
												"invoice.canceled",
												"invoice.storno.issued",
												"invoice.efactura_sent",
												"invoice.efactura_accepted",
												"invoice.efactura_rejected",
												"invoice.efactura_received",
												"customer.created",
												"customer.updated",
												"customer.deleted",
												"expense.created_from_efactura",
												"etransport.declaration.processed",
												"etransport.declaration.rejected",
												"account.provisioned",
												"account.activated",
												"account.subscribed"
											]
										},
										"minItems": 1,
										"uniqueItems": true,
										"description": "List of event types this endpoint should subscribe to",
										"example": [
											"invoice.issued",
											"invoice.paid"
										]
									}
								},
								"required": [
									"url",
									"events"
								],
								"additionalProperties": false,
								"example": {
									"url": "https://example.com/webhooks/billyou",
									"description": "Production webhook endpoint",
									"events": [
										"invoice.issued",
										"invoice.paid",
										"customer.created"
									]
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Webhook endpoint created successfully. The secret is only returned once.",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoint created successfully. The secret is only returned once.",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "Webhook endpoint unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"url": {
													"type": "string",
													"format": "uri",
													"description": "The URL that will receive webhook events",
													"example": "https://example.com/webhooks/billyou"
												},
												"description": {
													"type": "string",
													"description": "An optional description for the endpoint",
													"example": "Production webhook endpoint"
												},
												"events": {
													"type": "array",
													"items": {
														"type": "string",
														"enum": [
															"invoice.issued",
															"invoice.paid",
															"invoice.canceled",
															"invoice.storno.issued",
															"invoice.efactura_sent",
															"invoice.efactura_accepted",
															"invoice.efactura_rejected",
															"invoice.efactura_received",
															"customer.created",
															"customer.updated",
															"customer.deleted",
															"expense.created_from_efactura",
															"etransport.declaration.processed",
															"etransport.declaration.rejected",
															"account.provisioned",
															"account.activated",
															"account.subscribed"
														]
													},
													"description": "List of event types this endpoint subscribes to",
													"example": [
														"invoice.issued",
														"invoice.paid"
													]
												},
												"is_active": {
													"type": "boolean",
													"description": "Whether the endpoint is active and will receive events",
													"example": true
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"secret": {
													"type": "string",
													"description": "The HMAC signing secret for verifying webhook payloads. Only returned on creation.",
													"example": "whsec_a1b2c3d4e5f6..."
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"403": {
						"description": "Forbidden",
						"content": {
							"application/json": {
								"schema": {
									"description": "Forbidden",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "FORBIDDEN",
										"message": "You do not have permission to access this resource"
									}
								}
							}
						}
					},
					"429": {
						"description": "Rate Limit Exceeded",
						"content": {
							"application/json": {
								"schema": {
									"description": "Rate Limit Exceeded",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "RATE_LIMIT_EXCEEDED",
										"message": "You have exceeded the allowed request limit"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"summary": "List webhook endpoints",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve a paginated list of webhook endpoints for your organization.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 10,
							"example": 25
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Maximum number of items to return (1-100)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "starting_after",
						"required": false,
						"description": "Resource ID to paginate after (returns items created after this ID)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "ending_before",
						"required": false,
						"description": "Resource ID to paginate before (returns items created before this ID)"
					},
					{
						"schema": {
							"type": "boolean"
						},
						"in": "query",
						"name": "is_active",
						"required": false,
						"description": "Filter by active/inactive status"
					}
				],
				"responses": {
					"200": {
						"description": "Webhook endpoints retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoints retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"data": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "Webhook endpoint unique identifier",
																"example": "60f7b1b9c9e7b4a1e8d1c2b3"
															},
															"url": {
																"type": "string",
																"format": "uri",
																"description": "The URL that will receive webhook events",
																"example": "https://example.com/webhooks/billyou"
															},
															"description": {
																"type": "string",
																"description": "An optional description for the endpoint",
																"example": "Production webhook endpoint"
															},
															"events": {
																"type": "array",
																"items": {
																	"type": "string",
																	"enum": [
																		"invoice.issued",
																		"invoice.paid",
																		"invoice.canceled",
																		"invoice.storno.issued",
																		"invoice.efactura_sent",
																		"invoice.efactura_accepted",
																		"invoice.efactura_rejected",
																		"invoice.efactura_received",
																		"customer.created",
																		"customer.updated",
																		"customer.deleted",
																		"expense.created_from_efactura",
																		"etransport.declaration.processed",
																		"etransport.declaration.rejected",
																		"account.provisioned",
																		"account.activated",
																		"account.subscribed"
																	]
																},
																"description": "List of event types this endpoint subscribes to",
																"example": [
																	"invoice.issued",
																	"invoice.paid"
																]
															},
															"is_active": {
																"type": "boolean",
																"description": "Whether the endpoint is active and will receive events",
																"example": true
															},
															"created_at": {
																"type": "string",
																"format": "date-time",
																"description": "Creation timestamp",
																"example": "2026-01-15T10:00:00Z"
															},
															"updated_at": {
																"type": "string",
																"format": "date-time",
																"description": "Last update timestamp",
																"example": "2026-01-15T10:00:00Z"
															}
														}
													}
												},
												"has_more": {
													"type": "boolean",
													"description": "Whether there are more items available after this page",
													"example": true
												},
												"total_count": {
													"type": "integer",
													"description": "Total number of matching resources",
													"example": 42
												}
											},
											"required": [
												"data",
												"has_more",
												"total_count"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/endpoints/{id}": {
			"get": {
				"summary": "Get webhook endpoint",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve a single webhook endpoint by its ID.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Webhook endpoint retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoint retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "Webhook endpoint unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"url": {
													"type": "string",
													"format": "uri",
													"description": "The URL that will receive webhook events",
													"example": "https://example.com/webhooks/billyou"
												},
												"description": {
													"type": "string",
													"description": "An optional description for the endpoint",
													"example": "Production webhook endpoint"
												},
												"events": {
													"type": "array",
													"items": {
														"type": "string",
														"enum": [
															"invoice.issued",
															"invoice.paid",
															"invoice.canceled",
															"invoice.storno.issued",
															"invoice.efactura_sent",
															"invoice.efactura_accepted",
															"invoice.efactura_rejected",
															"invoice.efactura_received",
															"customer.created",
															"customer.updated",
															"customer.deleted",
															"expense.created_from_efactura",
															"etransport.declaration.processed",
															"etransport.declaration.rejected",
															"account.provisioned",
															"account.activated",
															"account.subscribed"
														]
													},
													"description": "List of event types this endpoint subscribes to",
													"example": [
														"invoice.issued",
														"invoice.paid"
													]
												},
												"is_active": {
													"type": "boolean",
													"description": "Whether the endpoint is active and will receive events",
													"example": true
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"put": {
				"summary": "Update webhook endpoint",
				"tags": [
					"Webhooks"
				],
				"description": "Update an existing webhook endpoint. All fields are optional — only provided fields will be updated.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"url": {
										"type": "string",
										"format": "uri",
										"description": "The URL that will receive webhook event POST requests",
										"example": "https://example.com/webhooks/billyou"
									},
									"description": {
										"type": "string",
										"maxLength": 500,
										"description": "An optional description for the endpoint",
										"example": "Updated production webhook endpoint"
									},
									"events": {
										"type": "array",
										"items": {
											"type": "string",
											"enum": [
												"invoice.issued",
												"invoice.paid",
												"invoice.canceled",
												"invoice.storno.issued",
												"invoice.efactura_sent",
												"invoice.efactura_accepted",
												"invoice.efactura_rejected",
												"invoice.efactura_received",
												"customer.created",
												"customer.updated",
												"customer.deleted",
												"expense.created_from_efactura",
												"etransport.declaration.processed",
												"etransport.declaration.rejected",
												"account.provisioned",
												"account.activated",
												"account.subscribed"
											]
										},
										"minItems": 1,
										"uniqueItems": true,
										"description": "List of event types this endpoint should subscribe to",
										"example": [
											"invoice.issued",
											"invoice.paid"
										]
									},
									"is_active": {
										"type": "boolean",
										"description": "Whether the endpoint is active and will receive events",
										"example": true
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Webhook endpoint updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoint updated successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "Webhook endpoint unique identifier",
													"example": "60f7b1b9c9e7b4a1e8d1c2b3"
												},
												"url": {
													"type": "string",
													"format": "uri",
													"description": "The URL that will receive webhook events",
													"example": "https://example.com/webhooks/billyou"
												},
												"description": {
													"type": "string",
													"description": "An optional description for the endpoint",
													"example": "Production webhook endpoint"
												},
												"events": {
													"type": "array",
													"items": {
														"type": "string",
														"enum": [
															"invoice.issued",
															"invoice.paid",
															"invoice.canceled",
															"invoice.storno.issued",
															"invoice.efactura_sent",
															"invoice.efactura_accepted",
															"invoice.efactura_rejected",
															"invoice.efactura_received",
															"customer.created",
															"customer.updated",
															"customer.deleted",
															"expense.created_from_efactura",
															"etransport.declaration.processed",
															"etransport.declaration.rejected",
															"account.provisioned",
															"account.activated",
															"account.subscribed"
														]
													},
													"description": "List of event types this endpoint subscribes to",
													"example": [
														"invoice.issued",
														"invoice.paid"
													]
												},
												"is_active": {
													"type": "boolean",
													"description": "Whether the endpoint is active and will receive events",
													"example": true
												},
												"created_at": {
													"type": "string",
													"format": "date-time",
													"description": "Creation timestamp",
													"example": "2026-01-15T10:00:00Z"
												},
												"updated_at": {
													"type": "string",
													"format": "date-time",
													"description": "Last update timestamp",
													"example": "2026-01-15T10:00:00Z"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request",
						"content": {
							"application/json": {
								"schema": {
									"description": "Bad Request",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "VALIDATION_ERROR",
										"message": "The provided data is invalid"
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			},
			"delete": {
				"summary": "Delete webhook endpoint",
				"tags": [
					"Webhooks"
				],
				"description": "Delete a webhook endpoint. This will stop all event deliveries to this endpoint.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Webhook endpoint deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoint deleted successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string",
													"pattern": "^[0-9a-fA-F]{24}$",
													"description": "The deleted endpoint ID"
												},
												"deleted": {
													"type": "boolean",
													"enum": [
														true
													]
												}
											},
											"required": [
												"id",
												"deleted"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/endpoints/{id}/deliveries": {
			"get": {
				"summary": "List webhook deliveries",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve a paginated list of webhook deliveries for a specific endpoint.",
				"parameters": [
					{
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 10,
							"example": 25
						},
						"in": "query",
						"name": "limit",
						"required": false,
						"description": "Maximum number of items to return (1-100)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "starting_after",
						"required": false,
						"description": "Resource ID to paginate after (returns items created after this ID)"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$",
							"example": "60f7b1b9c9e7b4a1e8d1c2b3"
						},
						"in": "query",
						"name": "ending_before",
						"required": false,
						"description": "Resource ID to paginate before (returns items created before this ID)"
					},
					{
						"schema": {
							"type": "string",
							"enum": [
								"pending",
								"success",
								"failed"
							]
						},
						"in": "query",
						"name": "status",
						"required": false,
						"description": "Filter deliveries by status"
					},
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Webhook deliveries retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook deliveries retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"data": {
													"type": "array",
													"items": {
														"type": "object",
														"properties": {
															"id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "Delivery unique identifier",
																"example": "60f7b1b9c9e7b4a1e8d1c2b4"
															},
															"endpoint_id": {
																"type": "string",
																"pattern": "^[0-9a-fA-F]{24}$",
																"description": "The endpoint this delivery was sent to"
															},
															"event_type": {
																"type": "string",
																"description": "The event type that triggered this delivery",
																"example": "invoice.issued"
															},
															"status": {
																"type": "string",
																"enum": [
																	"pending",
																	"success",
																	"failed"
																],
																"description": "Delivery status",
																"example": "success"
															},
															"status_code": {
																"type": "integer",
																"description": "HTTP response status code from the endpoint",
																"example": 200
															},
															"request_body": {
																"type": "object",
																"description": "The payload that was sent to the endpoint"
															},
															"response_body": {
																"type": "string",
																"description": "The response body from the endpoint (truncated to 1KB)"
															},
															"response_time_ms": {
																"type": "integer",
																"description": "Response time in milliseconds",
																"example": 250
															},
															"attempt_count": {
																"type": "integer",
																"description": "Number of delivery attempts",
																"example": 1
															},
															"next_retry_at": {
																"type": "string",
																"format": "date-time",
																"description": "When the next retry will be attempted (if applicable)"
															},
															"created_at": {
																"type": "string",
																"format": "date-time",
																"description": "Creation timestamp",
																"example": "2026-01-15T10:00:00Z"
															},
															"updated_at": {
																"type": "string",
																"format": "date-time",
																"description": "Last update timestamp",
																"example": "2026-01-15T10:00:00Z"
															}
														}
													}
												},
												"has_more": {
													"type": "boolean",
													"description": "Whether there are more items available after this page",
													"example": true
												},
												"total_count": {
													"type": "integer",
													"description": "Total number of matching resources",
													"example": 42
												}
											},
											"required": [
												"data",
												"has_more",
												"total_count"
											]
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/endpoints/{id}/secret": {
			"get": {
				"summary": "Reveal webhook endpoint signing secret",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve the signing secret for a webhook endpoint. Use this to verify webhook signatures.",
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Webhook endpoint signing secret",
						"content": {
							"application/json": {
								"schema": {
									"description": "Webhook endpoint signing secret",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"secret": {
													"type": "string"
												},
												"created_at": {
													"type": "string"
												}
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/endpoints/{id}/test": {
			"post": {
				"summary": "Test webhook endpoint",
				"tags": [
					"Webhooks"
				],
				"description": "Send a test event to a webhook endpoint to verify connectivity. The test delivery is recorded in the delivery log.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"event_type": {
										"type": "string",
										"enum": [
											"invoice.issued",
											"invoice.paid",
											"invoice.canceled",
											"invoice.storno.issued",
											"invoice.efactura_sent",
											"invoice.efactura_accepted",
											"invoice.efactura_rejected",
											"invoice.efactura_received",
											"customer.created",
											"customer.updated",
											"customer.deleted",
											"expense.created_from_efactura",
											"etransport.declaration.processed",
											"etransport.declaration.rejected",
											"account.provisioned",
											"account.activated",
											"account.subscribed"
										],
										"default": "invoice.issued",
										"description": "The event type to simulate for the test delivery",
										"example": "invoice.issued"
									}
								},
								"additionalProperties": false
							}
						}
					}
				},
				"parameters": [
					{
						"schema": {
							"type": "string",
							"pattern": "^[0-9a-fA-F]{24}$"
						},
						"in": "path",
						"name": "id",
						"required": true
					}
				],
				"responses": {
					"200": {
						"description": "Test delivery result",
						"content": {
							"application/json": {
								"schema": {
									"description": "Test delivery result",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "object",
											"properties": {
												"success": {
													"type": "boolean",
													"description": "Whether the test delivery was successful (2xx response)"
												},
												"status_code": {
													"type": "integer",
													"description": "HTTP response status code from the endpoint",
													"example": 200
												},
												"response_time_ms": {
													"type": "integer",
													"description": "Response time in milliseconds",
													"example": 250
												},
												"response_body": {
													"type": "string",
													"description": "The response body from the endpoint (truncated to 1KB)"
												}
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"404": {
						"description": "Not Found",
						"content": {
							"application/json": {
								"schema": {
									"description": "Not Found",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "NOT_FOUND",
										"message": "The requested resource was not found"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		},
		"/webhooks/event-types": {
			"get": {
				"summary": "List available event types",
				"tags": [
					"Webhooks"
				],
				"description": "Retrieve a list of all available webhook event types with descriptions and categories.",
				"responses": {
					"200": {
						"description": "Event types retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"description": "Event types retrieved successfully",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												true
											]
										},
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Event type identifier",
														"example": "invoice.issued"
													},
													"description": {
														"type": "string",
														"description": "Human-readable description of the event"
													},
													"category": {
														"type": "string",
														"description": "Category grouping for the event type",
														"example": "Invoices"
													}
												},
												"required": [
													"type",
													"description",
													"category"
												]
											}
										}
									},
									"required": [
										"success",
										"data"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized",
						"content": {
							"application/json": {
								"schema": {
									"description": "Unauthorized",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "UNAUTHORIZED",
										"message": "API key is invalid or missing"
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error",
						"content": {
							"application/json": {
								"schema": {
									"description": "Internal Server Error",
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"enum": [
												false
											]
										},
										"errorCode": {
											"type": "string"
										},
										"message": {
											"type": "string"
										},
										"details": {
											"anyOf": [
												{
													"type": "array",
													"items": {
														"type": "object",
														"additionalProperties": true
													}
												},
												{
													"type": "object",
													"additionalProperties": true
												}
											]
										}
									},
									"required": [
										"success",
										"errorCode",
										"message"
									],
									"example": {
										"success": false,
										"errorCode": "INTERNAL_ERROR",
										"message": "An internal error occurred"
									}
								}
							}
						}
					}
				}
			}
		}
	},
	"servers": [
		{
			"url": "https://app.billyou.ro/api",
			"description": "Production Server"
		}
	],
	"security": [
		{
			"ApiKeyAuth": []
		}
	],
	"tags": [
		{
			"name": "Invoices",
			"description": "Invoice management operations including creation, updates, cancellation, and PDF generation. Supports Romanian business rules and VAT compliance."
		},
		{
			"name": "Clients",
			"description": "Client and customer management with Romanian business validation including CUI/CNP verification and address management."
		},
		{
			"name": "Payments",
			"description": "Payment tracking and management including partial payments, payment history, and status monitoring."
		},
		{
			"name": "Series",
			"description": "Invoice series configuration and numbering management for Romanian invoice requirements."
		},
		{
			"name": "Webhooks",
			"description": "Webhook endpoint management and delivery tracking."
		},
		{
			"name": "E-Factura",
			"description": "Romanian government e-Factura integration."
		},
		{
			"name": "E-Transport",
			"description": "E-Transport declaration management. Submit transport declarations to ANAF, track their status, and receive webhook notifications when ANAF assigns a UIT code."
		}
	]
}
