Descripción general

Usa la API de Fluz para enviar solicitudes de aprobación para acciones sensibles de la cuenta, listar solicitudes pendientes y aprobarlas o rechazarlas en nombre de los gerentes. Las solicitudes de aprobación están disponibles a través de la API GraphQL del Transactional Graph Service. Cuando se envía una solicitud, Fluz crea un registro de aprobación duradero y notifica a los aprobadores configurados. Si se aprueba, la acción subyacente se ejecuta automáticamente (por ejemplo, comprar una tarjeta de regalo o transferir fondos).

Cómo funciona

Requester                    Manager / Approver
   |                                |
   |  1. request* mutation          |
   |------------------------------->|
   |                                |
   |  2. APPROVAL_CREATE webhook    |
   |<-------------------------------|
   |                                |
   |              3. approvalRequests query (optional)
   |              4. approveApprovalRequest or declineApprovalRequest
   |                                |
   |  5. APPROVAL_APPROVE or        |
   |     APPROVAL_DECLINE webhook   |
   |<-------------------------------|

Solicitud — Un usuario con el alcance REQUEST_* apropiado llama a una mutación request*. La API valida la entrada y pone la solicitud en cola. La mutación devuelve un messageId, no un approvalId.
Creación — Fluz crea una aprobación pendiente y asigna a los gerentes de cuenta como aprobadores. Tu aplicación recibe un webhook APPROVAL_CREATE con el approvalId.
Lista (opcional) — Los aprobadores con LIST_APPROVALS pueden llamar a approvalRequests para obtener las solicitudes abiertas de la cuenta.
Aprobar o rechazar — Los aprobadores con MANAGE_APPROVALS llaman a approveApprovalRequest o declineApprovalRequest. Al aprobar, Fluz ejecuta la acción solicitada.
Webhook — Tu aplicación recibe APPROVAL_APPROVE o APPROVAL_DECLINE. Si la ejecución falla después de la aprobación, podrías recibir APPROVAL_HANDLER_ERROR.

Las solicitudes se procesan de forma asíncrona. Haz polling a approvalRequests o escucha webhooks para obtener el approvalId después de enviar una solicitud.

Operaciones compartidas

Estas operaciones aplican a todos los tipos de solicitudes de aprobación.

Listar aprobaciones pendientes

approvalRequests Devuelve solicitudes de aprobación abiertas (PENDING) para la cuenta autenticada. Alcance requerido: LIST_APPROVALS

query {
  approvalRequests {
    approvalId
    accountId
    requesterUserId
    approvalType
    approvalCode
    approvalStatus
    approversLogic
    expireDate
    createdAt
    approvers {
      approvalApproverId
      approverUserId
      role
      status
    }
  }
}

Aprobar una solicitud

approveApprovalRequest Aprueba una solicitud pendiente. Si tiene éxito, Fluz ejecuta la acción asociada con la solicitud (por ejemplo, crear una tarjeta virtual). Alcance requerido: MANAGE_APPROVALS

mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}

Rechazar una solicitud

declineApprovalRequest Rechaza una solicitud pendiente. No se ejecuta ninguna acción posterior. Alcance requerido: MANAGE_APPROVALS

mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
    error {
      code
      message
    }
  }
}

Alcances de la aplicación

Los alcances relacionados con aprobaciones deben otorgarse tanto a nivel de aplicación (por Fluz) como a nivel de usuario (mediante consentimiento OAuth o generateUserAccessToken).

Alcance	Uso
`LIST_APPROVALS`	Listar solicitudes de aprobación pendientes; recibir webhooks `APPROVAL_CREATE` y `APPROVAL_HANDLER_ERROR`
`MANAGE_APPROVALS`	Aprobar o rechazar solicitudes; recibir webhooks `APPROVAL_APPROVE` y `APPROVAL_DECLINE`
`REQUEST_VIRTUAL_CARD`	Enviar solicitudes de creación de tarjeta virtual
`REQUEST_VIRTUAL_CARD_LIMIT_CHANGE`	Enviar solicitudes de cambio de límite de tarjeta virtual
`REQUEST_GIFT_CARD`	Enviar solicitudes de compra de tarjeta de regalo
`REQUEST_INTERNAL_TRANSFER`	Enviar solicitudes de transferencia interna de cuenta de gasto
`REQUEST_ACCOUNT_TRANSFER`	Enviar solicitudes de transferencia entre cuentas
`REQUEST_REIMBURSEMENT`	Enviar solicitudes de reembolso

