{
  "openapi": "3.0.0",
  "paths": {
    "/health": {
      "get": {
        "description": "Public health probe used by Kubernetes liveness and readiness probes, as well as external monitoring. Returns a static payload confirming that the gateway is reachable and able to respond to HTTP requests.",
        "operationId": "HealthController_checkHealth",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Service is up and reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "status": "ok"
                  }
                }
              }
            }
          }
        },
        "summary": "Service health check",
        "tags": [
          "Health"
        ]
      }
    },
    "/auth/login": {
      "post": {
        "description": "Authenticates a merchant integration using an Ed25519 digital signature challenge. Forwards the credentials to the authentication microservice over NATS and returns an access token and a refresh token on success. This endpoint is public and does not require a previous JWT.",
        "operationId": "AuthController_login",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthLoginDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication succeeded. Returns the access token and refresh token pair.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "accessToken": "<JWT_ACCESS_TOKEN>",
                      "refreshToken": "<JWT_REFRESH_TOKEN>",
                      "expirationToken": 1718467200,
                      "expirationRefreshToken": 1719072000
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing merchant identifier or signature payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "The Ed25519 signature could not be verified for the given merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7604",
                        "message": "Invalid signature, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Authenticate Merchant Integration",
        "tags": [
          "Authentication"
        ]
      }
    },
    "/auth/refresh": {
      "post": {
        "description": "Exchanges a valid refresh token for a new access token and refresh token pair. The refresh token must have been previously issued by the login endpoint and not be revoked or expired. The request is forwarded to the authentication microservice over NATS.",
        "operationId": "AuthController_refreshToken",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshTokenDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token refresh succeeded. Returns the new access token and refresh token pair.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "accessToken": "<JWT_ACCESS_TOKEN>",
                      "refreshToken": "<JWT_REFRESH_TOKEN>",
                      "expirationToken": 1718467200,
                      "expirationRefreshToken": 1719072000
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing or malformed refresh token payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "The refresh token is invalid, revoked or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Refresh Integration Access Token",
        "tags": [
          "Authentication"
        ]
      }
    },
    "/onboarding/ocr": {
      "post": {
        "description": "Requires the application access token issued by POST /rest/auth/login, granted the onboarding:ocr permission. The merchant and client are taken from that token, never from the request.",
        "operationId": "OnboardingController_ocr",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "dpiFront"
                ],
                "properties": {
                  "dpiFront": {
                    "type": "string",
                    "format": "binary"
                  },
                  "dpiBack": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "422": {
            "description": "Invalid image bytes or document."
          },
          "503": {
            "description": "Identity provider unavailable."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Verify a DPI document for self-service onboarding",
        "tags": [
          "Identity onboarding"
        ]
      }
    },
    "/onboarding/liveness": {
      "post": {
        "operationId": "OnboardingController_liveness",
        "parameters": [
          {
            "name": "verificationid",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "verificationId",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "selfie"
                ],
                "properties": {
                  "selfie": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "410": {
            "description": "Verification expired."
          },
          "422": {
            "description": "Invalid selfie."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Verify selfie liveness and optional face match",
        "tags": [
          "Identity onboarding"
        ]
      }
    },
    "/onboarding/sessions": {
      "post": {
        "description": "Creates the provider session for the merchant workflow and the verification that will receive its result. Returns the sessionToken the native SDK opens (url for web). The decision arrives by webhook: read it with GET /rest/onboarding/verifications/{verificationId}, then create the lead with POST /rest/leads and the verificationId header. Uses the same application token and permission as the OCR flow.",
        "operationId": "OnboardingController_session",
        "parameters": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOnboardingSessionDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session opened."
          },
          "403": {
            "description": "Identity onboarding disabled or the merchant has no workflow configured."
          },
          "503": {
            "description": "Identity provider unavailable."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Open an identity verification in the provider SDK",
        "tags": [
          "Identity onboarding"
        ]
      }
    },
    "/onboarding/verifications/{verificationId}": {
      "get": {
        "description": "Answers what happened with a verification: approved, declined, waiting for a person to review it, or already used to create a lead. A declined verification carries reasonCode when the method that failed left one (DOCUMENT_NUMBER_MISMATCH when the document is not the expected one). Uses the same application token and permission that opened the verification.",
        "operationId": "OnboardingController_verificationStatus",
        "parameters": [
          {
            "name": "verificationId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "404": {
            "description": "Unknown verification."
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Read the state of a verification",
        "tags": [
          "Identity onboarding"
        ]
      }
    },
    "/webhooks/didit": {
      "post": {
        "description": "Invoked by Didit when a workflow session changes status. Authenticated by the X-Signature-V2 HMAC over the canonical body and the X-Timestamp window (300 s). Approved and Declined decisions are applied to the matching verification; any other status is acknowledged without changes.",
        "operationId": "IdentityWebhookController_receive",
        "parameters": [
          {
            "name": "x-signature-v2",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-timestamp",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Signature-V2",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed or acknowledged."
          },
          "401": {
            "description": "Invalid signature or stale timestamp."
          },
          "500": {
            "description": "Not applied; Didit retries the delivery."
          }
        },
        "summary": "Receive Didit verification webhooks",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/volcan": {
      "post": {
        "description": "Endpoint invoked by the Volcan card processor whenever a card movement is produced. The payload is acknowledged synchronously and queued for asynchronous processing through the `process.volcan.webhook` event pattern, which creates or updates the matching transfer.",
        "operationId": "WebhooksController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VolcanWebhookDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook acknowledged synchronously and queued for asynchronous processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Webhook Received successfull"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the Volcan webhook payload is missing or malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the webhook could not be queued for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Receive Volcan card webhook",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/settlements": {
      "post": {
        "description": "Endpoint invoked by alternative payment providers whenever a settlement is produced. The payload is acknowledged synchronously and queued for asynchronous processing through the `process.settlement.webhook` event pattern, which forwards the settlement to the transactional orchestrator.",
        "operationId": "WebhooksController_settlements",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "example": {
                  "uid": "SET-9f8c1b2a",
                  "transactionId": "TX-123456789",
                  "amount": "150.75",
                  "currency": "GTQ",
                  "status": "approved",
                  "reference": "REF-0000123456",
                  "authorizationCode": "123456",
                  "deviceId": "DEV-001",
                  "paymentMethodType": "akisiQR",
                  "createdAt": "2026-05-21T15:30:00.000Z",
                  "additionalData": {
                    "provider": "akisi"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settlement webhook acknowledged synchronously and queued for asynchronous processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Settlement webhook received successfully"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the settlement webhook could not be queued for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Receive alternative payments settlement webhook",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/webhooks/migo": {
      "post": {
        "description": "Endpoint invoked by Migo to notify the status of a bank transfer. The payload is acknowledged synchronously and forwarded to the orchestrator through the `orchestrator.process.migo.webhook` event pattern. TODO: add Migo signature verification before production.",
        "operationId": "WebhooksController_migo",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MigoWebhookDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Migo webhook acknowledged synchronously and queued for asynchronous processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Webhook Received successfull"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the Migo webhook could not be queued for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Receive Migo bank transfer webhook",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/users": {
      "post": {
        "description": "Registers a new platform user. When an invitationCode is present in the body the payload is validated against ExternalUserRegistrationDto, otherwise it is validated against the shared CreateUserDto. Requires a valid JWT and the USER_REGISTRATION permission. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_userRegistration",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "User registration payload. When an invitationCode is present the payload is validated against ExternalUserRegistrationDto (documented schema); otherwise it is validated against the shared CreateUserDto.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalUserRegistrationDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully. For the invitation-code registration path data includes id, isUser and (for account users) isAssociated; for the plain CreateUserDto path data contains only the new user id.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "User created successfully",
                    "data": {
                      "id": 1,
                      "isUser": false,
                      "isAssociated": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the registration payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the USER_REGISTRATION application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced invitation code or branch was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7120",
                        "message": "Invitation code not found, please check your code and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "A user with the same username already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7101",
                        "message": "User already exists in the system, check your username."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating user, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7118",
                        "message": "Error creating user, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Register New User",
        "tags": [
          "Users"
        ]
      },
      "get": {
        "description": "Retrieves the detail of a user filtering by numeric identifier or username. At least one filter must be provided. Requires JWT, application permissions and user-level permissions. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_findUser",
        "parameters": [
          {
            "name": "id",
            "required": false,
            "in": "query",
            "description": "Numeric identifier of the user.",
            "schema": {
              "example": 1,
              "type": "string"
            }
          },
          {
            "name": "username",
            "required": false,
            "in": "query",
            "description": "Username (email) of the user.",
            "schema": {
              "example": "user@example.com",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User detail returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "userId": 10,
                      "username": "user@example.com",
                      "status": "Active",
                      "userType": "user",
                      "firstName": "John",
                      "lastName": "Doe",
                      "auth_user_role": [
                        {
                          "Role": {
                            "name": "shop_owner"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid id or username filter provided.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the DETAIL application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No user matches the provided id or username.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error finding user, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7124",
                        "message": "Error finding user, please check your userId and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find User By Id Or Username",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/by-document": {
      "get": {
        "description": "Returns the account registered under the caller's application for the given identification document (DPI by default), including the userId accepted by the /users/:userId/* routes. Only users of the merchant in the client JWT are visible: a document registered under another application answers 404, the same as an unknown one. Requires a valid JWT and the FIND_BY_DOCUMENT application permission. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_findUserByDocument",
        "parameters": [
          {
            "name": "documentNumber",
            "required": true,
            "in": "query",
            "description": "Identification document number.",
            "schema": {
              "example": "1234567890101",
              "type": "string"
            }
          },
          {
            "name": "documentType",
            "required": false,
            "in": "query",
            "description": "Identification document type. Defaults to DPI.",
            "schema": {
              "default": "DPI",
              "example": "DPI",
              "type": "string",
              "enum": [
                "DPI",
                "NIT",
                "PASSPORT",
                "LEGAL_ID",
                "PERSONAL_ID",
                "RESIDENCE_ID"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "User found",
                    "data": {
                      "userId": 123,
                      "firstName": "Marthinn",
                      "lastName": "Chew",
                      "address": "Calle 10, Zona 1, Ciudad de Guatemala",
                      "countryOfBirth": "GTM",
                      "placeOfBirth": "Ciudad de Guatemala",
                      "gender": "M",
                      "maritalStatus": "soltero",
                      "neighborhood": "Colonia Las Flores",
                      "phoneNumber": "50258396819",
                      "username": "marthinnchew@akisi.com",
                      "dateOfBirth": "1996-09-22",
                      "identificationDocuments": [
                        {
                          "documentNumber": "1234567890101",
                          "documentType": "DPI"
                        }
                      ],
                      "termsAndConditionsAccepted": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing document number or unknown document type.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_BY_DOCUMENT application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No user of the caller's application holds this document.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "More than one user of the caller's application holds this document.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7186",
                        "message": "More than one user is registered with this document, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error finding user by document.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7106",
                        "message": "Error finding user by document."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find User By Identification Document",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/permissions": {
      "post": {
        "description": "Creates one or more permissions in the authentication catalog. Requires JWT and the CREATE_PERMISSION application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_createPermission",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Object containing the list of permissions to create.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "permissions": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/PermissionDto"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Permissions created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "count": 2
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the permissions payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_PERMISSION application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "One or more permissions already exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7159",
                        "message": "User permission already exist, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating permission, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7608",
                        "message": "Error creating permission, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Permissions Batch",
        "tags": [
          "Users"
        ]
      },
      "get": {
        "description": "Returns the complete catalog of permissions known to the authorization service. Requires JWT and the FIND_ALL_PERMISSIONS application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_getPermissions",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of permissions returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "permissions": [
                        {
                          "id": 10,
                          "resource": "users",
                          "action": "create",
                          "description": "Create users",
                          "createdAt": "2026-01-01T00:00:00.000Z",
                          "updatedAt": "2026-01-01T00:00:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_ALL_PERMISSIONS application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving permissions, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List All Permissions",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/roles": {
      "get": {
        "description": "Returns the complete list of roles defined in the authorization catalog. Requires JWT and the FIND_ALL_ROLES application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_findAllRoles",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of roles returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "roles": [
                        {
                          "id": 1,
                          "name": "admin",
                          "description": "Administrator role",
                          "createdAt": "2026-01-01T00:00:00.000Z",
                          "updatedAt": "2026-01-01T00:00:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_ALL_ROLES application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving roles, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List All Roles",
        "tags": [
          "Users"
        ]
      },
      "post": {
        "description": "Creates one or more roles with their associated permissions. Requires JWT and the CREATE_ROLE application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_createRole",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Object containing the list of roles to create.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "roles": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/RoleDto"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Roles created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "roles": {
                        "items": 1
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the roles payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_ROLE application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "One or more permissions referenced by the roles were not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7612",
                        "message": "One or more permissions not found, please verify names."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "One or more roles already exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7158",
                        "message": "Role already exists, check roles"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating role, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7609",
                        "message": "Error creating role, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Roles Batch",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/roles/{name}": {
      "patch": {
        "description": "Updates the permissions and description of an existing role identified by its name. Requires JWT and the UPDATE_ROLE application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_updateRole",
        "parameters": [
          {
            "name": "name",
            "required": true,
            "in": "path",
            "description": "Name of the role to update.",
            "schema": {
              "example": "admin",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRoleDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Role updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "name": "admin",
                      "description": "Administrator role",
                      "createdAt": "2026-01-01T00:00:00.000Z",
                      "updatedAt": "2026-01-01T00:00:00.000Z",
                      "rolePermissions": [
                        {
                          "id": 1,
                          "roleId": 1,
                          "permissionId": 10,
                          "permission": {
                            "id": 10,
                            "resource": "users",
                            "action": "create",
                            "description": "Create users"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the update payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_ROLE application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The role to update was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7611",
                        "message": "One or more roles not found, please verify names."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating role, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7617",
                        "message": "Error updating role, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Role",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{id}/roles": {
      "get": {
        "description": "Returns all roles assigned to a given authentication user. Requires JWT and the FIND_ROLES_BY_AUTH_USER_ID application permission. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_findRoleByAuthUserId",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Identifier of the authentication user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Roles returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "role": "admin"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_ROLES_BY_AUTH_USER_ID application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No roles were found for the given authentication user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7156",
                        "message": "Auth user role not found, check names"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error finding auth user role, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7154",
                        "message": "Error finding auth user role, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find Roles By Auth User Id",
        "tags": [
          "Users"
        ]
      },
      "patch": {
        "description": "Adds or removes roles assigned to an authentication user. Requires JWT and the UPDATE_AUTH_USER_ROLES application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_updateAuthUserRoles",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Identifier of the authentication user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Object describing which roles to add and which to remove.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "addRoles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "admin"
                    ]
                  },
                  "removeRoles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "support"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Auth user roles updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "rolesAdded": 1,
                    "rolesRemoved": 1
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the roles update payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_AUTH_USER_ROLES application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The authentication user or one of the referenced roles was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7156",
                        "message": "Auth user role not found, check names"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating auth user role, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7153",
                        "message": "Error updating auth user role, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Auth User Roles",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{id}/permissions": {
      "post": {
        "description": "Creates user-level permissions assigned directly to an authentication user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_createAuthUserPermissions",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Identifier of the authentication user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Object containing the list of user permissions to create.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "permissions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "roleId": {
                          "type": "number",
                          "example": 1
                        },
                        "permissionId": {
                          "type": "number",
                          "example": 10
                        },
                        "granted": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "permissions": [
                    {
                      "roleId": 1,
                      "permissionId": 10,
                      "granted": true
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Auth user permissions created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "items": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the permissions payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_AUTH_USER_PERMISSIONS application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The authentication user or one of the referenced permissions was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7157",
                        "message": "Auth user permission not found, check names"
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "One or more user permissions already exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7159",
                        "message": "User permission already exist, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating auth user permission, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7151",
                        "message": "Error creating auth user permission, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Auth User Permissions",
        "tags": [
          "Users"
        ]
      },
      "patch": {
        "description": "Updates user-level permissions assigned directly to an authentication user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_updateAuthUserPermissions",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Identifier of the authentication user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Object containing the updated list of user permissions.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "permissions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "roleId": {
                          "type": "number",
                          "example": 1
                        },
                        "permissionId": {
                          "type": "number",
                          "example": 10
                        },
                        "granted": {
                          "type": "boolean",
                          "example": false
                        }
                      }
                    }
                  }
                },
                "example": {
                  "permissions": [
                    {
                      "roleId": 1,
                      "permissionId": 10,
                      "granted": false
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Auth user permissions updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "items": [
                        {
                          "authUserId": 1,
                          "roleId": 1,
                          "permissionId": 10,
                          "granted": false
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the permissions payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_AUTH_USER_PERMISSIONS application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The authentication user permission to update was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7157",
                        "message": "Auth user permission not found, check names"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating auth user permission, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7152",
                        "message": "Error updating auth user permission, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Auth User Permissions",
        "tags": [
          "Users"
        ]
      },
      "get": {
        "description": "Returns the effective permissions assigned to a given authentication user (role-derived and direct). Requires JWT and the FIND_ALL_PERMISSIONS_BY_AUTH_USER_ID application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_getPermissionsByAuthUserId",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Identifier of the authentication user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permissions for the auth user returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "name": "admin",
                        "permissions": [
                          {
                            "resource": "users",
                            "action": "create",
                            "description": "Create users"
                          }
                        ],
                        "customPermissions": [
                          {
                            "resource": "cards",
                            "action": "block",
                            "description": "Block cards",
                            "granted": true
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_ALL_PERMISSIONS_BY_AUTH_USER_ID application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No permissions were found for the given authentication user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7157",
                        "message": "Auth user permission not found, check names"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error finding auth user permission, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7155",
                        "message": "Error finding auth user permission, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List Permissions By Auth User Id",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/roles/{name}/permissions": {
      "get": {
        "description": "Returns the permissions associated with the given role name. Requires JWT and the FIND_PERMISSIONS_BY_ROLE application permission. The request is delegated to the role permissions service via NATS.",
        "operationId": "UsersController_getPermissionsByRole",
        "parameters": [
          {
            "name": "name",
            "required": true,
            "in": "path",
            "description": "Name of the role to inspect.",
            "schema": {
              "example": "admin",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permissions for the role returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "name": "admin",
                      "description": "Administrator role",
                      "createdAt": "2026-01-01T00:00:00.000Z",
                      "updatedAt": "2026-01-01T00:00:00.000Z",
                      "rolePermissions": [
                        {
                          "id": 1,
                          "roleId": 1,
                          "permissionId": 10,
                          "permission": {
                            "id": 10,
                            "resource": "users",
                            "action": "create",
                            "description": "Create users"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FIND_PERMISSIONS_BY_ROLE application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The role or its permissions were not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7613",
                        "message": "Role permissions not found, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving role permissions, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List Permissions By Role",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/invitation-code": {
      "post": {
        "description": "Generates a new invitation code that allows a future user to register against a specific branch with a predefined role. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_createInvitationCode",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationCodeGenerateDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invitation code generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Invitation code created successfully",
                    "data": {
                      "invitationCode": "INV-123456"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the invitation payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_INVITATION_CODE application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced branch was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7410",
                        "message": "Branch not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "An error occurred while creating the invitation code, check the branch status.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7110",
                        "message": "An error occurred while creating the invitation code, check the branch status"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Invitation Code",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/login": {
      "post": {
        "description": "Authenticates a platform user with username and password. Requires JWT (integration token) and the USER_LOGIN application permission. Returns the user access and refresh tokens. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_userLogin",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserLoginDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User authentication succeeded. Returns the user access and refresh tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "accessToken": "eyJhbGciOiJFZERTQSJ9...",
                      "refreshToken": "eyJhbGciOiJFZERTQSJ9...",
                      "expirationToken": 1771200000,
                      "expirationRefreshToken": 1773792000,
                      "branch": {
                        "id": 5,
                        "name": "Sucursal Central"
                      },
                      "commerceId": 3,
                      "sdk": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the login payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8000",
                        "message": "Invalid credentials, please try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the USER_LOGIN application permission or the user is suspended.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7139",
                        "message": "You have exceeded the number of login attempts, your user has been temporarily suspended"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No user matches the provided username.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7128",
                        "message": "User not found, please check your username and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "An error occurred while logging in, please try later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7138",
                        "message": "An error occurred while logging in, please try later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "User Login",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/refresh": {
      "post": {
        "description": "Exchanges a valid user refresh token for a new access token and refresh token pair. Requires JWT (integration token) and the USER_REFRESH_TOKEN application permission. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_userRefreshToken",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserRefreshTokenDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "New token pair issued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "accessToken": "eyJhbGciOiJFZERTQSJ9...",
                      "refreshToken": "eyJhbGciOiJFZERTQSJ9...",
                      "expirationToken": 1771200000,
                      "expirationRefreshToken": 1773792000,
                      "id": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid/expired refresh token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7149",
                        "message": "Expired user refresh token, please login again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid refresh token or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8003",
                        "message": "Invalid refresh token, please try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the USER_REFRESH_TOKEN application permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Refresh User Access Token",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/logout": {
      "post": {
        "description": "Invalidates the currently authenticated user session. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_userLogout",
        "parameters": [],
        "responses": {
          "200": {
            "description": "User session terminated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "User session terminated successfully."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the USER_LOGOUT application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error logging out, check your token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7142",
                        "message": "Error logging out, check your token"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "User Logout",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/summary": {
      "get": {
        "description": "Returns an aggregated summary of card activity for the given user in the requested date range. Requires JWT and the GET_SUMMARY card permission. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_getCardsSummary",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose cards summary will be returned.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "startDate",
            "required": true,
            "in": "query",
            "description": "Start date of the period to summarize (ISO 8601).",
            "schema": {
              "example": "2026-01-01",
              "type": "string"
            }
          },
          {
            "name": "endDate",
            "required": true,
            "in": "query",
            "description": "End date of the period to summarize (ISO 8601).",
            "schema": {
              "example": "2026-01-31",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cards summary returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "totalAvailable": "5000.00",
                      "totalDebits": "1200.00"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid date range or user identifier.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_SUMMARY card permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user has no cards.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7212",
                        "message": "The user does not have any cards."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error getting user cards, please check your userId and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7215",
                        "message": "Error getting user cards, please check your userId and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get Cards Summary By User",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards": {
      "post": {
        "description": "Links an existing card to the given user account using the provided card number and optional alias. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_linkCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the card to be linked.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "clientId",
            "required": true,
            "in": "query",
            "description": "Identifier of the integration client requesting the operation.",
            "schema": {
              "example": "client-acme-001"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalLinkCardUserDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Card linked to the user successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "cardId": 12345,
                      "userId": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the link card payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the LINK_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card or user was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already linked to an account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7209",
                        "message": "Card is already linked to an account."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating card information.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Link Card To User",
        "tags": [
          "Users"
        ]
      },
      "get": {
        "description": "Returns the complete list of cards associated with the given user identifier. Requires a valid JWT and the GET_ALL_BY_USER permission. The request is delegated to the cards microservice via NATS.",
        "operationId": "AuthUsersController_getAllByUser",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose cards will be returned.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of cards associated with the user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Cards found successfully",
                    "data": {
                      "holderName": "John Doe",
                      "cards": [
                        {
                          "cardId": 1,
                          "suffix": "1234",
                          "alias": "My main card",
                          "balance": "1500.0000",
                          "status": "Active",
                          "linkedAuthUserId": null,
                          "isFavorite": true
                        }
                      ],
                      "cardBranches": [
                        {
                          "id": 10,
                          "name": "Main Branch",
                          "cards": [
                            {
                              "cardId": 2,
                              "suffix": "5678",
                              "alias": null,
                              "balance": "0.0000",
                              "status": "Active",
                              "linkedAuthUserId": 42,
                              "isFavorite": false
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the GET_ALL_BY_USER permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found — the user has no cards or does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7212",
                        "message": "The user does not have any cards."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the cards microservice could not return the user cards.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7215",
                        "message": "Error getting user cards, please check your userId and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List Cards By User",
        "tags": [
          "Users - Cards"
        ]
      }
    },
    "/users/{userId}/cards/virtuals": {
      "post": {
        "description": "Creates a new virtual card for the given user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_createCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that will own the new virtual card.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Virtual card created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "cardId": 12345,
                      "externalId": "VLC-987654",
                      "suffix": "1234",
                      "manufacturing": "virtual",
                      "status": "Inactive",
                      "balance": "0.00"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user to own the card was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error while creating card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7211",
                        "message": "Error while creating card."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Virtual Card",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/{cardId}": {
      "get": {
        "description": "Returns sensitive card details (PAN, CVV) for the given user and card combination using a previously issued view token. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_checkCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the card.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Identifier of the card to inspect.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "token",
            "required": true,
            "in": "query",
            "description": "Single-use view token previously issued for the card.",
            "schema": {
              "example": "view-token-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card details returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "cardId": 12345,
                      "status": "Active",
                      "alias": "My virtual card",
                      "card": "4111111111111234",
                      "cvv": "123",
                      "balance": "5000.00",
                      "expirationDate": "2030-12-31T00:00:00.000Z",
                      "linkedAuthUserId": null,
                      "firstName": "John",
                      "lastName": "Doe",
                      "username": "user@example.com",
                      "externalId": "VLC-987654",
                      "authUserId": 1,
                      "suffix": "1234",
                      "clientId": "client-acme-001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired view token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7201",
                        "message": "Unauthorized card access. Please verify the information entered."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CHECK_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card or its view token was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7225",
                        "message": "View token not found, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error getting card, please check your cardId and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7214",
                        "message": "Error getting card, please check your cardId and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Check Card Details",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/auth/otp": {
      "post": {
        "description": "Creates the OTP for email or WhatsApp delivery and returns its timing metadata (channel, createdAt, expiration) while delivery is dispatched asynchronously. When channel is omitted, email is used by default. Requires JWT and the REQUEST_OTP permission.",
        "operationId": "UsersController_requestOtp",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "OTP request payload. Channel is optional and defaults to email when omitted.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestOtpDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP created and queued for delivery. Returns channel, createdAt and expiration.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "OTP request accepted."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the OTP request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7131",
                        "message": "Invalid OTP purpose, please check the purpose and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the REQUEST_OTP permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7607",
                        "message": "Forbidden resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Request One-Time Password",
        "tags": [
          "Users"
        ]
      },
      "put": {
        "description": "Verifies a previously requested OTP through the orchestrator. When channel is omitted, email is used by default. Requires JWT and the VALIDATE_OTP permission.",
        "operationId": "UsersController_verifyOtp",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "OTP validation payload. Channel is optional and defaults to email when omitted.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyOtpDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP verified successfully. For the password reset purpose a temporary access token is returned in data; for account verification data is an empty object.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "OTP verified successfully for email: user@example.com",
                    "data": {
                      "token": "temporal-access-token-abc123"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or expired OTP.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7135",
                        "message": "OTP has expired, please request a new OTP."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid OTP or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7132",
                        "message": "Invalid OTP, please check the OTP and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the VALIDATE_OTP permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7607",
                        "message": "Forbidden resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The OTP was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7133",
                        "message": "OTP not found, please check the OTP and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The OTP has already been used.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7134",
                        "message": "OTP has already been used, please request a new OTP."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Verify One-Time Password",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/auth/otp/resend": {
      "post": {
        "description": "Regenerates the OTP for email or WhatsApp delivery and returns its timing metadata (channel, createdAt, expiration) while delivery is dispatched asynchronously. When channel is omitted, email is used by default. Requires JWT and the RESEND_OTP permission.",
        "operationId": "UsersController_resendOtp",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "OTP resend payload. Channel is optional and defaults to email when omitted.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestOtpDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OTP regenerated and queued for delivery. Returns channel, createdAt and expiration.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "OTP resend accepted."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the OTP resend payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7131",
                        "message": "Invalid OTP purpose, please check the purpose and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the RESEND_OTP permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7607",
                        "message": "Forbidden resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Resend One-Time Password",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/auth/masked-contact": {
      "get": {
        "description": "Returns the masked email/phone and the notification channels available for the user (EMAIL when an email is registered, WHATSAPP when a phone is registered). The contact is resolved and masked in origin (op-users) so the client never receives raw PII. Consumed by the wallet before requesting the OTP to show the masked destination. Requires JWT and the GET_MASKED_CONTACT permission.",
        "operationId": "UsersController_getMaskedContact",
        "parameters": [
          {
            "name": "email",
            "required": true,
            "in": "query",
            "description": "Email of the user whose masked contact is requested.",
            "schema": {
              "example": "user@example.com",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Masked contact resolved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Masked contact found",
                    "data": {
                      "maskedEmail": "jo****@correo.com",
                      "maskedPhone": "+506 ****1234",
                      "channels": [
                        "email",
                        "whatsapp"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_MASKED_CONTACT permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7607",
                        "message": "Forbidden resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get masked contact and available OTP channels",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/auth": {
      "post": {
        "description": "Verifies the current password of the given user. Used to re-authenticate before sensitive operations. Authentication is optional but a JWT will be inspected when provided. The request is delegated to the authentication service via NATS.",
        "operationId": "UsersController_verifyPassword",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose password is being verified.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyPasswordDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password verified successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Password verified successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7117",
                        "message": "Invalid password, please check and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid JWT token when one is supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user to verify was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error validating user, please contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7137",
                        "message": "Error validating user, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Verify User Password",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/auth/password/reset": {
      "post": {
        "description": "Resets the password of a user account using a previously issued OTP/recovery token. Authentication is optional thanks to the OTP-based verification flow. The request is delegated to the authentication service via NATS.",
        "operationId": "UsersController_recoveryPassword",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecoveryPasswordDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset completed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Password reset completed successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid recovery token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7117",
                        "message": "Invalid password, please check and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid JWT token when one is supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the RESET_PASSWORD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user to reset was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The new password cannot reuse a previous password.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7119",
                        "message": "You cannot reuse a previous password, please try with a new one."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating user password, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7164",
                        "message": "Error updating user password, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Reset User Password",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/{cardId}/activate": {
      "post": {
        "description": "Activates a card linked to the given user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_activate",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Identifier of the card to activate.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the card.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card activated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "card": {
                        "cardId": 12345,
                        "suffix": "1234",
                        "alias": "My virtual card",
                        "balance": "0.00",
                        "status": "Active",
                        "createdAt": "2026-01-01T00:00:00.000Z",
                        "linkedAuthUserId": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CARD_ACTIVATION application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to activate was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already activated.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7202",
                        "message": "Card is already activated."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating card information.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate Card",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/{cardId}/block": {
      "post": {
        "description": "Blocks an active card linked to the given user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_block",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Identifier of the card to block.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the card.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card blocked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The card has been updated status successfully",
                    "data": {
                      "card": {
                        "cardId": 12345,
                        "suffix": "1234",
                        "alias": "My virtual card",
                        "balance": "5000.00",
                        "status": "BLOCK",
                        "createdAt": "2026-01-01T00:00:00.000Z",
                        "linkedAuthUserId": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_STATUS application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to block was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7203",
                        "message": "Card is already blocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating card information.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Block Card",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/{cardId}/unblock": {
      "post": {
        "description": "Unblocks a previously blocked card linked to the given user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_unblock",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Identifier of the card to unblock.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the card.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card unblocked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The card has been updated status successfully",
                    "data": {
                      "card": {
                        "cardId": 12345,
                        "suffix": "1234",
                        "alias": "My virtual card",
                        "balance": "5000.00",
                        "status": "UNBLOCK",
                        "createdAt": "2026-01-01T00:00:00.000Z",
                        "linkedAuthUserId": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_STATUS application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to unblock was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already unlocked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7204",
                        "message": "Card is already unlocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating card information.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Unblock Card",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/linked-cards": {
      "post": {
        "description": "Associates a third-party card (owned by another user) with the given user account. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_assignThirdPartyCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that will receive the third-party card association.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignThirdPartyCardPayloadDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Third-party card assigned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Third party card created successfully",
                    "data": {
                      "id": 42,
                      "alias": "Shared card",
                      "cardId": 12345,
                      "linkedByUserId": 1,
                      "status": "linked",
                      "createdAt": "2026-01-01T00:00:00.000Z",
                      "updatedAt": "2026-01-01T00:00:00.000Z",
                      "unlinkedAt": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the assignment payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the ASSIGN_THIRD_PARTY_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The third-party card was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7220",
                        "message": "Third party card not found, please verify suffix, username or id and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The third-party card is already assigned.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7222",
                        "message": "Third party card already exist, please verify suffix, username and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating third party card, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7221",
                        "message": "Error creating third party card, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assign Third Party Card",
        "tags": [
          "Users"
        ]
      },
      "get": {
        "description": "Returns the list of third-party cards linked to the given user account. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_getLinkedCardsByAuthUserId",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the linked third-party cards.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Linked third-party cards returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Linked cards found successfully",
                    "data": {
                      "cards": [
                        {
                          "associationId": 42,
                          "cardId": 12345,
                          "suffix": "1234",
                          "alias": "Shared card",
                          "ownerId": 7,
                          "createdAt": "2026-01-01T00:00:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_THIRD_PARTY_CARDS_BY_AUTH_USER_ID application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No third-party cards were found for the given user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7220",
                        "message": "Third party card not found, please verify suffix, username or id and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List Linked Third Party Cards",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/linked-cards/{associationId}": {
      "patch": {
        "description": "Updates the alias of a third-party card association linked to the user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_updateAliasThirdPartyCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the third-party card association.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "associationId",
            "required": true,
            "in": "path",
            "description": "Identifier of the third-party card association to update.",
            "schema": {
              "example": 42,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateThirdPartyCardDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Third-party card alias updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Alias updated successfully"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the update payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_ALIAS_THIRD_PARTY_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The third-party card association was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7220",
                        "message": "Third party card not found, please verify suffix, username or id and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating third party card, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7227",
                        "message": "Error updating third party card, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Third Party Card Alias",
        "tags": [
          "Users"
        ]
      },
      "delete": {
        "description": "Logically removes a third-party card association from the given user account (soft-delete: it stops appearing in the list but is not physically deleted). The operation is idempotent: if the association was already removed, it responds successfully without duplicating effects. Only the owner of the association can remove it. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice.",
        "operationId": "UsersController_unlinkThirdPartyCard",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the third-party card association.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "associationId",
            "required": true,
            "in": "path",
            "description": "Identifier of the third-party card association to remove.",
            "schema": {
              "example": 42,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Third-party card unlinked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Third party card unassigned successfully"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UNLINK_THIRD_PARTY_CARD application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The third-party card association was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7220",
                        "message": "Third party card not found, please verify suffix, username or id and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error unlinked third party card, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7226",
                        "message": "Error unlinked third party card, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Unlink Third Party Card",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/cards/{cardId}/favorite": {
      "post": {
        "description": "Marks a card as favorite for the given user. The card must be visible to the user, either owned or linked as a third-party card. The operation is idempotent: marking an already favorite card succeeds without creating a duplicate. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_setCardFavorite",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that marks the card as favorite.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to mark as favorite.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card marked as favorite successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Card favorite created successfully"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the SET_CARD_FAVORITE permission or is acting on another user account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      },
                      {
                        "code": "7144",
                        "message": "Forbidden access for this user."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card does not exist or is not visible to the user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error persisting the card favorite.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7229",
                        "message": "Error creating the card favorite."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Set Card As Favorite",
        "tags": [
          "Users"
        ]
      },
      "delete": {
        "description": "Removes a card from the favorites of the given user. The operation is idempotent: removing a card that is not a favorite succeeds. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the cards microservice via NATS.",
        "operationId": "UsersController_unsetCardFavorite",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the favorite.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to remove from favorites.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card removed from favorites successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Card removed from favorites"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UNSET_CARD_FAVORITE permission or is acting on another user account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      },
                      {
                        "code": "7144",
                        "message": "Forbidden access for this user."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card does not exist or is not visible to the user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error removing the card favorite.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7230",
                        "message": "Error deleting the card favorite."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove Card From Favorites",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/fcm-tokens": {
      "post": {
        "description": "Registers a Firebase Cloud Messaging token for the authenticated user so push notifications can be delivered to their device. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_registerFcmToken",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Object containing the FCM token to register and, optionally, an alias to recognize the user in the backoffice test push (the email). The device comes from the X-Platform, X-OS-Version, X-App-Version and X-Device-Model headers.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "example": "fcm-example-token"
                  },
                  "alias": {
                    "type": "string",
                    "maxLength": 254,
                    "example": "kevin@migo.com"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "FCM token registered successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "token": "fcm-example-token",
                      "authUserId": 1,
                      "createdAt": "2026-01-01T00:00:00.000Z",
                      "updatedAt": "2026-01-01T00:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the FCM token payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the REGISTER_FCM_TOKEN application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error registering FCM token, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7160",
                        "message": "Error registering FCM token, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Register FCM Token",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/fcm-tokens/{token}": {
      "delete": {
        "description": "Removes a previously registered Firebase Cloud Messaging token from the authenticated user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the users microservice via NATS.",
        "operationId": "UsersController_removeFcmToken",
        "parameters": [
          {
            "name": "token",
            "required": true,
            "in": "path",
            "description": "FCM token to remove.",
            "schema": {
              "example": "fcm-example-token",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "FCM token removed successfully."
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the DELETE_FCM_TOKEN application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The FCM token was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7163",
                        "message": "FCM Token not found, please renew the device token"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error removing FCM token, please verify data and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7161",
                        "message": "Error removing FCM token, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove FCM Token",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/profile-image": {
      "put": {
        "description": "Uploads a profile image (PNG, JPEG or JPG, up to 5 MB) for the given user. Requires JWT, application permissions, user authentication and user permissions. The image is stored via the profile service.",
        "operationId": "UsersController_uploadProfileImage",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose profile image is being uploaded.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Profile image file uploaded as multipart/form-data under the field profileImage.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "profileImage": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Profile image uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "userId": 1,
                      "profileImageUrl": "https://ali-public-files.s3.amazonaws.com/docs/dev/users/1/profile-1735689600000.png"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid file type or file too large.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7167",
                        "message": "Error uploading profile image, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPLOAD_PROFILE_IMAGE application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user to upload the image for was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error uploading file, please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload Profile Image",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{authUserId}/id-document": {
      "post": {
        "description": "Uploads the front and back covers (PNG, JPEG or JPG, up to 5 MB each) of an identity document for the given user. The document is identified by its type (document_type name). Requires JWT, application permissions, user authentication and user permissions.",
        "operationId": "UsersController_uploadIdDocument",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Identifier (auth_user id) of the user uploading the document.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Identity document covers uploaded as multipart/form-data under the fields front and back, plus the document type.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "example": "DPI"
                  },
                  "front": {
                    "type": "string",
                    "format": "binary"
                  },
                  "back": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload Identity Document",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{authUserId}/id-document/from-verification": {
      "post": {
        "description": "Sets the front and back covers of the user identity document from the photos captured by an approved identity verification (verification SDK), instead of uploading them. The verification must belong to the same application, be approved, and its verified document number must match the user document. Requires JWT, application permissions, user authentication and user permissions; the session user must be the authUserId.",
        "operationId": "UsersController_attachIdDocumentFromVerification",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Identifier (auth_user id) of the user that owns the document.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "verificationId",
                  "type"
                ],
                "properties": {
                  "verificationId": {
                    "type": "string",
                    "format": "uuid",
                    "example": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21"
                  },
                  "type": {
                    "type": "string",
                    "example": "DPI"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Attach Identity Document From a Verification",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/profile": {
      "get": {
        "description": "Returns the public profile information of the given user. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the profile service via NATS.",
        "operationId": "UsersController_getUserProfile",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose profile will be returned.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User profile returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "User profile retrieved successfully",
                    "data": {
                      "user": {
                        "id": 1,
                        "firstName": "John",
                        "lastName": "Doe",
                        "documentNumber": "1234567890101",
                        "nationality": "GTM",
                        "gender": "M",
                        "birthdate": "1990-01-01T00:00:00.000Z",
                        "placeBirth": "GTM"
                      },
                      "profile": {
                        "imageUrl": "https://ali-public-files.s3.amazonaws.com/docs/dev/users/1/profile-1735689600000.png"
                      },
                      "userType": "user",
                      "createdAt": "2026-01-01T00:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_USER_PROFILE application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user profile was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error fetching profile data, please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7170",
                        "message": "Error fetching profile data, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get User Profile",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/owner-data": {
      "patch": {
        "description": "Updates the first name, last name, birthdate and marital status of the authenticated owner. All four fields are optional: only the ones sent are evaluated, and only the ones that actually change are written. The data lives in a single row, so one update covers the whole change. Only owners hold personal data: an admin or cashier account has no such record.",
        "operationId": "UsersController_updateOwnerData",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose personal data will be updated.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOwnerDataDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Owner data updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Owner data updated successfully",
                    "data": {
                      "authUserId": 1,
                      "userId": 50,
                      "previous": {
                        "firstName": "Claudia",
                        "lastName": "Ulin",
                        "birthdate": "1990-05-14T00:00:00.000Z",
                        "maritalStatus": "single"
                      },
                      "firstName": "Claudia",
                      "lastName": "Ulin Pérez",
                      "birthdate": "1990-05-14T00:00:00.000Z",
                      "maritalStatus": "married"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No editable field was provided, the birthdate or marital status could not be read, or the account holds no personal data.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      },
                      {
                        "code": "7127",
                        "message": "User is an account, access denied."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid user token, or the caller is updating another person.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7145",
                        "message": "Invalid user access token, check your token"
                      },
                      {
                        "code": "7602",
                        "message": "Unauthorized access, please check your credentials."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the owner data, please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7169",
                        "message": "Error updating user profile, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Owner Personal Data",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/personal-data": {
      "patch": {
        "description": "Server-to-server update, with the integrator credentials, of the personal data of one of its own users, identified by the `userId` returned by the user lookup. No user token is required: the user must belong to the application of the token, otherwise it is reported as not found. Every field is optional, only the ones sent are evaluated and only the ones that actually change are written. A field can be replaced but not cleared. Any field outside this contract (email, document number, ...) rejects the whole request. Personal data belongs to the person, so the change is visible to every application the person has an account with. The phone number is the OTP recovery channel: it requires `phoneVerification`, the proof that the integrator verified the new number with its own OTP in the last hour; it is refused when the person also has an account with another application, and the owner is notified by email. The phone number is never returned.",
        "operationId": "UsersController_updateUserByIntegrator",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user, as returned by the user lookup.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserByIntegratorDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "User data updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/UpdateUserByIntegratorResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "message": "User data updated successfully",
                    "data": {
                      "userId": 1,
                      "updatedFields": [
                        "address",
                        "neighborhood"
                      ],
                      "firstName": "Claudia",
                      "lastName": "Ulin Pérez",
                      "birthdate": "1990-05-14T00:00:00.000Z",
                      "maritalStatus": "married",
                      "gender": "F",
                      "address": "Calzada Roosevelt 22-43",
                      "neighborhood": "Zona 11",
                      "placeBirth": "Guatemala City"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No editable field was provided, a field is not allowed, empty or invalid, the birthdate is in the future, the phone number comes without a recent verification or is not valid for the country of the user, or the user is an account with no personal data.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      },
                      {
                        "code": "7127",
                        "message": "User is an account, access denied."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7602",
                        "message": "Unauthorized access, please check your credentials."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The application lacks the permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user does not exist or does not belong to the application of the token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The phone number cannot be changed: the user also has an account with another application.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7189",
                        "message": "The user also has an account with another merchant, this data cannot be changed by an integrator."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the user data, please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7169",
                        "message": "Error updating user profile, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update User Personal Data (integrator)",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/email": {
      "patch": {
        "description": "Updates the email address of the authenticated user. The email is the username of the account, so it is propagated to every auth_user record of the person and to the owner (user) or admin/cashier (account) record. All active sessions are revoked, so the user must log in again. The request is delegated to the users service via NATS.",
        "operationId": "UsersController_updateUserEmail",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose email will be updated.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserEmailDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Email updated successfully",
                    "data": {
                      "authUserId": 1,
                      "previousEmail": "old.address@example.com",
                      "email": "new.address@example.com",
                      "updatedAuthUsers": 2,
                      "revokedSessions": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error on the provided email.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7002",
                        "message": "Invalid data, please check and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the UPDATE_EMAIL permission or is updating another user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user to update was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7100",
                        "message": "User not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The email is already used by another user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7101",
                        "message": "User already exists in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the user email, please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7169",
                        "message": "Error updating user profile, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update User Email",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/businesses/{businessId}/branches/summary": {
      "get": {
        "description": "Returns an aggregated branches summary for a given business owned by the user in the requested date range. Requires JWT, application permissions, user authentication and user permissions. The request is delegated to the businesses service via NATS.",
        "operationId": "UsersController_getBranchesSummary",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user that owns the business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "businessId",
            "required": true,
            "in": "path",
            "description": "Identifier of the business whose branches summary will be returned.",
            "schema": {
              "example": 100,
              "type": "number"
            }
          },
          {
            "name": "startDate",
            "required": true,
            "in": "query",
            "description": "Start date of the period to summarize (ISO 8601).",
            "schema": {
              "example": "2026-01-01",
              "type": "string"
            }
          },
          {
            "name": "endDate",
            "required": true,
            "in": "query",
            "description": "End date of the period to summarize (ISO 8601).",
            "schema": {
              "example": "2026-01-31",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Branches summary returned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "branches": [
                        {
                          "id": 1,
                          "name": "Sucursal Norte",
                          "liquidated": 3500,
                          "consumed": 1200,
                          "cards": [
                            1,
                            2,
                            3
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid date range or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_BRANCHES_SUMMARY application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The business or branch was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Please contact support for assistance.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get Branches Summary By Business",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/banks": {
      "get": {
        "description": "Returns the bank accounts saved by the user. The user can only access their own bank accounts. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_findUserBanks",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank accounts retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": 1,
                        "authUserId": 1,
                        "accountNumber": "0123456789",
                        "accountType": "MONETARY",
                        "currency": "GTQ",
                        "holderName": "John Doe",
                        "alias": "My payroll account",
                        "bankCode": "001",
                        "bankName": "Banco Industrial",
                        "isFavorite": true
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot access these bank accounts.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List user bank accounts",
        "tags": [
          "Users"
        ]
      },
      "post": {
        "description": "Saves a new bank account for the user. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_createUserBank",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserBankDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bank account created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Bank account created successfully",
                    "data": {
                      "id": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the bank account payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot create bank accounts for this user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7312",
                        "message": "Error while creating the bank account."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a user bank account",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/banks/{bankId}": {
      "get": {
        "description": "Returns a single bank account owned by the user. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_findUserBankById",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "bankId",
            "required": true,
            "in": "path",
            "description": "Bank account identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank account retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 1,
                      "authUserId": 1,
                      "accountNumber": "0123456789",
                      "accountType": "MONETARY",
                      "currency": "GTQ",
                      "holderName": "John Doe",
                      "alias": "My payroll account",
                      "bankCode": "001",
                      "bankName": "Banco Industrial",
                      "isFavorite": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot access this bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The bank account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7314",
                        "message": "Bank account not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a user bank account",
        "tags": [
          "Users"
        ]
      },
      "delete": {
        "description": "Deletes a bank account owned by the user. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_deleteUserBank",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "bankId",
            "required": true,
            "in": "path",
            "description": "Bank account identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank account deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Bank account deleted successfully"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot delete this bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The bank account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7314",
                        "message": "Bank account not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error deleting the bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7316",
                        "message": "Error while deleting the bank account."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete a user bank account",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/bank-transfers/total": {
      "get": {
        "description": "Returns the count and summed amount of the user's bank transfers for the given day (defaults to today), across the statuses that count toward the daily limit. Delegated to op-transfers via NATS.",
        "operationId": "UsersController_getUserBankTransfersTotal",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "date",
            "required": false,
            "in": "query",
            "description": "Day to aggregate (YYYY-MM-DD). Defaults to today.",
            "schema": {
              "example": "2026-07-01",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Daily bank transfers total retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "count": 3,
                      "total": "500.00"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot access this user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the daily bank transfers total.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a user's bank transfers total for the day",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/banks/{bankId}/alias": {
      "patch": {
        "description": "Updates the alias of a bank account owned by the user. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_updateUserBankAlias",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "bankId",
            "required": true,
            "in": "path",
            "description": "Bank account identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserBankAliasDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank account alias updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Bank account updated successfully",
                    "data": {
                      "id": 1,
                      "alias": "My savings account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the alias payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot update this bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The bank account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7314",
                        "message": "Bank account not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7315",
                        "message": "Error while updating the bank account."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a user bank account alias",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{userId}/banks/{bankId}/favorite": {
      "patch": {
        "description": "Marks a bank account as favorite for the user, or unsets it when the body carries `favorite: false`. Multiple favorite accounts per user are allowed. Delegated to the users microservice via NATS.",
        "operationId": "UsersController_setUserBankFavorite",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "User identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "bankId",
            "required": true,
            "in": "path",
            "description": "Bank account identifier",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetUserBankFavoriteDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank account favorite state updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Bank account updated successfully",
                    "data": {
                      "id": 1,
                      "isFavorite": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot update this bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The bank account was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7314",
                        "message": "Bank account not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the bank account.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7315",
                        "message": "Error while updating the bank account."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Set or unset a user bank account as favorite",
        "tags": [
          "Users"
        ]
      }
    },
    "/users/{authUserId}/balance": {
      "post": {
        "description": "Creates the wallet of the given user. Idempotent: if the user already has one, it reports so without altering the balance.",
        "operationId": "AuthUsersController_createWallet",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose wallet will be created.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create User Wallet",
        "tags": [
          "Users - Cards"
        ]
      },
      "get": {
        "description": "Returns the wallet balance of the given user. The wallet is the settlement vehicle used by businesses that collect without an active card.",
        "operationId": "AuthUsersController_getBalance",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose wallet balance will be returned.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get User Wallet Balance",
        "tags": [
          "Users - Cards"
        ]
      }
    },
    "/users/{authUserId}/balance/movements": {
      "get": {
        "description": "Returns the movement history of the user wallet, ordered from newest to oldest. These movements are the wallet ledger and are independent from the card movements, which are served by the cards history endpoints.",
        "operationId": "AuthUsersController_getWalletMovements",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Identifier of the user whose wallet movements are returned.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "description": "Number of movements to skip, for pagination.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "Maximum number of movements to return (1-100, defaults to 20).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "endDate",
            "required": false,
            "in": "query",
            "description": "Upper bound of the date range, in ISO format.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "startDate",
            "required": false,
            "in": "query",
            "description": "Lower bound of the date range, in ISO format.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The user has no wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get User Wallet Movements",
        "tags": [
          "Users - Cards"
        ]
      }
    },
    "/businesses": {
      "post": {
        "description": "Creates a new business (commerce) from an existing lead. Forwards the request to the businesses microservice. Requires authentication and the CREATE_BUSINESS permission.",
        "operationId": "BusinessesController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBussinessFromLeadDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Business created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Businesses created",
                    "data": {
                      "businesses": [
                        {
                          "commerceId": 1,
                          "legalName": "MIGO PAYMENTS S.A.",
                          "nit": "1234567-8"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Lead not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7130",
                        "message": "Lead not found, please check your lead information and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Business already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7414",
                        "message": "Business already exists, verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create business from lead",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/{commerceId}/branches": {
      "post": {
        "description": "Creates one or more branches under a given commerce/business. The payload contains a list of branches without commerce reference; the commerce id is taken from the URL.",
        "operationId": "BusinessesController_createBranch",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce/business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "example": {
                  "branches": [
                    {
                      "name": "Main Store",
                      "address": "5a Avenida 1-23 Zona 10",
                      "phone1": "50212345678",
                      "clientId": "CLIENT-001",
                      "partner": "migo"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Branches created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Branches created successfully",
                    "data": {
                      "branches": [
                        {
                          "branchId": 10,
                          "name": "Main Store",
                          "commerceId": 1
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Branch already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7415",
                        "message": "Branch already exists, verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create branches for a business",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/commerces/{commerceId}/keys": {
      "post": {
        "description": "Stores integration keys for the specified commerce/business. The keys are provided as a key-value map in the request body and the commerce id is taken from the URL.",
        "operationId": "BusinessesController_saveCommerceKeys",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce/business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Key-value map of integration keys to merge for the commerce.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "example": {
                  "MIGO_LINK": {
                    "apiKey": "ak_live_xxx",
                    "secret": "sk_live_xxx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Commerce keys saved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Commerce keys saved successfully",
                    "data": {
                      "id": 5,
                      "commerceId": 1,
                      "keys": {
                        "MIGO_LINK": {
                          "apiKey": "ak_live_xxx",
                          "secret": "sk_live_xxx"
                        }
                      },
                      "isActive": true,
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Save commerce keys",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/users/{authUserId}/terminals": {
      "post": {
        "description": "Creates a terminal device for a given authentication user and branch. Optionally notifies Zendesk about the new terminal. Requires the CREATE_TERMINAL_ACCOUNT permission.",
        "operationId": "BusinessesController_createTerminalForAuthUserId",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Authentication user identifier.",
            "schema": {
              "example": "auth-user-abc123",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deviceId",
                  "branchId"
                ],
                "properties": {
                  "deviceId": {
                    "type": "string",
                    "example": "device-abc123"
                  },
                  "branchId": {
                    "type": "number",
                    "example": 10
                  },
                  "notifyZendesk": {
                    "type": "boolean",
                    "example": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Terminal created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal created successfully",
                    "data": {
                      "id": 25,
                      "deviceId": "device-abc123",
                      "terminalType": "TapOnPhone",
                      "isActive": false,
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z",
                      "branchAuthUserId": 12,
                      "externalId": null,
                      "isDeleted": false,
                      "additionalData": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Branch auth user not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7416",
                        "message": "AuthUserId provided dont exists in branch auth user, please verify information."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Terminal already linked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7413",
                        "message": "Terminal already linked, please get a new terminal."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create terminal for auth user",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/users/{authUserId}/terminals/{deviceId}": {
      "get": {
        "description": "Retrieves the terminal information for a specific authentication user and device identifier. Returns the terminal profile if it exists for the given user.",
        "operationId": "BusinessesController_getTerminalByBranchUserId",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Authentication user identifier.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Terminal retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal found.",
                    "data": {
                      "id": 25,
                      "deviceId": "device-abc123",
                      "terminalType": "TapOnPhone",
                      "isActive": true,
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z",
                      "branchAuthUserId": 12,
                      "externalId": null,
                      "isDeleted": false,
                      "additionalData": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get terminal by auth user",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{deviceId}": {
      "delete": {
        "description": "Deletes the terminal identified by the given device id. Requires UPDATE_TERMINAL permission.",
        "operationId": "BusinessesController_deleteTerminal",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Terminal deleted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal deleted successfully"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete terminal",
        "tags": [
          "Businesses"
        ]
      },
      "patch": {
        "description": "Updates the configuration of a terminal identified by device id. Allows changing device id, external terminal id, active state, and terminal type. Requires UPDATE_TERMINAL permission.",
        "operationId": "BusinessesController_updateTerminal",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTerminalDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Terminal updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal updated successfully",
                    "data": {
                      "id": 25,
                      "deviceId": "device-abc123",
                      "terminalType": "TapOnPhone",
                      "isActive": true,
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z",
                      "branchAuthUserId": 12,
                      "externalId": "EXT-TERM-987654",
                      "isDeleted": false,
                      "additionalData": null,
                      "inUse": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update terminal",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{terminalId}/settlement-config": {
      "get": {
        "description": "Returns the settlement vehicle a terminal is currently configured to settle into.",
        "operationId": "BusinessesController_getTerminalSettlementConfig",
        "parameters": [
          {
            "name": "terminalId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get terminal settlement vehicle",
        "tags": [
          "Businesses"
        ]
      },
      "put": {
        "description": "Switches the settlement vehicle of a terminal. accountId is required for card and wallet; omitted for external.",
        "operationId": "BusinessesController_updateTerminalSettlementConfig",
        "parameters": [
          {
            "name": "terminalId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSettlementConfigDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update terminal settlement vehicle",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{deviceId}/accounts": {
      "post": {
        "description": "Associates a cash account with the specified terminal. Receives the cash account identifier and account type in the request body. Requires CREATE_TERMINAL_ACCOUNT permission.",
        "operationId": "BusinessesController_createTerminalAccount",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "accountType"
                ],
                "properties": {
                  "cashAccountId": {
                    "type": "number",
                    "example": 100,
                    "description": "Required for the card and wallet vehicles. Omitted for external, where a third party owns the account."
                  },
                  "accountType": {
                    "type": "string",
                    "enum": [
                      "card",
                      "wallet",
                      "external"
                    ],
                    "example": "card"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Terminal account created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Asociation account in terminal successfully",
                    "data": {
                      "id": 50,
                      "terminalId": 25,
                      "accountId": 100,
                      "accountType": "card",
                      "isActive": true,
                      "startDate": "2026-06-15T12:00:00.000Z",
                      "endDate": null,
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Terminal already linked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7413",
                        "message": "Terminal already linked, please get a new terminal."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create terminal cash account",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{deviceId}/processors": {
      "post": {
        "description": "Associates a payment processor (identified by slug) with the specified terminal. The processor must already exist in the catalog. Requires CREATE_TERMINAL_PROCESSOR permission.",
        "operationId": "BusinessesController_createTerminalProcessor",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slug"
                ],
                "properties": {
                  "slug": {
                    "type": "string",
                    "example": "volcan"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Terminal processor created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal processor created successfully",
                    "data": {
                      "terminalProcessorId": 7
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal or processor not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      },
                      {
                        "code": "7005",
                        "message": "Payment processor not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Terminal processor already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7015",
                        "message": "Terminal processor already exists"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create terminal processor",
        "tags": [
          "Businesses"
        ]
      },
      "get": {
        "description": "Returns the list of payment processors associated with the specified terminal. Requires GET_TERMINAL_PROCESSORS permission.",
        "operationId": "BusinessesController_findTerminalProcessorsByDeviceId",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Terminal processors retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal processors found successfully",
                    "data": {
                      "terminalId": 25,
                      "deviceId": "device-abc123",
                      "externalTerminalId": "EXT-TERM-987654",
                      "processors": [
                        {
                          "id": 7,
                          "processorId": 3,
                          "isActive": true,
                          "name": "Volcan",
                          "slug": "volcan"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List terminal processors",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/branches/{branchId}/commerce-data": {
      "patch": {
        "description": "Updates the commercial name of the branch, and the legal name and NIT of its commerce. The three fields are optional: only the ones sent are evaluated, and only the ones that actually change are written. The branch name and the commerce are updated in a single transaction. When the request identifies a person, that person must own the branch; a support call identifies no person and is authorised by the application permission alone. The requesting user is always taken from the authenticated context, never from the body.",
        "operationId": "BusinessesController_updateCommerceData",
        "parameters": [
          {
            "name": "branchId",
            "required": true,
            "in": "path",
            "description": "Identifier of the branch whose commerce data will be updated.",
            "schema": {
              "example": 12,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCommerceDataDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Commerce data updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Commerce data updated successfully",
                    "data": {
                      "branchId": 12,
                      "previous": {
                        "branchName": "Sucursal Centro",
                        "legalName": "TIENDA DEMO",
                        "nit": "1234567-8"
                      },
                      "branchName": "Sucursal Zona 10",
                      "legalName": "TIENDA DEMO, SOCIEDAD ANONIMA",
                      "nit": "9876543-2"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No editable field was provided or a field is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The branch or its commerce was not found. A person who does not own the branch gets the same answer, so the response never reveals whether a branch id exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7410",
                        "message": "Branch not found"
                      },
                      {
                        "code": "7408",
                        "message": "Business not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The branch name is already used at the same address, or the NIT belongs to another commerce.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7415",
                        "message": "Branch already exists"
                      },
                      {
                        "code": "7414",
                        "message": "Business already exists"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update commerce data of a branch",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/commerces/{commerceId}/regime": {
      "patch": {
        "description": "Changes the tax regime of a commerce and synchronizes its commissions in the same operation: it updates the regime in PostgreSQL and rewrites the variables and calculations of every processor with the configuration of the new regime. If the new regime has no commissions configuration for the card processor, the change is rejected and nothing is modified. Requires UPDATE_COMMERCE_REGIME permission.",
        "operationId": "BusinessesController_updateCommerceRegime",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce whose regime will be changed.",
            "schema": {
              "example": 273,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCommerceRegimeDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Commerce regime updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Commerce regime updated successfully"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Commerce, regime or commerce configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found"
                      },
                      {
                        "code": "7504",
                        "message": "Regime not found"
                      },
                      {
                        "code": "7508",
                        "message": "Config not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The new regime has no commissions configuration for the card processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7503",
                        "message": "Regime not valid"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update commerce regime",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{deviceId}/processors/{slug}": {
      "patch": {
        "description": "Activates or deactivates a payment processor associated with a terminal. The active state is provided in the request body. Requires UPDATE_TERMINAL_PROCESSOR permission.",
        "operationId": "BusinessesController_updateTerminalProcessor",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          },
          {
            "name": "slug",
            "required": true,
            "in": "path",
            "description": "Processor slug identifier.",
            "schema": {
              "example": "volcan",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "isActive"
                ],
                "properties": {
                  "isActive": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Terminal processor updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal processor updated successfully"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Terminal processor not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7013",
                        "message": "Terminal processor not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update terminal processor",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/terminals/{deviceId}/processors/{processorSlug}/acquirer": {
      "patch": {
        "description": "Assigns an acquirer to a specific payment processor on the given terminal. Requires JWT authentication and terminal processor update permissions.",
        "operationId": "BusinessesController_assignTerminalProcessorAcquirer",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier",
            "schema": {
              "example": "DEV001",
              "type": "string"
            }
          },
          {
            "name": "processorSlug",
            "required": true,
            "in": "path",
            "description": "Processor slug identifier",
            "schema": {
              "example": "processor-a",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Acquirer assigned successfully"
          },
          "400": {
            "description": "Invalid request parameters"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assign Acquirer to Terminal Processor",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/{commerceId}/files": {
      "post": {
        "description": "Uploads commerce supporting files (business photo and utility bill) via multipart/form-data. Each field accepts a maximum of one file. The commerce identifier is taken from the URL.",
        "operationId": "BusinessesController_uploadCommerceFiles",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce/business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadFilesDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Commerce files uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Files uploaded successfully",
                    "data": {
                      "business": 1,
                      "files": [
                        {
                          "type": "businessPhoto",
                          "url": "https://ali-public-files.s3.amazonaws.com/docs/dev/business/1/1718452800000-businessPhoto-0.png"
                        },
                        {
                          "type": "utilityBill",
                          "url": "https://ali-public-files.s3.amazonaws.com/docs/dev/business/1/1718452800000-utilityBill-0.jpg"
                        }
                      ],
                      "bucket": "ali-public-files"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid file — size limit exceeded, empty file or invalid type.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7628",
                        "message": "The file size exceeds the maximum allowed limit of 16 MB."
                      },
                      {
                        "code": "7630",
                        "message": "The file cannot be empty"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload commerce files",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/{commerceId}/socials": {
      "post": {
        "description": "Saves the social media URLs of a commerce (Facebook, Instagram, Twitter, LinkedIn, TikTok, website). All URLs are optional and can be partially updated.",
        "operationId": "BusinessesController_uploadSocials",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce/business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadSocialDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Social URLs uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Socials uploaded successfully",
                    "data": {
                      "business": 1,
                      "socials": [
                        {
                          "type": "urlFacebook",
                          "url": "https://facebook.com/migopayments"
                        },
                        {
                          "type": "urlInstagram",
                          "url": "https://instagram.com/migopayments"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or missing social media URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7621",
                        "message": "No social media links provided, please provide at least one social media link."
                      },
                      {
                        "code": "7622",
                        "message": "Invalid social media URL provided, please check the URL format."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload commerce social URLs",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/{commerceId}/docs": {
      "get": {
        "description": "Retrieves the documents associated with a commerce, including uploaded files and signed URLs for download. The commerce identifier is taken from the URL.",
        "operationId": "BusinessesController_getCommerceDocs",
        "parameters": [
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Identifier of the commerce/business.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Commerce documents retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Documents fetched successfully",
                    "data": {
                      "business": 1,
                      "docs": [
                        {
                          "id": 12,
                          "type": "businessPhoto",
                          "typeId": 2,
                          "isVerified": false,
                          "verifiedAt": null,
                          "url": "https://ali-public-files.s3.amazonaws.com/docs/dev/business/1/1718452800000-businessPhoto-0.png",
                          "createdAt": "2026-06-15T12:00:00.000Z",
                          "updatedAt": "2026-06-15T12:00:00.000Z"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get commerce documents",
        "tags": [
          "Businesses"
        ]
      }
    },
    "/businesses/commerces/{commerceId}/webhooks": {
      "post": {
        "description": "Registers an HTTPS URL that receives a signed POST for every approved or denied terminal payment of the commerce. The signing secret is returned only in this response.",
        "operationId": "CommerceWebhooksController_create",
        "parameters": [
          {
            "name": "x-user-token",
            "in": "header",
            "description": "Token of the commerce owner. ADMIN and SUPPORT applications may omit it.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Commerce whose terminal payments are notified.",
            "schema": {
              "example": 335,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCommerceWebhookRequestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook registered.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/CreatedCommerceWebhookResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "data": {
                      "id": "65f1c2a9e4b0a1b2c3d4e5f6",
                      "commerceId": 335,
                      "url": "https://erp.example.com/hooks/migo",
                      "events": [
                        "terminal.payment.approved"
                      ],
                      "enabled": true,
                      "headers": [
                        {
                          "name": "X-Api-Key",
                          "value": "****2345"
                        }
                      ],
                      "createdAt": "2026-10-01T15:04:05.000Z",
                      "updatedAt": "2026-10-01T15:04:05.000Z",
                      "secret": "whsec_<shown-only-once>"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid body, unsafe URL or invalid headers.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters."
                      },
                      {
                        "code": "7715",
                        "message": "The webhook URL must be a public HTTPS URL on port 443."
                      },
                      {
                        "code": "7716",
                        "message": "The webhook headers are invalid."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Limit reached or duplicated URL.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7714",
                        "message": "The commerce reached the maximum number of webhooks."
                      },
                      {
                        "code": "7717",
                        "message": "The commerce already has a webhook with this URL."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Register a terminal payment webhook",
        "tags": [
          "Commerce webhooks"
        ]
      },
      "get": {
        "description": "Newest first. Header values and URL query values are masked.",
        "operationId": "CommerceWebhooksController_list",
        "parameters": [
          {
            "name": "x-user-token",
            "in": "header",
            "description": "Token of the commerce owner. ADMIN and SUPPORT applications may omit it.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Commerce whose terminal payments are notified.",
            "schema": {
              "example": 335,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhooks of the commerce.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CommerceWebhookResponseDto"
                          }
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": "65f1c2a9e4b0a1b2c3d4e5f6",
                        "commerceId": 335,
                        "url": "https://erp.example.com/hooks/migo",
                        "events": [
                          "terminal.payment.approved"
                        ],
                        "enabled": true,
                        "headers": [
                          {
                            "name": "X-Api-Key",
                            "value": "****2345"
                          }
                        ],
                        "createdAt": "2026-10-01T15:04:05.000Z",
                        "updatedAt": "2026-10-01T15:04:05.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the webhooks of a commerce",
        "tags": [
          "Commerce webhooks"
        ]
      }
    },
    "/businesses/commerces/{commerceId}/webhooks/{webhookId}": {
      "get": {
        "operationId": "CommerceWebhooksController_get",
        "parameters": [
          {
            "name": "x-user-token",
            "in": "header",
            "description": "Token of the commerce owner. ADMIN and SUPPORT applications may omit it.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Commerce whose terminal payments are notified.",
            "schema": {
              "example": 335,
              "type": "number"
            }
          },
          {
            "name": "webhookId",
            "required": true,
            "in": "path",
            "description": "Webhook identifier.",
            "schema": {
              "example": "65f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/CommerceWebhookResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "data": {
                      "id": "65f1c2a9e4b0a1b2c3d4e5f6",
                      "commerceId": 335,
                      "url": "https://erp.example.com/hooks/migo",
                      "events": [
                        "terminal.payment.approved"
                      ],
                      "enabled": true,
                      "headers": [
                        {
                          "name": "X-Api-Key",
                          "value": "****2345"
                        }
                      ],
                      "createdAt": "2026-10-01T15:04:05.000Z",
                      "updatedAt": "2026-10-01T15:04:05.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business or webhook not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      },
                      {
                        "code": "7713",
                        "message": "Commerce webhook not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a webhook of a commerce",
        "tags": [
          "Commerce webhooks"
        ]
      },
      "patch": {
        "description": "Only the fields sent change. A new URL is validated again; `headers` replaces the whole list. The signing secret never changes.",
        "operationId": "CommerceWebhooksController_update",
        "parameters": [
          {
            "name": "x-user-token",
            "in": "header",
            "description": "Token of the commerce owner. ADMIN and SUPPORT applications may omit it.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Commerce whose terminal payments are notified.",
            "schema": {
              "example": 335,
              "type": "number"
            }
          },
          {
            "name": "webhookId",
            "required": true,
            "in": "path",
            "description": "Webhook identifier.",
            "schema": {
              "example": "65f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCommerceWebhookRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/CommerceWebhookResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "data": {
                      "id": "65f1c2a9e4b0a1b2c3d4e5f6",
                      "commerceId": 335,
                      "url": "https://erp.example.com/hooks/migo",
                      "events": [
                        "terminal.payment.approved"
                      ],
                      "enabled": false,
                      "headers": [
                        {
                          "name": "X-Api-Key",
                          "value": "****2345"
                        }
                      ],
                      "createdAt": "2026-10-01T15:04:05.000Z",
                      "updatedAt": "2026-10-01T15:04:05.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid body, unsafe URL or invalid headers.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters."
                      },
                      {
                        "code": "7715",
                        "message": "The webhook URL must be a public HTTPS URL on port 443."
                      },
                      {
                        "code": "7716",
                        "message": "The webhook headers are invalid."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business or webhook not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      },
                      {
                        "code": "7713",
                        "message": "Commerce webhook not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Duplicated URL.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7717",
                        "message": "The commerce already has a webhook with this URL."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update, pause or resume a webhook",
        "tags": [
          "Commerce webhooks"
        ]
      },
      "delete": {
        "description": "Pending deliveries of the webhook are dropped. Register it again to get a new secret.",
        "operationId": "CommerceWebhooksController_delete",
        "parameters": [
          {
            "name": "x-user-token",
            "in": "header",
            "description": "Token of the commerce owner. ADMIN and SUPPORT applications may omit it.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "commerceId",
            "required": true,
            "in": "path",
            "description": "Commerce whose terminal payments are notified.",
            "schema": {
              "example": 335,
              "type": "number"
            }
          },
          {
            "name": "webhookId",
            "required": true,
            "in": "path",
            "description": "Webhook identifier.",
            "schema": {
              "example": "65f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeletedCommerceWebhookResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true,
                    "data": {
                      "id": "65f1c2a9e4b0a1b2c3d4e5f6"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Business or webhook not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7408",
                        "message": "Business not found."
                      },
                      {
                        "code": "7713",
                        "message": "Commerce webhook not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete a webhook",
        "tags": [
          "Commerce webhooks"
        ]
      }
    },
    "/volcan/ActualizarDatosClienteOnbV2": {
      "post": {
        "description": "Links a card to an end customer by submitting their onboarding data. This endpoint proxies the request to the Volcan processor to associate cardholder personal, contact, and identification details with an existing card.",
        "operationId": "VolcanController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkCardUserDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card successfully linked to the customer in Volcan. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IdRequest": "REQ-2026-0001",
                    "ResponseCode": "0000",
                    "ResponseDescription": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the cardholder onboarding payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to link was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error linking the card in the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Link Card To Customer",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/ConsultarTarjetaV2": {
      "post": {
        "description": "Retrieves detailed information for a card such as status, balance, and holder data. This endpoint proxies the query to the Volcan processor using the card number or its access entry credentials.",
        "operationId": "VolcanController_checkCard",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckCardDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card information returned by the Volcan processor. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IdRequest": 100001,
                    "ResponseCode": "0000",
                    "ResponseDescription": "Aprobada",
                    "Card": 4512345678901234,
                    "ManufacturingType": "F",
                    "Account": 1234567890,
                    "CLABE": "000000000000000000",
                    "InernalAccount": "ACC-1234567890",
                    "ExpirationDate": "2028-12",
                    "Status": 1,
                    "DescripcionStatus": "Activa",
                    "Name": "John",
                    "FirstLastName": "Doe",
                    "CurrentBalance": [
                      {
                        "AccountId": "ACC-1234567890",
                        "AccountTypeKey": "1",
                        "AccountTypeDescription": "GTQ-Cuenta Autorización",
                        "Balance": "150.00"
                      }
                    ],
                    "CVV": "***",
                    "Balance": 150,
                    "HolderName": "JOHN DOE"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the card lookup payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested card was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card from the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Check Card Details",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/ActivarTarjeta": {
      "post": {
        "description": "Activates a previously issued card so it can be used for transactions. This endpoint proxies the activation request to the Volcan processor for the given card number.",
        "operationId": "VolcanController_cardActivation",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardActivationDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card successfully activated in Volcan. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IDSolicitud": 100001,
                    "Tarjeta": 4512345678901234,
                    "MedioAcceso": "ACC-12345",
                    "CodRespuesta": "0000",
                    "DescRespuesta": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the card activation payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to activate was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error activating the card in the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Activate Card",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/ConsultaTarjetaPorIdentificacion": {
      "post": {
        "description": "Lists the cards owned by a customer identified by their document number and type. This endpoint proxies the lookup to the Volcan processor and returns the matching cards for the holder.",
        "operationId": "VolcanController_getCards",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryByIdentificationDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of cards returned by the Volcan processor. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IDSolicitud": "100001",
                    "Tarjetas": [
                      {
                        "NumeroDocumentoCliente": "1234567890101",
                        "TipoMedioAcceso": "TARJETA",
                        "ClaveTipoDocumento": "DPI",
                        "NombreTarjetahabiente": "JOHN DOE",
                        "Cuenta": "ACC-1234567890",
                        "Disponible": "150.00",
                        "Flotante": "0.00",
                        "Consumido": "50.00",
                        "Tarjeta": 4512345678901234,
                        "TipoManufactura": "F",
                        "Estatus": 1,
                        "DescripcionEstatus": "Activa",
                        "FechaVencimiento": "2028-12",
                        "MotivoBloqueo": ""
                      }
                    ],
                    "CodRespuesta": "0000",
                    "DescRespuesta": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the identification lookup payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No cards were found for the provided identification.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7212",
                        "message": "The user does not have any cards."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the cards from the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Query Cards By Identification",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/BloquearTarjetaV2": {
      "post": {
        "description": "Blocks a card to prevent further transactions, optionally with a reason. This endpoint proxies the block operation to the Volcan processor and updates the card status accordingly.",
        "operationId": "VolcanController_blockCard",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlockOrUnlockCardDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card successfully blocked in Volcan. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IDSolicitud": 100001,
                    "Tarjeta": 4512345678901234,
                    "MedioAcceso": "ACC-12345",
                    "Saldo": 150,
                    "CodRespuesta": "0000",
                    "DescRespuesta": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the block card payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to block was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7203",
                        "message": "Card is already blocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error blocking the card in the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Block Card",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/DesbloquearTarjetaV2": {
      "post": {
        "description": "Unblocks a previously blocked card to allow transactions again. This endpoint proxies the unblock operation to the Volcan processor and updates the card status accordingly.",
        "operationId": "VolcanController_unlockCard",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BlockOrUnlockCardDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card successfully unblocked in Volcan. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IDSolicitud": 100001,
                    "Tarjeta": 4512345678901234,
                    "MedioAcceso": "ACC-12345",
                    "Saldo": 150,
                    "CodRespuesta": "0000",
                    "DescRespuesta": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the unblock card payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to unblock was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already unlocked.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7204",
                        "message": "Card is already unlocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error unblocking the card in the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Unblock Card",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/AsignarNip": {
      "post": {
        "description": "Assigns a new PIN (NIP) to a card so the holder can use it at ATMs and POS terminals. This endpoint proxies the request to the Volcan processor for secure PIN provisioning.",
        "operationId": "VolcanController_assignNIP",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignNIPDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PIN successfully assigned in Volcan. The response mirrors the raw Volcan processor payload (no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IDSolicitud": 100001,
                    "Tarjeta": 4512345678901234,
                    "MedioAcceso": "ACC-12345",
                    "CodRespuesta": "0000",
                    "DescRespuesta": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the assign PIN payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to assign the PIN to was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error assigning the PIN in the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Assign Card PIN",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/volcan/ConsultarMovimientosTarjetaV2": {
      "post": {
        "description": "Returns the transaction history (movements) for a card within an optional date range. This endpoint proxies the request to the Volcan processor and allows limiting the maximum number of movements returned.",
        "operationId": "VolcanController_getMovements",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetMovementsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card movements returned in the Volcan movement-history format (built by the gateway from the transfers microservice; no Migo envelope).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "IdRequest": null,
                    "Card": "4512345678901234",
                    "IBAN": "",
                    "Movements": [
                      {
                        "Observations": "Balance transfer",
                        "AmountMovement": "50.0000",
                        "CurrencyMovement": "GTQ",
                        "Authorization": "AUTH123456",
                        "Reference": "1001",
                        "DateMovement": "2026-05-21T10:15:00-06:00",
                        "ConceptMovement": "Transferencia recibida de tarjeta ****5678",
                        "TypeMovementChargeCredit": "Abono",
                        "MovementOriginAmount": "",
                        "CurrencyOriginMovement": "",
                        "TradeAffiliationNumber": "",
                        "TradeDescription": "",
                        "CountryTrade": "",
                        "DescriptionCountry": "",
                        "BalanceAfterMovement": "",
                        "KeyMovement": "MOV-0001",
                        "MCC": "6011",
                        "PostOperationStatus": "",
                        "PostOperationDescription": "",
                        "IdMovement": "IDMOV-0001"
                      }
                    ],
                    "ResponseCode": "0000",
                    "ResponseDescription": "Aprobada"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the card movements payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The card to query movements for was not found in Volcan.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card movements from the Volcan processor.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Get Card Movements",
        "tags": [
          "Volcan"
        ]
      }
    },
    "/configs/apps": {
      "get": {
        "description": "Retrieves the configuration stored in the database for the application identified by the `applicationId` header. The configuration includes feature toggles, branding, and integration metadata used by the mobile/web clients.",
        "operationId": "ConfigController_getAppConfig",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "header",
            "description": "Mobile or web application identifier (e.g. com.migo.ali).",
            "schema": {
              "type": "string",
              "example": "com.migo.ali"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Application configuration retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "merchant": "migo-demo",
                      "applicationId": "com.migo.ali",
                      "title": "Migo ALI",
                      "rules": {
                        "allowGuestCheckout": false,
                        "maxCards": 5,
                        "linkedCards": {
                          "crossPartnerEnabled": true,
                          "allowedDestinationStatuses": [
                            "Active"
                          ],
                          "allowedDestinationMerchants": [
                            "akisi",
                            "yayo"
                          ]
                        }
                      },
                      "colors": {
                        "primary": "#1A1A2E",
                        "secondary": "#16213E",
                        "accent": "#0F3460"
                      },
                      "svgs": [
                        {
                          "name": "logo",
                          "urlSvgs": [
                            "https://cdn.migo.com/svg/logo.svg"
                          ]
                        }
                      ],
                      "animations": [
                        {
                          "name": "splash",
                          "body": "{\"v\":\"5.7.4\",\"fr\":60}"
                        }
                      ],
                      "modules": [
                        "cards",
                        "transfers",
                        "settlements"
                      ],
                      "supportInfo": {
                        "email": "support@migopayments.com",
                        "phone": "+50223456789"
                      },
                      "additionalData": {
                        "linkedCards": {
                          "infoMessage": "Puedes agregar tarjetas emitidas por Migo de nuestros partners aliados.",
                          "partners": [
                            {
                              "merchant": "akisi",
                              "name": "Akisi",
                              "logoUrl": "https://cdn.migo.com/partners/akisi.svg"
                            },
                            {
                              "merchant": "yayo",
                              "name": "Yayo",
                              "logoUrl": "https://cdn.migo.com/partners/yayo.svg"
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No configuration exists for the provided applicationId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get application configuration",
        "tags": [
          "Configurations"
        ]
      },
      "post": {
        "description": "Creates a new application configuration document. The payload describes branding, supported features, processors, and other integration metadata that the client apps will consume at runtime.",
        "operationId": "ConfigController_createConfig",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppConfigDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Application configuration created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Config created successfully",
                    "data": {
                      "id": "665f1b2c4a3e2f001a2b3c4d",
                      "merchant": "migo-demo",
                      "applicationId": "com.migo.ali",
                      "title": "Migo ALI",
                      "logo": "https://cdn.migo.com/logo.png",
                      "colors": {
                        "primary": "#1A1A2E",
                        "secondary": "#16213E"
                      },
                      "rules": {
                        "allowGuestCheckout": false,
                        "maxCards": 5
                      },
                      "forms": [
                        {
                          "id": "665f1b2c4a3e2f001a2b3c4e",
                          "key": "onboarding-business",
                          "title": "Business onboarding",
                          "description": "Form to register a new business",
                          "permissions": [],
                          "fields": []
                        }
                      ],
                      "termsAndConditions": [],
                      "privacyPolicy": [],
                      "animations": [],
                      "svgs": [],
                      "modules": [
                        "cards",
                        "transfers"
                      ],
                      "callback": null,
                      "supportInfo": {
                        "email": "support@migopayments.com"
                      },
                      "additionalData": {},
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the application configuration payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the project configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7704",
                        "message": "Error creating project config, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create application configuration",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/configs/apps/{applicationId}": {
      "patch": {
        "description": "Partially updates the configuration document associated with the given `applicationId`. Only the fields provided in the body are replaced; all other fields remain unchanged.",
        "operationId": "ConfigController_updateConfig",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "description": "Mobile or web application identifier to update.",
            "schema": {
              "example": "com.migo.ali",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAppConfigDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application configuration updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Config updated successfully",
                    "data": {
                      "id": "665f1b2c4a3e2f001a2b3c4d",
                      "merchant": "migo-demo",
                      "applicationId": "com.migo.ali",
                      "title": "Migo ALI",
                      "logo": "https://cdn.migo.com/logo.png",
                      "colors": {
                        "primary": "#1A1A2E",
                        "secondary": "#16213E"
                      },
                      "rules": {
                        "allowGuestCheckout": false,
                        "maxCards": 5
                      },
                      "forms": [
                        {
                          "id": "665f1b2c4a3e2f001a2b3c4e",
                          "key": "onboarding-business",
                          "title": "Business onboarding",
                          "description": "Form to register a new business",
                          "permissions": [],
                          "fields": []
                        }
                      ],
                      "termsAndConditions": [],
                      "privacyPolicy": [],
                      "modules": [
                        "cards",
                        "transfers"
                      ],
                      "supportInfo": {
                        "email": "support@migopayments.com"
                      },
                      "additionalData": {},
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:30:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the application configuration payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No configuration exists for the provided applicationId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the project configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7703",
                        "message": "Error updating project config, please contact support."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update application configuration",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/configs/apps/forms": {
      "get": {
        "description": "Returns every form definition available in the configuration store, grouped by project. Used by the backoffice to render the catalog of dynamic forms managed in the platform.",
        "operationId": "ConfigController_getAllFormsByProject",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Forms list retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": "665f1b2c4a3e2f001a2b3c4e",
                        "key": "onboarding-business",
                        "title": "Business onboarding",
                        "description": "Form to register a new business"
                      },
                      {
                        "id": "665f1b2c4a3e2f001a2b3c4f",
                        "key": "kyc-individual",
                        "title": "Individual KYC",
                        "description": "Identity verification form for individuals"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List all forms grouped by project",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/configs/apps/forms/{formId}": {
      "get": {
        "description": "Retrieves a single dynamic form definition identified by `formId`. The response contains the form schema (fields, validations, layout) used by clients to render and submit the form.",
        "operationId": "ConfigController_getConfigForm",
        "parameters": [
          {
            "name": "formId",
            "required": true,
            "in": "path",
            "description": "Identifier of the form to retrieve.",
            "schema": {
              "example": "onboarding-business-v1",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Form configuration retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": "665f1b2c4a3e2f001a2b3c4e",
                      "key": "onboarding-business",
                      "title": "Business onboarding",
                      "description": "Form to register a new business",
                      "permissions": [],
                      "fields": [
                        {
                          "name": "businessName",
                          "type": "text",
                          "label": "Business name",
                          "required": true
                        },
                        {
                          "name": "taxId",
                          "type": "text",
                          "label": "Tax ID",
                          "required": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No form exists for the provided formId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7702",
                        "message": "Form details not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a configuration form by id",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/configs/apps/{applicationId}/legal": {
      "get": {
        "description": "Retrieves the legal information (terms of service, privacy policy, etc.) configured for the application in the requested language. Defaults to Spanish (`es`) when the `lang` query parameter is not provided.",
        "operationId": "ConfigController_getLegalInformation",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "description": "Mobile or web application identifier.",
            "schema": {
              "example": "com.migo.ali",
              "type": "string"
            }
          },
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "description": "Language code for the legal content. Supported values: `es`, `en`.",
            "schema": {
              "example": "es",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Legal information retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "termsAndConditions": {
                        "version": "1.0.0",
                        "updatedAt": "2026-06-15T12:00:00.000Z",
                        "title": "Terms and Conditions",
                        "body": "Full terms and conditions text..."
                      },
                      "privacyPolicy": {
                        "version": "1.0.0",
                        "updatedAt": "2026-06-15T12:00:00.000Z",
                        "title": "Privacy Policy",
                        "body": "Full privacy policy text..."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No legal information exists for the provided applicationId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get legal information for an application",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/general-config/types/{type}": {
      "get": {
        "description": "Retrieves a general_config document by its `type` (e.g. BANKS_GT) from ali-ms-tl-config. Returns the stored JSON `value` — used by clients to load reference catalogs such as the list of banks available for bank transfers.",
        "operationId": "GeneralConfigController_getGeneralConfig",
        "parameters": [
          {
            "name": "type",
            "required": true,
            "in": "path",
            "description": "General config type key.",
            "schema": {
              "example": "BANKS_GT",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "General configuration retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "value": {}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No general config exists for the provided type.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get general configuration by type",
        "tags": [
          "Configurations"
        ]
      }
    },
    "/files": {
      "post": {
        "description": "Generates a file (e.g. PDF or image) by rendering the provided template with the supplied data and dimensions. Delegates the rendering to the reports microservice and returns the generated file metadata.",
        "operationId": "FilesController_generate",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateFileDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "File generated. The response is the raw reply from the `generate.file` NATS handler passed through unchanged by the gateway (no wrapping/transform). The only confirmed top-level field is `file`, a base64-encoded string of the rendered file (consumers read it via `Buffer.from(response.file, \"base64\")`). `success: true` is required for the gateway interceptor to forward the reply.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "file": "JVBERi0xLjQKJ...base64-encoded-file-content...=="
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the template, data or dimensions are missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the file could not be generated by the reports microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Generate file from template",
        "tags": [
          "Files"
        ]
      }
    },
    "/reports/payfac/conciliation/upload/{affiliation}": {
      "post": {
        "description": "Receives the daily detail and liquidation files produced by the Payfac partner for a given affiliation and forwards them to the reports service for reconciliation. Files must be provided as multipart fields named `detail` and `liquidation`.",
        "operationId": "ReportsController_payfacConciliation",
        "parameters": [
          {
            "name": "affiliation",
            "required": true,
            "in": "path",
            "description": "Affiliation identifier the conciliation files belong to.",
            "schema": {
              "example": "AFF-001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Multipart payload containing the detail and liquidation files.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "detail": {
                    "type": "string",
                    "format": "binary"
                  },
                  "liquidation": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "detail",
                  "liquidation"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conciliation files uploaded and queued for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Conciliation files received successfully.",
                    "data": {
                      "affiliation": "AFF-001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the detail or liquidation file is missing, empty or of an invalid type.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7629",
                        "message": "Invalid file type. Only Excel files (.xlsx, .xls) are allowed."
                      },
                      {
                        "code": "7630",
                        "message": "The file cannot be empty"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the conciliation files could not be processed by the reports microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file, please try again later."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Upload Payfac conciliation files",
        "tags": [
          "Reports"
        ]
      }
    },
    "/reports/generic/conciliations": {
      "post": {
        "description": "\nGenera un reporte PDF para uno o más usuarios en un rango de fechas y lo envía por correo electrónico.\n\n**Flujo:**\n1. Valida la zona horaria y convierte `startDate`/`endDate` a UTC.\n2. Por cada `userId`, obtiene terminales activas y transferencias en el rango.\n3. Construye el template (consolidado o por terminal según `consolidated`).\n4. Genera el PDF con el template HTML de S3 y lo sube.\n5. Envía el correo a todos los `emails` indicados.\n\n**Archivo en S3:** `{fileName}-{sucursal}-{timestamp}-{uuid}.pdf`\n\n> Este endpoint actúa como proxy hacia el servicio **ali-ms-tl-reports** vía `TL_REPORTS_URL`.\n      ",
        "operationId": "ReportsController_generateManualReport",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualReportDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reporte generado y enviado exitosamente\n\nError controlado (sin transacciones, zona horaria inválida, etc.)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManualReportErrorResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validación fallida — campo requerido faltante o inválido",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error interno al comunicarse con ali-ms-tl-reports",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Generar y enviar reporte manual de transacciones",
        "tags": [
          "Reports"
        ]
      }
    },
    "/leads": {
      "post": {
        "description": "Creates a new lead in the platform. Normalizes nationality, country of birth, and country to ISO alpha-3 before delegating to the leads microservice. Without a verificationId header it is the original flow: the optional x-merchant-id header associates the lead with a merchant. With a verificationId header the lead belongs to the self-service onboarding: the verification opened by POST /rest/onboarding/ocr must be approved, the identity fields must match the verified document unless the merchant allows editing them, the merchant and client come from the token, and the body must also carry consentVersion and consentAcceptedAt. Idempotency-Key is then required.",
        "operationId": "LeadsController_createLead",
        "parameters": [
          {
            "name": "x-merchant-id",
            "required": false,
            "in": "header",
            "description": "Optional merchant identifier the lead is associated with. Ignored when verificationId is present: the merchant comes from the token.",
            "schema": {
              "type": "string",
              "example": "merchant-abc123"
            }
          },
          {
            "name": "verificationid",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "idempotency-key",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Required with verificationId (max 255 characters). Retrying with the same key replays the original result.",
            "required": false,
            "schema": {
              "type": "string",
              "example": "onboarding-lead-001"
            }
          },
          {
            "name": "verificationId",
            "in": "header",
            "description": "Identity verification returned by POST /rest/onboarding/ocr. Its presence switches the request to the self-service onboarding flow.",
            "required": false,
            "schema": {
              "type": "string",
              "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLeadDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lead created successfully",
                    "data": {
                      "invitationCode": "INV-123456",
                      "businessId": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error in the lead payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to create leads.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "A lead is already registered for this invitation code.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7121",
                        "message": "Lead already registered, please get a new invitation code."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the lead.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7105",
                        "message": "Error creating lead."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create lead",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/files/upload/{fileName}": {
      "post": {
        "description": "Reads the contents of a lead-related file previously uploaded to storage. The file name is provided as path parameter. Requires FILE_UPLOAD permission.",
        "operationId": "LeadsController_readUserFile",
        "parameters": [
          {
            "name": "fileName",
            "required": true,
            "in": "path",
            "description": "Name of the file stored for the lead.",
            "schema": {
              "example": "identification.pdf",
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Lead file read successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "File processed successfully",
                    "data": null
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the FILE_UPLOAD permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested lead file was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7130",
                        "message": "Lead not found, please check your lead information and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error reading the lead file.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7104",
                        "message": "Error reading user file."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Read lead file",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/{id}": {
      "patch": {
        "description": "Updates allowed fields of a lead: firstName, lastName, phone, businessName, address. Any other field will be rejected.",
        "operationId": "LeadsController_updateLead",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Lead identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLeadDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lead updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lead updated successfully"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or a disallowed field was provided.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No lead exists for the provided id.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7130",
                        "message": "Lead not found, please check your lead information and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update lead",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/{code}/invitation": {
      "get": {
        "description": "Returns the invitation of a lead: registered email, masked invitation code, last delivery result and the paginated audit trail. The full invitation code is never exposed. Requires the getInvitation permission.",
        "operationId": "LeadsController_getInvitationDetail",
        "parameters": [
          {
            "name": "code",
            "required": true,
            "in": "path",
            "description": "Invitation code that identifies the lead. A code replaced by a previous update is still accepted.",
            "schema": {
              "example": "A1B2C3D",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "example": 20,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invitation detail retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "summary": {
                        "leadId": "507f1f77bcf86cd799439011",
                        "email": "nuevo.correo@example.com",
                        "maskedInvitationCode": "****9C1",
                        "registered": false,
                        "editable": true,
                        "invitationCodeUpdatedAt": "2026-08-03T10:00:00.000Z",
                        "lastSendResult": "SUCCESS",
                        "lastSentAt": "2026-08-03T10:00:01.000Z",
                        "sendAttempts": 2,
                        "canRetry": true
                      },
                      "audit": {
                        "records": [],
                        "pagination": {
                          "page": 1,
                          "limit": 20,
                          "total": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The application lacks the getInvitation permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No invitation exists for the provided code.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7120",
                        "message": "Invitation code not found, please check your code and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get invitation detail (internal support)",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/{code}/invitation/email": {
      "patch": {
        "description": "Replaces the email of a pending invitation, invalidates the previous invitation code, generates a new one and sends it immediately. Only invitations that are not registered yet can be updated. Requires the updateInvitationEmail permission.",
        "operationId": "LeadsController_updateInvitationEmail",
        "parameters": [
          {
            "name": "code",
            "required": true,
            "in": "path",
            "description": "Invitation code currently in force for the lead. It is replaced by a new one when the update succeeds, and a code already replaced is no longer accepted here.",
            "schema": {
              "example": "A1B2C3D",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateInvitationEmailDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invitation email updated. The delivery result is included.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Invitation email updated successfully",
                    "data": {
                      "leadId": "507f1f77bcf86cd799439011",
                      "email": "nuevo.correo@example.com",
                      "maskedInvitationCode": "****9C1",
                      "updateResult": "SUCCESS",
                      "sendResult": "SUCCESS",
                      "canRetry": false
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or the confirmation does not match.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The application lacks the updateInvitationEmail permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No invitation exists for the provided code.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7120",
                        "message": "Invitation code not found, please check your code and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The invitation cannot be updated or the email is already in use.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7121",
                        "message": "Lead already registered, please get a new invitation code."
                      },
                      {
                        "code": "7176",
                        "message": "The email address is already in use, please use another one."
                      },
                      {
                        "code": "7177",
                        "message": "The email address is the same as the current one."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update invitation email (internal support)",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/{code}/invitation/resend": {
      "post": {
        "description": "Sends the current invitation code again to the registered email, without changing it. Can be retried immediately after a failed delivery. Requires the resendInvitationCode permission.",
        "operationId": "LeadsController_resendInvitationCode",
        "parameters": [
          {
            "name": "code",
            "required": true,
            "in": "path",
            "description": "Invitation code that identifies the lead. A code replaced by a previous update is still accepted.",
            "schema": {
              "example": "A1B2C3D",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResendInvitationCodeDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invitation code resent. The delivery result is included.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Invitation code resent",
                    "data": {
                      "leadId": "507f1f77bcf86cd799439011",
                      "email": "nuevo.correo@example.com",
                      "sendResult": "SUCCESS",
                      "canRetry": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The application lacks the resendInvitationCode permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No invitation exists for the provided code.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7120",
                        "message": "Invitation code not found, please check your code and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The invitation cannot be resent.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7121",
                        "message": "Lead already registered, please get a new invitation code."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Resend invitation code (internal support)",
        "tags": [
          "Leads"
        ]
      }
    },
    "/leads/{code}": {
      "get": {
        "description": "Retrieves a lead by its invitation code. Used during onboarding flows to resolve the lead linked to a public invitation. Requires GET_BY_INVITATION_CODE permission.",
        "operationId": "LeadsController_getByIntivationCode",
        "parameters": [
          {
            "name": "code",
            "required": true,
            "in": "path",
            "description": "Invitation code that identifies the lead.",
            "schema": {
              "example": "INV-ABC123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "_id": "507f1f77bcf86cd799439011",
                      "invitationCode": "INV-ABC123",
                      "firstName": "John",
                      "lastName": "Doe",
                      "nationality": "GTM",
                      "gender": "MALE",
                      "dateOfBirth": "1990-01-15",
                      "countryOfBirth": "GTM",
                      "placeOfBirth": "Guatemala City",
                      "neighborhood": "Zona 10",
                      "maritalStatus": "SOLTERO",
                      "cui": "1234567890101",
                      "expirationDate": "2030-12-31",
                      "createdAt": "2026-01-15T10:00:00.000Z",
                      "commercialName": "Tienda Migo",
                      "businessName": "Comercial Guatemala S.A.",
                      "phone": "+50212345678",
                      "address": "5a Avenida 12-34, Zona 1, Guatemala City",
                      "taxRegime": "GENERAL",
                      "canInvoice": true,
                      "hasRegime": true,
                      "partner": "MIGO",
                      "nit": "1234567-8",
                      "clientId": "app-001",
                      "country": "GTM",
                      "sdk": "",
                      "paymentMethods": [
                        "card",
                        "cash"
                      ],
                      "payoutAccountNumber": "1234567890"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the GET_BY_INVITATION_CODE permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No lead exists for the provided invitation code.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7120",
                        "message": "Invitation code not found, please check your code and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get lead by invitation code",
        "tags": [
          "Leads"
        ]
      }
    },
    "/branches/{branchId}/codes": {
      "post": {
        "description": "Creates a new invitation code for the specified branch. The code carries a type and a role used during redemption. Requires JWT authentication.",
        "operationId": "BranchController_createBranch",
        "parameters": [
          {
            "name": "branchId",
            "required": true,
            "in": "path",
            "description": "Identifier of the branch.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewCodeDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Branch invitation code created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Branch invitation code created successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the invitation code payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced branch was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7410",
                        "message": "Branch not found"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The invitation code could not be created.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7110",
                        "message": "An error occurred while creating the invitation code, check the branch status"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create branch invitation code",
        "tags": [
          "Branches"
        ]
      }
    },
    "/card-transfers/types": {
      "post": {
        "description": "Registers a new transfer type definition used to classify card transfers. Requires JWT authentication and application permissions. The created entity is returned in the response payload.",
        "operationId": "TransfersController_createTransferType",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTransferTypeDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Transfer type created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Transfer type created successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the transfer type payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the create transfer type permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The transfer type could not be created.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7305",
                        "message": "Error creating transfer type."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Transfer Type",
        "tags": [
          "Card Transfers"
        ]
      }
    },
    "/card-transfers/{id}": {
      "get": {
        "description": "Retrieves the details of a single card transfer by its internal identifier, including the last four digits and the brand of the sender and receiver cards. Card fields are null when the card cannot be resolved. Requires JWT authentication and application permissions.",
        "operationId": "TransfersController_findOneCardTransfer",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card transfer.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card transfer retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Transfer found successfully.",
                    "data": {
                      "id": 12345,
                      "type": "credit",
                      "authCode": "A1B2C3",
                      "origin": "topUp",
                      "reference": "REF-987654",
                      "amount": "150.0000",
                      "currency": "GTQ",
                      "status": "approved",
                      "concept": "Top up balance",
                      "description": null,
                      "transfer_type": {
                        "name": "topUp",
                        "type": "topUp",
                        "channel": "webService",
                        "movementType": "credit",
                        "model": "settlement",
                        "createdAt": "2026-06-15T10:00:00.000Z",
                        "updatedAt": "2026-06-15T10:00:00.000Z"
                      },
                      "senderCardId": 5001,
                      "senderCardSuffix": "1234",
                      "senderCardBrand": "mastercard",
                      "receiverCardId": 5002,
                      "receiverCardSuffix": "5678",
                      "receiverCardBrand": "mastercard",
                      "createdAt": "2026-06-15T10:00:00.000Z",
                      "updatedAt": "2026-06-15T10:05:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the transfer id is not a valid number.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the transfer details permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested card transfer was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7306",
                        "message": "Card transfer not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get Card Transfer Details",
        "tags": [
          "Card Transfers"
        ]
      }
    },
    "/terminal-payment": {
      "post": {
        "description": "Creates a terminal payment for the authenticated merchant by forwarding the request, with the trusted application context, to the orchestrator microservice. Requires a valid JWT and the createTerminalPayment permission; proxies the payload via HTTP. Returns the orchestrator response.",
        "operationId": "TerminalPaymentController_createTerminalPayment",
        "parameters": [
          {
            "name": "applicationid",
            "required": false,
            "in": "header",
            "description": "Optional application identifier bound to the authenticated merchant. Legacy clients may omit it; the configuration service then resolves the application from the authenticated merchant.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTerminalPaymentInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Terminal payment created successfully by the orchestrator.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "terminal payment created successfully.",
                    "data": {
                      "id": 1,
                      "terminalId": 42,
                      "externalId": "",
                      "operationId": "OP-2025-00123",
                      "subtotal": 150.5,
                      "totalAmount": 0,
                      "status": "created",
                      "currency": "GTQ",
                      "paymentMethodType": "card",
                      "additionalData": {
                        "invoiceNumber": "INV-001"
                      },
                      "createdAt": "2026-06-15T12:00:00.000Z",
                      "updatedAt": "2026-06-15T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the terminal payment payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      },
                      {
                        "code": "7329",
                        "message": "La ubicación es obligatoria para crear el cobro."
                      },
                      {
                        "code": "7330",
                        "message": "Las coordenadas recibidas están fuera de rango."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The terminal payment could not be created.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7307",
                        "message": "Error creating terminal payment."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Create Terminal Payment",
        "tags": [
          "Terminal Payments"
        ]
      }
    },
    "/terminal-payment/{id}": {
      "patch": {
        "description": "Updates an existing terminal payment by forwarding the change to the orchestrator microservice. The payload may include an external identifier, total amount, status and additional data for downstream reconciliation.",
        "operationId": "TerminalPaymentController_updateTerminalPayment",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the terminal payment to update.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "externalId": {
                    "type": "string",
                    "description": "External identifier from the payment network.",
                    "example": "EXT-001"
                  },
                  "totalAmount": {
                    "type": "number",
                    "description": "Total amount including taxes and fees.",
                    "example": 168.56
                  },
                  "status": {
                    "type": "string",
                    "description": "New status for the terminal payment.",
                    "example": "approved"
                  },
                  "additionalData": {
                    "type": "object",
                    "description": "Additional metadata related to the payment.",
                    "example": {
                      "authorization": "AUTH123",
                      "reference": "REF-456"
                    }
                  }
                },
                "required": [
                  "externalId",
                  "totalAmount",
                  "status"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Terminal payment updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal payment updated successfully.",
                    "data": {
                      "id": 12345,
                      "externalId": "EXT-001",
                      "totalAmount": 168.56,
                      "status": "approved",
                      "additionalData": {
                        "authorization": "AUTH123",
                        "reference": "REF-456"
                      },
                      "baseAmount": 150.5
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the terminal payment update payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the update terminal payment permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested terminal payment was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7402",
                        "message": "Terminal payment not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The terminal payment could not be updated.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7309",
                        "message": "Error updating terminal payment."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Update Terminal Payment",
        "tags": [
          "Terminal Payments"
        ]
      }
    },
    "/terminal-payment/{id}/signature": {
      "post": {
        "description": "Uploads the signature captured from the end user at the end of a purchase and forwards it to the transfers microservice, which stores the file and persists its URL on the terminal payment.",
        "operationId": "TerminalPaymentController_uploadTerminalPaymentSignature",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the terminal payment.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Signature file and branch id of the terminal.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadTerminalPaymentSignatureDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Signature uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Signature uploaded successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid file — size limit exceeded, empty file or invalid type.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7630",
                        "message": "The file cannot be empty"
                      },
                      {
                        "code": "7620",
                        "message": "Invalid file type."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the upload terminal payment signature permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested terminal payment was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7402",
                        "message": "Terminal payment not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The signature could not be uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Upload Terminal Payment Signature",
        "tags": [
          "Terminal Payments"
        ]
      }
    },
    "/cards/{cardId}/cvv": {
      "get": {
        "description": "Returns the CVV of the card associated with the supplied view token. Requires JWT authentication, application permissions, and user-level permissions. The token is single-use and short-lived.",
        "operationId": "CardsController_checkCVV",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "token",
            "required": true,
            "in": "query",
            "description": "View token previously issued to authorize sensitive data access.",
            "schema": {
              "example": "view-token-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CVV retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The card CVV has been obtained successfully",
                    "data": {
                      "idRequest": "REQ-987654",
                      "CVV": "123"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing or malformed card id or view token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to read this card CVV.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or view token does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7225",
                        "message": "View token not found, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card from the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7214",
                        "message": "Error getting card, please check your cardId and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Check Card CVV",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}": {
      "patch": {
        "description": "Partially updates the metadata of a card (currently the human-readable alias). Requires JWT authentication, application permissions, and user-level permissions over the card.",
        "operationId": "CardsController_updateAlias",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to update.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCardDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Card updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Card updated successfully",
                    "data": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the card update payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to update this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Card Alias",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/pin": {
      "post": {
        "description": "Sets or rotates the PIN associated with a card. The new PIN must satisfy the configured NIP policy. Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardsController_updatePIN",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardPinDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PIN assigned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The PIN has been assigned successfully",
                    "data": {
                      "idRequest": "REQ-987654"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the PIN payload is missing or invalid, or the card status is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7205",
                        "message": "Incorrect PIN entered."
                      },
                      {
                        "code": "7213",
                        "message": "The card status is invalid. Kindly verify that your card is active"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to assign a PIN to this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card PIN in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assign Card PIN",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/funds": {
      "put": {
        "description": "Loads or unloads funds against the card balance using the supplied operation type. Validates that the card belongs to the provided userId before processing the operation. Requires JWT authentication, application permissions, and user-level permissions over the card.",
        "operationId": "CardsController_updateFunds",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to operate on.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardAssingFundsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Funds operation queued successfully. The final result is delivered by webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Your transaction is being processed",
                    "data": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request body validation error. Amount, balance and card status are evaluated asynchronously after this endpoint answers, so their errors are reported through the funds.to.card webhook, not here.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters sent in the request."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to operate funds on this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error processing the funds operation in the transfers microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7300",
                        "message": "Error while creating the transfer."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assign Funds To Card",
        "tags": [
          "Cards"
        ]
      },
      "post": {
        "description": "Applies a funds operation (load/unload) on the card balance from an authorized channel. Requires JWT authentication and application permissions. Custom keys may be attached to enrich downstream reconciliation.",
        "operationId": "AuthCardsController_fundCard",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to be funded.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FundsOperationDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Funds operation processed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "cardTransferId": 987
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: invalid amount, insufficient funds or invalid card status.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7002",
                        "message": "Invalid amount format."
                      },
                      {
                        "code": "7303",
                        "message": "Insufficient funds to complete the transaction."
                      },
                      {
                        "code": "7213",
                        "message": "The card status is invalid. Kindly verify that your card is active"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to fund this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error processing the funds operation in the transfers microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7300",
                        "message": "Error while creating the transfer."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Fund Card Balance",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/request-token": {
      "post": {
        "description": "Issues a short-lived view token allowing the holder to retrieve sensitive card details (PAN, CVV). Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardsController_requestToken",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestTokenDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "View token issued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "token": "view-token-abc123",
                      "createdAt": "2026-06-15T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the view token request payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to request a view token for this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the view token in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7224",
                        "message": "Error creating view token, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Request Card View Token",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/transfer": {
      "post": {
        "description": "Moves funds between two cards belonging to the same ecosystem. Requires JWT authentication, application permissions, and user-level permissions over both cards.",
        "operationId": "CardsController_transferBetweenCards",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferBetweenCardsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer executed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The funds has been transfered successfully",
                    "data": {
                      "idRequest": "REQ-987654",
                      "operationId": "MOV-123456",
                      "originCardSuffix": "************1234",
                      "destinationCardSuffix": "************5678",
                      "amountTo": 100,
                      "balance": 900,
                      "currency": "GTQ",
                      "originCardId": 12345,
                      "cardTransferId": 56789
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: invalid amount, insufficient funds or invalid transfer status.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7303",
                        "message": "Insufficient funds to complete the transaction."
                      },
                      {
                        "code": "7304",
                        "message": "Invalid transfer status."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to transfer between these cards.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "One of the referenced cards does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The transfer collides with the current state of the cards.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7223",
                        "message": "You cannot associate cards that already belong to the user"
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the transfer in the transfers microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7300",
                        "message": "Error while creating the transfer."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Transfer Between Cards",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/statements": {
      "post": {
        "description": "Generates a monthly statement for the specified card. Requires JWT authentication, application permissions, and user-level permissions. The statement is produced asynchronously by the reports microservice.",
        "operationId": "CardsController_createStatement",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateStatementDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Statement created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Statement created successfully",
                    "data": {
                      "url": "https://s3.amazonaws.com/statements/card-12345-2026-05.pdf?X-Amz-Expires=900"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: invalid month/year or statement payload.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7626",
                        "message": "The month is invalid. It must be a value between 01 and 12."
                      },
                      {
                        "code": "7627",
                        "message": "The year is invalid. It must be a valid year."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to create a statement for this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error generating the statement in the reports microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7302",
                        "message": "Error retrieving transaction history."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Card Statement",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/users/{authUserId}/permissions": {
      "post": {
        "description": "Creates a permission entry that grants the specified user a capability over the card. Requires JWT authentication, application permissions, and user-level permissions. The permission is identified by a CardPermissionType value.",
        "operationId": "CardUserPermissionController_create",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the user receiving the permission.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Card permission payload. The cardId and authUserId are taken from the path; only the permission type is sent in the body.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "permission"
                ],
                "properties": {
                  "permission": {
                    "type": "string",
                    "enum": [
                      "updateAlias",
                      "checkCard",
                      "checkCvv",
                      "getCards",
                      "updateStatus",
                      "assignPIN",
                      "getAllTransfersByDate",
                      "transferBetweenCards",
                      "activation"
                    ],
                    "example": "checkCvv"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Permission created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Permission created successfully.",
                    "data": {
                      "id": 1,
                      "cardId": 12345,
                      "authUserId": 1,
                      "permission": "checkCvv",
                      "granted": true,
                      "createdAt": "2026-06-15T10:30:00.000Z",
                      "updatedAt": "2026-06-15T10:30:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the permission payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to grant card permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card user permission already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7159",
                        "message": "User permission already exist, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the card user permission in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7216",
                        "message": "Error creating card user permission, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Card User Permission",
        "tags": [
          "Cards"
        ]
      },
      "get": {
        "description": "Returns the permissions configured for the specified user on a particular card. Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardUserPermissionController_findByCardIdAndAuthUserId",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permissions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": 1,
                        "cardId": 12345,
                        "authUserId": 1,
                        "permission": "checkCvv",
                        "granted": true,
                        "createdAt": "2026-06-15T10:30:00.000Z",
                        "updatedAt": "2026-06-15T10:30:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to read card user permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card user permissions from the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7218",
                        "message": "Error finding card user permission, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find Permissions By Card And User",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/users/permissions/{id}": {
      "patch": {
        "description": "Toggles the granted flag of an existing card-user permission entry. Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardUserPermissionController_update",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card user permission entry.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Permission update payload. The permission entry id is taken from the path; only the granted flag is sent in the body.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "granted"
                ],
                "properties": {
                  "granted": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Permission updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Permission updated successfully.",
                    "data": {
                      "id": 1,
                      "cardId": 12345,
                      "authUserId": 1,
                      "permission": "checkCvv",
                      "granted": true,
                      "createdAt": "2026-06-15T10:30:00.000Z",
                      "updatedAt": "2026-06-15T10:35:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the permission update payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to update card permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card user permission does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7219",
                        "message": "Card user permission not found, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card user permission in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7217",
                        "message": "Error updating card user permission, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update Card User Permission",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/users/{authUserId}/permissions": {
      "get": {
        "description": "Returns the list of card permissions granted to the specified authenticated user across all cards. Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardUserPermissionController_findByAuthUserId",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permissions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": 1,
                        "cardId": 12345,
                        "authUserId": 1,
                        "permission": "checkCvv",
                        "granted": true,
                        "createdAt": "2026-06-15T10:30:00.000Z",
                        "updatedAt": "2026-06-15T10:30:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to read card user permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card user permissions from the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7218",
                        "message": "Error finding card user permission, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find Permissions By User",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/users/permissions": {
      "get": {
        "description": "Returns the list of user permissions configured for the specified card. Requires JWT authentication, application permissions, and user-level permissions.",
        "operationId": "CardUserPermissionController_findByCardId",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Permissions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": 1,
                        "cardId": 12345,
                        "authUserId": 1,
                        "permission": "checkCvv",
                        "granted": true,
                        "createdAt": "2026-06-15T10:30:00.000Z",
                        "updatedAt": "2026-06-15T10:30:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to read card user permissions.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the card user permissions from the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7218",
                        "message": "Error finding card user permission, verify ids and names and try again."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Find Permissions By Card",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/bank-transfer": {
      "post": {
        "description": "Withdraws funds from the card and requests a bank transfer to the destination account through the orchestrator. Requires JWT authentication and application permissions.",
        "operationId": "CardUserPermissionController_bankTransfer",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card the funds are withdrawn from.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BankTransferDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank transfer requested successfully (awaiting provider confirmation).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 321,
                      "status": "in_progress",
                      "reference": "BT-abc123"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: bank transfers disabled, limit exceeded, currency/partner mismatch or insufficient funds.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7321",
                        "message": "Bank transfers are not enabled for this merchant."
                      },
                      {
                        "code": "7322",
                        "message": "Daily bank transfer limit exceeded."
                      },
                      {
                        "code": "7324",
                        "message": "The merchant does not match the card partner."
                      },
                      {
                        "code": "7325",
                        "message": "The card currency does not match the bank account currency."
                      },
                      {
                        "code": "7303",
                        "message": "Insufficient funds to complete the transaction."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to initiate bank transfers.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or bank account does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7320",
                        "message": "Bank transfer not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error requesting the bank transfer in the orchestrator/provider.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7326",
                        "message": "Error while requesting the bank transfer with the provider."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Initiate a bank transfer",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/bank-transfer/{id}": {
      "get": {
        "description": "Returns a single bank transfer by its internal id. The transfer must belong to the caller (admin/support/webview roles bypass the ownership check). Delegated to op-transfers via NATS.",
        "operationId": "CardUserPermissionController_getBankTransferById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the bank transfer.",
            "schema": {
              "example": 321,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank transfer retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": {
                      "id": 321,
                      "authUserId": 1,
                      "withdrawalCardId": 12345,
                      "amount": "150.5000",
                      "currency": "GTQ",
                      "status": "in_progress",
                      "reference": "BT-abc123",
                      "externalId": null,
                      "createdAt": "2026-08-25T14:00:00.000Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT or user token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller cannot access this bank transfer.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced bank transfer does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7320",
                        "message": "Bank transfer not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the bank transfer.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a bank transfer by id",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/transfers/{month}/{year}": {
      "get": {
        "description": "Returns the movement history of a card filtered by month and year. Optionally filters by transfer type. Requires JWT authentication and application permissions.",
        "operationId": "AuthCardsController_getAllTransfersByDate",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "month",
            "required": true,
            "in": "path",
            "description": "Month to query (1-12).",
            "schema": {
              "example": 5,
              "type": "number"
            }
          },
          {
            "name": "year",
            "required": true,
            "in": "path",
            "description": "Four-digit year to query.",
            "schema": {
              "example": 2026,
              "type": "number"
            }
          },
          {
            "name": "type",
            "required": false,
            "in": "query",
            "description": "Optional transfer type filter.",
            "schema": {
              "example": "CARD_TO_CARD",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer history retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "data": [
                      {
                        "id": 987,
                        "terminalPaymentId": null,
                        "authCode": "123456",
                        "reference": "REF-987",
                        "senderCardId": 12345,
                        "receiverCardId": null,
                        "totalAmount": "100.0000",
                        "status": "approved",
                        "currency": "GTQ",
                        "description": "ATM top-up",
                        "transferType": "topUp",
                        "transferModel": "settlement",
                        "channel": "MOBILE",
                        "merchant": "migo",
                        "concept": "Top-up",
                        "createdAt": "2026-05-10T14:32:00.000Z",
                        "updatedAt": "2026-05-10T14:32:05.000Z",
                        "transfer_type": {
                          "movementType": "credit"
                        },
                        "externalCardSuffix": "1234"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: invalid card id, month or year.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7626",
                        "message": "The month is invalid. It must be a value between 01 and 12."
                      },
                      {
                        "code": "7627",
                        "message": "The year is invalid. It must be a valid year."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to read this card transfer history.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error retrieving the transaction history from the transfers microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7302",
                        "message": "Error retrieving transaction history."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get Card Transfers By Date",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/users/{authUserId}/pin": {
      "post": {
        "description": "Sets or rotates the PIN of a card on behalf of the specified authenticated user. Performs application-level verification before issuing the operation. Requires JWT authentication and application permissions.",
        "operationId": "ClientsCardsController_updatePIN",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the authenticated user.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CardPinDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PIN assigned successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The PIN has been assigned successfully",
                    "data": {
                      "idRequest": "123456789"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the PIN payload is missing or invalid, or the card status is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7205",
                        "message": "Incorrect PIN entered."
                      },
                      {
                        "code": "7213",
                        "message": "The card status is invalid. Kindly verify that your card is active"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to assign a PIN to this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card PIN in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Assign Card PIN For User",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/users/{authUserId}/block": {
      "post": {
        "description": "Blocks the specified card so that it can no longer process transactions. Requires JWT authentication and application permissions. The action is associated with the authenticated user for auditing.",
        "operationId": "ClientsCardsController_block",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to block.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the authenticated user performing the action.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card blocked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The card has been updated status successfully, new status: BLOCK"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to block this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already in the requested state.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7203",
                        "message": "Card is already blocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card status in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Block Card",
        "tags": [
          "Cards"
        ]
      }
    },
    "/cards/{cardId}/users/{authUserId}/unblock": {
      "post": {
        "description": "Removes the block flag from the specified card so that it can resume processing transactions. Requires JWT authentication and application permissions. The action is associated with the authenticated user for auditing.",
        "operationId": "ClientsCardsController_unblock",
        "parameters": [
          {
            "name": "cardId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the card to unblock.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          },
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Internal identifier of the authenticated user performing the action.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Card unblocked successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "The card has been updated status successfully, new status: UNBLOCK"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks permission to unblock this card.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced card or user does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7200",
                        "message": "Card not found in the system."
                      },
                      {
                        "code": "7129",
                        "message": "Application user not found, please check your user and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The card is already in the requested state.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7204",
                        "message": "Card is already unlocked."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error updating the card status in the cards microservice.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7210",
                        "message": "Error updating card information."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Unblock Card",
        "tags": [
          "Cards"
        ]
      }
    },
    "/card-emission-batches": {
      "get": {
        "operationId": "CardEmissionBatchController_findMany",
        "parameters": [
          {
            "name": "partner_code",
            "required": false,
            "in": "query",
            "schema": {
              "example": "akisi",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lotes del programa y total vigente.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lotes obtenidos",
                    "data": {
                      "batches": [],
                      "total": 90000,
                      "activeBatches": 2
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de emisión.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo consultar los lotes.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Lotes de emisión declarada, con el total vigente",
        "tags": [
          "Cards"
        ]
      },
      "post": {
        "operationId": "CardEmissionBatchController_create",
        "parameters": [
          {
            "name": "x-actor-email",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCardEmissionBatchDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lote registrado.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lote registrado",
                    "data": {
                      "id": 1,
                      "partnerCode": "akisi",
                      "quantity": 70000
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "El cuerpo no es válido: cantidad no positiva o fecha mal formada.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de emisión.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "El programa no está en el catálogo o está dado de baja.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo registrar el lote.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Registra un lote de plásticos mandados a fabricar",
        "tags": [
          "Cards"
        ]
      }
    },
    "/card-emission-batches/{id}": {
      "patch": {
        "operationId": "CardEmissionBatchController_update",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCardEmissionBatchDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lote corregido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lote corregido",
                    "data": {
                      "id": 1,
                      "reference": "OC-2026-001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "El cuerpo no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de emisión.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "El lote no existe, o ya estaba anulado.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo corregir el lote.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Corrige la referencia o la nota de un lote",
        "tags": [
          "Cards"
        ]
      }
    },
    "/card-emission-batches/{id}/void": {
      "post": {
        "operationId": "CardEmissionBatchController_void",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "x-actor-email",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoidCardEmissionBatchDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lote anulado.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Lote anulado",
                    "data": {
                      "id": 1,
                      "voidReason": "cantidad equivocada"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Falta el motivo de la anulación.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de emisión.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "El lote no existe, o ya estaba anulado.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo anular el lote.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Anula un lote, con motivo",
        "tags": [
          "Cards"
        ]
      }
    },
    "/client-prices": {
      "get": {
        "operationId": "ClientPriceController_findMany",
        "parameters": [
          {
            "name": "partner_code",
            "required": false,
            "in": "query",
            "schema": {
              "example": "akisi",
              "type": "string"
            }
          },
          {
            "name": "alcance",
            "required": false,
            "in": "query",
            "description": "Por omisión solo lo vigente; «todo» trae el historial.",
            "schema": {
              "enum": [
                "vigentes",
                "todo"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tarifario y catálogos.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Tarifario obtenido",
                    "data": {
                      "prices": [],
                      "concepts": [],
                      "programs": []
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de tarifario.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo consultar el tarifario.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Tarifario vigente, con los catálogos de programa y concepto",
        "tags": [
          "Cards"
        ]
      },
      "post": {
        "operationId": "ClientPriceController_create",
        "parameters": [
          {
            "name": "x-actor-email",
            "required": true,
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateClientPriceDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tarifa registrada.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Tarifa registrada",
                    "data": {
                      "id": 1,
                      "partnerCode": "akisi",
                      "concept": "tarjeta_emitida"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "El cuerpo no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de tarifario.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "El programa o el concepto no están en su catálogo.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Ya hay una tarifa de ese concepto para ese cliente y moneda en esas fechas.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7006",
                        "message": "External ID already exists."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo registrar la tarifa.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Registra una tarifa",
        "tags": [
          "Cards"
        ]
      }
    },
    "/client-prices/{id}/close": {
      "post": {
        "operationId": "ClientPriceController_close",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "example": 1,
              "type": "number"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CloseClientPriceDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vigencia cerrada.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Vigencia cerrada",
                    "data": {
                      "id": 1,
                      "validTo": "2026-07-01"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Falta la fecha de cierre o no es válida.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falta el token o no es válido.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "La credencial no tiene el permiso de tarifario.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Esa tarifa no existe.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7004",
                        "message": "Required services not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "No se pudo cerrar la vigencia.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Cierra la vigencia de una tarifa",
        "tags": [
          "Cards"
        ]
      }
    },
    "/messaging": {
      "get": {
        "description": "Serves the static HTML home page of the messaging service. Useful as a landing page or smoke-test endpoint when validating the WebSocket gateway deployment.",
        "operationId": "MessagingController_getHome",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The static messaging home page HTML was returned successfully.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the home page could not be served.",
            "content": {
              "text/html": {
                "schema": {
                  "example": {
                    "statusCode": 500,
                    "message": "Internal server error"
                  }
                }
              }
            }
          }
        },
        "summary": "Get messaging home page",
        "tags": [
          "Messaging"
        ]
      }
    },
    "/messaging/status": {
      "get": {
        "description": "Returns a basic health payload with a status string and a server-side timestamp. Used as a lightweight liveness probe for the messaging gateway.",
        "operationId": "MessagingController_getStatus",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Messaging server status retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "status": "Servidor funcionando",
                    "timestamp": "2026-06-14T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the messaging server status could not be retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "statusCode": 500,
                    "message": "Internal server error"
                  }
                }
              }
            }
          }
        },
        "summary": "Get messaging server status",
        "tags": [
          "Messaging"
        ]
      }
    },
    "/messaging/emit": {
      "post": {
        "description": "Emits a custom event to a specific connected WebSocket client identified by clientId. The payload is forwarded as-is. Returns an acknowledgment message. Requires a valid JWT.",
        "operationId": "MessagingController_handleEmitEvent",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmitEventDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Event emitted successfully to the target WebSocket client.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "message": "Evento enviado",
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the clientId or payload is missing or malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid JWT token.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7600",
                        "message": "Unauthorized access."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — the event could not be emitted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "statusCode": 500,
                    "message": "Internal server error"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Emit event to client",
        "tags": [
          "Messaging"
        ]
      }
    },
    "/settlements": {
      "post": {
        "description": "Processes a payment settlement for a terminal transaction. Forwards the request to the orchestrator service for settlement execution. Returns the settlement result including transaction reference and status.",
        "operationId": "SettlementsController_processTerminalPayment",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProcessTerminalPaymentDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Settlement processed successfully by the orchestrator.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Settlement processed successfully.",
                    "data": {
                      "cardTransferId": 1,
                      "amountTo": "100.00",
                      "card": "XXXX-1234"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the settlement payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced terminal payment was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7402",
                        "message": "Terminal payment not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The orchestrator failed to process the settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7500",
                        "message": "Error creating settlement."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Process Terminal Payment",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/settlements/reversal-preview": {
      "get": {
        "description": "Returns backend-dictated eligibility for a Tap to Phone reversal (amount, currency, balance, sufficiency and a typed reason when not eligible). The wallet renders the reversal button off this response and never computes the same-day window locally. The clientId is resolved server-side from the JWT.",
        "operationId": "SettlementsController_getReversalPreview",
        "parameters": [
          {
            "name": "terminalPaymentId",
            "required": true,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "timezone",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reversal preview retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Reversal preview retrieved successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing terminalPaymentId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the reversal preview permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Reversal eligibility preview",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/settlements/reversal/confirm": {
      "post": {
        "description": "Confirms a Tap to Phone reversal AFTER the processor approved it: attaches the authorization/voucher evidence and emits the PAYMENT_REVERSED push. Only after this does the buyer-side reversal count as successful (the debit itself does not push in the new flow).",
        "operationId": "SettlementsController_confirmReversal",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfirmReversalDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reversal confirmed and success push emitted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Reversal confirmed successfully."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing reversalId or terminalPaymentId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the reversal confirm permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Confirm reversal",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/settlements/reversal/compensation": {
      "post": {
        "description": "Compensates a Tap to Phone reversal whose processor annulment failed: recharges the debited amount to the Yayo card. On success the charge returns to liquidated; on recharge failure the movement is left pending for the end-of-day retry sweep.",
        "operationId": "SettlementsController_compensateReversal",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompensateReversalDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reversal compensated (liquidated) or left pending for retry.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Reversal compensation processed."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing reversalId or terminalPaymentId.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the reversal compensation permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Compensate reversal",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/settlements/details": {
      "get": {
        "description": "Retrieves the details of a specific settlement by external identifier and payment method. Requires JWT authentication and settlement detail permissions. Returns the full settlement record including amounts, status, and timestamps.",
        "operationId": "SettlementsController_getTerminalPayment",
        "parameters": [
          {
            "name": "externalId",
            "required": true,
            "in": "query",
            "description": "External transaction identifier",
            "schema": {
              "example": "TXN-12345",
              "type": "string"
            }
          },
          {
            "name": "paymentMethodType",
            "required": true,
            "in": "query",
            "description": "Payment method type",
            "schema": {
              "enum": [
                "card",
                "akisiQR",
                "nequi",
                "quickPayQR",
                "zigiQR",
                "bancoIndustrial",
                "bamQR",
                "yoloQR",
                "friQR",
                "okyQR"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Settlement details retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Settlement details retrieved successfully.",
                    "data": {
                      "status": "APPROVED",
                      "uid": "UID-789",
                      "currency": "GTQ",
                      "totalAmount": 100,
                      "additionalData": {
                        "authorization": "AUTH123",
                        "processor": "CARD",
                        "reference": "REF-456",
                        "affiliation": "aliGT"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: missing or invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the settlement detail permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The requested settlement was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7501",
                        "message": "Settlement not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get Settlement Details",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/settlements/pending": {
      "post": {
        "description": "Registers a settlement that could not be completed so it can be retried later. Forwards the request to the liquidations service. Requires the CREATE_PENDING settlements permission.",
        "operationId": "SettlementsController_createPendingSettlement",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePendingSettlementDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pending settlement created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Pending settlement created successfully",
                    "data": {
                      "id": "65f1c2a1e4b0f1a2b3c4d5e6",
                      "terminalPaymentId": 1,
                      "amount": "100.00",
                      "externalTerminalId": "TERM-001"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the pending settlement payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks the CREATE_PENDING settlements permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error creating the pending settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create Pending Settlement",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/devices/{deviceId}/transactions": {
      "get": {
        "description": "Returns the transaction history of the specified device. The list is sourced from the operational transfers microservice and includes successful and failed transactions.",
        "operationId": "DevicesController_getDeviceTransactions",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Device transactions retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Transactions for terminals [101] fetched successfully.",
                    "data": {
                      "transactions": [
                        {
                          "id": 12345,
                          "amount": "150.0000",
                          "date": "2026-06-14 10:32:05",
                          "currency": "GTQ",
                          "status": "liquidated",
                          "terminalId": 101,
                          "processor": "td/tc",
                          "reference": "REF-987654",
                          "authorizationCode": "AUTH-123456"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced device was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The transaction history could not be retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7302",
                        "message": "Error retrieving transaction history."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "List device transactions",
        "tags": [
          "Devices"
        ]
      }
    },
    "/devices/{deviceId}/transactions/{transactionId}": {
      "get": {
        "description": "Returns the details of a specific transaction processed by the specified device. Includes amount, status, and related metadata.",
        "operationId": "DevicesController_getDeviceTransactionById",
        "parameters": [
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          },
          {
            "name": "transactionId",
            "required": true,
            "in": "path",
            "description": "Transaction identifier.",
            "schema": {
              "example": 12345,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Device transaction retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Transaction 12345 for terminal EXT-TERM-001 fetched successfully.",
                    "data": {
                      "id": 12345,
                      "terminalId": 101,
                      "externalId": "EXT-TERM-001",
                      "operationId": "OP-555",
                      "subtotal": "150.0000",
                      "totalAmount": "150.0000",
                      "status": "liquidated",
                      "currency": "GTQ",
                      "paymentMethodType": "card",
                      "additionalData": {
                        "processor": "td/tc",
                        "reference": "REF-987654",
                        "authorizationCode": "AUTH-123456"
                      },
                      "createdAt": "2026-06-14T16:32:00.000Z",
                      "updatedAt": "2026-06-14T16:32:05.000Z",
                      "date": "2026-06-14 10:32:05",
                      "processor": "td/tc"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referenced device or transaction was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7402",
                        "message": "Terminal payment not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Get device transaction",
        "tags": [
          "Devices"
        ]
      }
    },
    "/devices/users/{authUserId}/terminals": {
      "post": {
        "description": "Creates a terminal device for the specified authentication user and branch. Delegates to the businesses service. Optionally notifies Zendesk about the new terminal.",
        "operationId": "DevicesController_createTerminalForAuthUserId",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Authentication user identifier.",
            "schema": {
              "example": "auth-user-abc123",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deviceId",
                  "branchId"
                ],
                "example": {
                  "deviceId": "device-abc123",
                  "branchId": 10,
                  "notifyZendesk": false
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Terminal created successfully for the authentication user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal created successfully",
                    "data": {
                      "id": 55,
                      "deviceId": "device-abc123",
                      "terminalType": "TapOnPhone",
                      "isActive": true,
                      "createdAt": "2026-06-14T16:32:00.000Z",
                      "updatedAt": "2026-06-14T16:32:00.000Z",
                      "branchAuthUserId": 20,
                      "externalId": "EXT-TERM-001",
                      "isDeleted": false,
                      "additionalData": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error: the terminal creation payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The authentication user or branch was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7416",
                        "message": "AuthUserId provided dont exists in branch auth user, please verify information."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The terminal could not be created.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7403",
                        "message": "Error creating terminal."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Create terminal for auth user",
        "tags": [
          "Devices"
        ]
      }
    },
    "/devices/users/{authUserId}/terminals/{deviceId}": {
      "get": {
        "description": "Retrieves the terminal information for a specific authentication user and device identifier. Delegates to the businesses service.",
        "operationId": "DevicesController_getTerminalByBranchUserId",
        "parameters": [
          {
            "name": "authUserId",
            "required": true,
            "in": "path",
            "description": "Authentication user identifier.",
            "schema": {
              "example": 1,
              "type": "number"
            }
          },
          {
            "name": "deviceId",
            "required": true,
            "in": "path",
            "description": "Device identifier of the terminal.",
            "schema": {
              "example": "device-abc123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Terminal retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Terminal found.",
                    "data": {
                      "id": 55,
                      "deviceId": "device-abc123",
                      "terminalType": "TapOnPhone",
                      "isActive": true,
                      "createdAt": "2026-06-14T16:32:00.000Z",
                      "updatedAt": "2026-06-14T16:32:00.000Z",
                      "branchAuthUserId": 20,
                      "externalId": "EXT-TERM-001",
                      "isDeleted": false,
                      "additionalData": null
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The terminal for the given user and device was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7400",
                        "message": "Terminal not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Get terminal by auth user",
        "tags": [
          "Devices"
        ]
      }
    },
    "/integrations/forms/webhook": {
      "post": {
        "description": "Validates the provided integration API key and integration key headers, then forwards the incoming payload to the transactional orchestrator forms webhook endpoint. Used by third-party form providers to push form submissions into the ALI ecosystem.",
        "operationId": "FormIntegrationsController_webhook",
        "parameters": [
          {
            "name": "x-ali-forms-api-key",
            "required": true,
            "in": "header",
            "description": "Integration API key issued to the forms provider.",
            "schema": {
              "type": "string",
              "example": "ali_pk_live_xxxxxxxxxxxxxxxxxxxx"
            }
          },
          {
            "name": "x-integration-key",
            "required": true,
            "in": "header",
            "description": "Integration identifier used by the orchestrator to route the payload.",
            "schema": {
              "type": "string",
              "example": "integration_abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Raw form provider payload forwarded as-is to the orchestrator. The example below shows an Airtable automation webhook; the structure depends on the configured platform.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "example": {
                  "platform": "airtable",
                  "event": "record_created",
                  "baseId": "appXXXXXXXXXXXXXX",
                  "tableName": "Leads",
                  "recordId": "recXXXXXXXXXXXXXX",
                  "fields": {
                    "email": "jane.doe@example.com",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "phone": "+50212345678"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook forwarded to the orchestrator successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Webhook received",
                    "data": {
                      "accepted": true,
                      "integrationId": "integration_abc123",
                      "platform": "airtable",
                      "sourceId": "airtable:appXXXXXXXXXXXXXX:Leads:recXXXXXXXXXXXXXX"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The x-integration-key header is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "The x-ali-forms-api-key header is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7602",
                        "message": "Unauthorized access, please check your credentials."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error forwarding the webhook to the orchestrator.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "summary": "Receive forms integration webhook",
        "tags": [
          "Form Integrations"
        ]
      }
    },
    "/integrity/app": {
      "get": {
        "description": "\nGenera un hash único para la aplicación indicada, utilizado en el flujo de validación de integridad de Google Play.\n\n**Flujo:**\n1. Recibe el `applicationid` en los headers de la petición.\n2. Consulta la configuración de integridad almacenada para esa aplicación.\n3. Retorna un hash firmado listo para ser enviado al dispositivo.\n\n> Este endpoint requiere autenticación JWT.\n      ",
        "operationId": "IntegrityController_getHash",
        "parameters": [
          {
            "name": "applicationid",
            "required": true,
            "in": "header",
            "description": "ID de la aplicación móvil (ej: com.migo.ali)",
            "schema": {
              "type": "string",
              "example": "com.migo.ali"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hash generado exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Hash generated successfully",
                    "data": {
                      "requestHash": "0971d5f5227bbe6a7571948cefae755bca9d7b0dec2158478a54d1eaf6b38e4e"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado — JWT inválido/ausente o token de integridad expirado",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Configuración de integridad no encontrada para el applicationId indicado",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7712",
                        "message": "App config integrity not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error interno del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Obtener hash para validación de integridad",
        "tags": [
          "Integrity"
        ]
      },
      "post": {
        "description": "\nValida el token de integridad de Google Play para verificar que la aplicación corre en un dispositivo legítimo.\n\n**Flujo:**\n1. Recibe el `hash`, `applicationId` y `token` de integridad.\n2. Verifica el token contra los servidores de Google Play Integrity API.\n3. Retorna si el dispositivo y la aplicación son válidos.\n\n> Este endpoint requiere autenticación JWT.\n      ",
        "operationId": "IntegrityController_validate",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateIntegrityDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Integridad validada exitosamente — todos los checks pasaron",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "errors": []
                  }
                }
              }
            }
          },
          "400": {
            "description": "Hash o applicationId inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7710",
                        "message": "Integrity hash is invalid."
                      },
                      {
                        "code": "7711",
                        "message": "Integrity application ID is invalid."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "No autorizado — JWT inválido/ausente o token de integridad expirado",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Una o más verificaciones de integridad de Google Play fallaron:\n- **7706 · App no reconocida**: El certificado o nombre de paquete no coincide con los registros de Google Play. Indica que la app fue modificada (APK alterado) o instalada desde una fuente no oficial.\n- **7707 · Dispositivo no confiable**: El dispositivo tiene root, bootloader desbloqueado, es un emulador que no pasa las verificaciones de Google Play, o muestra indicios de vulneración del sistema.\n- **7708 · Sin licencia de Play**: El usuario no adquirió ni descargó la app desde Google Play (sideload o tienda de terceros). Se puede resolver mostrando el diálogo `GET_LICENSED` de Play.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7706",
                        "message": "Unrecognized app version."
                      },
                      {
                        "code": "7707",
                        "message": "Unrecognized device integrity status."
                      },
                      {
                        "code": "7708",
                        "message": "Unrecognized licensing status."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Configuración de integridad no encontrada para el applicationId indicado",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7712",
                        "message": "App config integrity not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Error interno del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Validar integridad del dispositivo",
        "tags": [
          "Integrity"
        ]
      }
    },
    "/notifications": {
      "get": {
        "operationId": "NotificationsController_getNotifications",
        "parameters": [
          {
            "name": "page",
            "required": true,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": true,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lang",
            "required": true,
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Get notification history for the authenticated user",
        "tags": [
          "notifications"
        ]
      }
    },
    "/notifications/has-unread": {
      "get": {
        "operationId": "NotificationsController_hasUnreadNotifications",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Check if the authenticated user has unread notifications",
        "tags": [
          "notifications"
        ]
      }
    },
    "/notifications/{id}/read": {
      "patch": {
        "operationId": "NotificationsController_markAsRead",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Mark a single notification as read",
        "tags": [
          "notifications"
        ]
      }
    },
    "/notifications/read-all": {
      "patch": {
        "operationId": "NotificationsController_markAllAsRead",
        "parameters": [],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Mark all notifications as read for the authenticated user",
        "tags": [
          "notifications"
        ]
      }
    },
    "/notifications/opened": {
      "post": {
        "description": "The app reports where the user opened a push (tray, in-app alert or inbox) with the `trackingId` of its data. The device comes from the X-Platform, X-OS-Version, X-App-Version and X-Device-Model headers. Processed asynchronously; always answers 202.",
        "operationId": "PushOpensController_trackOpen",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackPushOpenRequestDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Open received.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Open received"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Track the open of a push",
        "tags": [
          "notifications"
        ]
      }
    },
    "/wallet/home": {
      "get": {
        "operationId": "WalletController_getHome",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletHomeDto"
                }
              }
            }
          }
        },
        "summary": "Home compuesto segun el rol del usuario",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/wallet/stores": {
      "get": {
        "operationId": "WalletController_getStores",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletStoresResponseDto"
                }
              }
            }
          }
        },
        "summary": "Listar las tiendas activas del usuario",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/wallet/charges": {
      "post": {
        "operationId": "WalletController_getCharges",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetChargesDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChargesResponseDto"
                }
              }
            }
          }
        },
        "summary": "Historial de cobros cross-sucursal (paginado)",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/wallet/charges/{terminalPaymentId}": {
      "get": {
        "operationId": "WalletController_getVoucher",
        "parameters": [
          {
            "name": "terminalPaymentId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChargeDetailDto"
                }
              }
            }
          }
        },
        "summary": "Voucher del cobro + bandera isReversible",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/wallet/charges/{terminalPaymentId}/voucher/email": {
      "post": {
        "operationId": "WalletController_sendVoucherEmail",
        "parameters": [
          {
            "name": "terminalPaymentId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoucherEmailDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": ""
          }
        },
        "summary": "Envia el voucher a un correo arbitrario",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/wallet/stores/{branchId}/summary": {
      "get": {
        "operationId": "WalletController_getStoreSummary",
        "parameters": [
          {
            "name": "branchId",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "required": false,
            "in": "query",
            "description": "Reporting period",
            "schema": {
              "default": "currentMonth",
              "type": "string",
              "enum": [
                "today",
                "last7d",
                "currentMonth"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreSummaryDto"
                }
              }
            }
          }
        },
        "summary": "Resumen financiero de una tienda",
        "tags": [
          "Wallet"
        ]
      }
    },
    "/banners": {
      "get": {
        "description": "Banners the authenticated user can see now (schedule, segments and app of the token), in carousel order and translated to `lang`, plus the in-apps of those banners and the carousel interval. If the banners cannot be read, answers empty lists so the home never blocks.",
        "operationId": "BannersController_getBanners",
        "parameters": [
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "schema": {
              "default": "es",
              "type": "string",
              "enum": [
                "es",
                "en"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banners of the user.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/UserBannersResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Banners of the home",
        "tags": [
          "Banners"
        ]
      }
    },
    "/banners/{bannerId}": {
      "get": {
        "description": "Detail screen of a banner the user can see now. Answers 404 BANNER_NOT_AVAILABLE when it does not exist, is inactive, out of schedule, has no detail or is not for this user.",
        "operationId": "BannersController_getBannerDetail",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          },
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "schema": {
              "default": "es",
              "type": "string",
              "enum": [
                "es",
                "en"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banner detail.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerDetailViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner is not available for the user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8301",
                        "message": "The banner is not available for this user."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7003",
                        "message": "Please contact support for assistance."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Banner detail",
        "tags": [
          "Banners"
        ]
      }
    },
    "/banners/{bannerId}/cta/execute": {
      "post": {
        "description": "Runs the DYNAMIC_SERVICE CTA at `ctaPath` of the stored banner (`\"\"` is the main one, `\"secondary\"` the secondary one of the detail and `\"tap\"` the service of the card tap, which never answers a next CTA; then `onSuccess` / `onError` chained with dots) and answers the next CTA, translated, with `nextCtaMode`: BUTTON shows it as a button, AUTO runs it at once. If the next one is dynamic too, call again with `nextCtaPath`.",
        "operationId": "BannersController_executeBannerCta",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExecuteBannerCtaRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result of the service and next CTA.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/ExecuteBannerCtaResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "The path is not a dynamic CTA or its service is not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8303",
                        "message": "Invalid CTA."
                      },
                      {
                        "code": "8350",
                        "message": "Dynamic service not supported."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner is not available for the user.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8301",
                        "message": "The banner is not available for this user."
                      }
                    ]
                  }
                }
              }
            }
          },
          "502": {
            "description": "The service timed out (5 s) or failed technically and the CTA has no onError.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8351",
                        "message": "Dynamic service failed."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Run a dynamic CTA of a banner",
        "tags": [
          "Banners"
        ]
      }
    },
    "/banners/{bannerId}/interactions": {
      "post": {
        "description": "Records a click on a banner or its CTA (where it happened and what was tapped). It is processed asynchronously and always answers 202.",
        "operationId": "BannersController_trackInteraction",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackBannerInteractionRequestDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Interaction received.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true,
                    "message": "Interaction received"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Track a banner interaction",
        "tags": [
          "Banners"
        ]
      }
    },
    "/admin/banners": {
      "get": {
        "description": "Paginated banners, filterable by app, status and an instant in schedule. Deleted banners only with includeDeleted.",
        "operationId": "BannersAdminController_getBanners",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the items shown in any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          },
          {
            "name": "includeDeleted",
            "required": false,
            "in": "query",
            "description": "Also returns soft-deleted items",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "activeAt",
            "required": false,
            "in": "query",
            "description": "Only banners in schedule at this instant (ISO-8601)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of banners.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannersPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List banners",
        "tags": [
          "Banners admin"
        ]
      },
      "post": {
        "description": "Multipart: `data` (JSON of the banner) and its four PNG images. The images must match exactly the dimensions of the target apps.",
        "operationId": "BannersAdminController_createBanner",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/BannerMultipartDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Banner created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data or images (format, dimensions, contrast, schedule or CTA).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An applicationId does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project configuration not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The images could not be uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a banner",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/preview": {
      "get": {
        "description": "What a given user would see in the home and why every other banner is left out. It has no side effects.",
        "operationId": "BannersAdminController_previewBanners",
        "parameters": [
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "schema": {
              "default": "es",
              "type": "string",
              "enum": [
                "es",
                "en"
              ]
            }
          },
          {
            "name": "subjectId",
            "required": true,
            "in": "query",
            "schema": {
              "example": "1234",
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": true,
            "in": "query",
            "description": "App the user is previewed in",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banners the user would see and the excluded ones.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerPreviewResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Preview the banners of a user",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/stats": {
      "get": {
        "description": "Clicks and unique users per day, week or month, for some or all banners, optionally for one app.",
        "operationId": "BannersAdminController_getBannerStats",
        "parameters": [
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-01T00:00:00.000Z",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-31T23:59:59.000Z",
              "type": "string"
            }
          },
          {
            "name": "granularity",
            "required": true,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "DAY",
                "WEEK",
                "MONTH"
              ]
            }
          },
          {
            "name": "bannerIds",
            "required": false,
            "in": "query",
            "description": "Comma-separated banner ids. Missing: all banners",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Only the clicks made in this app. Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Series per banner.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerStatsResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Banner stats by period",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/{bannerId}": {
      "get": {
        "description": "Raw banner, also when it was deleted (with deletedAt).",
        "operationId": "BannersAdminController_getBanner",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The banner.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8300",
                        "message": "Banner not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a banner",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Multipart: `data` with only the fields to change and, optionally, any of the four images. The target apps cannot change.",
        "operationId": "BannersAdminController_updateBanner",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/BannerMultipartDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Banner updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8300",
                        "message": "Banner not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The banner was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8305",
                        "message": "The banner was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a banner",
        "tags": [
          "Banners admin"
        ]
      },
      "delete": {
        "description": "Soft delete: the banner stays inactive with deletedAt; images and metrics are kept.",
        "operationId": "BannersAdminController_deleteBanner",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banner deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerDeletedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8300",
                        "message": "Banner not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The banner was already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8305",
                        "message": "The banner was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete a banner",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/{bannerId}/metrics": {
      "get": {
        "description": "Clicks and unique users in a range (up to 180 days), by source and action, optionally for one app.",
        "operationId": "BannersAdminController_getBannerMetrics",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          },
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-01T00:00:00.000Z",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-31T23:59:59.000Z",
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Only the clicks made in this app. Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metrics.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerMetricsDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Exact metrics of a banner",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/{bannerId}/devices": {
      "get": {
        "description": "Clicks in a range (up to 180 days) by platform, OS version, app version and model (top 20 each), with the optional device filters. Clicks of app versions that do not send their device count as unknown.",
        "operationId": "BannersAdminController_getBannerDevices",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          },
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-01T00:00:00.000Z",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-31T23:59:59.000Z",
              "type": "string"
            }
          },
          {
            "name": "platform",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ios",
                "android",
                "unknown"
              ]
            }
          },
          {
            "name": "osVersion",
            "required": false,
            "in": "query",
            "schema": {
              "example": "17.5",
              "type": "string"
            }
          },
          {
            "name": "appVersion",
            "required": false,
            "in": "query",
            "schema": {
              "example": "3.12.0",
              "type": "string"
            }
          },
          {
            "name": "model",
            "required": false,
            "in": "query",
            "schema": {
              "example": "iPhone15,2",
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Clicks by device.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeviceBreakdownDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Clicks of a banner by device",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/{bannerId}/interactions": {
      "get": {
        "description": "Paginated raw clicks (who, where and when) within the retention.",
        "operationId": "BannersAdminController_getBannerInteractions",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Only the clicks made in this app. Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of clicks.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerInteractionsPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Clicks of a banner",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/{bannerId}/status": {
      "patch": {
        "operationId": "BannersAdminController_updateBannerStatus",
        "parameters": [
          {
            "name": "bannerId",
            "required": true,
            "in": "path",
            "description": "Identifier of the banner.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f6",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Banner updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/BannerAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The banner does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8300",
                        "message": "Banner not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The banner was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8305",
                        "message": "The banner was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate a banner",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/deeplinks": {
      "get": {
        "description": "Routes of the catalog, ordered by path. `applicationIds` (comma-separated) keeps the routes of any of those apps.",
        "operationId": "DeeplinksAdminController_getRoutes",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the items shown in any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          },
          {
            "name": "includeDeleted",
            "required": false,
            "in": "query",
            "description": "Also returns soft-deleted items",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of routes.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRoutesPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the deeplink routes",
        "tags": [
          "Banners admin"
        ]
      },
      "post": {
        "description": "Every `:name` of the path must be a PATH param and every PATH param must be in the path. Key and path are unique per app.",
        "operationId": "DeeplinksAdminController_createRoute",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeeplinkRouteRequestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Route created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRouteDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Key or path already used.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8361",
                        "message": "Another route already uses this key or path in one of the apps."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a deeplink route",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/deeplinks/{routeId}": {
      "get": {
        "operationId": "DeeplinksAdminController_getRoute",
        "parameters": [
          {
            "name": "routeId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "6712aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The route.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRouteDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The route does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8360",
                        "message": "Deeplink route not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a deeplink route",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Only the fields sent change; the key is immutable. Path and params are checked together on the route as it ends up.",
        "operationId": "DeeplinksAdminController_updateRoute",
        "parameters": [
          {
            "name": "routeId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "6712aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeeplinkRouteRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Route after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRouteDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The route or an app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8360",
                        "message": "Deeplink route not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "Key or path already used.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8361",
                        "message": "Another route already uses this key or path in one of the apps."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Edit a deeplink route",
        "tags": [
          "Banners admin"
        ]
      },
      "delete": {
        "description": "Logical: what was already published keeps working.",
        "operationId": "DeeplinksAdminController_deleteRoute",
        "parameters": [
          {
            "name": "routeId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "6712aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Route deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRouteDeletedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The route does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8360",
                        "message": "Deeplink route not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete a deeplink route",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/deeplinks/{routeId}/status": {
      "patch": {
        "description": "An inactive route leaves the selects and new deeplinks to it are rejected; the published ones keep working.",
        "operationId": "DeeplinksAdminController_updateRouteStatus",
        "parameters": [
          {
            "name": "routeId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "6712aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Route after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/DeeplinkRouteDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The route does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8360",
                        "message": "Deeplink route not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate a deeplink route",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/engagement/dynamic-services": {
      "get": {
        "description": "The services a dynamic CTA can run (`serviceKey`), with their description and the params they read, to pick them in the CTA editor.",
        "operationId": "DynamicServicesAdminController_getServices",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Services by key.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/DynamicServiceDto"
                          }
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Dynamic services of the CTAs",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/engagement/order": {
      "get": {
        "description": "Banners and in-app sequences (per `triggerScreen`) not deleted nor expired of the apps (comma-separated `applicationIds`), in their order and marking what is visible now.",
        "operationId": "EngagementOrderAdminController_getOrder",
        "parameters": [
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "schema": {
              "default": "es",
              "type": "string",
              "enum": [
                "es",
                "en"
              ]
            }
          },
          {
            "name": "applicationIds",
            "required": true,
            "in": "query",
            "description": "Apps the order is applied to; each one keeps only its own items, in this order",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementOrderViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Order view of banners and in-apps",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/banners/order": {
      "put": {
        "description": "Each app keeps only its own items: the ones sent first, in that order, then the rest of the app as they were. Answers the order view after the change.",
        "operationId": "EngagementOrderAdminController_setBannersOrder",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetBannersOrderRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementOrderViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app or a banner does not exist in the apps.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      },
                      {
                        "code": "8300",
                        "message": "Banner not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Order the carousel",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/in-apps/order": {
      "put": {
        "description": "Standalone in-apps (`inAppId`) and in-apps of banners (`bannerId` + `name`) of the same `triggerScreen`. Each app keeps only its own items: the ones sent first, in that order, then the rest of the app as they were. Answers the order view after the change.",
        "operationId": "EngagementOrderAdminController_setInAppsOrder",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetInAppsOrderRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order view.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementOrderViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app or an in-app does not exist in the apps.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      },
                      {
                        "code": "8310",
                        "message": "In-app not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Order the in-app sequence of a screen",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/engagement/settings": {
      "get": {
        "description": "Global settings of banners; defaults when never configured.",
        "operationId": "EngagementSettingsController_getSettings",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Settings.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementSettingsDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get the engagement settings",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Merge: only the fields sent change. Changing a retention also adjusts the stored data (reducing it deletes what is left out right away).",
        "operationId": "EngagementSettingsController_updateSettings",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEngagementSettingsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementSettingsDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update the engagement settings",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/engagement/settings/apps/{applicationId}": {
      "get": {
        "description": "What the app overrides (`rules.engagement`) and the settings it ends up with.",
        "operationId": "EngagementSettingsController_getAppSettings",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Override and effective settings.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementAppSettingsViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get the engagement settings of an app",
        "tags": [
          "Banners admin"
        ]
      },
      "put": {
        "description": "Replaces the whole override of the app: a missing field inherits the general value and `{}` removes the override. Only bannerDetailRoute, maxBannersPerResponse, carouselIntervalMs and allowedExternalSchemes can be overridden.",
        "operationId": "EngagementSettingsController_setAppSettings",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetEngagementAppSettingsRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Override and effective settings after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/EngagementAppSettingsViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Set the engagement settings of an app",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/in-apps": {
      "get": {
        "description": "Standalone in-apps of the app of the token, active and in schedule, translated to `lang`, with the frequency flags the app applies locally by `name`. Works before the login; if they cannot be read, answers an empty list.",
        "operationId": "InAppsController_getInApps",
        "parameters": [
          {
            "name": "lang",
            "required": false,
            "in": "query",
            "schema": {
              "default": "es",
              "type": "string",
              "enum": [
                "es",
                "en"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "In-apps of the app.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/ActiveInAppsResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "In-apps of the app",
        "tags": [
          "Banners"
        ]
      }
    },
    "/admin/in-apps": {
      "get": {
        "description": "Paginated standalone in-apps. With applicationId, exactly the ones that app receives (active, inactive and expired, to edit). Deleted ones only with includeDeleted.",
        "operationId": "InAppsAdminController_getInApps",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the items shown in any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          },
          {
            "name": "includeDeleted",
            "required": false,
            "in": "query",
            "description": "Also returns soft-deleted items",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of in-apps.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppsPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List in-apps",
        "tags": [
          "Banners admin"
        ]
      },
      "post": {
        "description": "Multipart: `data` (JSON of the in-app) and its three PNG images, with the exact dimensions of the target apps. The name cannot start with banner_ and can never be reused.",
        "operationId": "InAppsAdminController_createInApp",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/InAppMultipartDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "In-app created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data or images (format, dimensions, name or contradictory frequency flags).",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The name is already used in one of the apps.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8311",
                        "message": "An in-app with this name already exists."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The images could not be uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create an in-app",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/in-apps/{inAppId}": {
      "get": {
        "description": "Raw in-app, to edit it; also when it was deleted (with deletedAt). Same permission as the list.",
        "operationId": "InAppsAdminController_getInApp",
        "parameters": [
          {
            "name": "inAppId",
            "required": true,
            "in": "path",
            "description": "Identifier of the in-app.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f7",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The in-app.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The in-app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8310",
                        "message": "In-app not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get an in-app",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Multipart: `data` with only the fields to change (never name nor applicationIds) and, optionally, any of the three images.",
        "operationId": "InAppsAdminController_updateInApp",
        "parameters": [
          {
            "name": "inAppId",
            "required": true,
            "in": "path",
            "description": "Identifier of the in-app.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f7",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/InAppMultipartDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "In-app updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The in-app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8310",
                        "message": "In-app not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The in-app was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8312",
                        "message": "The in-app was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update an in-app",
        "tags": [
          "Banners admin"
        ]
      },
      "delete": {
        "description": "Soft delete: inactive with deletedAt; its name stays taken and its images stay stored.",
        "operationId": "InAppsAdminController_deleteInApp",
        "parameters": [
          {
            "name": "inAppId",
            "required": true,
            "in": "path",
            "description": "Identifier of the in-app.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f7",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "In-app deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppDeletedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The in-app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8310",
                        "message": "In-app not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The in-app was already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8312",
                        "message": "The in-app was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete an in-app",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/in-apps/{inAppId}/status": {
      "patch": {
        "operationId": "InAppsAdminController_updateInAppStatus",
        "parameters": [
          {
            "name": "inAppId",
            "required": true,
            "in": "path",
            "description": "Identifier of the in-app.",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e5f7",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "In-app updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/InAppAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The in-app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8310",
                        "message": "In-app not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The in-app was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8312",
                        "message": "The in-app was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate an in-app",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/push-campaigns": {
      "get": {
        "description": "Paginated, the latest scheduled first. `applicationIds` (comma-separated) keeps the campaigns of any of those apps.",
        "operationId": "PushCampaignsAdminController_getCampaigns",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Comma-separated apps. Missing: every app",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "DRAFT",
                "SCHEDULED",
                "RUNNING",
                "DONE",
                "CANCELLED",
                "FAILED"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of campaigns.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushCampaignsPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List push campaigns",
        "tags": [
          "Push campaigns admin"
        ]
      },
      "post": {
        "description": "As DRAFT (not sent) or SCHEDULED (sent at `scheduleAt`, at least 5 minutes and at most 90 days ahead). It expires on the devices and leaves the inbox at `expiresAt` (default 72 h after it starts, at most 28 days). Texts are sent as written, in Spanish.",
        "operationId": "PushCampaignsAdminController_createCampaign",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePushCampaignRequestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campaign created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushCampaignAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data, schedule or audience.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8392",
                        "message": "The campaign must be scheduled in the future, within the allowed range, and expire after it starts."
                      },
                      {
                        "code": "8393",
                        "message": "A segment or topic of the audience does not exist or is not of the campaign apps."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a push campaign",
        "tags": [
          "Push campaigns admin"
        ]
      }
    },
    "/admin/push-campaigns/audience-estimate": {
      "post": {
        "description": "ALL: users of each app with a device refreshed in the last 60 days. SEGMENTS and TOPICS: their members now (some may have no device). RULES: the users with a device that match the rules, evaluated on up to 10,000 candidates per app and extrapolated beyond (`exact` false). Emails of a USERS rule are matched to the users of the apps; unknown ones answer 8393 with `unknownUsers`.",
        "operationId": "PushCampaignsAdminController_estimateAudience",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimatePushAudienceDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reach per app and in total.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushAudienceEstimateDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data or an audience of other apps.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8393",
                        "message": "A segment or topic of the audience does not exist or is not of the campaign apps."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Estimate the reach of an audience",
        "tags": [
          "Push campaigns admin"
        ]
      }
    },
    "/admin/push-campaigns/{campaignId}": {
      "get": {
        "description": "With its progress (counters) and its opens.",
        "operationId": "PushCampaignsAdminController_getCampaign",
        "parameters": [
          {
            "name": "campaignId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e7a0",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushCampaignDetailDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The campaign does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8390",
                        "message": "Push campaign not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a push campaign",
        "tags": [
          "Push campaigns admin"
        ]
      },
      "patch": {
        "description": "Only DRAFT or SCHEDULED; the apps do not change. Moving `scheduleAt` alone keeps the same time until it expires.",
        "operationId": "PushCampaignsAdminController_updateCampaign",
        "parameters": [
          {
            "name": "campaignId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e7a0",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePushCampaignRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Campaign after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushCampaignAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data, schedule or audience.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8392",
                        "message": "The campaign must be scheduled in the future, within the allowed range, and expire after it starts."
                      },
                      {
                        "code": "8393",
                        "message": "A segment or topic of the audience does not exist or is not of the campaign apps."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The campaign does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8390",
                        "message": "Push campaign not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The campaign already started or ended.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8391",
                        "message": "The push campaign already started or ended; only drafts and scheduled ones change."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a push campaign",
        "tags": [
          "Push campaigns admin"
        ]
      }
    },
    "/admin/push-campaigns/{campaignId}/cancel": {
      "post": {
        "description": "Only DRAFT or SCHEDULED: once it starts sending it cannot be stopped.",
        "operationId": "PushCampaignsAdminController_cancelCampaign",
        "parameters": [
          {
            "name": "campaignId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e7a0",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushCampaignAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The campaign does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8390",
                        "message": "Push campaign not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The campaign already started or ended.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8391",
                        "message": "The push campaign already started or ended; only drafts and scheduled ones change."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Cancel a push campaign",
        "tags": [
          "Push campaigns admin"
        ]
      }
    },
    "/admin/push-templates": {
      "get": {
        "description": "Paginated by event. `applicationIds` (comma-separated) keeps the templates of any of those apps; deleted ones only with includeDeleted.",
        "operationId": "PushTemplatesAdminController_getTemplates",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the items shown in any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          },
          {
            "name": "includeDeleted",
            "required": false,
            "in": "query",
            "description": "Also returns soft-deleted items",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "eventKey",
            "required": false,
            "in": "query",
            "schema": {
              "example": "SETTLEMENT_SUCCESSFUL",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of templates.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplatesPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List push templates",
        "tags": [
          "Push templates admin"
        ]
      },
      "post": {
        "description": "Multipart: `data` (JSON of the template) and an optional PNG `pushImage`. The navigation must be a route of the deeplink catalog of every app; its values may be {variable} of the event.",
        "operationId": "PushTemplatesAdminController_createTemplate",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/PushTemplateMultipartDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplateAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data, navigation or image.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "An app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The event already has a template in one of the apps.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8371",
                        "message": "Another push template already uses this event in one of the apps."
                      }
                    ]
                  }
                }
              }
            }
          },
          "500": {
            "description": "The image could not be uploaded.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7619",
                        "message": "Error uploading file."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a push template",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/stats": {
      "get": {
        "description": "Sent, failed, invalid tokens and opens per template and DAY / WEEK / MONTH, in the timezone of the app (or the default one). `eventKeys` is comma-separated.",
        "operationId": "PushTemplatesAdminController_getStats",
        "parameters": [
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-01T00:00:00.000Z",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-31T23:59:59.000Z",
              "type": "string"
            }
          },
          {
            "name": "granularity",
            "required": true,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "DAY",
                "WEEK",
                "MONTH"
              ]
            }
          },
          {
            "name": "eventKeys",
            "required": false,
            "in": "query",
            "description": "Comma-separated events. Missing: every event",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Series per template.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushStatsResponseDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Push stats per template",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/metrics/{eventKey}": {
      "get": {
        "description": "Totals in a range (up to 180 days): sends from the counters; opens, where they happened and the devices from the raw opens, with the optional device filters.",
        "operationId": "PushTemplatesAdminController_getMetrics",
        "parameters": [
          {
            "name": "eventKey",
            "required": true,
            "in": "path",
            "schema": {
              "example": "SETTLEMENT_SUCCESSFUL",
              "type": "string"
            }
          },
          {
            "name": "from",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-01T00:00:00.000Z",
              "type": "string"
            }
          },
          {
            "name": "to",
            "required": true,
            "in": "query",
            "schema": {
              "example": "2026-10-31T23:59:59.000Z",
              "type": "string"
            }
          },
          {
            "name": "platform",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ios",
                "android",
                "unknown"
              ]
            }
          },
          {
            "name": "osVersion",
            "required": false,
            "in": "query",
            "schema": {
              "example": "17.5",
              "type": "string"
            }
          },
          {
            "name": "appVersion",
            "required": false,
            "in": "query",
            "schema": {
              "example": "3.12.0",
              "type": "string"
            }
          },
          {
            "name": "model",
            "required": false,
            "in": "query",
            "schema": {
              "example": "iPhone15,2",
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "description": "Missing: every app",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metrics.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushMetricsDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Metrics of a push template",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/legacy": {
      "get": {
        "description": "The `applications.pushs` of the app, by event, to import them as v2 templates.",
        "operationId": "PushTemplatesAdminController_getLegacyTemplates",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "query",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Legacy templates.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/LegacyPushTemplateDto"
                          }
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Legacy templates of an app",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/test-devices": {
      "get": {
        "description": "Devices of the users of an app (their last login), the last registered first, to pick the one of a test push. `search` matches part of the alias the app sent (the email) or the start of the subjectId. Only the end of each token is shown.",
        "operationId": "PushTemplatesAdminController_getTestDevices",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationId",
            "required": true,
            "in": "query",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          },
          {
            "name": "search",
            "required": false,
            "in": "query",
            "description": "Part of the alias the app sent (the email) or the start of the subjectId",
            "schema": {
              "example": "kevin@",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of devices.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushDevicesPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Devices for the test push",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/settings/apps/{applicationId}": {
      "get": {
        "description": "Fixed variables per template (e.g. the currency) and the Android channel / iOS sound of each logical channel.",
        "operationId": "PushTemplatesAdminController_getAppSettings",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Push settings.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushAppSettingsViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Push settings of an app",
        "tags": [
          "Push templates admin"
        ]
      },
      "put": {
        "description": "Replaces both the variables and the channels. A channel the app does not declare uses its default channel.",
        "operationId": "PushTemplatesAdminController_setAppSettings",
        "parameters": [
          {
            "name": "applicationId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetPushAppSettingsRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Push settings saved.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushAppSettingsViewDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Replace the push settings of an app",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/{templateId}": {
      "get": {
        "description": "Raw template, to edit it; also when it was deleted (with deletedAt).",
        "operationId": "PushTemplatesAdminController_getTemplate",
        "parameters": [
          {
            "name": "templateId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e700",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The template.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplateAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8370",
                        "message": "Push template not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a push template",
        "tags": [
          "Push templates admin"
        ]
      },
      "patch": {
        "description": "Multipart: `data` with only the fields to change (never eventKey nor applicationIds) and, optionally, a new `pushImage`; `removeImage: true` removes it.",
        "operationId": "PushTemplatesAdminController_updateTemplate",
        "parameters": [
          {
            "name": "templateId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e700",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/PushTemplateMultipartDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplateAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data, navigation or image.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8370",
                        "message": "Push template not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The template was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8372",
                        "message": "The push template was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a push template",
        "tags": [
          "Push templates admin"
        ]
      },
      "delete": {
        "description": "Logical: the event falls back to the legacy template of the app, if any.",
        "operationId": "PushTemplatesAdminController_deleteTemplate",
        "parameters": [
          {
            "name": "templateId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e700",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplateDeletedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8370",
                        "message": "Push template not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The template was already deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8372",
                        "message": "The push template was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Delete a push template",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/test": {
      "post": {
        "description": "Sends the template as it is in the editor (saved or not) once to a device: the FCM `token` pasted or the device of the user `subjectId` of the app (one of the two), with the channel and fixed variables of the app. It is not kept in the inbox nor counted in the metrics. A new image is only tried once saved: `imageUrl` takes the uploaded one. A critical variable without value answers 422 (7019) with `missingVariables`.",
        "operationId": "PushTemplatesAdminController_sendTest",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTestPushDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Push accepted by FCM.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TestPushSentDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data or a token FCM does not accept.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7162",
                        "message": "Invalid registration token, please verify data and try again."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The app does not exist or the user has no device in it.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7700",
                        "message": "Project config not found."
                      },
                      {
                        "code": "8380",
                        "message": "The user has no device registered for push in the app."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Send a test push to a device",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/admin/push-templates/{templateId}/status": {
      "patch": {
        "description": "An inactive template is not sent; the event uses the legacy template of the app, if any.",
        "operationId": "PushTemplatesAdminController_updateTemplateStatus",
        "parameters": [
          {
            "name": "templateId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f1c2a9e4b0a1b2c3d4e700",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Template after the change.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PushTemplateAdminDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8370",
                        "message": "Push template not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The template was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8372",
                        "message": "The push template was deleted."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate a push template",
        "tags": [
          "Push templates admin"
        ]
      }
    },
    "/topics/track": {
      "post": {
        "description": "Registers the user of the token in segmentation topics (for example, that a promotion was viewed). Asynchronous; only the active topics that allow client tracking count, the rest are ignored in silence. Always answers 202.",
        "operationId": "TopicsController_trackTopics",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackTopicsRequestDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Topics received.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Track topics of the user",
        "tags": [
          "Banners"
        ]
      }
    },
    "/admin/topics": {
      "post": {
        "description": "A signal of something the user did (the key is immutable and is what the code tracks). allowClientTracking lets the app track it with POST /topics/track.",
        "operationId": "TopicsAdminController_createTopic",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTopicRequestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Topic created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The key already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8321",
                        "message": "A topic with this key already exists."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a topic",
        "tags": [
          "Banners admin"
        ]
      },
      "get": {
        "operationId": "TopicsAdminController_getTopics",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the ones of any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of topics.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicsPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List topics",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/topics/{topicId}": {
      "get": {
        "operationId": "TopicsAdminController_getTopic",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The topic.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a topic",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Only the fields sent change; the key never changes.",
        "operationId": "TopicsAdminController_updateTopic",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTopicRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Topic updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a topic",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/topics/{topicId}/status": {
      "patch": {
        "description": "An inactive topic is ignored by the tracking and stops counting in the segments; its members expire on their own.",
        "operationId": "TopicsAdminController_updateTopicStatus",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Topic updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate a topic",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/topics/{topicId}/members": {
      "post": {
        "description": "Manual lists: up to 1000 user ids per request. New ones are added, existing ones renew their expiration (ttlDays or the topic default).",
        "operationId": "TopicsAdminController_addTopicMembers",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddTopicMembersRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "How many were added and renewed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicMembersAddedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Add members to a topic",
        "tags": [
          "Banners admin"
        ]
      },
      "get": {
        "description": "Current members (not expired, not removed), most recent activity first.",
        "operationId": "TopicsAdminController_getTopicMembers",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of members.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicMembersPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Members of a topic",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/topics/{topicId}/members/{subjectId}": {
      "delete": {
        "description": "Logical: the member stops counting. If the user does the action of the topic again, they are back.",
        "operationId": "TopicsAdminController_removeTopicMember",
        "parameters": [
          {
            "name": "topicId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0aa000000000000000001",
              "type": "string"
            }
          },
          {
            "name": "subjectId",
            "required": true,
            "in": "path",
            "description": "Wallet user id as text",
            "schema": {
              "example": "1234",
              "type": "string"
            }
          },
          {
            "name": "applicationId",
            "required": true,
            "in": "query",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Member removed.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TopicMemberRemovedDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The topic does not exist, or does not apply to the app.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Remove a member from a topic",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/segments": {
      "post": {
        "description": "An audience built from topics: ANY (at least one) or ALL (every topic). Banners reference segments by id.",
        "operationId": "SegmentsAdminController_createSegment",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSegmentRequestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Segment created.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "A topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          },
          "409": {
            "description": "The key already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8331",
                        "message": "A segment with this key already exists."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a segment",
        "tags": [
          "Banners admin"
        ]
      },
      "get": {
        "operationId": "SegmentsAdminController_getSegments",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationIds",
            "required": false,
            "in": "query",
            "description": "Only the ones of any of these apps (comma-separated)",
            "schema": {
              "example": "com.migo.app.sv,com.migo.yayo",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of segments.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentsPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List segments",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/segments/{segmentId}": {
      "get": {
        "operationId": "SegmentsAdminController_getSegment",
        "parameters": [
          {
            "name": "segmentId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0bb000000000000000001",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The segment.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The segment does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8330",
                        "message": "Segment not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a segment",
        "tags": [
          "Banners admin"
        ]
      },
      "patch": {
        "description": "Only the fields sent change; the key never changes. Changing the topics applies at once to everyone who has them.",
        "operationId": "SegmentsAdminController_updateSegment",
        "parameters": [
          {
            "name": "segmentId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0bb000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSegmentRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Segment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The segment or a topic does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8330",
                        "message": "Segment not found."
                      },
                      {
                        "code": "8320",
                        "message": "Topic not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Update a segment",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/segments/{segmentId}/status": {
      "patch": {
        "description": "An inactive segment matches nobody, so the banners that only use it are hidden.",
        "operationId": "SegmentsAdminController_updateSegmentStatus",
        "parameters": [
          {
            "name": "segmentId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0bb000000000000000001",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Segment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The segment does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8330",
                        "message": "Segment not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Activate or deactivate a segment",
        "tags": [
          "Banners admin"
        ]
      }
    },
    "/admin/segments/{segmentId}/members": {
      "get": {
        "description": "Computed from the current members of its active topics: with ANY, who has at least one; with ALL, who has every topic.",
        "operationId": "SegmentsAdminController_getSegmentMembers",
        "parameters": [
          {
            "name": "segmentId",
            "required": true,
            "in": "path",
            "schema": {
              "example": "66f0bb000000000000000001",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "applicationId",
            "required": false,
            "in": "query",
            "schema": {
              "example": "com.migo.app.sv",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of members.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "example": true
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SegmentMembersPageDto"
                        }
                      }
                    }
                  ],
                  "example": {
                    "success": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error — the request body, params or query failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7000",
                        "message": "Check the parameters provided."
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated — the JWT is missing, malformed or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7606",
                        "message": "Invalid access token, please check your token."
                      }
                    ]
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required application or user permission.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "7615",
                        "message": "You do not have permission to access this resource."
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "The segment does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "example": {
                    "success": false,
                    "errors": [
                      {
                        "code": "8330",
                        "message": "Segment not found."
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Members of a segment",
        "tags": [
          "Banners admin"
        ]
      }
    }
  },
  "info": {
    "title": "Wallet Migo API",
    "description": "Public REST gateway for the Migo Payments platform. Routes authenticated traffic to internal microservices over NATS and HTTP, exposing user, card, business, transfer, settlement, device, messaging, configuration, reporting and processor (Volcan) operations.",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "Authentication",
      "description": "Token issuance and refresh for application-level access."
    },
    {
      "name": "Users",
      "description": "User registration, profile, roles, permissions, FCM tokens, OTP and password operations."
    },
    {
      "name": "Users - Cards",
      "description": "Card-related operations scoped to the authenticated user."
    },
    {
      "name": "Cards",
      "description": "Card lifecycle, status, balance, transfers, statements and user permissions."
    },
    {
      "name": "Card Transfers",
      "description": "Operational queries over card movements and transfers."
    },
    {
      "name": "Terminal Payments",
      "description": "Terminal-initiated payment flows."
    },
    {
      "name": "Businesses",
      "description": "Business onboarding, terminals, social documents and uploads."
    },
    {
      "name": "Branches",
      "description": "Branch and branch-code management."
    },
    {
      "name": "Settlements",
      "description": "Daily settlement calculation and listing."
    },
    {
      "name": "Devices",
      "description": "Device registration and association management."
    },
    {
      "name": "Messaging",
      "description": "In-app and real-time messaging endpoints."
    },
    {
      "name": "Reports",
      "description": "Manual and scheduled report generation."
    },
    {
      "name": "Leads",
      "description": "Sales leads and pre-onboarding flow."
    },
    {
      "name": "Files",
      "description": "File generation and upload endpoints."
    },
    {
      "name": "Configurations",
      "description": "Application and merchant configuration access."
    },
    {
      "name": "Volcan",
      "description": "Volcan processor proxy endpoints (card issuing and account operations)."
    },
    {
      "name": "Webhooks",
      "description": "Inbound webhook endpoints from external processors and integrations."
    },
    {
      "name": "Form Integrations",
      "description": "External form integration endpoints (landing/marketing flows)."
    },
    {
      "name": "Health",
      "description": "Service health check."
    },
    {
      "name": "Integrity",
      "description": "Payload integrity hashing and validation utilities."
    }
  ],
  "servers": [
    {
      "url": "https://api.ali.app/rest",
      "description": "Producción"
    },
    {
      "url": "https://ali-qa.ali.app/rest",
      "description": "QA"
    },
    {
      "url": "http://localhost:3010",
      "description": "Local"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "type": "http",
        "name": "Authorization",
        "description": "Enter JWT token",
        "in": "header"
      }
    },
    "schemas": {
      "AuthLoginDto": {
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "description": "Merchant identifier (public key alias) used to authenticate the integration.",
            "example": "merchant-acme-001"
          },
          "signature": {
            "type": "string",
            "description": "Ed25519 digital signature generated by the merchant private key over the login challenge.",
            "example": "MEUCIQD3xS...base64-signature...=="
          }
        },
        "required": [
          "merchant",
          "signature"
        ]
      },
      "RefreshTokenDto": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string",
            "description": "Refresh token previously issued by the authentication service that will be exchanged for a new access token.",
            "example": "<JWT_REFRESH_TOKEN>"
          }
        },
        "required": [
          "refreshToken"
        ]
      },
      "CreateOnboardingSessionDto": {
        "type": "object",
        "properties": {
          "expectedDocumentNumber": {
            "type": "string",
            "description": "Document number the app already knows, e.g. the one of the lead of the invitation code. When the merchant enabled documentMatchEnabled in its identity configuration and the verified document has another number, the verification ends DECLINED with reasonCode DOCUMENT_NUMBER_MISMATCH. Spaces and dashes are ignored.",
            "example": "2546874120101"
          }
        }
      },
      "VolcanWebhookDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "string",
            "description": "Original request identifier generated by Volcan.",
            "example": "REQ-987654321"
          },
          "IdMovimiento": {
            "type": "string",
            "description": "Unique movement identifier from the Volcan processor.",
            "example": "MOV-123456789"
          },
          "Tarjeta": {
            "type": "string",
            "description": "Masked card number related to the movement.",
            "example": "411111******1111"
          },
          "TipoManufactura": {
            "type": "string",
            "description": "Card manufacturing type (e.g. physical, virtual).",
            "example": "FISICA"
          },
          "NumeroCuenta": {
            "type": "string",
            "description": "Bank account number linked to the movement.",
            "example": "0123456789"
          },
          "Importe": {
            "type": "number",
            "description": "Movement amount expressed in the indicated currency.",
            "example": 150.75
          },
          "Moneda": {
            "type": "string",
            "description": "ISO currency code of the movement.",
            "example": "GTQ"
          },
          "FechaHora": {
            "format": "date-time",
            "type": "string",
            "description": "Date and time when the movement occurred, expressed as local Guatemala time (UTC-6). Sent as `dd/MM/yyyy HH:mm:ss`; ISO 8601 is also accepted. It is converted to UTC before being persisted.",
            "example": "26/08/2026 13:14:31"
          },
          "NumeroAutorizacion": {
            "type": "string",
            "description": "Authorization number returned by the issuer.",
            "example": "123456"
          },
          "IdOperacion": {
            "type": "string",
            "description": "Unique, incremental operation identifier assigned by the financial network.",
            "example": "4321"
          },
          "CodigoRespuesta": {
            "type": "string",
            "description": "Response code returned by the financial network. \"00\" means the transaction was approved; any other value means it was declined.",
            "example": "00"
          },
          "POSEntryMode": {
            "type": "string",
            "description": "POS entry mode code.",
            "example": "051"
          },
          "ClaveMovimiento": {
            "type": "string",
            "description": "Movement key identifying the type of operation.",
            "example": "COMPRA"
          },
          "CodigoProceso": {
            "type": "string",
            "description": "Process code for the movement.",
            "example": "000000"
          },
          "NumeroAfiliacionComercio": {
            "type": "string",
            "description": "Merchant affiliation number.",
            "example": "0123456789"
          },
          "NombreComercio": {
            "type": "string",
            "description": "Merchant business name.",
            "example": "Tienda Demo"
          },
          "MCC": {
            "type": "string",
            "description": "Merchant Category Code (ISO 18245).",
            "example": "5411"
          },
          "Nombre": {
            "type": "string",
            "description": "First name of the cardholder.",
            "example": "Juan"
          },
          "PrimerApellido": {
            "type": "string",
            "description": "First surname of the cardholder.",
            "example": "Perez"
          },
          "SegundoApellido": {
            "type": "string",
            "description": "Second surname of the cardholder.",
            "example": "Lopez"
          },
          "Telefono": {
            "type": "string",
            "description": "Cardholder phone number.",
            "example": "+50212345678"
          },
          "Correo": {
            "type": "string",
            "description": "Cardholder email address.",
            "example": "juan.perez@example.com"
          },
          "TipoMedioAcceso": {
            "type": "string",
            "description": "Type of access medium used in the transaction.",
            "example": "TARJETA"
          },
          "MedioAcceso": {
            "type": "string",
            "description": "Access medium identifier (terminal, channel, etc.).",
            "example": "POS-001"
          },
          "InstitucionOrdenante": {
            "type": "string",
            "description": "Ordering financial institution code.",
            "example": "40012"
          },
          "InstitucionBeneficiaria": {
            "type": "string",
            "description": "Beneficiary financial institution code.",
            "example": "40044"
          },
          "ClaveRastreo": {
            "type": "string",
            "description": "Tracking key for the operation.",
            "example": "CLAVE-001"
          },
          "NombreOrdenante": {
            "type": "string",
            "description": "Full name of the ordering party.",
            "example": "Juan Perez Lopez"
          },
          "RfcCurpOrdenante": {
            "type": "string",
            "description": "Tax identifier of the ordering party (RFC/CURP).",
            "example": "PEPJ800101ABC"
          },
          "NombreBeneficiario": {
            "type": "string",
            "description": "Full name of the beneficiary.",
            "example": "Maria Garcia"
          },
          "CuentaBeneficiario": {
            "type": "string",
            "description": "Beneficiary account number.",
            "example": "9876543210"
          },
          "RfcCurpBeneficiario": {
            "type": "string",
            "description": "Tax identifier of the beneficiary (RFC/CURP).",
            "example": "GAMM900202XYZ"
          },
          "ConceptoPago": {
            "type": "string",
            "description": "Payment concept or description.",
            "example": "Pago de servicios"
          },
          "ReferenciaNumerica": {
            "type": "string",
            "description": "Numeric reference associated with the payment.",
            "example": "0000123456"
          }
        }
      },
      "MigoWebhookDto": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "description": "Migo transaction identifier (externalId of the bank transfer).",
            "example": "CGhq3dQFywHmBaCY58bDu"
          },
          "status": {
            "type": "string",
            "description": "Status reported by Migo for the bank transfer (format TBD).",
            "example": "completed"
          },
          "additionalData": {
            "type": "object",
            "description": "Raw provider payload kept for traceability (format TBD).",
            "example": {}
          }
        },
        "required": [
          "uid"
        ]
      },
      "ExternalUserRegistrationDto": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "string",
            "description": "Unique device identifier of the client that initiated the registration.",
            "example": "device-9f3b2c1a-7d8e-4f0a"
          },
          "invitationCode": {
            "type": "string",
            "description": "Invitation code generated by an existing branch operator that grants the user access to register.",
            "example": "INV-2026-ABC123"
          },
          "username": {
            "type": "string",
            "description": "Email address used as the username for the new user account.",
            "example": "user@example.com"
          },
          "password": {
            "type": "string",
            "description": "Account password. Must satisfy the platform password policy.",
            "example": "StrongP@ssw0rd!"
          },
          "confirmPassword": {
            "type": "string",
            "description": "Password confirmation. Must match the value of the password field.",
            "example": "StrongP@ssw0rd!"
          },
          "nit": {
            "type": "string",
            "description": "Optional tax identification number (NIT) of the user.",
            "example": "1234567-8"
          },
          "termsAndConditionsAccepted": {
            "type": "boolean",
            "description": "Indicates whether the user accepted the terms and conditions during registration.",
            "example": true
          },
          "termsVersion": {
            "type": "string",
            "description": "Version of the terms accepted during registration.",
            "example": "v1"
          },
          "termsAcceptedAt": {
            "type": "string",
            "description": "ISO-8601 timestamp when the terms were accepted.",
            "example": "2026-09-20T15:30:00.000Z"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude captured for the onboarding event.",
            "example": 14.634915
          },
          "longitude": {
            "type": "number",
            "description": "Longitude captured for the onboarding event.",
            "example": -90.506882
          },
          "verificationId": {
            "type": "string",
            "description": "Identity verification taken with the invitation code of an existing lead. It is linked to the new account, also while the provider reviews it.",
            "example": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
            "format": "uuid"
          }
        },
        "required": [
          "deviceId",
          "invitationCode",
          "username",
          "password",
          "confirmPassword"
        ]
      },
      "UpdateRoleDto": {
        "type": "object",
        "properties": {
          "addPermissions": {
            "description": "List of permission identifiers to add to the role.",
            "example": [
              4,
              5
            ],
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "removePermissions": {
            "description": "List of permission identifiers to remove from the role.",
            "example": [
              1
            ],
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "description": {
            "type": "string",
            "description": "Updated human-readable description of the role.",
            "example": "Updated administrator role description"
          }
        }
      },
      "InvitationCodeGenerateDto": {
        "type": "object",
        "properties": {
          "branchId": {
            "type": "number",
            "description": "Identifier of the branch the invitation code is generated for.",
            "example": 12345
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "cashier"
            ],
            "description": "Role that the invited user will be assigned upon registration.",
            "example": "admin"
          }
        },
        "required": [
          "branchId",
          "role"
        ]
      },
      "UserLoginDto": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Email address used as username",
            "example": "john@example.com"
          },
          "password": {
            "type": "string",
            "description": "User password",
            "example": "SecureP@ss1"
          },
          "merchant": {
            "type": "string",
            "description": "Merchant identifier for multi-tenant login",
            "example": "migo"
          },
          "accessTokenTtl": {
            "type": "number",
            "description": "Access token time-to-live in seconds",
            "example": 3600
          },
          "refreshTokenTtl": {
            "type": "number",
            "description": "Refresh token time-to-live in seconds",
            "example": 86400
          },
          "failedLoginAttempts": {
            "type": "number",
            "description": "Maximum number of failed login attempts before suspension",
            "example": 5
          },
          "defaultSuspensionDuration": {
            "type": "number",
            "description": "Default suspension duration in minutes after max failed attempts",
            "example": 30
          }
        },
        "required": [
          "username",
          "password"
        ]
      },
      "UserRefreshTokenDto": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string",
            "description": "Refresh token obtained during login",
            "example": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
          },
          "merchant": {
            "type": "string",
            "description": "Merchant identifier for multi-tenant refresh",
            "example": "migo"
          },
          "accessTokenTtl": {
            "type": "number",
            "description": "New access token time-to-live in seconds",
            "example": 3600
          },
          "refreshTokenTtl": {
            "type": "number",
            "description": "New refresh token time-to-live in seconds",
            "example": 86400
          }
        },
        "required": [
          "refreshToken"
        ]
      },
      "ExternalLinkCardUserDto": {
        "type": "object",
        "properties": {
          "card": {
            "type": "string",
            "description": "Card number to be linked to the user account. Must pass card verification rules.",
            "example": "4111111111111111"
          },
          "alias": {
            "type": "string",
            "description": "Optional alias used to identify the card within the user account.",
            "example": "My Personal Card"
          }
        },
        "required": [
          "card"
        ]
      },
      "RequestOtpDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address that will receive the one-time password.",
            "example": "user@example.com"
          },
          "purpose": {
            "type": "string",
            "description": "Purpose of the OTP request (e.g. password reset, sensitive operation).",
            "example": "password_reset"
          },
          "channel": {
            "type": "string",
            "description": "Channel selected to deliver the OTP. Defaults to email when omitted.",
            "enum": [
              "email",
              "whatsapp"
            ],
            "example": "email"
          }
        },
        "required": [
          "email",
          "purpose"
        ]
      },
      "VerifyOtpDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address that received the one-time password.",
            "example": "user@example.com"
          },
          "otp": {
            "type": "string",
            "description": "One-time password value previously delivered to the user.",
            "example": "123456"
          },
          "purpose": {
            "type": "string",
            "description": "Purpose that matches the one declared when the OTP was requested.",
            "example": "password_reset"
          },
          "channel": {
            "type": "string",
            "description": "Channel used to validate the OTP. Defaults to email when omitted.",
            "enum": [
              "email",
              "whatsapp"
            ],
            "example": "email"
          }
        },
        "required": [
          "email",
          "otp",
          "purpose"
        ]
      },
      "VerifyPasswordDto": {
        "type": "object",
        "properties": {
          "password": {
            "type": "string",
            "description": "Current password used to verify the identity of the authenticated user.",
            "example": "StrongP@ssw0rd!"
          }
        },
        "required": [
          "password"
        ]
      },
      "RecoveryPasswordDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email of the account whose password is being recovered.",
            "example": "user@example.com"
          },
          "newPassword": {
            "type": "string",
            "description": "New password value that will replace the previous one.",
            "example": "NewStrongP@ssw0rd!"
          },
          "confirmPassword": {
            "type": "string",
            "description": "Confirmation of the new password. Must match newPassword.",
            "example": "NewStrongP@ssw0rd!"
          },
          "token": {
            "type": "object",
            "description": "OTP or recovery token previously issued to authorize the password change.",
            "example": "123456"
          }
        },
        "required": [
          "email"
        ]
      },
      "AssignThirdPartyCardPayloadDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email of the cardholder owning the third-party card.",
            "example": "cardholder@example.com"
          },
          "suffix": {
            "type": "string",
            "description": "Last four digits of the third-party card.",
            "example": "1234"
          },
          "alias": {
            "type": "string",
            "description": "Alias used to identify the third-party card within the user account.",
            "example": "Family Card"
          }
        },
        "required": [
          "email",
          "suffix",
          "alias"
        ]
      },
      "UpdateThirdPartyCardDto": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "description": "New alias for the linked third-party card.",
            "example": "Updated Family Card"
          }
        },
        "required": [
          "alias"
        ]
      },
      "UpdateOwnerDataDto": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "New first name of the owner.",
            "example": "Claudia"
          },
          "lastName": {
            "type": "string",
            "description": "New last name of the owner.",
            "example": "Ulin"
          },
          "birthdate": {
            "type": "string",
            "description": "Birthdate of the owner, as an ISO date. It cannot be in the future.",
            "example": "1990-05-14"
          },
          "maritalStatus": {
            "type": "string",
            "description": "Marital status. Accepts the stored value (single, married, divorced, widowed, separated) or its Spanish wording (soltera, casado...).",
            "example": "casada"
          }
        }
      },
      "UpdateUserByIntegratorResponseDto": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "number",
            "description": "Identifier of the updated user (the same `userId` of the path).",
            "example": 1
          },
          "updatedFields": {
            "description": "Fields that actually changed. Empty when every value sent was already stored.",
            "example": [
              "address",
              "neighborhood"
            ],
            "type": "array",
            "items": {
              "type": "array"
            }
          },
          "firstName": {
            "type": "string",
            "example": "Claudia"
          },
          "lastName": {
            "type": "string",
            "example": "Ulin Pérez"
          },
          "birthdate": {
            "type": "string",
            "example": "1990-05-14T00:00:00.000Z",
            "nullable": true
          },
          "maritalStatus": {
            "type": "string",
            "description": "single | married | divorced | widowed | separated",
            "example": "married",
            "nullable": true
          },
          "gender": {
            "type": "string",
            "description": "F | M | OTHER",
            "example": "F",
            "nullable": true
          },
          "address": {
            "type": "string",
            "example": "Calzada Roosevelt 22-43",
            "nullable": true
          },
          "neighborhood": {
            "type": "string",
            "example": "Zona 11",
            "nullable": true
          },
          "placeBirth": {
            "type": "string",
            "example": "Guatemala City",
            "nullable": true
          }
        },
        "required": [
          "userId",
          "updatedFields",
          "firstName",
          "lastName"
        ]
      },
      "PhoneVerificationDto": {
        "type": "object",
        "properties": {
          "verifiedAt": {
            "type": "string",
            "description": "When the integrator verified the new number (ISO 8601). Must be recent and not in the future",
            "example": "2026-11-03T15:04:05Z"
          },
          "reference": {
            "type": "string",
            "description": "Identifier of the verification on the integrator side",
            "example": "otp-7f3a2c"
          }
        },
        "required": [
          "verifiedAt",
          "reference"
        ]
      },
      "UpdateUserByIntegratorDto": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name",
            "example": "Claudia"
          },
          "lastName": {
            "type": "string",
            "description": "Last name",
            "example": "Ulin Pérez"
          },
          "birthdate": {
            "type": "string",
            "description": "Birthdate (ISO 8601), cannot be in the future",
            "example": "1990-05-14"
          },
          "maritalStatus": {
            "type": "string",
            "description": "Marital status, stored value or Spanish wording (single | married | divorced | widowed | separated, soltero/a, casado/a, ...)",
            "example": "casada"
          },
          "gender": {
            "type": "string",
            "enum": [
              "F",
              "M",
              "OTHER"
            ],
            "description": "Gender",
            "example": "F"
          },
          "address": {
            "type": "string",
            "description": "Residential address",
            "example": "5a Avenida 12-34, Zona 1"
          },
          "neighborhood": {
            "type": "string",
            "description": "Neighborhood",
            "example": "Zona 1"
          },
          "placeBirth": {
            "type": "string",
            "description": "Place of birth",
            "example": "Guatemala City"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Mobile phone number, digits only (7 to 15), as stored at registration. Requires phoneVerification",
            "example": "50212345678"
          },
          "phoneVerification": {
            "description": "Required with phoneNumber, and only accepted with it: the integrator verified the new number with its own OTP",
            "allOf": [
              {
                "$ref": "#/components/schemas/PhoneVerificationDto"
              }
            ]
          }
        }
      },
      "UpdateUserEmailDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "New email address that will replace the current one.",
            "example": "new.address@example.com"
          }
        },
        "required": [
          "email"
        ]
      },
      "CreateUserBankDto": {
        "type": "object",
        "properties": {
          "accountNumber": {
            "type": "string",
            "description": "Bank account number.",
            "example": "0123456789"
          },
          "accountType": {
            "type": "string",
            "description": "Type of bank account.",
            "enum": [
              "MONETARY",
              "SAVINGS"
            ],
            "example": "MONETARY"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code.",
            "example": "GTQ"
          },
          "holderName": {
            "type": "string",
            "description": "Name of the account holder.",
            "example": "John Doe"
          },
          "alias": {
            "type": "string",
            "description": "Optional alias the user assigns to the account.",
            "example": "My payroll account"
          },
          "bankCode": {
            "type": "string",
            "description": "Code that identifies the bank.",
            "example": "001"
          },
          "bankName": {
            "type": "string",
            "description": "Human readable name of the bank.",
            "example": "Banco Industrial"
          }
        },
        "required": [
          "accountNumber",
          "accountType",
          "currency",
          "holderName",
          "bankCode",
          "bankName"
        ]
      },
      "UpdateUserBankAliasDto": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "description": "New alias for the bank account.",
            "example": "My savings account"
          }
        },
        "required": [
          "alias"
        ]
      },
      "SetUserBankFavoriteDto": {
        "type": "object",
        "properties": {
          "favorite": {
            "type": "boolean",
            "description": "Desired favorite state. Send false to unset the account as favorite; send true or omit it to mark it as favorite. Multiple favorite accounts per user are allowed.",
            "example": true
          }
        }
      },
      "CreateBusinessesDto": {
        "type": "object",
        "properties": {
          "serialNumber": {
            "type": "string",
            "description": "Serial number of the device or registration",
            "example": "SN-2025-001"
          },
          "taxRegime": {
            "type": "string",
            "description": "Tax regime of the business",
            "example": "general"
          },
          "nit": {
            "type": "string",
            "description": "Tax identification number (NIT)",
            "example": "1234567-8"
          },
          "businessName": {
            "type": "string",
            "description": "Legal business name",
            "example": "Comercial Guatemala S.A."
          },
          "economicActivity": {
            "type": "string",
            "description": "Economic activity of the business",
            "example": "Retail sales"
          },
          "canInvoice": {
            "type": "string",
            "description": "Whether the business can issue invoices (must be \"si\")",
            "example": "si"
          },
          "hasRegime": {
            "type": "string",
            "description": "Whether the business has a tax regime (must be \"si\")",
            "example": "si"
          },
          "lastRtuUpdateDate": {
            "type": "string",
            "description": "Last RTU update date in YYYY-MM-DD format",
            "example": "2025-01-15"
          },
          "rtuType": {
            "type": "string",
            "description": "Type of RTU registration",
            "example": "standard"
          },
          "country": {
            "type": "string",
            "enum": [
              "ARG",
              "BOL",
              "BRA",
              "CHL",
              "COL",
              "CRI",
              "CUB",
              "DOM",
              "ECU",
              "SLV",
              "GTM",
              "HTI",
              "HND",
              "MEX",
              "NIC",
              "PAN",
              "PRY",
              "PER",
              "PRI",
              "URY",
              "VEN"
            ],
            "description": "Country where the business operates",
            "example": "GTM"
          },
          "partner": {
            "type": "string",
            "enum": [
              "tributax",
              "apex",
              "cbc",
              "migo",
              "ge",
              "cbc_fge",
              "cmi"
            ],
            "description": "Partner associated with the business",
            "example": "migo"
          },
          "commercialNameTxt": {
            "type": "string",
            "description": "Commercial or trade name",
            "example": "Tienda Migo"
          },
          "phone1": {
            "type": "string",
            "description": "Primary phone number",
            "example": "+50212345678"
          },
          "email": {
            "type": "string",
            "description": "Business email address",
            "example": "business@example.com"
          },
          "addressTxt": {
            "type": "string",
            "description": "Physical address of the business",
            "example": "5a Avenida 12-34, Zona 1, Guatemala City"
          },
          "clientId": {
            "type": "string",
            "description": "Client application identifier",
            "example": "app-001"
          }
        },
        "required": [
          "taxRegime",
          "businessName",
          "canInvoice",
          "hasRegime",
          "lastRtuUpdateDate",
          "country",
          "partner",
          "commercialNameTxt",
          "phone1",
          "email",
          "addressTxt"
        ]
      },
      "CreateBussinessFromLeadDto": {
        "type": "object",
        "properties": {
          "authUserId": {
            "type": "number",
            "description": "Auth user identifier of the lead owner",
            "example": 1
          },
          "businesses": {
            "description": "List of businesses to create from the lead",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateBusinessesDto"
            }
          }
        },
        "required": [
          "authUserId",
          "businesses"
        ]
      },
      "UpdateTerminalDto": {
        "type": "object",
        "properties": {
          "newDeviceId": {
            "type": "string",
            "description": "New device identifier to assign to the terminal.",
            "example": "device-abc123"
          },
          "externalTerminalId": {
            "type": "string",
            "description": "External terminal identifier provided by the payment processor.",
            "example": "EXT-TERM-987654"
          },
          "isActive": {
            "type": "boolean",
            "description": "Flag indicating whether the terminal is active.",
            "example": true
          },
          "terminalType": {
            "type": "number",
            "enum": [
              0
            ],
            "example": 0,
            "description": "Terminal hardware/software type."
          }
        },
        "required": [
          "isActive"
        ]
      },
      "UpdateSettlementConfigDto": {
        "type": "object",
        "properties": {
          "accountType": {
            "type": "string",
            "enum": [
              "card",
              "wallet",
              "external"
            ],
            "description": "Settlement vehicle the terminal will use.",
            "example": "card"
          },
          "accountId": {
            "type": "number",
            "description": "Destination account: card.id or wallet.id. Required for card and wallet; omitted for external.",
            "example": 100
          }
        },
        "required": [
          "accountType"
        ]
      },
      "UpdateCommerceDataDto": {
        "type": "object",
        "properties": {
          "branchName": {
            "type": "string",
            "description": "New commercial name of the branch.",
            "example": "Sucursal Zona 10"
          },
          "legalName": {
            "type": "string",
            "description": "New legal name of the commerce.",
            "example": "TIENDA DEMO, SOCIEDAD ANONIMA"
          },
          "nit": {
            "type": "string",
            "description": "New NIT of the commerce.",
            "example": "9876543-2"
          }
        }
      },
      "UpdateCommerceRegimeDto": {
        "type": "object",
        "properties": {
          "regime": {
            "type": "string",
            "enum": [
              "general",
              "small_taxpayer",
              "exempt",
              "small_electronic_taxpayer",
              "salaried",
              "natural_person_non_declarant",
              "natural_person",
              "legal_entity",
              "iva",
              "other_income"
            ],
            "example": "small_taxpayer",
            "description": "Slug of the regime to assign to the commerce. It must exist in the regime catalog."
          }
        },
        "required": [
          "regime"
        ]
      },
      "UploadFilesDto": {
        "type": "object",
        "properties": {
          "businessPhoto": {
            "type": "string",
            "description": "Business photo file uploaded via multipart/form-data.",
            "format": "binary"
          },
          "utilityBill": {
            "type": "string",
            "description": "Utility bill file uploaded via multipart/form-data.",
            "format": "binary"
          }
        }
      },
      "UploadSocialDto": {
        "type": "object",
        "properties": {
          "urlFacebook": {
            "type": "string",
            "description": "Facebook profile URL of the business.",
            "example": "https://facebook.com/migopayments"
          },
          "urlInstagram": {
            "type": "string",
            "description": "Instagram profile URL of the business.",
            "example": "https://instagram.com/migopayments"
          },
          "urlTwitter": {
            "type": "string",
            "description": "Twitter/X profile URL of the business.",
            "example": "https://twitter.com/migopayments"
          },
          "urlLinkedIn": {
            "type": "string",
            "description": "LinkedIn profile URL of the business.",
            "example": "https://linkedin.com/company/migopayments"
          },
          "urlTikTok": {
            "type": "string",
            "description": "TikTok profile URL of the business.",
            "example": "https://tiktok.com/@migopayments"
          },
          "urlWebsite": {
            "type": "string",
            "description": "Official website URL of the business.",
            "example": "https://migopayments.com"
          }
        }
      },
      "CommerceWebhookHeaderDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "X-Api-Key",
            "pattern": "^[A-Za-z0-9-]{1,64}$"
          },
          "value": {
            "type": "string",
            "example": "my-integration-key",
            "maxLength": 512
          }
        },
        "required": [
          "name",
          "value"
        ]
      },
      "CreatedCommerceWebhookResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "65f1c2a9e4b0a1b2c3d4e5f6"
          },
          "commerceId": {
            "type": "number",
            "example": 335
          },
          "url": {
            "type": "string",
            "description": "Query string values are masked.",
            "example": "https://erp.example.com/hooks/migo"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "terminal.payment.approved",
                "terminal.payment.denied"
              ]
            }
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "headers": {
            "description": "Header values are masked to their last 4 characters.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommerceWebhookHeaderDto"
            }
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-01T15:04:05.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-01T15:04:05.000Z"
          },
          "secret": {
            "type": "string",
            "description": "Signing secret (HMAC-SHA256). Shown only in this response: store it now.",
            "example": "whsec_<shown-only-once>"
          }
        },
        "required": [
          "id",
          "commerceId",
          "url",
          "events",
          "enabled",
          "headers",
          "createdAt",
          "updatedAt",
          "secret"
        ]
      },
      "CreateCommerceWebhookRequestDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Public HTTPS URL on port 443 that receives the events.",
            "example": "https://erp.example.com/hooks/migo",
            "maxLength": 2048
          },
          "events": {
            "type": "array",
            "description": "Events delivered to this URL.",
            "example": [
              "terminal.payment.approved",
              "terminal.payment.denied"
            ],
            "items": {
              "type": "string",
              "enum": [
                "terminal.payment.approved",
                "terminal.payment.denied"
              ]
            }
          },
          "headers": {
            "description": "Up to 5 custom headers sent with every delivery.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommerceWebhookHeaderDto"
            }
          }
        },
        "required": [
          "url",
          "events"
        ]
      },
      "CommerceWebhookResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "65f1c2a9e4b0a1b2c3d4e5f6"
          },
          "commerceId": {
            "type": "number",
            "example": 335
          },
          "url": {
            "type": "string",
            "description": "Query string values are masked.",
            "example": "https://erp.example.com/hooks/migo"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "terminal.payment.approved",
                "terminal.payment.denied"
              ]
            }
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "headers": {
            "description": "Header values are masked to their last 4 characters.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommerceWebhookHeaderDto"
            }
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-01T15:04:05.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-01T15:04:05.000Z"
          }
        },
        "required": [
          "id",
          "commerceId",
          "url",
          "events",
          "enabled",
          "headers",
          "createdAt",
          "updatedAt"
        ]
      },
      "UpdateCommerceWebhookRequestDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "example": "https://erp.example.com/hooks/migo-v2",
            "maxLength": 2048
          },
          "events": {
            "type": "array",
            "example": [
              "terminal.payment.approved"
            ],
            "items": {
              "type": "string",
              "enum": [
                "terminal.payment.approved",
                "terminal.payment.denied"
              ]
            }
          },
          "enabled": {
            "type": "boolean",
            "description": "false pauses the webhook.",
            "example": false
          },
          "headers": {
            "description": "Replaces the whole list; an empty list removes every header.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommerceWebhookHeaderDto"
            }
          }
        }
      },
      "DeletedCommerceWebhookResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "65f1c2a9e4b0a1b2c3d4e5f6"
          }
        },
        "required": [
          "id"
        ]
      },
      "LinkCardUserDto": {
        "type": "object",
        "properties": {
          "Card": {
            "type": "number",
            "description": "Card number (PAN) to link to the customer.",
            "example": 4512345678901234
          },
          "AccessEntry": {
            "type": "string",
            "description": "Alternative access entry (e.g., card alias or token).",
            "example": "ACC-12345"
          },
          "TypeAccessEntry": {
            "type": "string",
            "description": "Type of the access entry identifier.",
            "example": "TOKEN"
          },
          "Name": {
            "type": "string",
            "description": "First name of the cardholder.",
            "example": "John"
          },
          "FirstLastName": {
            "type": "string",
            "description": "First last name (paternal surname) of the cardholder.",
            "example": "Doe"
          },
          "SecondLastName": {
            "type": "string",
            "description": "Second last name (maternal surname) of the cardholder.",
            "example": "Smith"
          },
          "CardholderName": {
            "type": "string",
            "description": "Name as embossed on the card.",
            "example": "JOHN D SMITH"
          },
          "Nationality": {
            "type": "string",
            "description": "Nationality of the cardholder (ISO country code).",
            "example": "GTM"
          },
          "PlaceOfBirth": {
            "type": "string",
            "description": "Place of birth (3-letter entity code).",
            "example": "GUA"
          },
          "Birthdate": {
            "type": "string",
            "description": "Date of birth in YYYY-MM-DD format.",
            "example": "1990-05-21"
          },
          "Gender": {
            "type": "string",
            "description": "Gender of the cardholder.",
            "enum": [
              "F",
              "M"
            ]
          },
          "Email": {
            "type": "string",
            "description": "Email address of the cardholder.",
            "example": "john.doe@example.com"
          },
          "PhoneNumber": {
            "type": "number",
            "description": "Landline phone number of the cardholder.",
            "example": 50223456789
          },
          "CellPhone": {
            "type": "number",
            "description": "Cell phone number of the cardholder.",
            "example": 50255556666
          },
          "Occupation": {
            "type": "string",
            "description": "Occupation of the cardholder.",
            "example": "Engineer"
          },
          "Profession": {
            "type": "string",
            "description": "Profession of the cardholder.",
            "example": "Software Developer"
          },
          "LineOfBusiness": {
            "type": "string",
            "description": "Line of business of the cardholder.",
            "example": "Technology"
          },
          "Latitude": {
            "type": "string",
            "description": "Latitude of the cardholder address.",
            "example": "14.6349"
          },
          "Longitude": {
            "type": "string",
            "description": "Longitude of the cardholder address.",
            "example": "-90.5069"
          },
          "StateKey": {
            "type": "string",
            "description": "State/region key of the cardholder address.",
            "example": "GU"
          },
          "City": {
            "type": "string",
            "description": "City of the cardholder address.",
            "example": "Guatemala City"
          },
          "Street": {
            "type": "string",
            "description": "Street of the cardholder address.",
            "example": "Av. Reforma"
          },
          "ExteriorNumber": {
            "type": "string",
            "description": "Exterior number of the address.",
            "example": "123"
          },
          "InteriorNumber": {
            "type": "string",
            "description": "Interior number of the address.",
            "example": "4B"
          },
          "Neighborhood": {
            "type": "string",
            "description": "Neighborhood of the address.",
            "example": "Zona 10"
          },
          "Delegation": {
            "type": "string",
            "description": "Delegation/municipality of the address.",
            "example": "Guatemala"
          },
          "TownID": {
            "type": "string",
            "description": "Town identifier of the address.",
            "example": "GT01"
          },
          "ZipCode": {
            "type": "number",
            "description": "ZIP / postal code of the address.",
            "example": 1010
          },
          "Country": {
            "type": "number",
            "description": "Country numeric code of the address.",
            "example": 320
          },
          "IDType": {
            "type": "string",
            "description": "Identification document type of the cardholder.",
            "enum": [
              "CDJ",
              "CDP",
              "CDR",
              "NIT",
              "PAS",
              "RUC",
              "DNI"
            ]
          },
          "IDNumber": {
            "type": "string",
            "description": "Identification document number of the cardholder.",
            "example": "1234567890101"
          },
          "addres_line1": {
            "type": "string",
            "description": "Address line 1.",
            "example": "Av. Reforma 123"
          },
          "addres_line2": {
            "type": "string",
            "description": "Address line 2.",
            "example": "Apt 4B"
          },
          "CustomerType": {
            "type": "string",
            "description": "Customer type classification.",
            "enum": [
              "1"
            ]
          },
          "Acceptance": {
            "type": "number",
            "description": "Terms acceptance flag.",
            "enum": [
              0,
              1
            ]
          }
        },
        "required": [
          "Card",
          "Name",
          "FirstLastName",
          "Birthdate",
          "Gender",
          "Email",
          "Occupation",
          "Profession",
          "LineOfBusiness",
          "IDType",
          "IDNumber"
        ]
      },
      "CheckCardDto": {
        "type": "object",
        "properties": {
          "IdRequest": {
            "type": "string",
            "description": "Optional client-provided request identifier.",
            "example": "REQ-2026-0001"
          },
          "Card": {
            "type": "number",
            "description": "Card number (PAN) to query.",
            "example": 4512345678901234
          },
          "AccessEntry": {
            "type": "string",
            "description": "Alternative access entry (e.g., card alias or token).",
            "example": "ACC-12345"
          },
          "TypeAccessEntry": {
            "type": "string",
            "description": "Type of the access entry identifier.",
            "example": "TOKEN"
          }
        }
      },
      "CardActivationDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "number",
            "description": "Optional client-provided request identifier.",
            "example": 100001
          },
          "Tarjeta": {
            "type": "number",
            "description": "Card number (PAN) to activate.",
            "example": 4512345678901234
          }
        },
        "required": [
          "Tarjeta"
        ]
      },
      "QueryByIdentificationDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "number",
            "description": "Optional client-provided request identifier.",
            "example": 100001
          },
          "NumeroDocumentoCliente": {
            "type": "number",
            "description": "Customer document number.",
            "example": 1234567890101
          },
          "ClaveTipoDocumento": {
            "type": "string",
            "description": "Customer document type key.",
            "example": "DPI"
          },
          "ClaveEmpresa": {
            "type": "string",
            "description": "Company identifier key.",
            "example": "COMP-001"
          },
          "email": {
            "type": "string",
            "description": "Email address of the customer.",
            "example": "john.doe@example.com"
          }
        },
        "required": [
          "NumeroDocumentoCliente",
          "ClaveTipoDocumento",
          "email"
        ]
      },
      "BlockOrUnlockCardDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "number",
            "description": "Optional client-provided request identifier.",
            "example": 100001
          },
          "Tarjeta": {
            "type": "number",
            "description": "Card number (PAN) to block or unblock.",
            "example": 4512345678901234
          },
          "MedioAcceso": {
            "type": "string",
            "description": "Alternative access entry (e.g., card alias or token).",
            "example": "ACC-12345"
          },
          "TipoMedioAcceso": {
            "type": "string",
            "description": "Type of the access entry identifier.",
            "example": "TOKEN"
          },
          "MotivoBloqueo": {
            "type": "string",
            "description": "Reason for blocking or unblocking the card.",
            "example": "Lost card"
          }
        },
        "required": [
          "Tarjeta",
          "MotivoBloqueo"
        ]
      },
      "AssignNIPDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "number",
            "description": "Optional client-provided request identifier.",
            "example": 100001
          },
          "Tarjeta": {
            "type": "number",
            "description": "Card number (PAN) to assign the PIN to.",
            "example": 4512345678901234
          },
          "MedioAcceso": {
            "type": "string",
            "description": "Alternative access entry (e.g., card alias or token).",
            "example": "ACC-12345"
          },
          "TipoMedioAcceso": {
            "type": "string",
            "description": "Type of the access entry identifier.",
            "example": "TOKEN"
          },
          "NIPNuevo": {
            "type": "string",
            "description": "New 4-digit PIN (NIP) to assign to the card.",
            "example": "1234"
          }
        },
        "required": [
          "Tarjeta",
          "NIPNuevo"
        ]
      },
      "GetMovementsDto": {
        "type": "object",
        "properties": {
          "IDSolicitud": {
            "type": "number",
            "description": "Optional client-provided request identifier.",
            "example": 100001
          },
          "Card": {
            "type": "number",
            "description": "Card number (PAN) to query movements for.",
            "example": 4512345678901234
          },
          "StartDate": {
            "type": "object",
            "description": "Start date of the movement query range.",
            "example": "2026-01-01"
          },
          "FinalDate": {
            "type": "object",
            "description": "End date of the movement query range.",
            "example": "2026-05-21"
          },
          "MaxMovements": {
            "type": "number",
            "description": "Maximum number of movements to return.",
            "example": 50
          }
        },
        "required": [
          "Card"
        ]
      },
      "VersionDto": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "Version identifier",
            "example": "1.0.0"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2025-01-15T10:30:00.000Z"
          },
          "content": {
            "type": "object",
            "description": "Version content payload"
          }
        },
        "required": [
          "version",
          "content"
        ]
      },
      "FormsDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Unique key identifier for the form",
            "example": "onboarding-form"
          },
          "title": {
            "type": "string",
            "description": "Display title of the form",
            "example": "Onboarding Form"
          },
          "description": {
            "type": "string",
            "description": "Description of the form purpose",
            "example": "Form used during user onboarding"
          },
          "fields": {
            "description": "List of field definitions for the form",
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "permissions": {
            "description": "List of permission rules for the form",
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "key",
          "title",
          "fields"
        ]
      },
      "AppConfigDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "description": "Unique application identifier",
            "example": "migo-wallet-app"
          },
          "merchant": {
            "type": "string",
            "description": "Merchant identifier",
            "example": "migo"
          },
          "title": {
            "type": "string",
            "description": "Application display title",
            "example": "Migo Wallet"
          },
          "colors": {
            "type": "object",
            "description": "Color scheme configuration",
            "example": {
              "primary": "#1A73E8",
              "secondary": "#FFFFFF"
            }
          },
          "termsAndConditions": {
            "description": "Terms and conditions versions",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VersionDto"
            }
          },
          "privacyPolicy": {
            "description": "Privacy policy versions",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VersionDto"
            }
          },
          "rules": {
            "type": "object",
            "description": "Application rules configuration"
          },
          "callback": {
            "type": "object",
            "description": "Callback URL configuration"
          },
          "forms": {
            "description": "List of custom forms",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormsDto"
            }
          },
          "commissionDisplayMode": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "description": "Wallet per-store commission display mode: fixed (debited amount) or percentage (rate)",
            "example": "fixed"
          }
        },
        "required": [
          "applicationId",
          "merchant",
          "title",
          "colors"
        ]
      },
      "UpdateAppConfigDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "description": "Unique application identifier",
            "example": "migo-wallet-app"
          },
          "merchant": {
            "type": "string",
            "description": "Merchant identifier",
            "example": "migo"
          },
          "title": {
            "type": "string",
            "description": "Application display title",
            "example": "Migo Wallet"
          },
          "colors": {
            "type": "object",
            "description": "Color scheme configuration",
            "example": {
              "primary": "#1A73E8"
            }
          },
          "termsAndConditions": {
            "description": "Updated terms and conditions versions",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VersionDto"
            }
          },
          "privacyPolicy": {
            "description": "Updated privacy policy versions",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VersionDto"
            }
          },
          "rules": {
            "type": "object",
            "description": "Application rules configuration"
          },
          "forms": {
            "description": "Updated list of custom forms",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormsDto"
            }
          },
          "commissionDisplayMode": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "description": "Wallet per-store commission display mode: fixed (debited amount) or percentage (rate)",
            "example": "fixed"
          }
        }
      },
      "DimensionsInput": {
        "type": "object",
        "properties": {
          "width": {
            "type": "number",
            "description": "Width of the generated file in pixels.",
            "example": 800
          },
          "height": {
            "type": "number",
            "description": "Height of the generated file in pixels.",
            "example": 1200
          }
        },
        "required": [
          "width",
          "height"
        ]
      },
      "GenerateFileDto": {
        "type": "object",
        "properties": {
          "templateContent": {
            "type": "string",
            "description": "Raw template content (e.g. Handlebars/HTML) used to render the file.",
            "example": "<html><body>{{transaction.id}}</body></html>"
          },
          "data": {
            "type": "object",
            "description": "Free-form data injected into the template at render time.",
            "example": {
              "transactionId": "TXN-ABC123",
              "amount": "125.50"
            },
            "additionalProperties": true
          },
          "fileType": {
            "type": "string",
            "description": "Output file type (e.g. pdf, png).",
            "example": "pdf"
          },
          "dimensions": {
            "description": "Dimensions of the generated file.",
            "allOf": [
              {
                "$ref": "#/components/schemas/DimensionsInput"
              }
            ]
          }
        },
        "required": [
          "templateContent",
          "data",
          "fileType",
          "dimensions"
        ]
      },
      "ManualReportDto": {
        "type": "object",
        "properties": {
          "emails": {
            "description": "Destinatarios del correo electrónico",
            "example": [
              "admin@empresa.com",
              "reporte@empresa.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "userIds": {
            "description": "IDs de los usuarios (authUserId) cuyos reportes se generarán",
            "example": [
              1001,
              1002
            ],
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "startDate": {
            "type": "string",
            "description": "Inicio del rango de fechas en formato ISO 8601",
            "example": "2026-02-01T00:00:00"
          },
          "endDate": {
            "type": "string",
            "description": "Fin del rango de fechas en formato ISO 8601",
            "example": "2026-03-01T00:00:00"
          },
          "timezone": {
            "type": "string",
            "description": "Zona horaria IANA para la conversión de fechas",
            "example": "America/Guatemala"
          },
          "template": {
            "type": "string",
            "description": "Path del template HTML almacenado en S3",
            "example": "ali-templates/estado_cuenta_mensual_v1.html"
          },
          "fileName": {
            "type": "string",
            "description": "Prefijo base del nombre del archivo PDF. Se añade slug de sucursal, timestamp y UUID.",
            "example": "estado_cuenta_mensual"
          },
          "emailTemplate": {
            "type": "string",
            "description": "Path del template de correo electrónico almacenado en S3",
            "example": "ali-templates/ali-email-template.html"
          },
          "subjectEmail": {
            "type": "string",
            "description": "Asunto del correo electrónico",
            "example": "Estado de cuenta mensual - Febrero 2026"
          },
          "consolidated": {
            "type": "boolean",
            "description": "true → un PDF consolidado por usuario | false → un PDF por terminal",
            "example": false
          },
          "reportType": {
            "type": "string",
            "description": "transactions → estado de cuenta | cards → resumen de tarjetas",
            "enum": [
              "transactions",
              "cards"
            ],
            "example": "transactions"
          }
        },
        "required": [
          "emails",
          "userIds",
          "startDate",
          "endDate",
          "timezone",
          "template",
          "fileName",
          "emailTemplate",
          "subjectEmail",
          "consolidated",
          "reportType"
        ]
      },
      "ManualReportErrorResponse": {
        "type": "object",
        "properties": {}
      },
      "LeadPaymentMethodDto": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Payment method slug",
            "example": "card"
          },
          "acquirerSlug": {
            "type": "string",
            "description": "Acquirer slug",
            "example": "visanet"
          }
        },
        "required": [
          "slug",
          "acquirerSlug"
        ]
      },
      "LeadDocumentDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL of the uploaded document",
            "example": "https://storage.example.com/docs/dpi-front.jpg"
          },
          "type": {
            "type": "string",
            "description": "Type of document",
            "example": "dpi_front"
          },
          "provider": {
            "type": "string",
            "description": "Storage provider name",
            "example": "s3"
          }
        },
        "required": [
          "url"
        ]
      },
      "LeadAdditionalDataDto": {
        "type": "object",
        "properties": {
          "externalReferralCode": {
            "type": "string",
            "description": "External referral code from the partner employee",
            "example": "EMP-001"
          },
          "externalBranchCode": {
            "type": "string",
            "description": "External branch code from the partner employee",
            "example": "BR-001"
          },
          "nrc": {
            "type": "string",
            "description": "Taxpayer registry number (NRC) of the business",
            "example": "123456-7"
          }
        }
      },
      "CreateLeadDto": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name of the lead",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Last name of the lead",
            "example": "Doe"
          },
          "nationality": {
            "type": "string",
            "enum": [
              "ARG",
              "BOL",
              "BRA",
              "CHL",
              "COL",
              "CRI",
              "CUB",
              "DOM",
              "ECU",
              "SLV",
              "GTM",
              "HTI",
              "HND",
              "MEX",
              "NIC",
              "PAN",
              "PRY",
              "PER",
              "PRI",
              "URY",
              "VEN"
            ],
            "description": "Nationality of the lead",
            "example": "GTM"
          },
          "gender": {
            "type": "string",
            "enum": [
              "F",
              "M",
              "OTHER"
            ],
            "description": "Gender of the lead",
            "example": "M"
          },
          "dateOfBirth": {
            "type": "string",
            "description": "Date of birth in YYYY-MM-DD format",
            "example": "1990-01-15"
          },
          "cui": {
            "type": "string",
            "description": "Unique personal identification number (CUI)",
            "example": "1234567890101"
          },
          "placeOfBirth": {
            "type": "string",
            "description": "Place of birth",
            "example": "Guatemala City"
          },
          "neighborhood": {
            "type": "string",
            "description": "Neighborhood or district",
            "example": "Zona 10"
          },
          "maritalStatus": {
            "type": "string",
            "enum": [
              "soltero",
              "casado",
              "viudo",
              "divorciado",
              "separado"
            ],
            "description": "Marital status",
            "example": "soltero"
          },
          "expirationDate": {
            "type": "string",
            "description": "Document expiration date in YYYY-MM-DD format",
            "example": "2030-12-31"
          },
          "serialNumber": {
            "type": "string",
            "description": "Serial number of the device or registration",
            "example": "SN-2025-001"
          },
          "taxRegime": {
            "type": "string",
            "enum": [
              "pequeño contribuyente",
              "general",
              "excento",
              "asalariado",
              "pequeño contribuyente electronico",
              "persona natural no declara",
              "persona juridica",
              "persona natural",
              "IVA",
              "otras rentas",
              "NA"
            ],
            "description": "Tax regime type",
            "example": "general"
          },
          "nit": {
            "type": "string",
            "description": "Tax identification number (NIT)",
            "example": "1234567-8"
          },
          "commercialName": {
            "type": "string",
            "description": "Commercial or trade name",
            "example": "Tienda Migo"
          },
          "businessName": {
            "type": "string",
            "description": "Legal business name (defaults to commercialName if not provided)",
            "example": "Comercial Guatemala S.A."
          },
          "economicActivity": {
            "type": "string",
            "description": "Economic activity of the business",
            "example": "Retail sales"
          },
          "canInvoice": {
            "type": "boolean",
            "description": "Whether the business can issue invoices",
            "example": true
          },
          "countryOfBirth": {
            "type": "string",
            "enum": [
              "ARG",
              "BOL",
              "BRA",
              "CHL",
              "COL",
              "CRI",
              "CUB",
              "DOM",
              "ECU",
              "SLV",
              "GTM",
              "HTI",
              "HND",
              "MEX",
              "NIC",
              "PAN",
              "PRY",
              "PER",
              "PRI",
              "URY",
              "VEN"
            ],
            "description": "Country of birth",
            "example": "GTM"
          },
          "partner": {
            "type": "string",
            "enum": [
              "tributax",
              "apex",
              "cbc",
              "migo",
              "ge",
              "cbc_fge",
              "cmi"
            ],
            "description": "Partner associated with the lead",
            "example": "migo"
          },
          "lastRtuUpdateDate": {
            "type": "string",
            "description": "Last RTU update date in YYYY-MM-DD format (required for Tributax partner)",
            "example": "2025-01-15"
          },
          "rtuType": {
            "type": "string",
            "description": "Type of RTU registration",
            "example": "standard"
          },
          "country": {
            "type": "string",
            "enum": [
              "ARG",
              "BOL",
              "BRA",
              "CHL",
              "COL",
              "CRI",
              "CUB",
              "DOM",
              "ECU",
              "SLV",
              "GTM",
              "HTI",
              "HND",
              "MEX",
              "NIC",
              "PAN",
              "PRY",
              "PER",
              "PRI",
              "URY",
              "VEN"
            ],
            "description": "Country where the lead operates",
            "example": "GTM"
          },
          "personType": {
            "type": "string",
            "enum": [
              "persona individual",
              "persona juridica"
            ],
            "description": "Type of person of the lead",
            "example": "persona individual"
          },
          "phone": {
            "type": "string",
            "description": "Phone number in international format",
            "example": "+50212345678"
          },
          "email": {
            "type": "string",
            "description": "Email address",
            "example": "john@example.com"
          },
          "address": {
            "type": "string",
            "description": "Physical address",
            "example": "5a Avenida 12-34, Zona 1, Guatemala City"
          },
          "clientId": {
            "type": "string",
            "description": "Client application identifier",
            "example": "app-001"
          },
          "paymentMethods": {
            "description": "Accepted payment methods with acquirer",
            "example": [
              {
                "slug": "card",
                "acquirerSlug": "visanet"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeadPaymentMethodDto"
            }
          },
          "documents": {
            "description": "Supporting documents for the lead",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeadDocumentDto"
            }
          },
          "payoutAccountNumber": {
            "type": "string",
            "description": "Bank account number for payout",
            "example": "1234567890"
          },
          "additionalData": {
            "description": "Controlled additional data for the lead",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeadAdditionalDataDto"
              }
            ]
          },
          "sourceIntegrationKey": {
            "type": "string",
            "description": "Integration key of the form the lead came from, kept so the invitation email can be rebuilt with the same template",
            "example": "airtable-migo-gt"
          },
          "sourceId": {
            "type": "string",
            "description": "Identifier of the form submission the lead came from",
            "example": "recXXXXXXXXXXXXXX"
          }
        },
        "required": [
          "firstName",
          "lastName",
          "gender",
          "cui",
          "expirationDate",
          "commercialName",
          "partner",
          "phone",
          "address"
        ]
      },
      "UpdateLeadDto": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name of the lead",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Last name of the lead",
            "example": "Doe"
          },
          "phone": {
            "type": "string",
            "description": "Phone number in international format",
            "example": "+50212345678"
          },
          "commercialName": {
            "type": "string",
            "description": "Commercial name of the business",
            "example": "Tienda Migo"
          },
          "address": {
            "type": "string",
            "description": "Physical address",
            "example": "5a Avenida 12-34, Zona 1, Guatemala City"
          },
          "taxRegime": {
            "type": "string",
            "enum": [
              "pequeño contribuyente",
              "general",
              "excento",
              "asalariado",
              "pequeño contribuyente electronico",
              "persona natural no declara",
              "persona juridica",
              "persona natural",
              "IVA",
              "otras rentas",
              "NA"
            ],
            "description": "Tax regime type",
            "example": "general"
          }
        }
      },
      "UpdateInvitationEmailDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "New email address for the invitation",
            "example": "nuevo.correo@example.com"
          },
          "emailConfirmation": {
            "type": "string",
            "description": "Confirmation of the new email address, must match email",
            "example": "nuevo.correo@example.com"
          },
          "integrationKey": {
            "type": "string",
            "description": "Integration key used to resolve the invitation email template. Only needed for leads created before the integration key was stored on the lead.",
            "example": "airtable-migo-gt"
          }
        },
        "required": [
          "email",
          "emailConfirmation"
        ]
      },
      "ResendInvitationCodeDto": {
        "type": "object",
        "properties": {
          "integrationKey": {
            "type": "string",
            "description": "Integration key used to resolve the invitation email template. Only needed for leads created before the integration key was stored on the lead.",
            "example": "airtable-migo-gt"
          }
        }
      },
      "NewCodeDTO": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Type of invitation code (e.g. activation, onboarding).",
            "example": "activation"
          },
          "role": {
            "type": "string",
            "description": "Role assigned to the user when redeeming the code.",
            "example": "cashier"
          }
        },
        "required": [
          "type",
          "role"
        ]
      },
      "TransferTypeDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Descriptive name for the transfer type",
            "example": "POS Purchase"
          },
          "type": {
            "type": "string",
            "enum": [
              "posPurchase",
              "ecommercePurchase",
              "balanceInquiry",
              "atmWithdrawal",
              "purchasewithCashback",
              "internalContactlessBalances",
              "balanceTransfertoUser",
              "balanceTransferfromUser",
              "topUp",
              "balanceDecrease",
              "reversalOfOperation"
            ],
            "description": "Type of the transfer",
            "example": "posPurchase"
          },
          "channel": {
            "type": "string",
            "enum": [
              "financialNetwork",
              "webService"
            ],
            "description": "Communication channel for the transfer",
            "example": "financialNetwork"
          },
          "movementType": {
            "type": "string",
            "enum": [
              "debit",
              "credit"
            ],
            "description": "Type of financial movement (debit or credit)",
            "example": "debit"
          },
          "model": {
            "type": "string",
            "enum": [
              "reversed",
              "settlement"
            ],
            "description": "Processing model for the transfer type",
            "example": "settlement"
          }
        },
        "required": [
          "type",
          "channel",
          "movementType",
          "model"
        ]
      },
      "CreateTransferTypeDto": {
        "type": "object",
        "properties": {
          "types": {
            "description": "Array of transfer type configurations to create",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransferTypeDto"
            }
          }
        },
        "required": [
          "types"
        ]
      },
      "CreateTerminalPaymentInput": {
        "type": "object",
        "properties": {
          "externalTerminalId": {
            "type": "string",
            "description": "External terminal identifier from the payment network",
            "example": "TRM-EXT-001"
          },
          "terminalId": {
            "type": "number",
            "description": "Internal terminal identifier",
            "example": 42
          },
          "deviceId": {
            "type": "string",
            "description": "Identifier of the device initiating the payment",
            "example": "DEV-12345"
          },
          "operationId": {
            "type": "string",
            "description": "Unique operation identifier for tracking purposes",
            "example": "OP-2025-00123"
          },
          "subtotal": {
            "type": "number",
            "description": "Payment subtotal amount (must be greater than 0)",
            "example": 150.5
          },
          "additionalData": {
            "type": "object",
            "description": "Additional metadata related to the payment",
            "example": {
              "invoiceNumber": "INV-001"
            }
          },
          "firstAttemptAt": {
            "type": "string",
            "description": "Timestamp of the original charge attempt that failed. Set on settlement retries to preserve the real time the merchant made the charge.",
            "example": "2026-07-27T15:30:00.000Z"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude captured for the payment operation",
            "example": 14.634915
          },
          "longitude": {
            "type": "number",
            "description": "Longitude captured for the payment operation",
            "example": -90.506882
          }
        },
        "required": [
          "subtotal"
        ]
      },
      "UploadTerminalPaymentSignatureDto": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "Signature image file uploaded via multipart/form-data.",
            "format": "binary"
          },
          "branchId": {
            "type": "string",
            "description": "Id of the branch where the terminal is located.",
            "example": "12"
          }
        },
        "required": [
          "signature",
          "branchId"
        ]
      },
      "UpdateCardDto": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "description": "Human-readable alias to identify the card for the cardholder.",
            "example": "Personal card"
          }
        },
        "required": [
          "alias"
        ]
      },
      "CardPinDto": {
        "type": "object",
        "properties": {
          "pin": {
            "type": "string",
            "description": "New PIN value for the card.",
            "example": "1234"
          }
        },
        "required": [
          "pin"
        ]
      },
      "CardAssingFundsDto": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "number",
            "description": "Internal identifier of the user that owns the card.",
            "example": 12345
          },
          "amount": {
            "type": "number",
            "description": "Monetary amount to apply to the card balance.",
            "example": 250.5
          },
          "reference": {
            "type": "string",
            "description": "External reference for the funds operation.",
            "example": "REF-2026-0001"
          },
          "observations": {
            "type": "string",
            "description": "Optional free-text observations for auditing or reconciliation.",
            "example": "Top-up requested by support."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code. Defaults to the card currency when omitted.",
            "example": "GTQ"
          },
          "operation": {
            "type": "string",
            "enum": [
              "ADD_FUNDS",
              "WITHDRAW_FUNDS"
            ],
            "example": "ADD_FUNDS",
            "description": "Type of funds operation to perform (ADD_FUNDS/WITHDRAW_FUNDS)."
          },
          "customKeys": {
            "type": "object",
            "additionalProperties": true,
            "description": "Custom metadata to attach to the operation as key-value pairs."
          }
        },
        "required": [
          "userId",
          "amount",
          "reference",
          "operation"
        ]
      },
      "RequestTokenDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "cvv",
              "card"
            ],
            "description": "Type of token requested by the client.",
            "example": "cvv"
          }
        },
        "required": [
          "type"
        ]
      },
      "TransferBetweenCardsDto": {
        "type": "object",
        "properties": {
          "fromCardId": {
            "type": "number",
            "description": "Internal identifier of the source card.",
            "example": 12345
          },
          "toCardId": {
            "type": "number",
            "description": "Internal identifier of the destination card.",
            "example": 67890
          },
          "amount": {
            "type": "number",
            "description": "Monetary amount to transfer between the two cards.",
            "example": 100
          },
          "observations": {
            "type": "string",
            "description": "Optional notes describing the reason of the transfer.",
            "example": "Allowance transfer."
          },
          "allowedDestinationStatuses": {
            "description": "Allowed destination card statuses resolved from backend config.",
            "example": [
              "Active"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "fromCardId",
          "toCardId",
          "amount"
        ]
      },
      "CreateStatementDto": {
        "type": "object",
        "properties": {
          "month": {
            "type": "number",
            "description": "Month for which the statement will be generated (1-12).",
            "example": 5
          },
          "year": {
            "type": "number",
            "description": "Four-digit year for which the statement will be generated.",
            "example": 2026
          }
        },
        "required": [
          "month",
          "year"
        ]
      },
      "BankTransferDto": {
        "type": "object",
        "properties": {
          "bankAccountId": {
            "type": "number",
            "description": "Destination bank account id (user_banks.id).",
            "example": 89
          },
          "amount": {
            "type": "number",
            "description": "Amount to transfer to the bank account (without commission).",
            "example": 150.5
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code for the transfer.",
            "example": "GTQ"
          },
          "concept": {
            "type": "string",
            "description": "Concept/description for the bank transfer.",
            "example": "Bank transfer"
          },
          "customKeys": {
            "type": "object",
            "description": "Custom keys attached for downstream reconciliation.",
            "example": {
              "reconciliationId": "abc-123"
            }
          }
        },
        "required": [
          "bankAccountId",
          "amount",
          "currency"
        ]
      },
      "FundsOperationDto": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "Monetary amount to apply to the card balance.",
            "example": 250.5
          },
          "description": {
            "type": "string",
            "description": "Optional short description (up to 50 characters) for the operation.",
            "example": "ATM top-up"
          },
          "channel": {
            "type": "string",
            "description": "Channel through which the operation originated (e.g., MOBILE, WEB, ATM).",
            "example": "MOBILE"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code. Defaults to the card currency when omitted.",
            "example": "GTQ"
          },
          "operation": {
            "type": "string",
            "enum": [
              "ADD_FUNDS",
              "WITHDRAW_FUNDS"
            ],
            "example": "ADD_FUNDS",
            "description": "Type of funds operation to perform (ADD_FUNDS/WITHDRAW_FUNDS)."
          },
          "reference": {
            "type": "string",
            "description": "External reference for the funds operation.",
            "example": "REF-2026-0001"
          },
          "customKeys": {
            "type": "object",
            "additionalProperties": true,
            "description": "Custom metadata to attach to the operation as key-value pairs."
          }
        },
        "required": [
          "amount",
          "channel",
          "operation",
          "reference"
        ]
      },
      "CreateCardEmissionBatchDto": {
        "type": "object",
        "properties": {
          "partnerCode": {
            "type": "string",
            "description": "Programa emisor, tal como está en el catálogo. En minúscula y del catálogo: si llega «AKISI» o el nombre comercial, el lote no se une a nada.",
            "example": "akisi"
          },
          "quantity": {
            "type": "number",
            "description": "Plásticos mandados a fabricar en este lote.",
            "example": 70000
          },
          "emittedOn": {
            "type": "string",
            "description": "Fecha del lote, en ISO.",
            "example": "2026-01-15"
          },
          "reference": {
            "type": "string",
            "description": "Orden de compra o lote del fabricante, para rastrear.",
            "example": "OC-2026-001"
          },
          "note": {
            "type": "string",
            "description": "Nota libre."
          }
        },
        "required": [
          "partnerCode",
          "quantity",
          "emittedOn"
        ]
      },
      "UpdateCardEmissionBatchDto": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "Orden de compra o lote."
          },
          "note": {
            "type": "string",
            "description": "Nota libre."
          }
        }
      },
      "VoidCardEmissionBatchDto": {
        "type": "object",
        "properties": {
          "voidReason": {
            "type": "string",
            "description": "Por qué se anula. Obligatorio: la cantidad no se corrige, se anula y se vuelve a crear.",
            "example": "cantidad equivocada en la orden"
          }
        },
        "required": [
          "voidReason"
        ]
      },
      "CreateClientPriceDto": {
        "type": "object",
        "properties": {
          "partnerCode": {
            "type": "string",
            "description": "Programa del catálogo.",
            "example": "akisi"
          },
          "concept": {
            "type": "string",
            "description": "Concepto del catálogo cerrado.",
            "example": "tarjeta_emitida"
          },
          "unitPrice": {
            "type": "number",
            "description": "Precio unitario.",
            "example": 1.25
          },
          "currency": {
            "type": "string",
            "description": "Moneda ISO de tres letras.",
            "example": "USD"
          },
          "validFrom": {
            "type": "string",
            "description": "Desde cuándo rige. Un precio nuevo no corrige al anterior: lo sucede.",
            "example": "2026-01-01"
          }
        },
        "required": [
          "partnerCode",
          "concept",
          "unitPrice",
          "currency",
          "validFrom"
        ]
      },
      "CloseClientPriceDto": {
        "type": "object",
        "properties": {
          "validTo": {
            "type": "string",
            "description": "Hasta cuándo rigió. Es lo único que se puede cambiar de una tarifa.",
            "example": "2026-07-01"
          }
        },
        "required": [
          "validTo"
        ]
      },
      "EmitEventDto": {
        "type": "object",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "Identifier of the registered WebSocket client to emit the event to.",
            "example": "client-123"
          },
          "payload": {
            "type": "object",
            "description": "Event payload forwarded as-is to the client via the \"clientUpdated\" event.",
            "additionalProperties": true,
            "example": {
              "type": "cardUpdated",
              "cardId": 1001,
              "status": "ACTIVE"
            }
          }
        },
        "required": [
          "clientId",
          "payload"
        ]
      },
      "ProcessTerminalPaymentDto": {
        "type": "object",
        "properties": {
          "terminalPaymentId": {
            "type": "number",
            "description": "Terminal payment identifier to process",
            "example": 1
          },
          "reference": {
            "type": "string",
            "description": "Transaction reference code",
            "example": "REF-2025-001"
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "approved",
              "processed",
              "denied",
              "reversed",
              "refunded",
              "cancelled",
              "in_progress",
              "liquidated",
              "pending",
              "reversalPending",
              "reversalProcessing"
            ],
            "description": "Status to set for the terminal payment",
            "example": "approved"
          },
          "additionalData": {
            "type": "object",
            "description": "Additional metadata for the processing",
            "example": {
              "processorResponse": "OK"
            }
          },
          "clientId": {
            "type": "string",
            "description": "Client application identifier",
            "example": "app-001"
          },
          "reversalId": {
            "type": "string",
            "description": "Reversal request identifier (UUID generated by the wallet). Used as the idempotency key for the debit so retries do not move funds twice.",
            "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
          },
          "merchant": {
            "type": "string",
            "description": "Merchant that owns the application configuration",
            "example": "aliGT"
          }
        },
        "required": [
          "terminalPaymentId",
          "status"
        ]
      },
      "ConfirmReversalDto": {
        "type": "object",
        "properties": {
          "terminalPaymentId": {
            "type": "number",
            "description": "Terminal payment being reversed",
            "example": 1
          },
          "reversalId": {
            "type": "string",
            "description": "Reversal request identifier (idempotency key)",
            "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
          },
          "authorization": {
            "type": "string",
            "description": "Processor authorization / voucher evidence of the approved reversal",
            "example": "AUTH-998877"
          }
        },
        "required": [
          "terminalPaymentId",
          "reversalId"
        ]
      },
      "CompensateReversalDto": {
        "type": "object",
        "properties": {
          "terminalPaymentId": {
            "type": "number",
            "description": "Terminal payment whose reversal must be compensated",
            "example": 1
          },
          "reversalId": {
            "type": "string",
            "description": "Reversal request identifier (idempotency key)",
            "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
          }
        },
        "required": [
          "terminalPaymentId",
          "reversalId"
        ]
      },
      "CreatePendingSettlementDto": {
        "type": "object",
        "properties": {
          "terminalPaymentId": {
            "type": "number",
            "description": "Identifier of the terminal payment the pending settlement belongs to.",
            "example": 1
          },
          "status": {
            "type": "string",
            "description": "Status of the settlement at the time it was queued for retry.",
            "example": "pending"
          },
          "amount": {
            "type": "string",
            "description": "Amount pending to be settled.",
            "example": "100.00"
          },
          "externalTerminalId": {
            "type": "string",
            "description": "External identifier of the terminal.",
            "example": "TERM-001"
          },
          "additionalData": {
            "type": "object",
            "description": "Additional metadata captured at the time of the failure."
          }
        },
        "required": [
          "terminalPaymentId",
          "status",
          "amount",
          "externalTerminalId"
        ]
      },
      "ValidateIntegrityDto": {
        "type": "object",
        "properties": {
          "hash": {
            "type": "string",
            "description": "Hash previously generated by the `GET /integrity/app` endpoint.",
            "example": "0971d5f5227bbe6a7571948cefae755bca9d7b0dec2158478a54d1eaf6b38e4e"
          },
          "applicationId": {
            "type": "string",
            "description": "Mobile application identifier the integrity check belongs to.",
            "example": "com.migo.ali"
          },
          "token": {
            "type": "string",
            "description": "Integrity token produced on-device by the Google Play Integrity API.",
            "example": "<integrity token from Google Play API>"
          }
        },
        "required": [
          "hash",
          "applicationId",
          "token"
        ]
      },
      "TrackPushOpenRequestDto": {
        "type": "object",
        "properties": {
          "trackingId": {
            "type": "string",
            "example": "push:SETTLEMENT_SUCCESSFUL",
            "description": "`trackingId` of the push data"
          },
          "source": {
            "type": "string",
            "enum": [
              "NOTIFICATION_TRAY",
              "IN_APP_ALERT",
              "INBOX"
            ]
          },
          "appState": {
            "type": "string",
            "enum": [
              "TERMINATED",
              "BACKGROUND"
            ],
            "description": "Only for NOTIFICATION_TRAY: the push launched the app or brought it back"
          },
          "eventId": {
            "type": "string",
            "example": "6f1c2a9e-4b0a-4b2c-9d4e-5f6a7b8c9d0e",
            "description": "Id of this open generated by the app: a retry with the same id counts once"
          }
        },
        "required": [
          "trackingId",
          "source"
        ]
      },
      "WalletCardDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 12
          },
          "suffix": {
            "type": "string",
            "nullable": true,
            "example": "4821"
          },
          "balance": {
            "type": "string",
            "nullable": true,
            "description": "Available balance",
            "example": "627.14"
          },
          "monthlyExpenses": {
            "type": "string",
            "nullable": true,
            "description": "Main card's spending this calendar month (approved debits); null when unavailable",
            "example": "340.00"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "example": "Active"
          },
          "activationDate": {
            "type": "string",
            "nullable": true,
            "example": "2026-01-15T00:00:00.000Z"
          },
          "balanceAsOf": {
            "type": "string",
            "nullable": true,
            "description": "When the balance was last refreshed",
            "example": "2026-07-13T18:00:00.000Z"
          }
        },
        "required": [
          "id",
          "suffix",
          "balance",
          "monthlyExpenses",
          "status",
          "activationDate",
          "balanceAsOf"
        ]
      },
      "WalletStoreDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 50
          },
          "name": {
            "type": "string",
            "example": "Central"
          },
          "commerceId": {
            "type": "number",
            "example": 77
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "example": "GTQ"
          },
          "totalCharges": {
            "type": "string",
            "nullable": true,
            "description": "Total charges this month, in the store currency",
            "example": "2123.12"
          },
          "commission": {
            "type": "string",
            "nullable": true,
            "description": "Usage commission accrued this month; null when op-liquidations is degraded",
            "example": "106.16"
          },
          "netIncome": {
            "type": "string",
            "nullable": true,
            "description": "Net income this month (charges − commission)",
            "example": "2016.96"
          },
          "commissionDisplay": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "description": "How the frontend renders the commission for this store (from ms-config commissionDisplayMode)",
            "example": "fixed"
          },
          "commissionPercentage": {
            "type": "string",
            "nullable": true,
            "description": "Commerce commission rate (%) shown in percentage mode; null in fixed mode or when there is no configured rate",
            "example": "5.00"
          }
        },
        "required": [
          "id",
          "name",
          "commerceId",
          "currency",
          "totalCharges",
          "commission",
          "netIncome",
          "commissionDisplay",
          "commissionPercentage"
        ]
      },
      "WalletHomeDto": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "SHOP_CASHIER",
              "SHOP_ADMIN",
              "SHOP_OWNER",
              "SHOP_CUSTOMER"
            ],
            "example": "SHOP_OWNER"
          },
          "card": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/WalletCardDto"
              }
            ]
          },
          "stores": {
            "description": "All stores with per-store income for the current month",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WalletStoreDto"
            }
          },
          "activeStore": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/WalletStoreDto"
              }
            ]
          },
          "storesCount": {
            "type": "number",
            "example": 3
          },
          "quickActions": {
            "description": "Contextual quick actions (e.g. activateCard, support)",
            "example": [
              "activateCard"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "degraded": {
            "type": "boolean",
            "description": "True when a non-critical dependency degraded the response",
            "example": false
          }
        },
        "required": [
          "role",
          "card",
          "stores",
          "activeStore",
          "storesCount",
          "quickActions",
          "degraded"
        ]
      },
      "WalletStoresResponseDto": {
        "type": "object",
        "properties": {
          "stores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WalletStoreDto"
            }
          },
          "activeStoreId": {
            "type": "number",
            "nullable": true,
            "example": 50
          }
        },
        "required": [
          "stores",
          "activeStoreId"
        ]
      },
      "GetChargesDto": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "number",
            "description": "Page size (1..50)",
            "minimum": 1,
            "maximum": 50,
            "default": 20
          },
          "offset": {
            "type": "number",
            "description": "Number of records to skip",
            "minimum": 0,
            "default": 0
          },
          "month": {
            "type": "string",
            "description": "Calendar month to query (YYYY-MM). Defaults to the current month.",
            "example": "2026-07"
          },
          "branchId": {
            "type": "number",
            "description": "Restrict the history to a single branch the user belongs to",
            "example": 42
          }
        }
      },
      "ChargeBranchDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 50
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Central"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "TerminalPaymentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 900
          },
          "terminalId": {
            "type": "number",
            "example": 101
          },
          "externalId": {
            "type": "string",
            "example": "EXT-000123"
          },
          "operationId": {
            "type": "string",
            "nullable": true,
            "example": "OP-000123"
          },
          "subtotal": {
            "type": "string",
            "description": "Decimal serialized as string",
            "example": "125.5000"
          },
          "totalAmount": {
            "type": "string",
            "description": "Decimal serialized as string",
            "example": "125.5000"
          },
          "status": {
            "type": "string",
            "description": "Raw terminal_payment status",
            "example": "approved"
          },
          "currency": {
            "type": "string",
            "example": "GTQ"
          },
          "paymentMethodType": {
            "type": "string",
            "example": "card"
          },
          "additionalData": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true
          },
          "firstAttemptAt": {
            "type": "string",
            "nullable": true,
            "example": "2026-07-10T12:00:00.000Z"
          },
          "signatureUrl": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-07-10T12:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-07-10T12:05:00.000Z"
          }
        },
        "required": [
          "id",
          "terminalId",
          "externalId",
          "operationId",
          "subtotal",
          "totalAmount",
          "status",
          "currency",
          "paymentMethodType",
          "additionalData",
          "firstAttemptAt",
          "signatureUrl",
          "createdAt",
          "updatedAt"
        ]
      },
      "ChargeItemDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 900
          },
          "amount": {
            "type": "string",
            "nullable": true,
            "description": "Gross total (terminal_payment.totalAmount)",
            "example": "125.50"
          },
          "commission": {
            "type": "string",
            "nullable": true,
            "description": "Commerce commission for this charge; null if not liquidated yet or op-liquidations degraded",
            "example": "5.50"
          },
          "netIncome": {
            "type": "string",
            "nullable": true,
            "description": "Net income (amount − commission); null when commission is null",
            "example": "120.00"
          },
          "commissionDisplay": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "description": "How the frontend renders this charge commission (from ms-config commissionDisplayMode)",
            "example": "fixed"
          },
          "commissionPercentage": {
            "type": "string",
            "nullable": true,
            "description": "Commerce commission rate (%) shown in percentage mode; null in fixed mode or when there is no configured rate",
            "example": "5.00"
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "example": "GTQ"
          },
          "paymentMethodType": {
            "type": "string",
            "enum": [
              "card",
              "akisiQR",
              "nequi",
              "quickPayQR",
              "zigiQR",
              "bancoIndustrial",
              "bamQR",
              "yoloQR",
              "friQR",
              "okyQR"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Raw terminal_payment status",
            "example": "approved"
          },
          "statusChip": {
            "type": "string",
            "enum": [
              "Aprobado",
              "En espera",
              "Rechazado",
              "Denegado",
              "Revertido"
            ],
            "nullable": true,
            "description": "Visual chip; null when the status maps to no chip"
          },
          "createdAt": {
            "type": "string",
            "example": "2026-07-10T12:00:00.000Z"
          },
          "branch": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ChargeBranchDto"
              }
            ]
          },
          "collaboratorAuthUserId": {
            "type": "number",
            "nullable": true,
            "description": "authUserId of the collaborator who made the charge (terminal owner)",
            "example": 700
          },
          "collaboratorName": {
            "type": "string",
            "nullable": true,
            "description": "Name of the collaborator who made the charge; null when unresolved or op-users degraded",
            "example": "Ana Ruiz"
          },
          "terminalPayment": {
            "$ref": "#/components/schemas/TerminalPaymentDto"
          }
        },
        "required": [
          "id",
          "amount",
          "commission",
          "netIncome",
          "commissionDisplay",
          "commissionPercentage",
          "currency",
          "paymentMethodType",
          "status",
          "statusChip",
          "createdAt",
          "branch",
          "collaboratorAuthUserId",
          "collaboratorName",
          "terminalPayment"
        ]
      },
      "ChargesResponseDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChargeItemDto"
            }
          },
          "limit": {
            "type": "number",
            "example": 20
          },
          "offset": {
            "type": "number",
            "example": 0
          },
          "hasMore": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "items",
          "limit",
          "offset",
          "hasMore"
        ]
      },
      "VoucherCardDto": {
        "type": "object",
        "properties": {
          "suffix": {
            "type": "string",
            "example": "4321"
          }
        },
        "required": [
          "suffix"
        ]
      },
      "ChargeDetailDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 900
          },
          "amount": {
            "type": "string",
            "nullable": true,
            "description": "Gross total (terminal_payment.totalAmount)",
            "example": "125.50"
          },
          "commission": {
            "type": "string",
            "nullable": true,
            "description": "Commerce commission for this charge; null if not liquidated yet or op-liquidations degraded",
            "example": "5.50"
          },
          "netIncome": {
            "type": "string",
            "nullable": true,
            "description": "Net income (amount − commission); null when commission is null",
            "example": "120.00"
          },
          "commissionDisplay": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "description": "How the frontend renders this charge commission (from ms-config commissionDisplayMode)",
            "example": "fixed"
          },
          "commissionPercentage": {
            "type": "string",
            "nullable": true,
            "description": "Commerce commission rate (%) shown in percentage mode; null in fixed mode or when there is no configured rate",
            "example": "5.00"
          },
          "currency": {
            "type": "string",
            "nullable": true,
            "example": "GTQ"
          },
          "paymentMethodType": {
            "type": "string",
            "enum": [
              "card",
              "akisiQR",
              "nequi",
              "quickPayQR",
              "zigiQR",
              "bancoIndustrial",
              "bamQR",
              "yoloQR",
              "friQR",
              "okyQR"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Raw terminal_payment status",
            "example": "approved"
          },
          "statusChip": {
            "type": "string",
            "enum": [
              "Aprobado",
              "En espera",
              "Rechazado",
              "Denegado",
              "Revertido"
            ],
            "nullable": true,
            "description": "Visual chip; null when the status maps to no chip"
          },
          "createdAt": {
            "type": "string",
            "example": "2026-07-10T12:00:00.000Z"
          },
          "branch": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ChargeBranchDto"
              }
            ]
          },
          "collaboratorAuthUserId": {
            "type": "number",
            "nullable": true,
            "description": "authUserId of the collaborator who made the charge (terminal owner)",
            "example": 700
          },
          "collaboratorName": {
            "type": "string",
            "nullable": true,
            "description": "Name of the collaborator who made the charge; null when unresolved or op-users degraded",
            "example": "Ana Ruiz"
          },
          "terminalPayment": {
            "$ref": "#/components/schemas/TerminalPaymentDto"
          },
          "card": {
            "nullable": true,
            "description": "Null when the charge has no card_transfer",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/VoucherCardDto"
              }
            ]
          },
          "concept": {
            "type": "string",
            "nullable": true,
            "description": "card_transfer.concept (\"Descripción\"); null when no transfer",
            "example": "Compra en Tienda"
          },
          "channel": {
            "type": "string",
            "nullable": true,
            "description": "card_transfer.channel (\"Origen\")",
            "example": "yayo app"
          },
          "authCode": {
            "type": "string",
            "nullable": true,
            "description": "card_transfer.authCode (\"Autorización\")",
            "example": "208826"
          },
          "reference": {
            "type": "string",
            "nullable": true,
            "description": "card_transfer.reference (\"Referencia\")",
            "example": "501315000181"
          },
          "isReversible": {
            "type": "boolean",
            "description": "Replicates the server reversal gate (settlement + single liquidated + sameDay); false for cashiers",
            "example": true
          }
        },
        "required": [
          "id",
          "amount",
          "commission",
          "netIncome",
          "commissionDisplay",
          "commissionPercentage",
          "currency",
          "paymentMethodType",
          "status",
          "statusChip",
          "createdAt",
          "branch",
          "collaboratorAuthUserId",
          "collaboratorName",
          "terminalPayment",
          "card",
          "concept",
          "channel",
          "authCode",
          "reference",
          "isReversible"
        ]
      },
      "VoucherEmailDto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "example": "destinatario@correo.com"
          }
        },
        "required": [
          "email"
        ]
      },
      "StoreRefDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 50
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Central"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "TrendDto": {
        "type": "object",
        "properties": {
          "direction": {
            "type": "string",
            "enum": [
              "up",
              "down",
              "flat"
            ],
            "example": "up"
          },
          "percentage": {
            "type": "string",
            "nullable": true,
            "description": "Magnitude of the change; null when the previous period was 0",
            "example": "8.4"
          },
          "previousNetIncome": {
            "type": "string",
            "example": "1860.00"
          }
        },
        "required": [
          "direction",
          "percentage",
          "previousNetIncome"
        ]
      },
      "MoneyTotalsDto": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "example": "GTQ"
          },
          "totalCharges": {
            "type": "string",
            "example": "2016.96"
          },
          "totalCommissions": {
            "type": "string",
            "nullable": true,
            "description": "Null when op-liquidations is unavailable (degraded)",
            "example": "156.96"
          },
          "netIncome": {
            "type": "string",
            "nullable": true,
            "example": "1860.00"
          },
          "commissionPending": {
            "type": "boolean",
            "description": "True when at least one charge has no settlement yet",
            "example": false
          },
          "trend": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/TrendDto"
              }
            ]
          }
        },
        "required": [
          "currency",
          "totalCharges",
          "totalCommissions",
          "netIncome",
          "commissionPending",
          "trend"
        ]
      },
      "CommissionDto": {
        "type": "object",
        "properties": {
          "display": {
            "type": "string",
            "enum": [
              "fixed",
              "percentage"
            ],
            "example": "fixed"
          },
          "percentage": {
            "type": "string",
            "nullable": true,
            "example": null
          }
        },
        "required": [
          "display",
          "percentage"
        ]
      },
      "CollaboratorCardDto": {
        "type": "object",
        "properties": {
          "suffix": {
            "type": "string",
            "example": "4821"
          },
          "balance": {
            "type": "string",
            "example": "627.14"
          }
        },
        "required": [
          "suffix",
          "balance"
        ]
      },
      "CollaboratorDto": {
        "type": "object",
        "properties": {
          "authUserId": {
            "type": "number",
            "example": 1001
          },
          "name": {
            "type": "string",
            "nullable": true,
            "example": "Ana Admin"
          },
          "role": {
            "type": "string",
            "enum": [
              "SHOP_CASHIER",
              "SHOP_ADMIN",
              "SHOP_OWNER",
              "SHOP_CUSTOMER"
            ],
            "example": "SHOP_ADMIN"
          },
          "netIncome": {
            "type": "string",
            "description": "Net income attributed to this collaborator; omitted when degraded",
            "example": "320.00"
          },
          "card": {
            "description": "Omitted for cashiers and for collaborators without a card",
            "allOf": [
              {
                "$ref": "#/components/schemas/CollaboratorCardDto"
              }
            ]
          }
        },
        "required": [
          "authUserId",
          "name",
          "role"
        ]
      },
      "TerminalNetDto": {
        "type": "object",
        "properties": {
          "terminalId": {
            "type": "number",
            "example": 101
          },
          "currency": {
            "type": "string",
            "example": "GTQ"
          },
          "totalCharges": {
            "type": "string",
            "example": "100.00"
          },
          "totalCommissions": {
            "type": "string",
            "nullable": true,
            "description": "Null when op-liquidations is degraded",
            "example": "5.00"
          },
          "netIncome": {
            "type": "string",
            "nullable": true,
            "example": "95.00"
          },
          "collaboratorAuthUserId": {
            "type": "number",
            "nullable": true,
            "example": 1001
          },
          "collaboratorName": {
            "type": "string",
            "nullable": true,
            "description": "Null for a terminal with no resolvable owner",
            "example": "Ana Admin"
          }
        },
        "required": [
          "terminalId",
          "currency",
          "totalCharges",
          "totalCommissions",
          "netIncome",
          "collaboratorAuthUserId",
          "collaboratorName"
        ]
      },
      "StoreSummaryDto": {
        "type": "object",
        "properties": {
          "store": {
            "$ref": "#/components/schemas/StoreRefDto"
          },
          "period": {
            "type": "string",
            "enum": [
              "today",
              "last7d",
              "currentMonth"
            ]
          },
          "totals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MoneyTotalsDto"
            }
          },
          "commission": {
            "$ref": "#/components/schemas/CommissionDto"
          },
          "adminCount": {
            "type": "number",
            "example": 2
          },
          "cashierCount": {
            "type": "number",
            "example": 3
          },
          "collaborators": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CollaboratorDto"
            }
          },
          "terminals": {
            "description": "Net income per terminal+currency (charges − commission) with the owning collaborator",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TerminalNetDto"
            }
          },
          "degraded": {
            "type": "boolean",
            "example": false
          }
        },
        "required": [
          "store",
          "period",
          "totals",
          "commission",
          "adminCount",
          "cashierCount",
          "collaborators",
          "terminals",
          "degraded"
        ]
      },
      "AppCtaDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "INTERNAL_DEEPLINK",
              "EXTERNAL_DEEPLINK",
              "DYNAMIC_SERVICE"
            ]
          },
          "label": {
            "type": "string",
            "example": "Ir a cobrar"
          },
          "route": {
            "type": "string",
            "example": "/charge",
            "description": "INTERNAL_DEEPLINK"
          },
          "params": {
            "type": "object",
            "example": {
              "amount": 100
            },
            "description": "INTERNAL_DEEPLINK"
          },
          "navigationType": {
            "type": "string",
            "enum": [
              "push",
              "pushReplacement",
              "go",
              "pop"
            ],
            "description": "INTERNAL_DEEPLINK"
          },
          "url": {
            "type": "string",
            "example": "akisi://promo",
            "description": "EXTERNAL_DEEPLINK"
          },
          "fallbackUrl": {
            "type": "string",
            "example": "https://play.google.com/store",
            "description": "EXTERNAL_DEEPLINK"
          }
        },
        "required": [
          "type",
          "label"
        ]
      },
      "BannerCardDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "title": {
            "type": "string",
            "example": "Cobra sin comisión"
          },
          "description": {
            "type": "string",
            "example": "Durante octubre no hay comisión."
          },
          "actionLabel": {
            "type": "string",
            "example": "Conoce más",
            "nullable": true,
            "description": "Text of the link on the card; null: the app shows its default"
          },
          "backgroundColor": {
            "type": "string",
            "example": "#0B3D91"
          },
          "textColor": {
            "type": "string",
            "example": "#FFFFFF"
          },
          "imageUrl": {
            "type": "string",
            "example": "https://ali-public-files.s3.us-east-1.amazonaws.com/engagement/prod/banners/66f1c2a9e4b0a1b2c3d4e5f6/bannerImage-1790000000000.png"
          },
          "hasDetail": {
            "type": "boolean",
            "example": true
          },
          "detailDeepLink": {
            "type": "string",
            "example": "/banner-detail?bannerId=66f1c2a9e4b0a1b2c3d4e5f6",
            "nullable": true
          },
          "cta": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AppCtaDto"
              }
            ]
          },
          "hasTapCta": {
            "type": "boolean",
            "example": false,
            "description": "true: on every tap the app calls cta/execute with ctaPath \"tap\" without waiting, then opens the banner as usual"
          },
          "priority": {
            "type": "number",
            "example": 1,
            "description": "Carousel order (ascending)"
          },
          "visibleFrom": {
            "type": "string",
            "example": null,
            "nullable": true,
            "description": "Visible from (ISO UTC) by its schedule; null: no lower bound"
          },
          "visibleUntil": {
            "type": "string",
            "example": null,
            "nullable": true,
            "description": "Visible until (ISO UTC) by its schedule; null: no upper bound"
          },
          "endAt": {
            "type": "string",
            "example": "2026-11-01T05:59:59.000Z"
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "actionLabel",
          "backgroundColor",
          "textColor",
          "imageUrl",
          "hasDetail",
          "detailDeepLink",
          "cta",
          "hasTapCta",
          "priority",
          "visibleFrom",
          "visibleUntil",
          "endAt"
        ]
      },
      "AppInAppDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "banner_66f1c2a9e4b0a1b2c3d4e5f6_promo_landing"
          },
          "title": {
            "type": "string",
            "example": "Promo de octubre"
          },
          "description": {
            "type": "string",
            "example": "Cobra sin comisión todo el mes."
          },
          "deepLink": {
            "type": "string",
            "example": "/banner-detail?bannerId=66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "triggerScreen": {
            "type": "string",
            "example": "/home"
          },
          "priority": {
            "type": "number",
            "example": 0,
            "description": "Order among the in-apps (ascending)"
          },
          "visibleFrom": {
            "type": "string",
            "example": null,
            "nullable": true,
            "description": "Visible from (ISO UTC) by its schedule; null: no lower bound"
          },
          "visibleUntil": {
            "type": "string",
            "example": null,
            "nullable": true,
            "description": "Visible until (ISO UTC) by its schedule; null: no upper bound"
          },
          "isOneTime": {
            "type": "boolean",
            "example": false
          },
          "maxImpressions": {
            "type": "number",
            "example": 3,
            "nullable": true
          },
          "minIntervalHours": {
            "type": "number",
            "example": 24,
            "nullable": true
          },
          "urlImageLargeSize": {
            "type": "string"
          },
          "urlImageSmallSize": {
            "type": "string"
          },
          "urlImageMediumSize": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "deepLink",
          "triggerScreen",
          "priority",
          "visibleFrom",
          "visibleUntil",
          "isOneTime",
          "maxImpressions",
          "minIntervalHours",
          "urlImageLargeSize",
          "urlImageSmallSize",
          "urlImageMediumSize"
        ]
      },
      "UserBannersSettingsDto": {
        "type": "object",
        "properties": {
          "carouselIntervalMs": {
            "type": "number",
            "example": 5000
          }
        },
        "required": [
          "carouselIntervalMs"
        ]
      },
      "UserBannersResponseDto": {
        "type": "object",
        "properties": {
          "banners": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerCardDto"
            }
          },
          "inApps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AppInAppDto"
            }
          },
          "settings": {
            "$ref": "#/components/schemas/UserBannersSettingsDto"
          },
          "nextChangeAt": {
            "type": "string",
            "example": "2026-10-19T18:00:00.000Z",
            "nullable": true,
            "description": "Next instant something appears or hides by its dates or schedule: ask again then. null: nothing changes"
          }
        },
        "required": [
          "banners",
          "inApps",
          "settings",
          "nextChangeAt"
        ]
      },
      "BannerDetailViewDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "title": {
            "type": "string",
            "example": "Octubre sin comisión"
          },
          "content": {
            "type": "string",
            "example": "Texto ampliado del detalle..."
          },
          "backgroundColor": {
            "type": "string",
            "example": "#0B3D91"
          },
          "textColor": {
            "type": "string",
            "example": "#FFFFFF"
          },
          "urlImageSmallSize": {
            "type": "string"
          },
          "urlImageMediumSize": {
            "type": "string"
          },
          "urlImageLargeSize": {
            "type": "string"
          },
          "cta": {
            "nullable": true,
            "description": "Main button of the detail",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AppCtaDto"
              }
            ]
          },
          "secondaryCta": {
            "nullable": true,
            "description": "Link inside the detail box (for example \"Conocer más de la promoción\"). Any type; a DYNAMIC_SERVICE one runs with ctaPath \"secondary\"",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AppCtaDto"
              }
            ]
          },
          "endAt": {
            "type": "string",
            "example": "2026-11-01T05:59:59.000Z"
          }
        },
        "required": [
          "id",
          "title",
          "content",
          "backgroundColor",
          "textColor",
          "urlImageSmallSize",
          "urlImageMediumSize",
          "urlImageLargeSize",
          "cta",
          "secondaryCta",
          "endAt"
        ]
      },
      "ExecuteBannerCtaResponseDto": {
        "type": "object",
        "properties": {
          "serviceSuccess": {
            "type": "boolean",
            "example": true,
            "description": "false when the service failed by business or technically (with onError)"
          },
          "result": {
            "type": "object",
            "nullable": true,
            "description": "What the service answered"
          },
          "message": {
            "type": "string",
            "example": "¡Listo! Te avisaremos",
            "description": "successMessage or errorMessage of the CTA, to show together with nextCta; absent when not configured"
          },
          "nextCta": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AppCtaDto"
              }
            ]
          },
          "nextCtaPath": {
            "type": "string",
            "example": "onSuccess",
            "nullable": true,
            "description": "ctaPath to send if nextCta is dynamic too; null when the chain ends"
          },
          "nextCtaMode": {
            "type": "string",
            "enum": [
              "BUTTON",
              "AUTO"
            ],
            "nullable": true,
            "description": "BUTTON: show nextCta as a button; AUTO: run it at once without showing it. null when there is no nextCta"
          }
        },
        "required": [
          "serviceSuccess",
          "result",
          "nextCta",
          "nextCtaPath",
          "nextCtaMode"
        ]
      },
      "ExecuteBannerCtaRequestDto": {
        "type": "object",
        "properties": {
          "lang": {
            "type": "string",
            "enum": [
              "es",
              "en"
            ],
            "default": "es"
          },
          "ctaPath": {
            "type": "string",
            "example": "onSuccess",
            "description": "'' for the main CTA, 'secondary' for the secondary one of the detail and 'tap' for the card tap; onSuccess / onError chained with dots (never after 'tap')"
          }
        }
      },
      "TrackBannerInteractionRequestDto": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "HOME_CAROUSEL",
              "DETAIL",
              "INBOX",
              "IN_APP"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "CLICK",
              "CTA"
            ]
          },
          "eventId": {
            "type": "string",
            "example": "6f1c2a9e-4b0a-4b2c-9d4e-5f6a7b8c9d0e",
            "description": "Id of this click generated by the app: a retry with the same id counts once"
          }
        },
        "required": [
          "source",
          "action"
        ]
      },
      "ScheduleWindowDto": {
        "type": "object",
        "properties": {
          "days": {
            "example": [
              1,
              2,
              3,
              4,
              5
            ],
            "description": "ISO days: 1 = Monday … 7 = Sunday",
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "from": {
            "type": "string",
            "example": "12:00",
            "description": "HH:mm in the timezone of the app"
          },
          "to": {
            "type": "string",
            "example": "14:00",
            "description": "HH:mm; earlier than `from` crosses midnight (22:00 → 02:00)"
          }
        },
        "required": [
          "days",
          "from",
          "to"
        ]
      },
      "EngagementScheduleDto": {
        "type": "object",
        "properties": {
          "windows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScheduleWindowDto"
            }
          }
        },
        "required": [
          "windows"
        ]
      },
      "LocalizedTextDto": {
        "type": "object",
        "properties": {
          "es": {
            "type": "string",
            "example": "Cobra sin comisión"
          },
          "en": {
            "type": "string",
            "example": "Charge with no fee"
          }
        },
        "required": [
          "es"
        ]
      },
      "BannerDetailContentDto": {
        "type": "object",
        "properties": {
          "title": {
            "description": "Defaults to the banner title",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "content": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "secondaryCta": {
            "type": "object",
            "description": "Link inside the detail box, besides the main button (`cta`): INTERNAL_DEEPLINK, EXTERNAL_DEEPLINK or DYNAMIC_SERVICE (run with ctaPath \"secondary\")"
          }
        },
        "required": [
          "content"
        ]
      },
      "TapCtaDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "DYNAMIC_SERVICE"
            ]
          },
          "serviceKey": {
            "type": "string",
            "example": "JOIN_TOPIC"
          },
          "params": {
            "type": "object",
            "example": {
              "topicId": "66f0aa000000000000000001"
            }
          },
          "successMessage": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "errorMessage": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          }
        },
        "required": [
          "type",
          "serviceKey"
        ]
      },
      "ResponsiveImageDto": {
        "type": "object",
        "properties": {
          "small": {
            "type": "string"
          },
          "medium": {
            "type": "string"
          },
          "large": {
            "type": "string"
          }
        },
        "required": [
          "small",
          "medium",
          "large"
        ]
      },
      "BannerInAppDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "promo_landing"
          },
          "title": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "deepLink": {
            "type": "string",
            "description": "Own deep link of the in-app; empty: tapping it does not navigate"
          },
          "triggerScreen": {
            "type": "string",
            "example": "/landing"
          },
          "isOneTime": {
            "type": "boolean"
          },
          "priority": {
            "type": "number",
            "example": 1,
            "default": 0,
            "description": "Order among the in-apps (ascending)"
          },
          "maxImpressions": {
            "type": "object",
            "nullable": true,
            "minimum": 1
          },
          "minIntervalHours": {
            "type": "object",
            "nullable": true,
            "minimum": 0
          },
          "images": {
            "description": "Own images, uploaded in the multipart (inApp{index}_imageSmall|Medium|Large) or kept from the stored banner. Required for every in-app sent; only in-apps saved before they existed fall back to the detail images.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponsiveImageDto"
              }
            ]
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "triggerScreen",
          "isOneTime"
        ]
      },
      "BannerInboxConfigDto": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "type": {
            "type": "string",
            "enum": [
              "success",
              "info"
            ]
          }
        },
        "required": [
          "enabled",
          "type"
        ]
      },
      "BannerImagesDto": {
        "type": "object",
        "properties": {
          "banner": {
            "type": "string"
          },
          "detail": {
            "$ref": "#/components/schemas/ResponsiveImageDto"
          }
        },
        "required": [
          "banner",
          "detail"
        ]
      },
      "BannerAdminDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "promo_octubre_sin_comision"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ],
            "default": "ACTIVE"
          },
          "priority": {
            "type": "number",
            "example": 1,
            "description": "Carousel order (ascending)"
          },
          "startAt": {
            "type": "string",
            "example": "2026-10-01T06:00:00.000Z"
          },
          "endAt": {
            "type": "string",
            "example": "2026-11-01T05:59:59.000Z"
          },
          "schedule": {
            "nullable": true,
            "description": "Recurring windows inside startAt–endAt (timezone of each app); its in-apps follow it too. null removes it",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementScheduleDto"
              }
            ]
          },
          "title": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "actionLabel": {
            "nullable": true,
            "example": {
              "es": "Conoce más",
              "en": "Learn more"
            },
            "description": "Text of the link on the banner card; missing or null: the app shows its default",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "backgroundColor": {
            "type": "string",
            "example": "#0B3D91"
          },
          "textColor": {
            "type": "string",
            "example": "#FFFFFF"
          },
          "detail": {
            "$ref": "#/components/schemas/BannerDetailContentDto"
          },
          "cta": {
            "type": "object",
            "description": "INTERNAL_DEEPLINK, EXTERNAL_DEEPLINK or DYNAMIC_SERVICE"
          },
          "tapCta": {
            "nullable": true,
            "description": "Service run when the card is tapped (run with ctaPath \"tap\"): DYNAMIC_SERVICE only, no chaining. null removes it",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/TapCtaDto"
              }
            ]
          },
          "segmentIds": {
            "description": "Empty or missing: visible to every user",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audienceRules": {
            "type": "object",
            "nullable": true,
            "description": "Who sees it, like the RULES audience of a campaign: a root group { type: GROUP, operator: AND | OR, not?, children } of groups and conditions over SEGMENT, ROLE, PLATFORM, APP_VERSION, DEVICE_MODEL and USERS. Applies together with segmentIds; the in-apps of the banner inherit it. Missing: no rules; null removes them"
          },
          "inApps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerInAppDto"
            }
          },
          "inbox": {
            "$ref": "#/components/schemas/BannerInboxConfigDto"
          },
          "applicationIds": {
            "example": [
              "com.migo.yayo"
            ],
            "description": "applicationId of every app it is shown in (one or more)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "images": {
            "$ref": "#/components/schemas/BannerImagesDto"
          },
          "deletedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          }
        },
        "required": [
          "name",
          "priority",
          "startAt",
          "endAt",
          "title",
          "description",
          "backgroundColor",
          "textColor",
          "applicationIds",
          "id",
          "images",
          "deletedAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "BannersPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerAdminDto"
            }
          },
          "total": {
            "type": "number",
            "example": 12
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "BannerExclusionDto": {
        "type": "object",
        "properties": {
          "bannerId": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "name": {
            "type": "string",
            "example": "promo_kyc"
          },
          "reason": {
            "type": "string",
            "enum": [
              "INACTIVE",
              "NOT_STARTED",
              "EXPIRED",
              "NOT_IN_SEGMENT",
              "NOT_IN_AUDIENCE",
              "OVER_LIMIT",
              "OUT_OF_SCHEDULE"
            ]
          }
        },
        "required": [
          "bannerId",
          "name",
          "reason"
        ]
      },
      "BannerPreviewResponseDto": {
        "type": "object",
        "properties": {
          "banners": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerCardDto"
            }
          },
          "inApps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AppInAppDto"
            }
          },
          "settings": {
            "$ref": "#/components/schemas/UserBannersSettingsDto"
          },
          "nextChangeAt": {
            "type": "string",
            "example": "2026-10-19T18:00:00.000Z",
            "nullable": true,
            "description": "Next instant something appears or hides by its dates or schedule: ask again then. null: nothing changes"
          },
          "excluded": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerExclusionDto"
            }
          }
        },
        "required": [
          "banners",
          "inApps",
          "settings",
          "nextChangeAt",
          "excluded"
        ]
      },
      "BannerStatsPointDto": {
        "type": "object",
        "properties": {
          "periodKey": {
            "type": "string",
            "example": "2026-10-15"
          },
          "totalInteractions": {
            "type": "number",
            "example": 52
          },
          "uniqueUsers": {
            "type": "number",
            "example": 40
          },
          "byAction": {
            "type": "object",
            "example": {
              "CLICK": 45,
              "CTA": 7
            }
          },
          "bySource": {
            "type": "object",
            "example": {
              "HOME_CAROUSEL": 40,
              "DETAIL": 8,
              "INBOX": 3,
              "IN_APP": 1
            }
          }
        },
        "required": [
          "periodKey",
          "totalInteractions",
          "uniqueUsers",
          "byAction",
          "bySource"
        ]
      },
      "BannerStatsSeriesDto": {
        "type": "object",
        "properties": {
          "bannerId": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerStatsPointDto"
            }
          }
        },
        "required": [
          "bannerId",
          "points"
        ]
      },
      "BannerStatsResponseDto": {
        "type": "object",
        "properties": {
          "granularity": {
            "type": "string",
            "enum": [
              "DAY",
              "WEEK",
              "MONTH"
            ]
          },
          "timezone": {
            "type": "string",
            "example": "America/Guatemala",
            "description": "Timezone the periods were cut in: the app of `applicationId`, otherwise the default"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerStatsSeriesDto"
            }
          }
        },
        "required": [
          "granularity",
          "timezone",
          "series"
        ]
      },
      "BannerMetricsDto": {
        "type": "object",
        "properties": {
          "bannerId": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "from": {
            "type": "string",
            "example": "2026-10-01T00:00:00.000Z"
          },
          "to": {
            "type": "string",
            "example": "2026-10-31T23:59:59.000Z"
          },
          "totalInteractions": {
            "type": "number",
            "example": 1520
          },
          "uniqueUsers": {
            "type": "number",
            "example": 870
          },
          "bySource": {
            "type": "object",
            "example": {
              "HOME_CAROUSEL": 1100,
              "DETAIL": 300,
              "INBOX": 80,
              "IN_APP": 40
            }
          },
          "byAction": {
            "type": "object",
            "example": {
              "CLICK": 1200,
              "CTA": 320
            }
          }
        },
        "required": [
          "bannerId",
          "from",
          "to",
          "totalInteractions",
          "uniqueUsers",
          "bySource",
          "byAction"
        ]
      },
      "DeviceCountDto": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "example": "android"
          },
          "count": {
            "type": "number",
            "example": 120
          }
        },
        "required": [
          "value",
          "count"
        ]
      },
      "DeviceBreakdownDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 230
          },
          "byPlatform": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceCountDto"
            }
          },
          "byOsVersion": {
            "description": "Top 20",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceCountDto"
            }
          },
          "byAppVersion": {
            "description": "Top 20",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceCountDto"
            }
          },
          "byModel": {
            "description": "Top 20",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceCountDto"
            }
          }
        },
        "required": [
          "total",
          "byPlatform",
          "byOsVersion",
          "byAppVersion",
          "byModel"
        ]
      },
      "BannerInteractionDto": {
        "type": "object",
        "properties": {
          "subjectId": {
            "type": "string",
            "example": "1234"
          },
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "HOME_CAROUSEL",
              "DETAIL",
              "INBOX",
              "IN_APP"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "CLICK",
              "CTA"
            ]
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-15T14:03:00.000Z"
          }
        },
        "required": [
          "subjectId",
          "applicationId",
          "source",
          "action",
          "createdAt"
        ]
      },
      "BannerInteractionsPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerInteractionDto"
            }
          },
          "total": {
            "type": "number",
            "example": 1520
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "BannerMultipartDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "description": "JSON of the banner (CreateBannerRequestDto on create; only the fields to change on update)",
            "example": "{\"applicationIds\":[\"com.migo.yayo\"],\"name\":\"promo_octubre\"}"
          },
          "bannerImage": {
            "type": "string",
            "format": "binary"
          },
          "detailImageSmall": {
            "type": "string",
            "format": "binary"
          },
          "detailImageMedium": {
            "type": "string",
            "format": "binary"
          },
          "detailImageLarge": {
            "type": "string",
            "format": "binary"
          },
          "inApp0_imageSmall": {
            "type": "string",
            "format": "binary",
            "description": "Images of each in-app of `data.inApps`, by its index: inApp{index}_imageSmall, inApp{index}_imageMedium and inApp{index}_imageLarge (in-app dimensions). Every in-app sent must end with its three images: uploaded here or kept in `data.inApps[].images`."
          },
          "inApp0_imageMedium": {
            "type": "string",
            "format": "binary"
          },
          "inApp0_imageLarge": {
            "type": "string",
            "format": "binary"
          }
        },
        "required": [
          "data"
        ]
      },
      "StatusChangeRequestDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "BannerDeletedDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f6"
          },
          "deletedAt": {
            "type": "string",
            "example": "2026-10-15T20:00:00.000Z"
          }
        },
        "required": [
          "id",
          "deletedAt"
        ]
      },
      "DeeplinkRouteParamViewDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "cardId"
          },
          "in": {
            "type": "string",
            "enum": [
              "PATH",
              "QUERY"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "ADMIN",
              "APP"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "STRING",
              "NUMBER",
              "BOOLEAN"
            ]
          },
          "required": {
            "type": "boolean",
            "example": true
          },
          "description": {
            "type": "object",
            "nullable": true,
            "example": {
              "es": "Tarjeta activa del usuario"
            }
          },
          "options": {
            "nullable": true,
            "example": null,
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "in",
          "source",
          "type",
          "required",
          "description",
          "options"
        ]
      },
      "DeeplinkRouteDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6712aa000000000000000001"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "key": {
            "type": "string",
            "example": "CARD_DETAIL"
          },
          "path": {
            "type": "string",
            "example": "/my_card/:cardId"
          },
          "description": {
            "type": "object",
            "example": {
              "es": "Detalle de una tarjeta"
            }
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeeplinkRouteParamViewDto"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          },
          "deletedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-18T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-18T15:00:00.000Z"
          }
        },
        "required": [
          "id",
          "applicationIds",
          "key",
          "path",
          "description",
          "params",
          "status",
          "deletedAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "DeeplinkRoutesPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeeplinkRouteDto"
            }
          },
          "total": {
            "type": "number",
            "example": 12
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "DeeplinkRouteParamDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "cardId",
            "description": "Also the `:name` of the path"
          },
          "in": {
            "type": "string",
            "enum": [
              "PATH",
              "QUERY"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "ADMIN",
              "APP"
            ],
            "description": "ADMIN: the backoffice fills it; APP: the app fills it at runtime from its context"
          },
          "type": {
            "type": "string",
            "enum": [
              "STRING",
              "NUMBER",
              "BOOLEAN"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "description": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "options": {
            "example": [
              "from_email",
              "from_charge"
            ],
            "description": "Allowed values of an ADMIN param; the backoffice shows them as a select",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "in",
          "source",
          "type",
          "required"
        ]
      },
      "CreateDeeplinkRouteRequestDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "CARD_DETAIL",
            "description": "Immutable; unique per app"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps the route exists in. Editable",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "path": {
            "type": "string",
            "example": "/my_card/:cardId",
            "description": "As the app router declares it; unique per app"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeeplinkRouteParamDto"
            }
          }
        },
        "required": [
          "key",
          "applicationIds",
          "path",
          "description",
          "params"
        ]
      },
      "UpdateDeeplinkRouteRequestDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps the route exists in. Editable",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "path": {
            "type": "string",
            "example": "/my_card/:cardId",
            "description": "As the app router declares it; unique per app"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeeplinkRouteParamDto"
            }
          }
        }
      },
      "DeeplinkRouteDeletedDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6712aa000000000000000001"
          },
          "deletedAt": {
            "type": "string",
            "example": "2026-10-18T20:00:00.000Z"
          }
        },
        "required": [
          "id",
          "deletedAt"
        ]
      },
      "DynamicServiceTextDto": {
        "type": "object",
        "properties": {
          "es": {
            "type": "string",
            "example": "Me interesa: registra al usuario en un topic."
          },
          "en": {
            "type": "string",
            "example": "I'm interested: adds the user to a topic."
          }
        },
        "required": [
          "es"
        ]
      },
      "DynamicServiceParamDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "topicId"
          },
          "type": {
            "type": "string",
            "enum": [
              "STRING",
              "NUMBER",
              "BOOLEAN",
              "TOPIC"
            ],
            "description": "`TOPIC`: the id of a segmentation topic of the target apps"
          },
          "required": {
            "type": "boolean",
            "example": true
          },
          "description": {
            "$ref": "#/components/schemas/DynamicServiceTextDto"
          }
        },
        "required": [
          "name",
          "type",
          "required",
          "description"
        ]
      },
      "DynamicServiceDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "JOIN_TOPIC"
          },
          "description": {
            "$ref": "#/components/schemas/DynamicServiceTextDto"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DynamicServiceParamDto"
            }
          }
        },
        "required": [
          "key",
          "description",
          "params"
        ]
      },
      "BannerOrderEntryDto": {
        "type": "object",
        "properties": {
          "banner": {
            "description": "`priorityByApp` holds its position in each app",
            "allOf": [
              {
                "$ref": "#/components/schemas/BannerAdminDto"
              }
            ]
          },
          "visibleNow": {
            "type": "boolean",
            "description": "Shown right now in at least one of the apps (status, dates and schedule)"
          }
        },
        "required": [
          "banner",
          "visibleNow"
        ]
      },
      "InAppAdminDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "welcome_app",
            "description": "Used by the app as identifier. Cannot start with banner_"
          },
          "title": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "description": {
            "$ref": "#/components/schemas/LocalizedTextDto"
          },
          "deepLink": {
            "type": "string"
          },
          "triggerScreen": {
            "type": "string",
            "example": "/landing"
          },
          "isOneTime": {
            "type": "boolean"
          },
          "priority": {
            "type": "number",
            "example": 1,
            "default": 0,
            "description": "Order among the in-apps (ascending)"
          },
          "maxImpressions": {
            "type": "object",
            "nullable": true,
            "minimum": 1
          },
          "minIntervalHours": {
            "type": "object",
            "nullable": true,
            "minimum": 0
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ],
            "default": "ACTIVE"
          },
          "startAt": {
            "type": "object",
            "nullable": true
          },
          "endAt": {
            "type": "object",
            "nullable": true
          },
          "schedule": {
            "nullable": true,
            "description": "Recurring windows inside startAt–endAt (timezone of each app). null removes it",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementScheduleDto"
              }
            ]
          },
          "applicationIds": {
            "example": [
              "com.migo.yayo"
            ],
            "description": "applicationId of every app it is shown in (one or more)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f7"
          },
          "images": {
            "$ref": "#/components/schemas/ResponsiveImageDto"
          },
          "deletedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "triggerScreen",
          "isOneTime",
          "applicationIds",
          "id",
          "images",
          "deletedAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "InAppOrderEntryDto": {
        "type": "object",
        "properties": {
          "inAppId": {
            "type": "string",
            "nullable": true,
            "example": "66f1c2a9e4b0a1b2c3d4e5f7",
            "description": "Standalone in-app; null for the in-app of a banner"
          },
          "bannerId": {
            "type": "string",
            "nullable": true,
            "example": null,
            "description": "Banner of the in-app"
          },
          "bannerName": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "inApp": {
            "$ref": "#/components/schemas/InAppAdminDto"
          },
          "visibleNow": {
            "type": "boolean",
            "description": "Shown right now in at least one of the apps (status, dates and schedule)"
          }
        },
        "required": [
          "inAppId",
          "bannerId",
          "bannerName",
          "inApp",
          "visibleNow"
        ]
      },
      "InAppScreenOrderDto": {
        "type": "object",
        "properties": {
          "triggerScreen": {
            "type": "string",
            "example": "/home"
          },
          "items": {
            "description": "Sequence of the screen, in order",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InAppOrderEntryDto"
            }
          }
        },
        "required": [
          "triggerScreen",
          "items"
        ]
      },
      "EngagementOrderViewDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "banners": {
            "description": "Carousel order (the first selected app of each banner)",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BannerOrderEntryDto"
            }
          },
          "inAppScreens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InAppScreenOrderDto"
            }
          }
        },
        "required": [
          "applicationIds",
          "banners",
          "inAppScreens"
        ]
      },
      "SetBannersOrderRequestDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv",
              "com.migo.yayo"
            ],
            "description": "Apps the order is applied to; each one keeps only its own items, in this order",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bannerIds": {
            "description": "Banners in the order to show them",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "applicationIds",
          "bannerIds"
        ]
      },
      "InAppOrderRefDto": {
        "type": "object",
        "properties": {
          "inAppId": {
            "type": "string"
          },
          "bannerId": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Name of the in-app inside its banner"
          }
        }
      },
      "SetInAppsOrderRequestDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv",
              "com.migo.yayo"
            ],
            "description": "Apps the order is applied to; each one keeps only its own items, in this order",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "triggerScreen": {
            "type": "string",
            "example": "/home"
          },
          "items": {
            "description": "In-apps in the order of the sequence",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InAppOrderRefDto"
            }
          }
        },
        "required": [
          "applicationIds",
          "triggerScreen",
          "items"
        ]
      },
      "ImageDimensionsDto": {
        "type": "object",
        "properties": {
          "width": {
            "type": "number",
            "example": 300
          },
          "height": {
            "type": "number",
            "example": 200
          }
        },
        "required": [
          "width",
          "height"
        ]
      },
      "ResponsiveImageSpecsDto": {
        "type": "object",
        "properties": {
          "small": {
            "$ref": "#/components/schemas/ImageDimensionsDto"
          },
          "medium": {
            "$ref": "#/components/schemas/ImageDimensionsDto"
          },
          "large": {
            "$ref": "#/components/schemas/ImageDimensionsDto"
          }
        },
        "required": [
          "small",
          "medium",
          "large"
        ]
      },
      "EngagementImageSpecsDto": {
        "type": "object",
        "properties": {
          "maxBytes": {
            "type": "number",
            "example": 512000
          },
          "banner": {
            "$ref": "#/components/schemas/ImageDimensionsDto"
          },
          "detail": {
            "$ref": "#/components/schemas/ResponsiveImageSpecsDto"
          },
          "inApp": {
            "$ref": "#/components/schemas/ResponsiveImageSpecsDto"
          },
          "push": {
            "description": "Image of a push; missing: 1024x512",
            "allOf": [
              {
                "$ref": "#/components/schemas/ImageDimensionsDto"
              }
            ]
          }
        },
        "required": [
          "maxBytes",
          "banner",
          "detail",
          "inApp"
        ]
      },
      "EngagementSettingsDto": {
        "type": "object",
        "properties": {
          "bannerDetailRoute": {
            "type": "string",
            "example": "/banner-detail"
          },
          "maxBannersPerResponse": {
            "type": "object",
            "example": null,
            "nullable": true,
            "minimum": 1,
            "description": "Max banners in the home carousel; null means no limit (the default)"
          },
          "carouselIntervalMs": {
            "type": "number",
            "example": 5000
          },
          "allowedExternalSchemes": {
            "example": [
              "akisi",
              "https"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reportRecipients": {
            "example": [
              "marketing@empresa.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "clickRetentionDays": {
            "type": "number",
            "example": 180
          },
          "bannerNotificationRetentionDays": {
            "type": "number",
            "example": 30
          },
          "reportLinkExpirationDays": {
            "type": "number",
            "example": 7
          },
          "defaultImageSpecs": {
            "$ref": "#/components/schemas/EngagementImageSpecsDto"
          },
          "defaultTimezone": {
            "type": "string",
            "example": "America/Guatemala",
            "description": "Reporting timezone of the apps without rules.timezone"
          },
          "pushPublishPageDelayMs": {
            "type": "number",
            "example": 0,
            "description": "Pause (ms) between the audience pages of a push campaign; spreads the load on users (0: none)"
          }
        },
        "required": [
          "bannerDetailRoute",
          "maxBannersPerResponse",
          "carouselIntervalMs",
          "allowedExternalSchemes",
          "reportRecipients",
          "clickRetentionDays",
          "bannerNotificationRetentionDays",
          "reportLinkExpirationDays",
          "defaultImageSpecs",
          "defaultTimezone",
          "pushPublishPageDelayMs"
        ]
      },
      "UpdateEngagementSettingsDto": {
        "type": "object",
        "properties": {
          "bannerDetailRoute": {
            "type": "string",
            "example": "/banner-detail"
          },
          "maxBannersPerResponse": {
            "type": "object",
            "example": null,
            "nullable": true,
            "minimum": 1,
            "description": "Max banners in the home carousel; null means no limit (the default)"
          },
          "carouselIntervalMs": {
            "type": "number",
            "example": 5000
          },
          "allowedExternalSchemes": {
            "example": [
              "akisi",
              "https"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reportRecipients": {
            "example": [
              "marketing@empresa.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "clickRetentionDays": {
            "type": "number",
            "example": 180
          },
          "bannerNotificationRetentionDays": {
            "type": "number",
            "example": 30
          },
          "reportLinkExpirationDays": {
            "type": "number",
            "example": 7
          },
          "defaultImageSpecs": {
            "$ref": "#/components/schemas/EngagementImageSpecsDto"
          },
          "defaultTimezone": {
            "type": "string",
            "example": "America/Guatemala",
            "description": "Reporting timezone of the apps without rules.timezone"
          },
          "pushPublishPageDelayMs": {
            "type": "number",
            "example": 0,
            "description": "Pause (ms) between the audience pages of a push campaign; spreads the load on users (0: none)"
          }
        }
      },
      "SetEngagementAppSettingsRequestDto": {
        "type": "object",
        "properties": {
          "bannerDetailRoute": {
            "type": "string",
            "example": "/banner-detail"
          },
          "maxBannersPerResponse": {
            "type": "object",
            "example": null,
            "nullable": true,
            "minimum": 1,
            "description": "Max banners in the home carousel; null means no limit (the default)"
          },
          "carouselIntervalMs": {
            "type": "number",
            "example": 5000
          },
          "allowedExternalSchemes": {
            "example": [
              "akisi",
              "https"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EngagementAppSettingsViewDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv"
          },
          "overrides": {
            "description": "What the app overrides; the rest inherits the general settings",
            "allOf": [
              {
                "$ref": "#/components/schemas/SetEngagementAppSettingsRequestDto"
              }
            ]
          },
          "effective": {
            "description": "Settings the app ends up with (general + override)",
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementSettingsDto"
              }
            ]
          }
        },
        "required": [
          "applicationId",
          "overrides",
          "effective"
        ]
      },
      "ActiveInAppsResponseDto": {
        "type": "object",
        "properties": {
          "inApps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AppInAppDto"
            }
          },
          "nextChangeAt": {
            "type": "string",
            "example": "2026-10-19T18:00:00.000Z",
            "nullable": true,
            "description": "Next instant something appears or hides by its dates or schedule: ask again then. null: nothing changes"
          }
        },
        "required": [
          "inApps",
          "nextChangeAt"
        ]
      },
      "InAppsPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InAppAdminDto"
            }
          },
          "total": {
            "type": "number",
            "example": 4
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "InAppMultipartDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "description": "JSON of the in-app (CreateInAppRequestDto on create; only the fields to change on update, never name nor applicationIds)",
            "example": "{\"applicationIds\":[\"com.migo.yayo\"],\"name\":\"welcome_app\",\"triggerScreen\":\"/landing\",\"isOneTime\":true}"
          },
          "imageSmall": {
            "type": "string",
            "format": "binary"
          },
          "imageMedium": {
            "type": "string",
            "format": "binary"
          },
          "imageLarge": {
            "type": "string",
            "format": "binary"
          }
        },
        "required": [
          "data"
        ]
      },
      "InAppDeletedDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e5f7"
          },
          "deletedAt": {
            "type": "string",
            "example": "2026-10-15T20:00:00.000Z"
          }
        },
        "required": [
          "id",
          "deletedAt"
        ]
      },
      "PushTemplateNavigationDto": {
        "type": "object",
        "properties": {
          "deeplink": {
            "type": "string",
            "example": "/transaction_details/{cardTransferId}",
            "description": "Route of the deeplink catalog, opened on tap; {variable} values come from the event. Required unless the type is pop, exit or logout, which must not carry one"
          },
          "type": {
            "type": "string",
            "enum": [
              "push",
              "pushReplacement",
              "go",
              "pop",
              "exit",
              "logout"
            ],
            "nullable": true,
            "description": "What the app does as soon as the push arrives; null: nothing, the deeplink opens on tap"
          }
        }
      },
      "PushTemplateIosDto": {
        "type": "object",
        "properties": {
          "subtitle": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "threadId": {
            "type": "object",
            "example": "payments",
            "nullable": true
          }
        }
      },
      "PushTemplateToastDto": {
        "type": "object",
        "properties": {
          "show": {
            "type": "boolean",
            "description": "false: sent but not kept in the inbox"
          },
          "type": {
            "type": "string",
            "enum": [
              "success",
              "info",
              "error"
            ]
          }
        },
        "required": [
          "show",
          "type"
        ]
      },
      "PushCampaignContentDto": {
        "type": "object",
        "properties": {
          "title": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "body": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "bodyExtended": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "navigation": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateNavigationDto"
              }
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "transactions",
              "security",
              "promotions"
            ],
            "description": "Logical channel; each app maps it to its Android channel and iOS sound"
          },
          "ios": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateIosDto"
              }
            ]
          },
          "toast": {
            "$ref": "#/components/schemas/PushTemplateToastDto"
          },
          "imageUrl": {
            "type": "object",
            "nullable": true,
            "description": "Image already uploaded (https), for example the one of a push template"
          }
        },
        "required": [
          "title",
          "body",
          "channel",
          "toast"
        ]
      },
      "PushCampaignAudienceDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALL",
              "SEGMENTS",
              "TOPICS",
              "RULES"
            ]
          },
          "segmentIds": {
            "description": "SEGMENTS: users in any of them",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topicIds": {
            "description": "TOPICS: users in any of them",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rules": {
            "type": "object",
            "description": "RULES: a root group { type: GROUP, operator: AND | OR, not?, children } of groups and conditions { type: CONDITION, field, not?, ids?, days?, comparator?, text? } (see AudienceField)"
          }
        },
        "required": [
          "type"
        ]
      },
      "PushCampaignCountersDto": {
        "type": "object",
        "properties": {
          "targeted": {
            "type": "number",
            "example": 2000,
            "description": "Tokens published; known once every chunk is published"
          },
          "chunks": {
            "type": "number",
            "example": 4
          },
          "sent": {
            "type": "number",
            "example": 1985
          },
          "failed": {
            "type": "number",
            "example": 5
          },
          "invalidToken": {
            "type": "number",
            "example": 10,
            "description": "Tokens FCM rejected; deleted from the app"
          }
        },
        "required": [
          "targeted",
          "chunks",
          "sent",
          "failed",
          "invalidToken"
        ]
      },
      "PushCampaignAdminDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Promo de fin de mes"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Immutable",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "content": {
            "$ref": "#/components/schemas/PushCampaignContentDto"
          },
          "audience": {
            "$ref": "#/components/schemas/PushCampaignAudienceDto"
          },
          "scheduleAt": {
            "type": "string",
            "example": "2026-11-01T15:00:00.000Z"
          },
          "addToInbox": {
            "type": "boolean",
            "description": "Also keep it in the inbox of each user"
          },
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e7a0"
          },
          "expiresAt": {
            "type": "string",
            "example": "2026-11-04T15:00:00.000Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "SCHEDULED",
              "RUNNING",
              "DONE",
              "CANCELLED",
              "FAILED"
            ]
          },
          "failureReason": {
            "type": "string",
            "enum": [
              "INVALID_PAYLOAD",
              "MISSED_WINDOW",
              "PUBLISH_ERROR",
              "INTERRUPTED"
            ],
            "nullable": true
          },
          "estimatedReach": {
            "type": "number",
            "nullable": true,
            "example": 2000,
            "description": "Users with a device (ALL) or members (segments, topics) when it was saved"
          },
          "counters": {
            "$ref": "#/components/schemas/PushCampaignCountersDto"
          },
          "startedAt": {
            "type": "string",
            "nullable": true,
            "example": "2026-11-01T15:03:00.000Z"
          },
          "publishedAt": {
            "type": "string",
            "nullable": true,
            "example": "2026-11-01T15:04:10.000Z"
          },
          "finishedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "cancelledAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-20T00:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-20T00:00:00.000Z"
          }
        },
        "required": [
          "name",
          "applicationIds",
          "content",
          "audience",
          "scheduleAt",
          "addToInbox",
          "id",
          "expiresAt",
          "status",
          "failureReason",
          "estimatedReach",
          "counters",
          "startedAt",
          "publishedAt",
          "finishedAt",
          "cancelledAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "PushCampaignsPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushCampaignAdminDto"
            }
          },
          "total": {
            "type": "number",
            "example": 1
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "PushAudienceSampleUserDto": {
        "type": "object",
        "properties": {
          "subjectId": {
            "type": "string",
            "example": "1024"
          },
          "alias": {
            "type": "string",
            "nullable": true,
            "example": "kevin@migo.com"
          },
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv"
          }
        },
        "required": [
          "subjectId",
          "alias",
          "applicationId"
        ]
      },
      "PushAudienceEstimateDto": {
        "type": "object",
        "properties": {
          "reach": {
            "type": "number",
            "example": 2000
          },
          "exact": {
            "type": "boolean",
            "example": true,
            "description": "false: a RULES audience bigger than the sample, extrapolated from it"
          },
          "byApplication": {
            "type": "object",
            "example": {
              "com.migo.app.sv": 1500,
              "com.migo.ali": 500
            }
          },
          "sample": {
            "description": "A few users that would receive it",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushAudienceSampleUserDto"
            }
          }
        },
        "required": [
          "reach",
          "exact",
          "byApplication",
          "sample"
        ]
      },
      "EstimatePushAudienceDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audience": {
            "$ref": "#/components/schemas/PushCampaignAudienceDto"
          }
        },
        "required": [
          "applicationIds",
          "audience"
        ]
      },
      "PushCampaignDetailDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Promo de fin de mes"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Immutable",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "content": {
            "$ref": "#/components/schemas/PushCampaignContentDto"
          },
          "audience": {
            "$ref": "#/components/schemas/PushCampaignAudienceDto"
          },
          "scheduleAt": {
            "type": "string",
            "example": "2026-11-01T15:00:00.000Z"
          },
          "addToInbox": {
            "type": "boolean",
            "description": "Also keep it in the inbox of each user"
          },
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e7a0"
          },
          "expiresAt": {
            "type": "string",
            "example": "2026-11-04T15:00:00.000Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "SCHEDULED",
              "RUNNING",
              "DONE",
              "CANCELLED",
              "FAILED"
            ]
          },
          "failureReason": {
            "type": "string",
            "enum": [
              "INVALID_PAYLOAD",
              "MISSED_WINDOW",
              "PUBLISH_ERROR",
              "INTERRUPTED"
            ],
            "nullable": true
          },
          "estimatedReach": {
            "type": "number",
            "nullable": true,
            "example": 2000,
            "description": "Users with a device (ALL) or members (segments, topics) when it was saved"
          },
          "counters": {
            "$ref": "#/components/schemas/PushCampaignCountersDto"
          },
          "startedAt": {
            "type": "string",
            "nullable": true,
            "example": "2026-11-01T15:03:00.000Z"
          },
          "publishedAt": {
            "type": "string",
            "nullable": true,
            "example": "2026-11-01T15:04:10.000Z"
          },
          "finishedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "cancelledAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-20T00:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-20T00:00:00.000Z"
          },
          "opened": {
            "type": "number",
            "example": 320,
            "description": "Opens of the push of the campaign"
          }
        },
        "required": [
          "name",
          "applicationIds",
          "content",
          "audience",
          "scheduleAt",
          "addToInbox",
          "id",
          "expiresAt",
          "status",
          "failureReason",
          "estimatedReach",
          "counters",
          "startedAt",
          "publishedAt",
          "finishedAt",
          "cancelledAt",
          "createdAt",
          "updatedAt",
          "opened"
        ]
      },
      "CreatePushCampaignRequestDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Promo de fin de mes"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Immutable",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "content": {
            "$ref": "#/components/schemas/PushCampaignContentDto"
          },
          "audience": {
            "$ref": "#/components/schemas/PushCampaignAudienceDto"
          },
          "scheduleAt": {
            "type": "string",
            "example": "2026-11-01T15:00:00.000Z"
          },
          "expiresAt": {
            "type": "string",
            "example": "2026-11-04T15:00:00.000Z",
            "description": "When the push expires on the devices and leaves the inbox. Default: 72 h after it starts"
          },
          "addToInbox": {
            "type": "boolean",
            "description": "Also keep it in the inbox of each user"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "SCHEDULED"
            ],
            "description": "DRAFT is not sent; SCHEDULED is sent at scheduleAt"
          }
        },
        "required": [
          "name",
          "applicationIds",
          "content",
          "audience",
          "scheduleAt",
          "addToInbox",
          "status"
        ]
      },
      "UpdatePushCampaignRequestDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Promo de fin de mes"
          },
          "content": {
            "$ref": "#/components/schemas/PushCampaignContentDto"
          },
          "audience": {
            "$ref": "#/components/schemas/PushCampaignAudienceDto"
          },
          "scheduleAt": {
            "type": "string",
            "example": "2026-11-01T15:00:00.000Z"
          },
          "expiresAt": {
            "type": "string",
            "example": "2026-11-04T15:00:00.000Z",
            "description": "When the push expires on the devices and leaves the inbox. Default: 72 h after it starts"
          },
          "addToInbox": {
            "type": "boolean",
            "description": "Also keep it in the inbox of each user"
          },
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "SCHEDULED"
            ],
            "description": "DRAFT is not sent; SCHEDULED is sent at scheduleAt"
          }
        }
      },
      "PushTemplateAdminDto": {
        "type": "object",
        "properties": {
          "title": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "body": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "bodyExtended": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "navigation": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateNavigationDto"
              }
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "transactions",
              "security",
              "promotions"
            ],
            "description": "Logical channel; each app maps it to its Android channel and iOS sound"
          },
          "ios": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateIosDto"
              }
            ]
          },
          "dedupeBy": {
            "type": "object",
            "example": "settlementId",
            "nullable": true,
            "description": "Variable that identifies the event: one push per user and value"
          },
          "fallbacks": {
            "type": "object",
            "example": {
              "currency": {
                "isCritical": false,
                "default": "$"
              }
            },
            "nullable": true
          },
          "topics": {
            "example": [
              "PAYMENTS"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audienceRoles": {
            "example": [
              "owner",
              "admin"
            ],
            "description": "Roles that receive it; empty: every user",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "toast": {
            "$ref": "#/components/schemas/PushTemplateToastDto"
          },
          "ttlDays": {
            "type": "number",
            "example": 90,
            "description": "Days it stays in the inbox"
          },
          "eventKey": {
            "type": "string",
            "example": "SETTLEMENT_SUCCESSFUL",
            "description": "Event that sends it; unique per app and immutable"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv",
              "com.migo.ali"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e700"
          },
          "imageUrl": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          },
          "deletedAt": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-19T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-10-19T15:00:00.000Z"
          }
        },
        "required": [
          "title",
          "body",
          "channel",
          "toast",
          "ttlDays",
          "eventKey",
          "applicationIds",
          "id",
          "imageUrl",
          "status",
          "deletedAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "PushTemplatesPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushTemplateAdminDto"
            }
          },
          "total": {
            "type": "number",
            "example": 1
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "PushStatsPointDto": {
        "type": "object",
        "properties": {
          "periodKey": {
            "type": "string",
            "example": "2026-10-19"
          },
          "sent": {
            "type": "number",
            "example": 120
          },
          "failed": {
            "type": "number",
            "example": 2
          },
          "invalidToken": {
            "type": "number",
            "example": 1
          },
          "opened": {
            "type": "number",
            "example": 100
          },
          "uniqueOpened": {
            "type": "number",
            "example": 90
          },
          "bySource": {
            "type": "object",
            "example": {
              "NOTIFICATION_TRAY": 80,
              "IN_APP_ALERT": 12,
              "INBOX": 8
            },
            "description": "Opens by where they happened"
          },
          "byAppState": {
            "type": "object",
            "example": {
              "TERMINATED": 30,
              "BACKGROUND": 50
            },
            "description": "Tray opens: the push launched the app or brought it back"
          }
        },
        "required": [
          "periodKey",
          "sent",
          "failed",
          "invalidToken",
          "opened",
          "uniqueOpened",
          "bySource",
          "byAppState"
        ]
      },
      "PushStatsSeriesDto": {
        "type": "object",
        "properties": {
          "eventKey": {
            "type": "string",
            "example": "SETTLEMENT_SUCCESSFUL"
          },
          "points": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushStatsPointDto"
            }
          }
        },
        "required": [
          "eventKey",
          "points"
        ]
      },
      "PushStatsResponseDto": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "example": "PUSH"
          },
          "granularity": {
            "type": "string",
            "example": "DAY"
          },
          "timezone": {
            "type": "string",
            "example": "America/El_Salvador"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushStatsSeriesDto"
            }
          }
        },
        "required": [
          "channel",
          "granularity",
          "timezone",
          "series"
        ]
      },
      "PushMetricsDto": {
        "type": "object",
        "properties": {
          "eventKey": {
            "type": "string",
            "example": "SETTLEMENT_SUCCESSFUL"
          },
          "channel": {
            "type": "string",
            "example": "PUSH"
          },
          "from": {
            "type": "string",
            "example": "2026-10-01T00:00:00.000Z"
          },
          "to": {
            "type": "string",
            "example": "2026-10-31T23:59:59.000Z"
          },
          "sent": {
            "type": "number",
            "example": 1200,
            "description": "Accepted by FCM"
          },
          "failed": {
            "type": "number",
            "example": 10
          },
          "invalidToken": {
            "type": "number",
            "example": 4
          },
          "opened": {
            "type": "number",
            "example": 400,
            "description": "With the device filters"
          },
          "uniqueOpened": {
            "type": "number",
            "example": 380
          },
          "bySource": {
            "type": "object",
            "example": {
              "NOTIFICATION_TRAY": 80,
              "IN_APP_ALERT": 12,
              "INBOX": 8
            },
            "description": "Opens by where they happened"
          },
          "byAppState": {
            "type": "object",
            "example": {
              "TERMINATED": 30,
              "BACKGROUND": 50
            },
            "description": "Tray opens: the push launched the app or brought it back"
          },
          "devices": {
            "$ref": "#/components/schemas/DeviceBreakdownDto"
          }
        },
        "required": [
          "eventKey",
          "channel",
          "from",
          "to",
          "sent",
          "failed",
          "invalidToken",
          "opened",
          "uniqueOpened",
          "bySource",
          "byAppState",
          "devices"
        ]
      },
      "LegacyPushTemplateDto": {
        "type": "object",
        "properties": {
          "eventKey": {
            "type": "string",
            "example": "SETTLEMENT_SUCCESSFUL"
          },
          "template": {
            "type": "object",
            "additionalProperties": true,
            "description": "The template as stored in applications.pushs (tittle, body, navigation, ...)"
          }
        },
        "required": [
          "eventKey",
          "template"
        ]
      },
      "ClientDeviceDto": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "enum": [
              "ios",
              "android",
              "unknown"
            ]
          },
          "osVersion": {
            "type": "string",
            "example": "17.5"
          },
          "appVersion": {
            "type": "string",
            "example": "3.12.0"
          },
          "model": {
            "type": "string",
            "example": "iPhone15,2"
          }
        },
        "required": [
          "platform",
          "osVersion",
          "appVersion",
          "model"
        ]
      },
      "PushDeviceSummaryDto": {
        "type": "object",
        "properties": {
          "subjectId": {
            "type": "string",
            "example": "1024"
          },
          "alias": {
            "type": "string",
            "example": "kevin@migo.com",
            "nullable": true,
            "description": "What the app sent with the token (the email); null for older app versions"
          },
          "device": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ClientDeviceDto"
              }
            ]
          },
          "tokenEnding": {
            "type": "string",
            "example": "b-1a2b",
            "description": "Last characters of the token, never the token"
          },
          "registeredAt": {
            "type": "string",
            "example": "2026-10-20T12:00:00.000Z",
            "description": "Last login of the user in the app"
          }
        },
        "required": [
          "subjectId",
          "alias",
          "device",
          "tokenEnding",
          "registeredAt"
        ]
      },
      "PushDevicesPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PushDeviceSummaryDto"
            }
          },
          "total": {
            "type": "number",
            "example": 120
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "PushChannelSettingsDto": {
        "type": "object",
        "properties": {
          "androidChannelId": {
            "type": "string",
            "example": "k2p_default_channel"
          },
          "iosSound": {
            "type": "object",
            "example": "default",
            "nullable": true,
            "description": "Sound file bundled in the iOS app, or default"
          },
          "iosInterruptionLevel": {
            "type": "string",
            "enum": [
              "passive",
              "active",
              "time-sensitive"
            ],
            "nullable": true
          }
        },
        "required": [
          "androidChannelId"
        ]
      },
      "PushChannelsDto": {
        "type": "object",
        "properties": {
          "transactions": {
            "$ref": "#/components/schemas/PushChannelSettingsDto"
          },
          "security": {
            "$ref": "#/components/schemas/PushChannelSettingsDto"
          },
          "promotions": {
            "$ref": "#/components/schemas/PushChannelSettingsDto"
          }
        }
      },
      "PushAppSettingsViewDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv"
          },
          "variables": {
            "type": "object",
            "example": {
              "SETTLEMENT_SUCCESSFUL": {
                "currency": "$"
              }
            },
            "description": "Fixed variables per template (eventKey → variable → value)"
          },
          "channels": {
            "$ref": "#/components/schemas/PushChannelsDto"
          }
        },
        "required": [
          "applicationId",
          "variables",
          "channels"
        ]
      },
      "SetPushAppSettingsRequestDto": {
        "type": "object",
        "properties": {
          "variables": {
            "type": "object",
            "example": {
              "SETTLEMENT_SUCCESSFUL": {
                "currency": "$"
              }
            },
            "description": "Fixed variables of the app per template (eventKey → variable → value)"
          },
          "channels": {
            "description": "Missing channel: the default channel of the app",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushChannelsDto"
              }
            ]
          }
        },
        "required": [
          "variables",
          "channels"
        ]
      },
      "PushTemplateMultipartDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string",
            "description": "JSON of the template (CreatePushTemplateRequestDto on create; only the fields to change on update, never eventKey nor applicationIds; removeImage: true removes the image)",
            "example": "{\"eventKey\":\"SETTLEMENT_SUCCESSFUL\",\"applicationIds\":[\"com.migo.app.sv\"],\"title\":{\"es\":\"Cobro recibido\"},\"body\":{\"es\":\"Recibiste {currency}{amount}\"},\"channel\":\"transactions\",\"toast\":{\"show\":true,\"type\":\"success\"},\"ttlDays\":90}"
          },
          "pushImage": {
            "type": "string",
            "format": "binary",
            "description": "Optional PNG with the push dimensions of the apps (default 1024x512)"
          }
        },
        "required": [
          "data"
        ]
      },
      "TestPushSentDto": {
        "type": "object",
        "properties": {
          "sent": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "sent"
        ]
      },
      "PushTemplateContentDto": {
        "type": "object",
        "properties": {
          "title": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "body": {
            "description": "Texts take {variable} from the event, the app or the fallbacks",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "bodyExtended": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocalizedTextDto"
              }
            ]
          },
          "navigation": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateNavigationDto"
              }
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "transactions",
              "security",
              "promotions"
            ],
            "description": "Logical channel; each app maps it to its Android channel and iOS sound"
          },
          "ios": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PushTemplateIosDto"
              }
            ]
          },
          "dedupeBy": {
            "type": "object",
            "example": "settlementId",
            "nullable": true,
            "description": "Variable that identifies the event: one push per user and value"
          },
          "fallbacks": {
            "type": "object",
            "example": {
              "currency": {
                "isCritical": false,
                "default": "$"
              }
            },
            "nullable": true
          },
          "topics": {
            "example": [
              "PAYMENTS"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audienceRoles": {
            "example": [
              "owner",
              "admin"
            ],
            "description": "Roles that receive it; empty: every user",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "toast": {
            "$ref": "#/components/schemas/PushTemplateToastDto"
          },
          "ttlDays": {
            "type": "number",
            "example": 90,
            "description": "Days it stays in the inbox"
          }
        },
        "required": [
          "title",
          "body",
          "channel",
          "toast",
          "ttlDays"
        ]
      },
      "SendTestPushDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv",
            "description": "App whose channel and fixed variables the push uses"
          },
          "eventKey": {
            "type": "string",
            "example": "SETTLEMENT_SUCCESSFUL",
            "description": "Event of the template; the app receives it as `type`"
          },
          "token": {
            "type": "string",
            "description": "FCM registration token of the device; required without `subjectId`"
          },
          "subjectId": {
            "type": "string",
            "example": "1024",
            "description": "User of the app whose device receives the push; required without `token`"
          },
          "lang": {
            "type": "string",
            "enum": [
              "es",
              "en"
            ],
            "default": "es"
          },
          "variables": {
            "type": "object",
            "example": {
              "amount": "25.00"
            },
            "description": "Values of the event; the missing ones take the app values and the fallbacks"
          },
          "content": {
            "$ref": "#/components/schemas/PushTemplateContentDto"
          },
          "imageUrl": {
            "type": "object",
            "nullable": true,
            "description": "Image already uploaded (the saved one of the template)"
          }
        },
        "required": [
          "applicationId",
          "eventKey",
          "content"
        ]
      },
      "PushTemplateDeletedDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f1c2a9e4b0a1b2c3d4e700"
          },
          "deletedAt": {
            "type": "string",
            "example": "2026-10-19T20:00:00.000Z"
          }
        },
        "required": [
          "id",
          "deletedAt"
        ]
      },
      "TrackTopicsRequestDto": {
        "type": "object",
        "properties": {
          "topicKeys": {
            "example": [
              "VIEWED_PROMO_OCT"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "topicKeys"
        ]
      },
      "TopicDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f0aa000000000000000001"
          },
          "key": {
            "type": "string",
            "example": "SETTLEMENT_DONE"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Liquidó al menos una vez"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          },
          "defaultTtlDays": {
            "type": "number",
            "example": 30
          },
          "allowClientTracking": {
            "type": "boolean",
            "example": false
          },
          "createdAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          }
        },
        "required": [
          "id",
          "key",
          "applicationIds",
          "name",
          "description",
          "status",
          "defaultTtlDays",
          "allowClientTracking",
          "createdAt",
          "updatedAt"
        ]
      },
      "CreateTopicRequestDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "SETTLEMENT_DONE",
            "description": "Immutable, used by the code; unique per app"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps it applies to (one or more). Editable: a new app can join",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Liquidó al menos una vez"
          },
          "description": {
            "type": "string"
          },
          "defaultTtlDays": {
            "type": "number",
            "default": 30
          },
          "allowClientTracking": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "key",
          "applicationIds",
          "name"
        ]
      },
      "TopicsPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopicDto"
            }
          },
          "total": {
            "type": "number",
            "example": 3
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "UpdateTopicRequestDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps it applies to (one or more). Editable: a new app can join",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Liquidó al menos una vez"
          },
          "description": {
            "type": "string"
          },
          "defaultTtlDays": {
            "type": "number",
            "default": 30
          },
          "allowClientTracking": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "TopicMembersAddedDto": {
        "type": "object",
        "properties": {
          "added": {
            "type": "number",
            "example": 120,
            "description": "Subjects that were not members"
          },
          "refreshed": {
            "type": "number",
            "example": 30,
            "description": "Subjects that were members and renewed their expiration"
          }
        },
        "required": [
          "added",
          "refreshed"
        ]
      },
      "AddTopicMembersRequestDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv",
            "description": "App of the users; one of the topic"
          },
          "subjectIds": {
            "example": [
              "1234",
              "5678"
            ],
            "description": "Wallet user ids as text",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ttlDays": {
            "type": "number"
          }
        },
        "required": [
          "applicationId",
          "subjectIds"
        ]
      },
      "TopicMemberRemovedDto": {
        "type": "object",
        "properties": {
          "topicId": {
            "type": "string",
            "example": "66f0aa000000000000000001"
          },
          "subjectId": {
            "type": "string",
            "example": "1234"
          },
          "removedAt": {
            "type": "string",
            "example": "2026-10-15T20:00:00.000Z"
          }
        },
        "required": [
          "topicId",
          "subjectId",
          "removedAt"
        ]
      },
      "TopicMemberDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv"
          },
          "subjectId": {
            "type": "string",
            "example": "1234"
          },
          "expiresAt": {
            "type": "string",
            "example": "2026-11-14T12:00:00.000Z"
          },
          "lastEventAt": {
            "type": "string",
            "example": "2026-10-15T12:00:00.000Z"
          },
          "source": {
            "type": "string",
            "enum": [
              "INTERCEPTOR",
              "PUSH_TEMPLATE",
              "SERVICE",
              "CLIENT",
              "ADMIN"
            ]
          },
          "createdAt": {
            "type": "string",
            "example": "2026-10-15T12:00:00.000Z"
          }
        },
        "required": [
          "applicationId",
          "subjectId",
          "expiresAt",
          "lastEventAt",
          "source",
          "createdAt"
        ]
      },
      "TopicMembersPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopicMemberDto"
            }
          },
          "total": {
            "type": "number",
            "example": 150
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "TopicSummaryDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f0aa000000000000000001"
          },
          "key": {
            "type": "string",
            "example": "SETTLEMENT_DONE"
          },
          "name": {
            "type": "string",
            "example": "Liquidó al menos una vez"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          }
        },
        "required": [
          "id",
          "key",
          "name",
          "status"
        ]
      },
      "SegmentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "66f0bb000000000000000001"
          },
          "key": {
            "type": "string",
            "example": "ACTIVE_MERCHANTS"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Comercios activos"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "example": null
          },
          "topicIds": {
            "example": [
              "66f0aa000000000000000001"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TopicSummaryDto"
            }
          },
          "match": {
            "type": "string",
            "enum": [
              "ANY",
              "ALL"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "INACTIVE"
            ]
          },
          "createdAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "example": "2026-09-26T15:00:00.000Z"
          }
        },
        "required": [
          "id",
          "key",
          "applicationIds",
          "name",
          "description",
          "topicIds",
          "topics",
          "match",
          "status",
          "createdAt",
          "updatedAt"
        ]
      },
      "CreateSegmentRequestDto": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "ACTIVE_MERCHANTS",
            "description": "Immutable; unique per app"
          },
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps it applies to (one or more). Editable: a new app can join",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Comercios activos"
          },
          "description": {
            "type": "string"
          },
          "topicIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "match": {
            "type": "string",
            "enum": [
              "ANY",
              "ALL"
            ]
          }
        },
        "required": [
          "key",
          "applicationIds",
          "name",
          "topicIds",
          "match"
        ]
      },
      "SegmentsPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SegmentDto"
            }
          },
          "total": {
            "type": "number",
            "example": 2
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      },
      "UpdateSegmentRequestDto": {
        "type": "object",
        "properties": {
          "applicationIds": {
            "example": [
              "com.migo.app.sv"
            ],
            "description": "Apps it applies to (one or more). Editable: a new app can join",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "example": "Comercios activos"
          },
          "description": {
            "type": "string"
          },
          "topicIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "match": {
            "type": "string",
            "enum": [
              "ANY",
              "ALL"
            ]
          }
        }
      },
      "SegmentMemberDto": {
        "type": "object",
        "properties": {
          "applicationId": {
            "type": "string",
            "example": "com.migo.app.sv"
          },
          "subjectId": {
            "type": "string",
            "example": "1234"
          },
          "matchedTopicIds": {
            "example": [
              "66f0aa000000000000000001"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "applicationId",
          "subjectId",
          "matchedTopicIds"
        ]
      },
      "SegmentMembersPageDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SegmentMemberDto"
            }
          },
          "total": {
            "type": "number",
            "example": 870
          },
          "page": {
            "type": "number",
            "example": 1
          },
          "limit": {
            "type": "number",
            "example": 20
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "limit"
        ]
      }
    }
  }
}