# API REST de Fluxis

La API REST de Fluxis te permite autenticarte, gestionar cuentas y puntos de venta, crear solicitudes de pago y recibir notificaciones webhook. Esta página te orienta; la referencia interactiva está en [/api](/api).

## URLs base

| Entorno | Host                       |
| ----------- | -------------------------- |
| Staging     | `https://api.stgfluxis.us` |
| Production  | `https://api.fluxis.us`    |

Todos los endpoints tienen el prefijo `/v1`.

## Autenticación

Cada solicitud protegida requiere **ambos** encabezados:

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

Obtén un token intercambiando tu clave API y secreto:

**`POST /v1/auth/token`**

Consulta [Authentication](/api/authentication#authenticate-and-get-access-token) en la referencia API.

::::warning
Nunca expongas tu secreto API en código del lado del cliente, navegadores o apps móviles.
::::

## Recursos principales

| Recurso         | Propósito                                   | Referencia                            |
| ---------------- | ----------------------------------------- | ------------------------------------ |
| **Accounts**     | Cuentas de comercio, direcciones de liquidación   | [/api — Accounts](/api/account)      |
| **Point of Sale**| Puntos de entrada de pago, solicitudes de pago    | [/api — Point of Sale](/api/point-of-sale) |
| **Webhooks**     | Notificaciones de eventos a nivel de cuenta         | [/api — Webhooks](/api/webhooks)     |
| **Transactions** | Conciliación e informes              | [/api — Transactions](/api/transactions) |
| **NASPIP**       | Leer o crear tokens NASPIP              | [/api — NASPIP Token](/api/naspip-token) |

## Flujo de integración típico

1. **Autenticación** — `POST /v1/auth/token`
2. **Descubrimiento de recursos** — `GET /v1/account`, `GET /v1/pos?page=1&page_size=20`
3. **Crear pagos** — `POST /v1/pos/{posID}/payment-request` (o `payment-request-checkout` para checkout alojado)
4. **Recibir actualizaciones** — Registra `POST /v1/account/{accountID}/webhook` con `event_type: payment_request`
5. **Conciliar** — `GET /v1/transactions?page=1&page_size=50` o haz polling de `GET /v1/pos/{posID}/payment-request/{paymentRequestID}`

Guía paso a paso: [Guía de integración API](/es/docs/developers/tutorials/api-integration-guide).

## Paginación

Los endpoints de listado usan los parámetros de consulta **`page`** y **`page_size`** (no offset/limit):

- **POS:** `page` ≥ 1, `page_size` 1–100
- **Transactions:** `page` ≥ 1, `page_size` 5–100
- **Webhook logs:** `page` ≥ 1, `page_size` 5–20

Las respuestas incluyen `{ data, total, page, page_size, total_pages }`.

## Webhooks

Los webhooks se registran por **cuenta**, no por POS. Fluxis firma las entregas con HMAC-SHA256.

- [Resumen de webhooks](/es/docs/developers/webhooks) — Registro y comportamiento de entrega
- [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification) — JSON canónico y flujo de prueba

Valores `event_type` compatibles: `payment_request`, `incoming_transfer`, `refund`.

## Explorar la API

<div
  style={{
    padding: "1.5rem",
    border: "1px solid #00e4a4",
    borderRadius: "8px",
    backgroundColor: "rgba(0, 228, 164, 0.05)",
    marginTop: "1.5rem",
  }}
>
  <h4 style={{ marginTop: 0, color: "#00e4a4" }}>Referencia API interactiva</h4>
  <p style={{ marginBottom: "1rem" }}>
    Explora endpoints, esquemas y prueba solicitudes en el playground.
  </p>
  <a href="/api" style={{ color: "#00d086", fontWeight: 600 }}>
    Abrir referencia API →
  </a>
</div>

## Guías relacionadas

- [Guía de integración API](/es/docs/developers/tutorials/api-integration-guide)
- [Crear y monitorear solicitudes de pago](/es/docs/developers/tutorials/payment-request)
- [Webhooks](/es/docs/developers/webhooks)
- [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification)
- [SDKs (próximamente)](/es/docs/developers/sdk)