[CRD-1915] feat: document chargeback file and evidence-type endpoints

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:

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"

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"

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"

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

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: []

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: []

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: []

resources/chargebacks/chargeback_files_batch.yml

@@ -0,0 +1,52 @@
+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:
+    $ref: '../../requestBodies/chargebacks/chargeback_files_batch.yml'
+  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: []

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.cannot_process",
+          debug_message: "chargeback status is won",
+        }
+      ]
+      log_id: "641b6c253cd9a50001514fae"
+      object: "error"
+      type: "resource_error"

schemas/chargebacks/chargeback_evidence_file_response.yml

@@ -0,0 +1,20 @@
+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:
+    $ref: chargeback_evidence_type.yml
+  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=..."

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

schemas/chargebacks/chargeback_evidence_type_response.yml

@@ -0,0 +1,14 @@
+title: chargeback_evidence_type_response
+type: object
+description: "An evidence type accepted for a chargeback, and the constraints for uploading it"
+properties:
+  type:
+    $ref: chargeback_evidence_type.yml
+  permit_formats:
+    type: array
+    items:
+      type: string
+    example: ["application/pdf", "image/jpeg", "image/png"]
+  required:
+    type: boolean
+    example: true

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