> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
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   |
   |<-------------------------------|
```

1. **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`.
2. **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`.
3. **Lista (opcional)** — Los aprobadores con `LIST_APPROVALS` pueden llamar a `approvalRequests` para obtener las solicitudes abiertas de la cuenta.
4. **Aprobar o rechazar** — Los aprobadores con `MANAGE_APPROVALS` llaman a `approveApprovalRequest` o `declineApprovalRequest`. Al aprobar, Fluz ejecuta la acción solicitada.
5. **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`

```graphql theme={null}
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`

```graphql theme={null}
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`

```graphql theme={null}
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](/concepts/authentication) 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](/developers) 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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).

```json theme={null}
{
  "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](/concepts/authentication).

## Manejo de errores

Las mutaciones de solicitud devuelven un `RequestApprovalResponse`:

```json theme={null}
{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}
```

En caso de falla:

```json theme={null}
{
  "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).