> ## 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.

# Cómo funciona la API GraphQL

> Un endpoint, queries y mutations, y el formato de respuesta que puedes esperar en cada llamada.

Fluz expone un único endpoint de GraphQL por entorno. No hay rutas REST versionadas ni URLs base por capacidad: envías una query o mutation a `/graphql`, y el token decide en la cuenta de quién estás operando.

## Endpoints

| Environment | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| Staging     | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Live        | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

Los tokens de acceso se emiten desde un servicio OAuth separado en `https://oauth-service.fluzapp.com`.

## Anatomía de una solicitud

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetWallet($id: ID!) { wallet(id: $id) { balance { value currency } } }",
    "variables": { "id": "wal_01H..." }
  }'
```

* **`query`** — el documento GraphQL. Usa operaciones con nombre (`query GetWallet`) para mejores logs.
* **`variables`** — entradas tipadas, manteniendo los valores fuera del query string.
* **`operationName`** — opcional, útil cuando un documento define múltiples operaciones.

## Queries vs. mutations

* **Queries** son de solo lectura (`viewer`, `wallet`, `transactions`).
* **Mutations** cambian el estado (`createVirtualCard`, `purchaseGiftCard`, `depositCashBalance`, `createTransfer`).

Las mutations que mueven dinero usan desduplicación de solicitudes — ver [Idempotency](/concepts/idempotency).

## Formato de respuesta

GraphQL siempre devuelve HTTP 200 con un contenedor `data` / `errors`:

```json theme={null}
{
  "data": { "wallet": { "balance": { "value": 12500, "currency": "USD" } } },
  "errors": null,
  "extensions": { "requestId": "req_01H..." }
}
```

En caso de error, `data` puede ser `null` y `errors` describirá qué salió mal, incluyendo un `code` legible por máquina sobre el cual puedes bifurcar. Ver [Errors](/api-reference/errors).

## Introspección y esquema

La introspección está habilitada en staging para que puedas apuntar herramientas como Apollo Studio o GraphiQL al endpoint. En live, la introspección está deshabilitada; usa el esquema publicado en la [API reference](/api-reference/overview).

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/concepts/authentication">
    Cómo se emite el token en ese encabezado `Authorization`: para tu cuenta o la de un cliente.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    Qué contiene el arreglo `errors` y cómo bifurcar según códigos de error.
  </Card>
</CardGroup>