# Transacciones

La API de Transacciones devuelve registros de libro creados después de confirmar pagos exitosos. Úsala para conciliar pagos, auditar saldos y respaldar integraciones basadas en webhooks.

## Resumen

Cada solicitud de pago confirmada produce un registro de transacción. Las transacciones incluyen montos brutos y netos, metadatos de activo y red, direcciones de origen y destino, y hashes de transacción on-chain opcionales.

Las transacciones están limitadas a la entidad autenticada:

- **Claves API a nivel de cuenta** — transacciones solo de esa cuenta
- **Claves API a nivel de organización** — todas las transacciones de la organización, o una sola cuenta cuando se proporciona `accountID`

## Autenticación

Todas las solicitudes requieren ambos encabezados:

- `Authorization: Bearer <access_token>`
- `x-fluxis-api-key: <your_api_key>`

## Listar transacciones

```
GET /v1/transactions?page=1&page_size=50
```

### Parámetros de consulta

| Parámetro | Requerido | Descripción |
| --------- | -------- | ----------- |
| `page` | Sí | Número de página (mínimo `1`) |
| `page_size` | Sí | Elementos por página (`5`–`100`) |
| `accountID` | No | Filtrar a una cuenta específica (solo claves de organización). Debe pertenecer a tu organización |

::::warning
**Desfase de Swagger:** La referencia OpenAPI puede documentar parámetros de consulta `limit` y `offset` y una respuesta de array plano. El manejador en vivo usa **`page` y `page_size`** y devuelve un sobre paginado con `data`, `total`, `page`, `page_size` y `total_pages`. Sigue esta página y el comportamiento del manejador — no tipos swagger obsoletos.
::::

### Ejemplo

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

Para claves de organización limitadas a una cuenta:

```bash
curl "https://api.fluxis.us/v1/transactions?page=1&page_size=50&accountID=c87464d1-c54a-48c3-80c9-bee4fddf593d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"
```

### Forma de la respuesta

```json
{
  "data": {
    "data": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "payment_in",
        "status": "completed",
        "gross_amount": "100.00",
        "net_amount": "97.50",
        "expected_amount": "100.00",
        "currency": "USDC",
        "network": "polygon",
        "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "from_type": "wallet",
        "to": "0x1234567890abcdef1234567890abcdef12345678",
        "to_type": "vault",
        "financial_provider": "fluxis",
        "transaction_hash": "0xabcdef...",
        "created_at": "2026-05-21T12:00:00Z",
        "updated_at": "2026-05-21T12:05:00Z"
      }
    ],
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3
  }
}
```

::::note
Campos opcionales como `account_external_id`, `unique_asset_id`, `network` y `transaction_hash` usan `omitempty` y pueden estar ausentes según el tipo de transacción y la etapa de procesamiento.
::::

## Tipos de transacción

| Tipo | Descripción |
| ---- | ----------- |
| `payment_in` | Pago entrante de cliente |
| `payment_out` | Pago saliente |
| `deposit` | Depósito |
| `withdraw` | Retiro |
| `refund` | Reembolso |
| `adjustment` | Ajuste manual |
| `swap` | Intercambio de activos |
| `dry_run` | Registro de prueba / vista previa |

La mayoría de integraciones de comercio interactúan principalmente con registros `payment_in` creados cuando las solicitudes de pago alcanzan `confirmed`.

## Estados de transacción

| Estado | Descripción |
| ------ | ----------- |
| `preview` | Estado de vista previa |
| `pending` | Esperando procesamiento |
| `created` | Registro creado |
| `processing` | En progreso |
| `completed` | Completado exitosamente |
| `failed` | Fallido |
| `error` | Estado de error |
| `expired` | Expirado |

## Relación con solicitudes de pago

```mermaid
sequenceDiagram
    participant PR as Payment Request
    participant WH as Webhook
    participant TX as Transaction

    PR->>PR: processing → completed / underpaid / overpaid
    PR->>WH: payment_request_status_update
    PR->>PR: confirmed (ledger step)
    PR->>TX: payment_in transaction created
```

1. Los webhooks se disparan en `processing`, `completed`, `underpaid` y `overpaid` — consulta [Eventos de webhook](/es/docs/developers/webhook-events).
2. Tras la confirmación, aparece una transacción de libro en `GET /v1/transactions`.
3. Haz polling de transacciones como respaldo si se pierde un webhook.

## Patrón de conciliación

::::note
Combina webhooks (tiempo real) con polling periódico de transacciones (red de seguridad). Empareja por `payment_request_id` vía tu `external_reference_id` o correlacionando montos, marcas de tiempo y hashes de transacción.
::::

Flujo recomendado:

1. Almacena IDs de solicitud de pago cuando creas sesiones de checkout
2. Actualiza el estado del pedido desde webhooks `payment_request`
3. Nightly (o bajo demanda), recorre `GET /v1/transactions` y concilia brechas

## Documentación relacionada

- [Solicitudes de pago](/es/docs/key-concepts/payment-request) — ciclo de vida de estados
- [Eventos de webhook](/es/docs/developers/webhook-events) — actualizaciones de estado en tiempo real
- [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification) — verificación HMAC para entregas de webhook
- [Liquidaciones y consolidación](/es/docs/key-concepts/settlements-and-consolidation) — cómo se mueven los fondos tras la confirmación
- [Guía de integración API](/es/docs/developers/tutorials/api-integration-guide) — Paso 7 conciliación