Cómo funciona la API GraphQL

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

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.

Formato de respuesta

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

{
  "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.

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.

Próximos pasos

Authentication

Cómo se emite el token en ese encabezado Authorization: para tu cuenta o la de un cliente.

Errors

Qué contiene el arreglo errors y cómo bifurcar según códigos de error.

Desarrolladores

Recetas

Cómo funciona la API GraphQL

Endpoints

Anatomía de una solicitud

Queries vs. mutations

Formato de respuesta

Introspección y esquema

Próximos pasos

Authentication

Errors

​Endpoints

​Anatomía de una solicitud

​Queries vs. mutations

​Formato de respuesta

​Introspección y esquema

​Próximos pasos

Authentication

Errors

Endpoints

Anatomía de una solicitud

Queries vs. mutations

Formato de respuesta

Introspección y esquema

Próximos pasos