{ "schemes": ["https"], "swagger": "2.0", "info": { "description": "Reconcio API - API for reconciliation automatization", "title": "Reconcio API", "contact": { "name": "Support", "email": "support@reconcio.pro" }, "version": "1.0" }, "host": "api.reconcio.pro", "basePath": "/api/v1", "paths": { "/reconciliations/prepare": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Uploads two datasets, validates them, stores source files and creates a reconciliation draft. Returns suggested column mappings and basic reconciliation metadata", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "Reconciliation" ], "summary": "Prepare reconciliation", "operationId": "reconciliation-prepare", "parameters": [ { "type": "file", "description": "Dataset A (CSV or XLSX)", "name": "file_a", "in": "formData", "required": true }, { "type": "file", "description": "Dataset B (CSV or XLSX)", "name": "file_b", "in": "formData", "required": true } ], "responses": { "200": { "description": "Reconciliation draft created successfully", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Unauthorized" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Forbidden" } }, "422": { "description": "Invalid file type, file size limit exceeded or validation error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.UnprocessableEntity" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.InternalServerError" } } } } }, "/reconciliations/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns reconciliation details, current status, selected columns and calculated results if processing has completed", "produces": [ "application/json" ], "tags": [ "Reconciliation" ], "summary": "Get reconciliation", "operationId": "reconciliation-get-by-id", "parameters": [ { "type": "string", "format": "uuid", "description": "Reconciliation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Reconciliation details", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Unauthorized" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Forbidden" } }, "422": { "description": "Reconciliation not found", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.NotFound" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.InternalServerError" } } } } }, "/reconciliations/{id}/diff": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns a CSV file containing detailed reconciliation differences between the uploaded datasets", "produces": [ "text/csv" ], "tags": [ "Reconciliation" ], "summary": "Download reconciliation diff", "operationId": "reconciliation-diff", "parameters": [ { "type": "string", "format": "uuid", "description": "Reconciliation ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "CSV diff file", "schema": { "type": "file" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Unauthorized" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Forbidden" } }, "404": { "description": "Reconciliation not found", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.NotFound" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.InternalServerError" } } } } }, "/reconciliations/{id}/run": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Starts reconciliation processing using the selected column mappings and returns updated reconciliation information", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Reconciliation" ], "summary": "Run reconciliation", "operationId": "reconciliation-run", "parameters": [ { "type": "string", "format": "uuid", "description": "Reconciliation ID", "name": "id", "in": "path", "required": true }, { "description": "Reconciliation configuration", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.RunReconciliationRequest" } } ], "responses": { "200": { "description": "Reconciliation started successfully", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.BadRequest" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Unauthorized" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.Forbidden" } }, "404": { "description": "Reconciliation not found", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.NotFound" } }, "422": { "description": "Validation error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.UnprocessableEntity" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.InternalServerError" } } } } } }, "definitions": { "gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnDetailedStats": { "description": "Detailed quality metrics including mismatch counts and issue detection", "type": "object", "properties": { "both_null": { "description": "Number of rows where both values are NULL", "type": "integer", "example": 0 }, "column_name": { "description": "Column name", "type": "string", "example": "Currency" }, "has_issues": { "description": "Whether column has data quality issues", "type": "boolean", "example": false }, "has_nulls": { "description": "Whether column contains NULL values", "type": "boolean", "example": true }, "matching_rate": { "description": "Ratio of matching values (0-1)", "type": "number", "example": 0.9709 }, "mismatch_count": { "description": "Number of mismatched values", "type": "integer", "example": 0 }, "nulls_in_a": { "description": "Number of NULL values in file A", "type": "integer", "example": 0 }, "nulls_in_b": { "description": "Number of NULL values in file B", "type": "integer", "example": 3 } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnQuality": { "description": "Map of column names to their quality metrics", "type": "object", "additionalProperties": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnStats" } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnStats": { "description": "Simplified quality metrics for a single column", "type": "object", "properties": { "matching_rate": { "description": "Ratio of matching values (0-1)", "type": "number", "example": 0.9709 }, "nulls_in_a": { "description": "Number of NULL values in file A", "type": "integer", "example": 0 }, "nulls_in_b": { "description": "Number of NULL values in file B", "type": "integer", "example": 3 } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.JoinColumnStat": { "description": "Quality analysis of columns used as join keys", "type": "object", "properties": { "column_name": { "description": "Column name", "type": "string", "example": "OrderID" }, "duplicates_in_a": { "description": "Number of duplicate values in file A", "type": "integer", "example": 0 }, "duplicates_in_b": { "description": "Number of duplicate values in file B", "type": "integer", "example": 0 }, "effectiveness": { "description": "Key effectiveness as identifier (0-1)", "type": "number", "example": 1 }, "matching_rate": { "description": "Ratio of matching key values (0-1)", "type": "number", "example": 0.9709 }, "nulls_in_a": { "description": "Number of NULL values in file A", "type": "integer", "example": 0 }, "nulls_in_b": { "description": "Number of NULL values in file B", "type": "integer", "example": 3 } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.NumericColumnStat": { "description": "Statistical analysis of numeric field discrepancies", "type": "object", "properties": { "column_name": { "description": "Column name", "type": "string", "example": "TotalAmount" }, "difference": { "description": "Difference between sums (A - B)", "type": "number", "example": 0 }, "difference_percent": { "description": "Percentage difference relative to file A", "type": "number", "example": 0 }, "matching_rate": { "description": "Ratio of matching values (0-1)", "type": "number", "example": 1 }, "total_a": { "description": "Sum of values in file A", "type": "number", "example": 5343.99 }, "total_b": { "description": "Sum of values in file B", "type": "number", "example": 5343.99 } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.Recommendation": { "description": "Improvement suggestions based on reconciliation analysis", "type": "object", "properties": { "details": { "description": "Detailed recommendation data (structure depends on type)", "type": "object", "additionalProperties": {} }, "type": { "description": "Type of recommendation\n@enum low_convergence,missing_rows,duplicates_in_column,numeric_column_difference", "type": "string", "example": "missing_rows" } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationColumn": { "description": "Defines how columns from file A and file B should be compared", "type": "object", "required": [ "file_a_column", "file_b_column" ], "properties": { "condition": { "description": "Comparison condition\n@enum EQ,GT,GTE,LT,LTE,IGNORE", "type": "string", "enum": [ "EQ", "GT", "GTE", "LT", "LTE", "IGNORE" ], "example": "EQ" }, "file_a_column": { "description": "Column name from first file (Dataset A)\n@required", "type": "string", "maxLength": 255, "example": "transaction_id" }, "file_b_column": { "description": "Column name from second file (Dataset B)\n@required", "type": "string", "maxLength": 255, "example": "payment_id" }, "is_join_key": { "description": "Whether this column is used as join key", "type": "boolean", "example": true } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResponse": { "description": "Complete reconciliation information including status, results, and metadata", "type": "object", "properties": { "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time", "example": "2025-06-05T10:00:00Z" }, "diff_file_expired_at": { "description": "Expiration timestamp for diff file", "type": "string", "format": "date-time", "example": "2025-06-06T15:04:05Z" }, "diff_file_name": { "description": "Name of generated diff file (if available)", "type": "string", "example": "reconciliation_diff.csv" }, "duration": { "description": "Total processing duration", "type": "string", "example": "2m14s" }, "error": { "description": "Error message if reconciliation failed", "type": "string", "example": "failed to parse CSV" }, "expired_at": { "description": "Expiration timestamp for reconciliation data", "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z" }, "file_a_name": { "description": "Original name of first file", "type": "string", "example": "bank_statement_2024.csv" }, "file_a_rows_count": { "description": "Number of rows in first file (Dataset A)", "type": "integer", "example": 10542 }, "file_b_name": { "description": "Original name of second file", "type": "string", "example": "erp_export_2024.csv" }, "file_b_rows_count": { "description": "Number of rows in second file (Dataset B)", "type": "integer", "example": 10531 }, "id": { "description": "Reconciliation unique identifier\n@required", "type": "string", "format": "uuid", "example": "8f2b9d51-f5a8-4b64-8a0d-4c8db2dc6e4f" }, "results": { "description": "Reconciliation results statistics", "allOf": [ { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResults" } ] }, "status": { "description": "Current reconciliation status\n@enum uploaded,converting,analyzing,awaiting_user_config,reconciling,completed,failed", "type": "string", "enum": [ "uploaded", "converting", "analyzing", "awaiting_user_config", "reconciling", "completed", "failed" ], "example": "completed" }, "suggested_columns": { "description": "Suggested column mappings for reconciliation", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationColumn" } }, "template_name": { "description": "Template name used for reconciliation", "type": "string", "example": "Bank vs ERP Standard" }, "updated_at": { "description": "Last update timestamp", "type": "string", "format": "date-time", "example": "2025-06-05T10:05:30Z" } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationResults": { "description": "Detailed statistics about data matching, discrepancies, and data quality", "type": "object", "properties": { "column_detailed_stats": { "description": "Detailed statistics per column", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnDetailedStats" } }, "columns_quality": { "description": "Simplified column quality metrics", "allOf": [ { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ColumnQuality" } ] }, "convergence": { "description": "Percentage of matching rows (0-100)", "type": "number", "example": 99.62 }, "float_avg_discrepancy": { "description": "Average discrepancy for float columns", "type": "number", "example": 0.001 }, "float_column_stat": { "description": "Statistics for float columns", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.NumericColumnStat" } }, "float_discrepancy_columns": { "description": "Columns with float discrepancies", "type": "array", "items": { "type": "string" } }, "float_max_discrepancy": { "description": "Maximum discrepancy for float columns", "type": "number", "example": 0.01 }, "float_total_discrepancy_abs": { "description": "Total absolute discrepancy for float columns", "type": "number", "example": 0.05 }, "int_avg_discrepancy": { "description": "Average discrepancy for integer columns", "type": "number", "example": 12.4 }, "int_column_stat": { "description": "Statistics for integer columns", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.NumericColumnStat" } }, "int_discrepancy_columns": { "description": "Columns with integer discrepancies", "type": "array", "items": { "type": "string" } }, "int_max_discrepancy": { "description": "Maximum discrepancy for integer columns", "type": "number", "example": 100 }, "int_total_discrepancy_abs": { "description": "Total absolute discrepancy for integer columns", "type": "number", "example": 1520 }, "join_column_stat": { "description": "Statistics for join key columns", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.JoinColumnStat" } }, "matched_rows_count": { "description": "Number of rows with all fields matching", "type": "integer", "example": 10487 }, "mismatched_rows_count": { "description": "Number of rows with mismatched values", "type": "integer", "example": 29 }, "missed_rows_count_in_file_a": { "description": "Number of rows present only in file A", "type": "integer", "example": 15 }, "missed_rows_count_in_file_b": { "description": "Number of rows present only in file B", "type": "integer", "example": 11 }, "recommendations": { "description": "Improvement recommendations", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.Recommendation" } } } }, "gitlab_com_reconcio_reconcio_internal_openapi_model.RunReconciliationRequest": { "description": "Request body for running reconciliation with selected column mappings", "type": "object", "required": [ "final_columns", "id" ], "properties": { "final_columns": { "description": "List of column mappings for reconciliation\n@required", "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_internal_openapi_model.ReconciliationColumn" } }, "id": { "description": "Reconciliation unique identifier (UUID format)\n@required", "type": "string", "example": "8f2b9d51-f5a8-4b64-8a0d-4c8db2dc6e4f" } } }, "gitlab_com_reconcio_reconcio_pkg_http_problems.BadRequest": { "type": "object", "properties": { "invalidParams": { "type": "array", "items": { "$ref": "#/definitions/gitlab_com_reconcio_reconcio_pkg_http_problems.InvalidParam" } } } }, "gitlab_com_reconcio_reconcio_pkg_http_problems.Forbidden": { "type": "object", "properties": { "detail": { "type": "string" }, "instance": { "type": "string" } } }, "gitlab_com_reconcio_reconcio_pkg_http_problems.InternalServerError": { "type": "object" }, "gitlab_com_reconcio_reconcio_pkg_http_problems.InvalidParam": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" }, "value": {} } }, "gitlab_com_reconcio_reconcio_pkg_http_problems.NotFound": { "type": "object" }, "gitlab_com_reconcio_reconcio_pkg_http_problems.Unauthorized": { "type": "object", "properties": { "detail": { "type": "string" } } }, "gitlab_com_reconcio_reconcio_pkg_http_problems.UnprocessableEntity": { "type": "object", "properties": { "details": {}, "type": { "type": "string" } } } }, "securityDefinitions": { "BearerAuth": { "description": "Your API token", "type": "apiKey", "name": "Authorization", "in": "header" } } }