Consulta Autenticación para saber cómo se otorgan y validan los alcances.

Tipos de solicitud

Solicitud	Mutación	Alcance de creación
Creación de tarjeta virtual	`requestVirtualCard`	`REQUEST_VIRTUAL_CARD`
Cambio de límite de tarjeta virtual	`requestVirtualCardLimitChange`	`REQUEST_VIRTUAL_CARD_LIMIT_CHANGE`
Compra de tarjeta de regalo	`requestGiftCardPurchase`	`REQUEST_GIFT_CARD`
Transferencia interna	`requestInternalTransfer`	`REQUEST_INTERNAL_TRANSFER`
Transferencia entre cuentas	`requestAccountTransfer`	`REQUEST_ACCOUNT_TRANSFER`
Reembolso	`requestReimbursement`	`REQUEST_REIMBURSEMENT`

Cada tipo de solicitud tiene una guía dedicada con campos de entrada, ejemplos e identificadores de webhook.

Webhooks

Configura webhooks en el portal de desarrolladores de Fluz. Los eventos de aprobación usan el mismo mecanismo de entrega que otros webhooks de Fluz. Consulta la Descripción general para desarrolladores para la configuración y verificación.

Evento	Cuándo se activa	Alcance de suscripción al webhook
`APPROVAL_CREATE`	Se crea una nueva solicitud de aprobación	`LIST_APPROVALS`
`APPROVAL_APPROVE`	Se aprueba una solicitud	`MANAGE_APPROVALS`
`APPROVAL_DECLINE`	Se rechaza una solicitud	`MANAGE_APPROVALS`
`APPROVAL_HANDLER_ERROR`	La aprobación tuvo éxito pero la ejecución de la acción falló	`LIST_APPROVALS`

Carga útil de APPROVAL_CREATE

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "PENDING",
  "createdAt": "2025-07-09T10:00:00Z"
}

Usa approvalType y approvalCode juntos para identificar el tipo de solicitud. Cada guía por tipo enumera los valores para esa solicitud.

Carga útil de APPROVAL_APPROVE / APPROVAL_DECLINE

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "approverAccountId": "d4e5f6a7-b8c9-0123-def4-567890123456",
  "approverUserId": "e5f6a7b8-c9d0-1234-ef56-789012345678",
  "linkId": "f6a7b8c9-d0e1-2345-f678-901234567890",
  "attemptedAt": "2025-07-09T10:05:00Z"
}

Para rechazos, approvalAction es DECLINE y approvalStatus es DECLINED.

Carga útil de APPROVAL_HANDLER_ERROR

Se envía cuando una solicitud es aprobada pero la acción posterior falla (por ejemplo, saldo insuficiente en el momento de la ejecución).

{
  "approvalId": "07df5653-43a8-4532-9881-3ab5857bbe12",
  "accountId": "b1155504-ad30-4b2f-873d-b8795277b128",
  "userId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "approvalType": "GIFT_CARD",
  "approvalCode": "400007",
  "approvalStatus": "APPROVED",
  "approvalAction": "APPROVE",
  "failureStage": "ACTION_EXECUTION",
  "error": "Insufficient balance",
  "failedAt": "2025-07-09T10:05:01Z"
}

Autenticación

Las mutaciones de aprobación admiten token Bearer (OAuth de usuario) y Basic Auth (clave de API de la aplicación), según tu patrón de integración. El principal autenticado se convierte en el solicitante. Usa un User Access Token con los alcances requeridos. Consulta la Guía de Autenticación y Autorización.

Manejo de errores

Las mutaciones de solicitud devuelven un RequestApprovalResponse:

{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}

En caso de falla:

{
  "data": {
    "requestGiftCardPurchase": {
      "success": false,
      "messageId": null,
      "error": {
        "code": "APPROVAL_REQUEST_FAILED",
        "message": "Input validation error: ..."
      }
    }
  }
}

Las mutaciones de aprobar y rechazar devuelven success: false con un objeto error cuando la acción no puede completarse (por ejemplo, aprobación no encontrada o ya resuelta).

​Cómo funciona

​Operaciones compartidas

​Listar aprobaciones pendientes

​Aprobar una solicitud

​Rechazar una solicitud

​Alcances de la aplicación

​Tipos de solicitud

​Webhooks

​Carga útil de APPROVAL_CREATE

​Carga útil de APPROVAL_APPROVE / APPROVAL_DECLINE

​Carga útil de APPROVAL_HANDLER_ERROR

​Autenticación

​Manejo de errores