{ "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." }, "400": { "description": "Validation error: missing merchant identifier or signature payload." } }, "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." }, "400": { "description": "Validation error or invalid/expired refresh token." } }, "summary": "Refresh Integration Access Token", "tags": [ "Authentication" ] } }, "/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 received and queued for processing." }, "400": { "description": "Validation error." } }, "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": [], "responses": { "200": { "description": "Settlement webhook received and queued for processing." }, "400": { "description": "Validation error." } }, "summary": "Receive alternative payments settlement 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. Either an ExternalUserRegistrationDto (with invitationCode) or a CreateUserDto.", "content": { "application/json": { "schema": { "type": "string" } } } }, "responses": { "201": { "description": "User created successfully." }, "400": { "description": "Validation error in the registration payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Find User By Id Or Username", "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." }, "400": { "description": "Validation error in the permissions payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the roles payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the update payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the roles update payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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": "string" } } } }, "responses": { "201": { "description": "Auth user permissions created successfully." }, "400": { "description": "Validation error in the permissions payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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": "string" } } } }, "responses": { "200": { "description": "Auth user permissions updated successfully." }, "400": { "description": "Validation error in the permissions payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the invitation payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error or invalid credentials." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error or invalid/expired refresh token." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT 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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the link card payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Check Card Details", "tags": [ "Users" ] } }, "/users/auth/otp": { "post": { "description": "Requests a one-time password (OTP) to be delivered to the user email for a given purpose (e.g. password reset). Requires JWT. The request is delegated to the authentication service via NATS.", "operationId": "UsersController_requestOtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestOtpDto" } } } }, "responses": { "201": { "description": "OTP requested successfully." }, "400": { "description": "Validation error in the OTP request payload." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Request One-Time Password", "tags": [ "Users" ] }, "put": { "description": "Verifies a previously requested one-time password (OTP) for a given email and purpose. Requires JWT. The request is delegated to the authentication service via NATS.", "operationId": "UsersController_verifyOtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpDto" } } } }, "responses": { "200": { "description": "OTP verified successfully." }, "400": { "description": "Validation error or invalid/expired OTP." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Verify One-Time Password", "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." }, "400": { "description": "Validation error or password mismatch." }, "401": { "description": "Missing or invalid JWT token when one is supplied." } }, "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." }, "400": { "description": "Validation error or invalid recovery token." }, "401": { "description": "Missing or invalid JWT token when one is supplied." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the assignment payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error in the update payload." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Update Third Party Card Alias", "tags": [ "Users" ] }, "delete": { "description": "Removes a third-party card association from 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_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": { "204": { "description": "Third-party card unlinked successfully." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Unlink Third Party Card", "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "fcm-token-abc123xyz" } } } } } }, "responses": { "201": { "description": "FCM token registered successfully." }, "400": { "description": "Validation error in the FCM token payload." }, "401": { "description": "Missing or invalid JWT token." } }, "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-token-abc123xyz", "type": "string" } } ], "responses": { "204": { "description": "FCM token removed successfully." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Invalid file type or file too large." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Upload Profile Image", "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get User Profile", "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get Branches Summary By Business", "tags": [ "Users" ] } }, "/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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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" } } ], "responses": { "201": { "description": "Branches created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Create branches for a business", "tags": [ "Businesses" ] } }, "/businesses/commerces/{commerceId}/keys": { "post": { "operationId": "BusinessesController_saveCommerceKeys", "parameters": [ { "name": "commerceId", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "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" } } ], "responses": { "201": { "description": "Terminal created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get terminal by auth user", "tags": [ "Businesses" ] } }, "/businesses/terminals/{deviceId}": { "delete": { "operationId": "BusinessesController_deleteTerminal", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Update terminal", "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" } } ], "responses": { "201": { "description": "Terminal account created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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" } } ], "responses": { "201": { "description": "Terminal processor created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "List terminal processors", "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" } } ], "responses": { "200": { "description": "Terminal processor updated successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Update 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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get commerce documents", "tags": [ "Businesses" ] } }, "/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": { "201": { "description": "Card successfully linked to the customer in Volcan." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "Card information returned by the Volcan processor." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "Card successfully activated in Volcan." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "List of cards returned by the Volcan processor." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "Card successfully blocked in Volcan." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "Card successfully unblocked in Volcan." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "PIN successfully assigned in Volcan." }, "400": { "description": "Validation error." } }, "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": { "201": { "description": "Card movements returned by the Volcan processor." }, "400": { "description": "Validation error." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get legal information for an application", "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 successfully." }, "400": { "description": "Validation error." } }, "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." }, "400": { "description": "Validation error." } }, "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": "Validation error.\n\nValidación fallida — campo requerido faltante o inválido" }, "500": { "description": "Error interno al comunicarse con ali-ms-tl-reports" } }, "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. Optionally accepts an x-merchant-id header to associate the lead with a specific merchant.", "operationId": "LeadsController_createLead", "parameters": [ { "name": "x-merchant-id", "required": false, "in": "header", "description": "Optional merchant identifier the lead is associated with.", "schema": { "type": "string", "example": "merchant-abc123" } } ], "responses": { "201": { "description": "Lead created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error or disallowed field." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Update lead", "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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. Requires JWT authentication and application permissions.", "operationId": "TransfersController_findOneCardTransfer", "parameters": [ { "name": "id", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "id", "required": true, "in": "path", "description": "Internal identifier of the card transfer.", "schema": { "example": 12345, "type": "number" } } ], "responses": { "200": { "description": "Transfer retrieved successfully." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Get Card Transfer Details", "tags": [ "Card Transfers" ] } }, "/terminal-payment": { "post": { "description": "Creates a terminal payment by forwarding the request to the orchestrator microservice. The endpoint is currently public (guards commented out) and proxies the payload via HTTP. Returns the orchestrator response.", "operationId": "TerminalPaymentController_createTerminalPayment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTerminalPaymentInput" } } } }, "responses": { "201": { "description": "Terminal payment created successfully." }, "400": { "description": "Validation error." } }, "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" } } ], "responses": { "200": { "description": "Terminal payment updated successfully." }, "400": { "description": "Validation error." } }, "summary": "Update Terminal Payment", "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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. 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 processed successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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 creation accepted." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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" } } ], "responses": { "200": { "description": "Permission created successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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" } } ], "responses": { "200": { "description": "Permission updated successfully." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Find Permissions By Card", "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "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." }, "401": { "description": "Missing or invalid JWT token." } }, "security": [ { "bearer": [] } ], "summary": "Unblock Card", "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": "Home page returned successfully." } }, "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." } }, "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.", "operationId": "MessagingController_handleEmitEvent", "parameters": [], "responses": { "201": { "description": "Event emitted successfully." }, "400": { "description": "Validation error." } }, "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": { "200": { "description": "Payment processed successfully" }, "400": { "description": "Invalid request parameters" } }, "summary": "Process Terminal Payment", "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" ], "type": "string" } } ], "responses": { "200": { "description": "Settlement details retrieved successfully" }, "400": { "description": "Invalid or missing query parameters" }, "401": { "description": "Invalid or missing JWT token" } }, "security": [ { "bearer": [] } ], "summary": "Get Settlement Details", "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." } }, "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." } }, "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" } } ], "responses": { "201": { "description": "Terminal created successfully." }, "400": { "description": "Validation error." } }, "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." } }, "summary": "Get terminal by auth user", "tags": [ "Devices" ] } }, "/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": "Missing or invalid JWT token.\n\nNo 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": "Validation error.\n\nHash 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": "Missing or invalid JWT token.\n\nNo 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" ] } } }, "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": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.refresh.payload" } }, "required": [ "refreshToken" ] }, "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.", "example": "2026-05-21T15:30:00.000Z" }, "NumeroAutorizacion": { "type": "string", "description": "Authorization number returned by the issuer.", "example": "123456" }, "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" } } }, "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" } }, "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" } }, "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" ] }, "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" ], "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" ] }, "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" } } }, "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" } } }, "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" } } } }, "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": "{{transaction.id}}" }, "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": {} }, "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" } } }, "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" } } }, "required": [ "subtotal" ] }, "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": { "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)." } }, "required": [ "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." } }, "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" ] }, "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" ] }, "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" ], "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" } }, "required": [ "terminalPaymentId", "status" ] }, "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": "" } }, "required": [ "hash", "applicationId", "token" ] } } } }