From b1c638995af820f06d88753b0de65359e7940968 Mon Sep 17 00:00:00 2001 From: Ezequiel Rozen Date: Wed, 19 Aug 2026 14:34:05 -0400 Subject: [PATCH 1/3] feat: document chargeback file and evidence-type endpoints Adds GET /files, GET /files/{file_id}, POST /files/batch, and GET /evidence-types under /charges/{charge_id}/chargebacks/{chargeback_id}, matching bo-chargeback's gateway routes, which were previously undocumented. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_012862o2cEy3JbDvcNcG2sYb --- _build/api.yaml | 785 ++++++++++++++++++ api.yaml | 10 + parameters/commons/path_param/charge_id.yml | 7 + .../commons/path_param/chargeback_id.yml | 7 + parameters/commons/path_param/file_id.yml | 7 + .../chargebacks/chargeback_evidence_types.yml | 50 ++ resources/chargebacks/chargeback_file.yml | 49 ++ resources/chargebacks/chargeback_files.yml | 50 ++ .../chargebacks/chargeback_files_batch.yml | 117 +++ resources/errors/400.yml | 17 + .../chargeback_evidence_file_response.yml | 38 + .../chargeback_evidence_type_response.yml | 32 + .../chargeback_files_batch_response.yml | 8 + 13 files changed, 1177 insertions(+) create mode 100644 parameters/commons/path_param/charge_id.yml create mode 100644 parameters/commons/path_param/chargeback_id.yml create mode 100644 parameters/commons/path_param/file_id.yml create mode 100644 resources/chargebacks/chargeback_evidence_types.yml create mode 100644 resources/chargebacks/chargeback_file.yml create mode 100644 resources/chargebacks/chargeback_files.yml create mode 100644 resources/chargebacks/chargeback_files_batch.yml create mode 100644 resources/errors/400.yml create mode 100644 schemas/chargebacks/chargeback_evidence_file_response.yml create mode 100644 schemas/chargebacks/chargeback_evidence_type_response.yml create mode 100644 schemas/chargebacks/chargeback_files_batch_response.yml diff --git a/_build/api.yaml b/_build/api.yaml index 8bfe3f8..bb9cbcd 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -16,6 +16,8 @@ servers: security: - bearerAuth: [] tags: +- description: Chargeback evidence file and evidence-type endpoints + name: Chargebacks - description: "All subscription-related endpoints including creation, management,\ \ and events" name: Subscriptions @@ -1449,6 +1451,654 @@ paths: summary: Update a charge tags: - Charges + /charges/{charge_id}/chargebacks/{chargeback_id}/files: + get: + description: Retrieve the list of evidence files uploaded for a chargeback. + operationId: getChargebackFiles + parameters: + - description: Identifier of the charge resource + explode: false + in: path + name: charge_id + required: true + schema: + example: 6966a06c044243000156c24d + type: string + style: simple + - description: Identifier of the chargeback resource + explode: false + in: path + name: chargeback_id + required: true + schema: + example: chbk_2zPxWFUnGNLySoumn + type: string + style: simple + - description: Use for knowing which language to use + examples: + es: + summary: for spanish request/response + value: es + en: + summary: for english request/response + value: en + explode: false + in: header + name: Accept-Language + required: false + schema: + default: es + enum: + - es + - en + type: string + style: simple + - description: "In the case of a holding company, the company id of the child\ + \ company to which will process the request." + example: 6441b6376b60c3a638da80af + explode: false + in: header + name: X-Child-Company-Id + required: false + schema: + type: string + style: simple + responses: + "200": + content: + application/vnd.conekta-v2.3.0+json: + schema: + items: + $ref: "#/components/schemas/chargeback_evidence_file_response" + nullable: true + type: array + description: A list of evidence files for the chargeback. + headers: + Date: + description: The date and time that the response was sent + explode: false + schema: + type: string + style: simple + Content-Type: + description: The format of the response body + explode: false + schema: + type: string + style: simple + Content-Length: + description: The length of the response body in bytes + explode: false + schema: + type: string + style: simple + Connection: + description: The type of connection used to transfer the response + explode: false + schema: + type: string + style: simple + Conekta-Media-Type: + explode: false + schema: + type: string + style: simple + "400": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The chargeback status does not allow this operation. + code: conekta.errors.business.chargebacks.could_not_be_processed + debug_message: chargeback status is won + log_id: 641b6c253cd9a50001514fae + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: bad request + "401": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: Please include your access key in your request. + code: conekta.errors.authentication.missing_key + log_id: 507f1f77bcf86cd799439011 + object: error + type: authentication_error + schema: + $ref: "#/components/schemas/error" + description: authentication error + "404": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The resource was not found. + code: conekta.errors.resource_not_found.entity + debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could + not be found. + log_id: 641b6c253cd9a50001514fae + object: error + type: resource_not_found_error + schema: + $ref: "#/components/schemas/error" + description: not found entity + "500": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - debug_message: There was a runtime error and Conekta engineers have + been notified. + message: There was a runtime error and Conekta engineers have been + notified. + code: conekta.errors.api.system.general_failure + object: error + type: api_error + log_id: 641b6f2b3cd9a50001515098 + schema: + $ref: "#/components/schemas/error" + description: internal server error + security: + - bearerAuth: [] + summary: Get Chargeback Files + tags: + - Chargebacks + /charges/{charge_id}/chargebacks/{chargeback_id}/files/{file_id}: + get: + description: Retrieve the metadata and a presigned download URL for a single + chargeback evidence file. + operationId: getChargebackFile + parameters: + - description: Identifier of the charge resource + explode: false + in: path + name: charge_id + required: true + schema: + example: 6966a06c044243000156c24d + type: string + style: simple + - description: Identifier of the chargeback resource + explode: false + in: path + name: chargeback_id + required: true + schema: + example: chbk_2zPxWFUnGNLySoumn + type: string + style: simple + - description: Identifier of the chargeback evidence file + explode: false + in: path + name: file_id + required: true + schema: + example: chbkf_2zPxWFUnGNLySoums + type: string + style: simple + - description: Use for knowing which language to use + examples: + es: + summary: for spanish request/response + value: es + en: + summary: for english request/response + value: en + explode: false + in: header + name: Accept-Language + required: false + schema: + default: es + enum: + - es + - en + type: string + style: simple + - description: "In the case of a holding company, the company id of the child\ + \ company to which will process the request." + example: 6441b6376b60c3a638da80af + explode: false + in: header + name: X-Child-Company-Id + required: false + schema: + type: string + style: simple + responses: + "200": + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: "#/components/schemas/chargeback_evidence_file_response" + description: The requested evidence file. + headers: + Date: + description: The date and time that the response was sent + explode: false + schema: + type: string + style: simple + Content-Type: + description: The format of the response body + explode: false + schema: + type: string + style: simple + Content-Length: + description: The length of the response body in bytes + explode: false + schema: + type: string + style: simple + Connection: + description: The type of connection used to transfer the response + explode: false + schema: + type: string + style: simple + Conekta-Media-Type: + explode: false + schema: + type: string + style: simple + "400": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The chargeback status does not allow this operation. + code: conekta.errors.business.chargebacks.could_not_be_processed + debug_message: chargeback status is won + log_id: 641b6c253cd9a50001514fae + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: bad request + "401": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: Please include your access key in your request. + code: conekta.errors.authentication.missing_key + log_id: 507f1f77bcf86cd799439011 + object: error + type: authentication_error + schema: + $ref: "#/components/schemas/error" + description: authentication error + "404": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The resource was not found. + code: conekta.errors.resource_not_found.entity + debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could + not be found. + log_id: 641b6c253cd9a50001514fae + object: error + type: resource_not_found_error + schema: + $ref: "#/components/schemas/error" + description: not found entity + "500": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - debug_message: There was a runtime error and Conekta engineers have + been notified. + message: There was a runtime error and Conekta engineers have been + notified. + code: conekta.errors.api.system.general_failure + object: error + type: api_error + log_id: 641b6f2b3cd9a50001515098 + schema: + $ref: "#/components/schemas/error" + description: internal server error + security: + - bearerAuth: [] + summary: Get Chargeback File + tags: + - Chargebacks + /charges/{charge_id}/chargebacks/{chargeback_id}/files/batch: + post: + description: | + Uploads multiple evidence files for a chargeback in a single request. Each part of the multipart body must be keyed by an evidence type (see the evidence-types endpoint for the valid values for this chargeback), with exactly one file per evidence type. Limits: at most 10 files per request, at most 2MB per file, and only application/pdf, image/jpeg or image/png content is accepted. The chargeback must be in the `action_required` status, and none of the submitted evidence types may already exist on the chargeback. On success the chargeback transitions to `pending_review`. + operationId: uploadChargebackFilesBatch + parameters: + - description: Identifier of the charge resource + explode: false + in: path + name: charge_id + required: true + schema: + example: 6966a06c044243000156c24d + type: string + style: simple + - description: Identifier of the chargeback resource + explode: false + in: path + name: chargeback_id + required: true + schema: + example: chbk_2zPxWFUnGNLySoumn + type: string + style: simple + - description: Use for knowing which language to use + examples: + es: + summary: for spanish request/response + value: es + en: + summary: for english request/response + value: en + explode: false + in: header + name: Accept-Language + required: false + schema: + default: es + enum: + - es + - en + type: string + style: simple + - description: "In the case of a holding company, the company id of the child\ + \ company to which will process the request." + example: 6441b6376b60c3a638da80af + explode: false + in: header + name: X-Child-Company-Id + required: false + schema: + type: string + style: simple + requestBody: + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/chargeback_files_batch_request" + description: | + Multipart form where each field name is an evidence type and its value is the file to upload for that evidence type. Include only the fields being uploaded (at most 10 per request); every field is optional. + required: true + responses: + "200": + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: "#/components/schemas/chargeback_files_batch_response" + description: Files uploaded successfully. + headers: + Date: + description: The date and time that the response was sent + explode: false + schema: + type: string + style: simple + Content-Type: + description: The format of the response body + explode: false + schema: + type: string + style: simple + Content-Length: + description: The length of the response body in bytes + explode: false + schema: + type: string + style: simple + Connection: + description: The type of connection used to transfer the response + explode: false + schema: + type: string + style: simple + Conekta-Media-Type: + explode: false + schema: + type: string + style: simple + "400": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The chargeback status does not allow this operation. + code: conekta.errors.business.chargebacks.could_not_be_processed + debug_message: chargeback status is won + log_id: 641b6c253cd9a50001514fae + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: bad request + "401": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: Please include your access key in your request. + code: conekta.errors.authentication.missing_key + log_id: 507f1f77bcf86cd799439011 + object: error + type: authentication_error + schema: + $ref: "#/components/schemas/error" + description: authentication error + "404": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The resource was not found. + code: conekta.errors.resource_not_found.entity + debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could + not be found. + log_id: 641b6c253cd9a50001514fae + object: error + type: resource_not_found_error + schema: + $ref: "#/components/schemas/error" + description: not found entity + "422": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The token does not exist. + param: payment_method.token_id + code: conekta.errors.parameter_validation.payment_method.token_id.nonexistent_token + debug_message: The token does not exist. + log_id: 641b6d813cd9a50001515017 + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: parameter validation error + "500": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - debug_message: There was a runtime error and Conekta engineers have + been notified. + message: There was a runtime error and Conekta engineers have been + notified. + code: conekta.errors.api.system.general_failure + object: error + type: api_error + log_id: 641b6f2b3cd9a50001515098 + schema: + $ref: "#/components/schemas/error" + description: internal server error + security: + - bearerAuth: [] + summary: Upload Chargeback Evidence Files (Batch) + tags: + - Chargebacks + /charges/{charge_id}/chargebacks/{chargeback_id}/evidence-types: + get: + description: "Retrieve the catalog of evidence types accepted for a chargeback,\ + \ including which are mandatory and their allowed file formats." + operationId: getChargebackEvidenceTypes + parameters: + - description: Identifier of the charge resource + explode: false + in: path + name: charge_id + required: true + schema: + example: 6966a06c044243000156c24d + type: string + style: simple + - description: Identifier of the chargeback resource + explode: false + in: path + name: chargeback_id + required: true + schema: + example: chbk_2zPxWFUnGNLySoumn + type: string + style: simple + - description: Use for knowing which language to use + examples: + es: + summary: for spanish request/response + value: es + en: + summary: for english request/response + value: en + explode: false + in: header + name: Accept-Language + required: false + schema: + default: es + enum: + - es + - en + type: string + style: simple + - description: "In the case of a holding company, the company id of the child\ + \ company to which will process the request." + example: 6441b6376b60c3a638da80af + explode: false + in: header + name: X-Child-Company-Id + required: false + schema: + type: string + style: simple + responses: + "200": + content: + application/vnd.conekta-v2.3.0+json: + schema: + items: + $ref: "#/components/schemas/chargeback_evidence_type_response" + type: array + description: The list of evidence types accepted for the chargeback. + headers: + Date: + description: The date and time that the response was sent + explode: false + schema: + type: string + style: simple + Content-Type: + description: The format of the response body + explode: false + schema: + type: string + style: simple + Content-Length: + description: The length of the response body in bytes + explode: false + schema: + type: string + style: simple + Connection: + description: The type of connection used to transfer the response + explode: false + schema: + type: string + style: simple + Conekta-Media-Type: + explode: false + schema: + type: string + style: simple + "400": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The chargeback status does not allow this operation. + code: conekta.errors.business.chargebacks.could_not_be_processed + debug_message: chargeback status is won + log_id: 641b6c253cd9a50001514fae + object: error + type: parameter_validation_error + schema: + $ref: "#/components/schemas/error" + description: bad request + "401": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: Please include your access key in your request. + code: conekta.errors.authentication.missing_key + log_id: 507f1f77bcf86cd799439011 + object: error + type: authentication_error + schema: + $ref: "#/components/schemas/error" + description: authentication error + "404": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - message: The resource was not found. + code: conekta.errors.resource_not_found.entity + debug_message: The object Webhook "641b1d5662d7e00001eaa46b" could + not be found. + log_id: 641b6c253cd9a50001514fae + object: error + type: resource_not_found_error + schema: + $ref: "#/components/schemas/error" + description: not found entity + "500": + content: + application/vnd.conekta-v2.3.0+json: + example: + details: + - debug_message: There was a runtime error and Conekta engineers have + been notified. + message: There was a runtime error and Conekta engineers have been + notified. + code: conekta.errors.api.system.general_failure + object: error + type: api_error + log_id: 641b6f2b3cd9a50001515098 + schema: + $ref: "#/components/schemas/error" + description: internal server error + security: + - bearerAuth: [] + summary: Get Chargeback Evidence Types + tags: + - Chargebacks /orders/{id}/charges: post: description: Create charge for an existing orden @@ -16391,6 +17041,141 @@ components: example: "278482642" type: string title: charge_update_request + chargeback_evidence_file_response: + description: A file uploaded as evidence for a chargeback + properties: + id: + example: chbkf_2zPxWFUnGNLySoums + type: string + name: + example: 20251221500000000000201.pdf + type: string + created_at: + example: 2025-12-21T15:00:00Z + format: date-time + type: string + evidence_type: + enum: + - charge_information + - contract + - other_evidence + - receipt_of_shipment + - identification + - order_details + - terms_and_conditions + - cardholder_information + - proof_invalidate_claim + - internal_validations + - proof_of_cancellation + - recurring_contract + - proof_of_return + - exhibit_8 + - duplicate_analysis + - full_evidence + example: contract + type: string + url: + description: Presigned download URL for the file. Only present when fetching + a single file. + example: https://conekta-files.s3.amazonaws.com/chbkf_2zPxWFUnGNLySoums?signature=... + nullable: true + type: string + title: chargeback_evidence_file_response + chargeback_files_batch_request: + properties: + charge_information: + format: binary + type: string + contract: + format: binary + type: string + other_evidence: + format: binary + type: string + receipt_of_shipment: + format: binary + type: string + identification: + format: binary + type: string + order_details: + format: binary + type: string + terms_and_conditions: + format: binary + type: string + cardholder_information: + format: binary + type: string + proof_invalidate_claim: + format: binary + type: string + internal_validations: + format: binary + type: string + proof_of_cancellation: + format: binary + type: string + recurring_contract: + format: binary + type: string + proof_of_return: + format: binary + type: string + exhibit_8: + format: binary + type: string + duplicate_analysis: + format: binary + type: string + full_evidence: + format: binary + type: string + title: chargeback_files_batch_request + chargeback_files_batch_response: + description: Result of a batch evidence file upload + properties: + files: + items: + $ref: "#/components/schemas/chargeback_evidence_file_response" + type: array + title: chargeback_files_batch_response + chargeback_evidence_type_response: + description: "An evidence type accepted for a chargeback, and the constraints\ + \ for uploading it" + properties: + type: + enum: + - charge_information + - contract + - other_evidence + - receipt_of_shipment + - identification + - order_details + - terms_and_conditions + - cardholder_information + - proof_invalidate_claim + - internal_validations + - proof_of_cancellation + - recurring_contract + - proof_of_return + - exhibit_8 + - duplicate_analysis + - full_evidence + example: contract + type: string + permit_formats: + example: + - application/pdf + - image/jpeg + - image/png + items: + type: string + type: array + required: + example: true + type: boolean + title: chargeback_evidence_type_response payment_method_pbb_request: allOf: - description: Contains details of the payment methods that the customer has diff --git a/api.yaml b/api.yaml index 60bd62e..0ade58c 100644 --- a/api.yaml +++ b/api.yaml @@ -32,6 +32,14 @@ paths: $ref: "./resources/charges/charges.yml" /charges/{id}: $ref: "./resources/charges/update_charge.yml" + /charges/{charge_id}/chargebacks/{chargeback_id}/files: + $ref: "./resources/chargebacks/chargeback_files.yml" + /charges/{charge_id}/chargebacks/{chargeback_id}/files/{file_id}: + $ref: "./resources/chargebacks/chargeback_file.yml" + /charges/{charge_id}/chargebacks/{chargeback_id}/files/batch: + $ref: "./resources/chargebacks/chargeback_files_batch.yml" + /charges/{charge_id}/chargebacks/{chargeback_id}/evidence-types: + $ref: "./resources/chargebacks/chargeback_evidence_types.yml" /orders/{id}/charges: $ref: "./resources/orders/order_charge_param.yml" /orders/{id}/add_charges: @@ -167,6 +175,8 @@ paths: security: - bearerAuth: [] tags: + - name: Chargebacks + description: Chargeback evidence file and evidence-type endpoints - name: Subscriptions description: All subscription-related endpoints including creation, management, and events - name: Subscriptions - Customer Portal diff --git a/parameters/commons/path_param/charge_id.yml b/parameters/commons/path_param/charge_id.yml new file mode 100644 index 0000000..e40def0 --- /dev/null +++ b/parameters/commons/path_param/charge_id.yml @@ -0,0 +1,7 @@ +in: path +name: "charge_id" +description: Identifier of the charge resource +required: true +schema: + type: string + example: "6966a06c044243000156c24d" diff --git a/parameters/commons/path_param/chargeback_id.yml b/parameters/commons/path_param/chargeback_id.yml new file mode 100644 index 0000000..f7ca598 --- /dev/null +++ b/parameters/commons/path_param/chargeback_id.yml @@ -0,0 +1,7 @@ +in: path +name: "chargeback_id" +description: Identifier of the chargeback resource +required: true +schema: + type: string + example: "chbk_2zPxWFUnGNLySoumn" diff --git a/parameters/commons/path_param/file_id.yml b/parameters/commons/path_param/file_id.yml new file mode 100644 index 0000000..585a7cb --- /dev/null +++ b/parameters/commons/path_param/file_id.yml @@ -0,0 +1,7 @@ +in: path +name: "file_id" +description: Identifier of the chargeback evidence file +required: true +schema: + type: string + example: "chbkf_2zPxWFUnGNLySoums" diff --git a/resources/chargebacks/chargeback_evidence_types.yml b/resources/chargebacks/chargeback_evidence_types.yml new file mode 100644 index 0000000..4ced74e --- /dev/null +++ b/resources/chargebacks/chargeback_evidence_types.yml @@ -0,0 +1,50 @@ +get: + tags: + - Chargebacks + operationId: getChargebackEvidenceTypes + summary: Get Chargeback Evidence Types + description: Retrieve the catalog of evidence types accepted for a chargeback, including which are mandatory and their allowed file formats. + parameters: + - $ref: '../../parameters/commons/path_param/charge_id.yml' + - $ref: '../../parameters/commons/path_param/chargeback_id.yml' + - $ref: '../../parameters/commons/headers/accept_language.yml' + - $ref: '../../parameters/commons/headers/x_child_company_id.yml' + responses: + '200': + description: The list of evidence types accepted for the chargeback. + content: + application/vnd.conekta-v2.3.0+json: + schema: + type: array + items: + $ref: '../../schemas/chargebacks/chargeback_evidence_type_response.yml' + headers: + Date: + description: The date and time that the response was sent + schema: + type: string + Content-Type: + description: The format of the response body + schema: + type: string + Content-Length: + description: The length of the response body in bytes + schema: + type: string + Connection: + description: The type of connection used to transfer the response + schema: + type: string + Conekta-Media-Type: + schema: + type: string + '400': + $ref: '../errors/400.yml' + '401': + $ref: '../errors/401.yml' + '404': + $ref: '../errors/404.yml' + '500': + $ref: '../errors/500.yml' + security: + - bearerAuth: [] diff --git a/resources/chargebacks/chargeback_file.yml b/resources/chargebacks/chargeback_file.yml new file mode 100644 index 0000000..a8a9887 --- /dev/null +++ b/resources/chargebacks/chargeback_file.yml @@ -0,0 +1,49 @@ +get: + tags: + - Chargebacks + operationId: getChargebackFile + summary: Get Chargeback File + description: Retrieve the metadata and a presigned download URL for a single chargeback evidence file. + parameters: + - $ref: '../../parameters/commons/path_param/charge_id.yml' + - $ref: '../../parameters/commons/path_param/chargeback_id.yml' + - $ref: '../../parameters/commons/path_param/file_id.yml' + - $ref: '../../parameters/commons/headers/accept_language.yml' + - $ref: '../../parameters/commons/headers/x_child_company_id.yml' + responses: + '200': + description: The requested evidence file. + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: '../../schemas/chargebacks/chargeback_evidence_file_response.yml' + headers: + Date: + description: The date and time that the response was sent + schema: + type: string + Content-Type: + description: The format of the response body + schema: + type: string + Content-Length: + description: The length of the response body in bytes + schema: + type: string + Connection: + description: The type of connection used to transfer the response + schema: + type: string + Conekta-Media-Type: + schema: + type: string + '400': + $ref: '../errors/400.yml' + '401': + $ref: '../errors/401.yml' + '404': + $ref: '../errors/404.yml' + '500': + $ref: '../errors/500.yml' + security: + - bearerAuth: [] diff --git a/resources/chargebacks/chargeback_files.yml b/resources/chargebacks/chargeback_files.yml new file mode 100644 index 0000000..7caa720 --- /dev/null +++ b/resources/chargebacks/chargeback_files.yml @@ -0,0 +1,50 @@ +get: + tags: + - Chargebacks + operationId: getChargebackFiles + summary: Get Chargeback Files + description: Retrieve the list of evidence files uploaded for a chargeback. + parameters: + - $ref: '../../parameters/commons/path_param/charge_id.yml' + - $ref: '../../parameters/commons/path_param/chargeback_id.yml' + - $ref: '../../parameters/commons/headers/accept_language.yml' + - $ref: '../../parameters/commons/headers/x_child_company_id.yml' + responses: + '200': + description: A list of evidence files for the chargeback. + content: + application/vnd.conekta-v2.3.0+json: + schema: + type: [array, "null"] + items: + $ref: '../../schemas/chargebacks/chargeback_evidence_file_response.yml' + headers: + Date: + description: The date and time that the response was sent + schema: + type: string + Content-Type: + description: The format of the response body + schema: + type: string + Content-Length: + description: The length of the response body in bytes + schema: + type: string + Connection: + description: The type of connection used to transfer the response + schema: + type: string + Conekta-Media-Type: + schema: + type: string + '400': + $ref: '../errors/400.yml' + '401': + $ref: '../errors/401.yml' + '404': + $ref: '../errors/404.yml' + '500': + $ref: '../errors/500.yml' + security: + - bearerAuth: [] diff --git a/resources/chargebacks/chargeback_files_batch.yml b/resources/chargebacks/chargeback_files_batch.yml new file mode 100644 index 0000000..0a14f0a --- /dev/null +++ b/resources/chargebacks/chargeback_files_batch.yml @@ -0,0 +1,117 @@ +post: + tags: + - Chargebacks + operationId: uploadChargebackFilesBatch + summary: Upload Chargeback Evidence Files (Batch) + description: > + Uploads multiple evidence files for a chargeback in a single request. Each part of the + multipart body must be keyed by an evidence type (see the evidence-types endpoint for the + valid values for this chargeback), with exactly one file per evidence type. Limits: at most + 10 files per request, at most 2MB per file, and only application/pdf, image/jpeg or image/png + content is accepted. The chargeback must be in the `action_required` status, and none of the + submitted evidence types may already exist on the chargeback. On success the chargeback + transitions to `pending_review`. + parameters: + - $ref: '../../parameters/commons/path_param/charge_id.yml' + - $ref: '../../parameters/commons/path_param/chargeback_id.yml' + - $ref: '../../parameters/commons/headers/accept_language.yml' + - $ref: '../../parameters/commons/headers/x_child_company_id.yml' + requestBody: + description: > + Multipart form where each field name is an evidence type and its value is the file to + upload for that evidence type. Include only the fields being uploaded (at most 10 per + request); every field is optional. + required: true + content: + multipart/form-data: + schema: + title: chargeback_files_batch_request + type: object + properties: + charge_information: + type: string + format: binary + contract: + type: string + format: binary + other_evidence: + type: string + format: binary + receipt_of_shipment: + type: string + format: binary + identification: + type: string + format: binary + order_details: + type: string + format: binary + terms_and_conditions: + type: string + format: binary + cardholder_information: + type: string + format: binary + proof_invalidate_claim: + type: string + format: binary + internal_validations: + type: string + format: binary + proof_of_cancellation: + type: string + format: binary + recurring_contract: + type: string + format: binary + proof_of_return: + type: string + format: binary + exhibit_8: + type: string + format: binary + duplicate_analysis: + type: string + format: binary + full_evidence: + type: string + format: binary + responses: + '200': + description: Files uploaded successfully. + content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: '../../schemas/chargebacks/chargeback_files_batch_response.yml' + headers: + Date: + description: The date and time that the response was sent + schema: + type: string + Content-Type: + description: The format of the response body + schema: + type: string + Content-Length: + description: The length of the response body in bytes + schema: + type: string + Connection: + description: The type of connection used to transfer the response + schema: + type: string + Conekta-Media-Type: + schema: + type: string + '400': + $ref: '../errors/400.yml' + '401': + $ref: '../errors/401.yml' + '404': + $ref: '../errors/404.yml' + '422': + $ref: '../errors/422.yml' + '500': + $ref: '../errors/500.yml' + security: + - bearerAuth: [] diff --git a/resources/errors/400.yml b/resources/errors/400.yml new file mode 100644 index 0000000..c826baa --- /dev/null +++ b/resources/errors/400.yml @@ -0,0 +1,17 @@ +description: bad request +content: + application/vnd.conekta-v2.3.0+json: + schema: + $ref: '../../schemas/errors/error.yml' + example: + details: [ + { + message: "The chargeback status does not allow this operation.", + param: null, + code: "conekta.errors.business.chargebacks.could_not_be_processed", + debug_message: "chargeback status is won", + } + ] + log_id: "641b6c253cd9a50001514fae" + object: "error" + type: "parameter_validation_error" diff --git a/schemas/chargebacks/chargeback_evidence_file_response.yml b/schemas/chargebacks/chargeback_evidence_file_response.yml new file mode 100644 index 0000000..7424cda --- /dev/null +++ b/schemas/chargebacks/chargeback_evidence_file_response.yml @@ -0,0 +1,38 @@ +title: chargeback_evidence_file_response +type: object +description: "A file uploaded as evidence for a chargeback" +properties: + id: + type: string + example: "chbkf_2zPxWFUnGNLySoums" + name: + type: string + example: "20251221500000000000201.pdf" + created_at: + type: string + format: date-time + example: "2025-12-21T15:00:00Z" + evidence_type: + type: string + example: "contract" + enum: + - charge_information + - contract + - other_evidence + - receipt_of_shipment + - identification + - order_details + - terms_and_conditions + - cardholder_information + - proof_invalidate_claim + - internal_validations + - proof_of_cancellation + - recurring_contract + - proof_of_return + - exhibit_8 + - duplicate_analysis + - full_evidence + url: + description: Presigned download URL for the file. Only present when fetching a single file. + type: [string, "null"] + example: "https://conekta-files.s3.amazonaws.com/chbkf_2zPxWFUnGNLySoums?signature=..." diff --git a/schemas/chargebacks/chargeback_evidence_type_response.yml b/schemas/chargebacks/chargeback_evidence_type_response.yml new file mode 100644 index 0000000..1eadff6 --- /dev/null +++ b/schemas/chargebacks/chargeback_evidence_type_response.yml @@ -0,0 +1,32 @@ +title: chargeback_evidence_type_response +type: object +description: "An evidence type accepted for a chargeback, and the constraints for uploading it" +properties: + type: + type: string + example: "contract" + enum: + - charge_information + - contract + - other_evidence + - receipt_of_shipment + - identification + - order_details + - terms_and_conditions + - cardholder_information + - proof_invalidate_claim + - internal_validations + - proof_of_cancellation + - recurring_contract + - proof_of_return + - exhibit_8 + - duplicate_analysis + - full_evidence + permit_formats: + type: array + items: + type: string + example: ["application/pdf", "image/jpeg", "image/png"] + required: + type: boolean + example: true diff --git a/schemas/chargebacks/chargeback_files_batch_response.yml b/schemas/chargebacks/chargeback_files_batch_response.yml new file mode 100644 index 0000000..d0b4272 --- /dev/null +++ b/schemas/chargebacks/chargeback_files_batch_response.yml @@ -0,0 +1,8 @@ +title: chargeback_files_batch_response +type: object +description: "Result of a batch evidence file upload" +properties: + files: + type: array + items: + $ref: chargeback_evidence_file_response.yml From a2b8958936419e2ff115e99c8732ffa1e1a920b0 Mon Sep 17 00:00:00 2001 From: Ezequiel Rozen Date: Thu, 20 Aug 2026 08:53:12 -0400 Subject: [PATCH 2/3] fix: align chargeback endpoint docs with repo conventions Removes the unprecedented root Chargebacks tag entry (only Subscriptions domains get one), corrects the 400 error example's type/code to match bo-chargeback's actual error_handler.go mapping, and extracts the batch upload's multipart requestBody into requestBodies/chargebacks/ to match how every other non-trivial request body in this repo is organized. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_012862o2cEy3JbDvcNcG2sYb --- _build/api.yaml | 33 +++++---- api.yaml | 2 - .../chargebacks/chargeback_files_batch.yml | 56 +++++++++++++++ .../chargebacks/chargeback_files_batch.yml | 69 +------------------ resources/errors/400.yml | 4 +- 5 files changed, 79 insertions(+), 85 deletions(-) create mode 100644 requestBodies/chargebacks/chargeback_files_batch.yml diff --git a/_build/api.yaml b/_build/api.yaml index bb9cbcd..e551ab0 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -16,8 +16,6 @@ servers: security: - bearerAuth: [] tags: -- description: Chargeback evidence file and evidence-type endpoints - name: Chargebacks - description: "All subscription-related endpoints including creation, management,\ \ and events" name: Subscriptions @@ -1549,11 +1547,11 @@ paths: example: details: - message: The chargeback status does not allow this operation. - code: conekta.errors.business.chargebacks.could_not_be_processed + code: conekta.errors.business.chargebacks.cannot_process debug_message: chargeback status is won log_id: 641b6c253cd9a50001514fae object: error - type: parameter_validation_error + type: resource_error schema: $ref: "#/components/schemas/error" description: bad request @@ -1711,11 +1709,11 @@ paths: example: details: - message: The chargeback status does not allow this operation. - code: conekta.errors.business.chargebacks.could_not_be_processed + code: conekta.errors.business.chargebacks.cannot_process debug_message: chargeback status is won log_id: 641b6c253cd9a50001514fae object: error - type: parameter_validation_error + type: resource_error schema: $ref: "#/components/schemas/error" description: bad request @@ -1770,8 +1768,14 @@ paths: - Chargebacks /charges/{charge_id}/chargebacks/{chargeback_id}/files/batch: post: - description: | - Uploads multiple evidence files for a chargeback in a single request. Each part of the multipart body must be keyed by an evidence type (see the evidence-types endpoint for the valid values for this chargeback), with exactly one file per evidence type. Limits: at most 10 files per request, at most 2MB per file, and only application/pdf, image/jpeg or image/png content is accepted. The chargeback must be in the `action_required` status, and none of the submitted evidence types may already exist on the chargeback. On success the chargeback transitions to `pending_review`. + description: "Uploads multiple evidence files for a chargeback in a single request.\ + \ Each part of the multipart body must be keyed by an evidence type (see the\ + \ evidence-types endpoint for the valid values for this chargeback), with\ + \ exactly one file per evidence type. Limits: at most 10 files per request,\ + \ at most 2MB per file, and only application/pdf, image/jpeg or image/png\ + \ content is accepted. The chargeback must be in the `action_required` status,\ + \ and none of the submitted evidence types may already exist on the chargeback.\ + \ On success the chargeback transitions to `pending_review`." operationId: uploadChargebackFilesBatch parameters: - description: Identifier of the charge resource @@ -1826,8 +1830,9 @@ paths: multipart/form-data: schema: $ref: "#/components/schemas/chargeback_files_batch_request" - description: | - Multipart form where each field name is an evidence type and its value is the file to upload for that evidence type. Include only the fields being uploaded (at most 10 per request); every field is optional. + description: Multipart form where each field name is an evidence type and + its value is the file to upload for that evidence type. Include only the + fields being uploaded (at most 10 per request); every field is optional. required: true responses: "200": @@ -1872,11 +1877,11 @@ paths: example: details: - message: The chargeback status does not allow this operation. - code: conekta.errors.business.chargebacks.could_not_be_processed + code: conekta.errors.business.chargebacks.cannot_process debug_message: chargeback status is won log_id: 641b6c253cd9a50001514fae object: error - type: parameter_validation_error + type: resource_error schema: $ref: "#/components/schemas/error" description: bad request @@ -2042,11 +2047,11 @@ paths: example: details: - message: The chargeback status does not allow this operation. - code: conekta.errors.business.chargebacks.could_not_be_processed + code: conekta.errors.business.chargebacks.cannot_process debug_message: chargeback status is won log_id: 641b6c253cd9a50001514fae object: error - type: parameter_validation_error + type: resource_error schema: $ref: "#/components/schemas/error" description: bad request diff --git a/api.yaml b/api.yaml index 0ade58c..09da41c 100644 --- a/api.yaml +++ b/api.yaml @@ -175,8 +175,6 @@ paths: security: - bearerAuth: [] tags: - - name: Chargebacks - description: Chargeback evidence file and evidence-type endpoints - name: Subscriptions description: All subscription-related endpoints including creation, management, and events - name: Subscriptions - Customer Portal diff --git a/requestBodies/chargebacks/chargeback_files_batch.yml b/requestBodies/chargebacks/chargeback_files_batch.yml new file mode 100644 index 0000000..e8f304e --- /dev/null +++ b/requestBodies/chargebacks/chargeback_files_batch.yml @@ -0,0 +1,56 @@ +description: "Multipart form where each field name is an evidence type and its value is the file to upload for that evidence type. Include only the fields being uploaded (at most 10 per request); every field is optional." +required: true +content: + multipart/form-data: + schema: + title: chargeback_files_batch_request + type: object + properties: + charge_information: + type: string + format: binary + contract: + type: string + format: binary + other_evidence: + type: string + format: binary + receipt_of_shipment: + type: string + format: binary + identification: + type: string + format: binary + order_details: + type: string + format: binary + terms_and_conditions: + type: string + format: binary + cardholder_information: + type: string + format: binary + proof_invalidate_claim: + type: string + format: binary + internal_validations: + type: string + format: binary + proof_of_cancellation: + type: string + format: binary + recurring_contract: + type: string + format: binary + proof_of_return: + type: string + format: binary + exhibit_8: + type: string + format: binary + duplicate_analysis: + type: string + format: binary + full_evidence: + type: string + format: binary diff --git a/resources/chargebacks/chargeback_files_batch.yml b/resources/chargebacks/chargeback_files_batch.yml index 0a14f0a..f8eb123 100644 --- a/resources/chargebacks/chargeback_files_batch.yml +++ b/resources/chargebacks/chargeback_files_batch.yml @@ -3,79 +3,14 @@ post: - Chargebacks operationId: uploadChargebackFilesBatch summary: Upload Chargeback Evidence Files (Batch) - description: > - Uploads multiple evidence files for a chargeback in a single request. Each part of the - multipart body must be keyed by an evidence type (see the evidence-types endpoint for the - valid values for this chargeback), with exactly one file per evidence type. Limits: at most - 10 files per request, at most 2MB per file, and only application/pdf, image/jpeg or image/png - content is accepted. The chargeback must be in the `action_required` status, and none of the - submitted evidence types may already exist on the chargeback. On success the chargeback - transitions to `pending_review`. + description: "Uploads multiple evidence files for a chargeback in a single request. Each part of the multipart body must be keyed by an evidence type (see the evidence-types endpoint for the valid values for this chargeback), with exactly one file per evidence type. Limits: at most 10 files per request, at most 2MB per file, and only application/pdf, image/jpeg or image/png content is accepted. The chargeback must be in the `action_required` status, and none of the submitted evidence types may already exist on the chargeback. On success the chargeback transitions to `pending_review`." parameters: - $ref: '../../parameters/commons/path_param/charge_id.yml' - $ref: '../../parameters/commons/path_param/chargeback_id.yml' - $ref: '../../parameters/commons/headers/accept_language.yml' - $ref: '../../parameters/commons/headers/x_child_company_id.yml' requestBody: - description: > - Multipart form where each field name is an evidence type and its value is the file to - upload for that evidence type. Include only the fields being uploaded (at most 10 per - request); every field is optional. - required: true - content: - multipart/form-data: - schema: - title: chargeback_files_batch_request - type: object - properties: - charge_information: - type: string - format: binary - contract: - type: string - format: binary - other_evidence: - type: string - format: binary - receipt_of_shipment: - type: string - format: binary - identification: - type: string - format: binary - order_details: - type: string - format: binary - terms_and_conditions: - type: string - format: binary - cardholder_information: - type: string - format: binary - proof_invalidate_claim: - type: string - format: binary - internal_validations: - type: string - format: binary - proof_of_cancellation: - type: string - format: binary - recurring_contract: - type: string - format: binary - proof_of_return: - type: string - format: binary - exhibit_8: - type: string - format: binary - duplicate_analysis: - type: string - format: binary - full_evidence: - type: string - format: binary + $ref: '../../requestBodies/chargebacks/chargeback_files_batch.yml' responses: '200': description: Files uploaded successfully. diff --git a/resources/errors/400.yml b/resources/errors/400.yml index c826baa..3ac791f 100644 --- a/resources/errors/400.yml +++ b/resources/errors/400.yml @@ -8,10 +8,10 @@ content: { message: "The chargeback status does not allow this operation.", param: null, - code: "conekta.errors.business.chargebacks.could_not_be_processed", + code: "conekta.errors.business.chargebacks.cannot_process", debug_message: "chargeback status is won", } ] log_id: "641b6c253cd9a50001514fae" object: "error" - type: "parameter_validation_error" + type: "resource_error" From fe00c1f378fd0824babe92e3330c5ea264434894 Mon Sep 17 00:00:00 2001 From: Ezequiel Rozen Date: Thu, 20 Aug 2026 13:40:33 -0400 Subject: [PATCH 3/3] refactor: extract repeated evidence_type enum into shared schema The 16-value evidence type enum was duplicated across chargeback_evidence_file_response and chargeback_evidence_type_response; extracted to chargeback_evidence_type.yml and referenced via $ref from both, per review feedback from @fcarrero on PR #127. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_012862o2cEy3JbDvcNcG2sYb --- _build/api.yaml | 4 ++++ .../chargeback_evidence_file_response.yml | 20 +----------------- .../chargebacks/chargeback_evidence_type.yml | 21 +++++++++++++++++++ .../chargeback_evidence_type_response.yml | 20 +----------------- 4 files changed, 27 insertions(+), 38 deletions(-) create mode 100644 schemas/chargebacks/chargeback_evidence_type.yml diff --git a/_build/api.yaml b/_build/api.yaml index e551ab0..5a1ac0f 100644 --- a/_build/api.yaml +++ b/_build/api.yaml @@ -17060,6 +17060,7 @@ components: format: date-time type: string evidence_type: + description: The evidence type used for a chargeback file upload enum: - charge_information - contract @@ -17078,6 +17079,7 @@ components: - duplicate_analysis - full_evidence example: contract + title: chargeback_evidence_type type: string url: description: Presigned download URL for the file. Only present when fetching @@ -17150,6 +17152,7 @@ components: \ for uploading it" properties: type: + description: The evidence type used for a chargeback file upload enum: - charge_information - contract @@ -17168,6 +17171,7 @@ components: - duplicate_analysis - full_evidence example: contract + title: chargeback_evidence_type type: string permit_formats: example: diff --git a/schemas/chargebacks/chargeback_evidence_file_response.yml b/schemas/chargebacks/chargeback_evidence_file_response.yml index 7424cda..4013838 100644 --- a/schemas/chargebacks/chargeback_evidence_file_response.yml +++ b/schemas/chargebacks/chargeback_evidence_file_response.yml @@ -13,25 +13,7 @@ properties: format: date-time example: "2025-12-21T15:00:00Z" evidence_type: - type: string - example: "contract" - enum: - - charge_information - - contract - - other_evidence - - receipt_of_shipment - - identification - - order_details - - terms_and_conditions - - cardholder_information - - proof_invalidate_claim - - internal_validations - - proof_of_cancellation - - recurring_contract - - proof_of_return - - exhibit_8 - - duplicate_analysis - - full_evidence + $ref: chargeback_evidence_type.yml url: description: Presigned download URL for the file. Only present when fetching a single file. type: [string, "null"] diff --git a/schemas/chargebacks/chargeback_evidence_type.yml b/schemas/chargebacks/chargeback_evidence_type.yml new file mode 100644 index 0000000..acaf266 --- /dev/null +++ b/schemas/chargebacks/chargeback_evidence_type.yml @@ -0,0 +1,21 @@ +title: chargeback_evidence_type +type: string +description: "The evidence type used for a chargeback file upload" +example: "contract" +enum: + - charge_information + - contract + - other_evidence + - receipt_of_shipment + - identification + - order_details + - terms_and_conditions + - cardholder_information + - proof_invalidate_claim + - internal_validations + - proof_of_cancellation + - recurring_contract + - proof_of_return + - exhibit_8 + - duplicate_analysis + - full_evidence diff --git a/schemas/chargebacks/chargeback_evidence_type_response.yml b/schemas/chargebacks/chargeback_evidence_type_response.yml index 1eadff6..049a47f 100644 --- a/schemas/chargebacks/chargeback_evidence_type_response.yml +++ b/schemas/chargebacks/chargeback_evidence_type_response.yml @@ -3,25 +3,7 @@ type: object description: "An evidence type accepted for a chargeback, and the constraints for uploading it" properties: type: - type: string - example: "contract" - enum: - - charge_information - - contract - - other_evidence - - receipt_of_shipment - - identification - - order_details - - terms_and_conditions - - cardholder_information - - proof_invalidate_claim - - internal_validations - - proof_of_cancellation - - recurring_contract - - proof_of_return - - exhibit_8 - - duplicate_analysis - - full_evidence + $ref: chargeback_evidence_type.yml permit_formats: type: array items: