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

# Pagar a un proveedor

> El lado comprador de Qopper (Business): fondear una cuenta de empresa, dar de alta un proveedor, subir una factura y enrutar el pago por el mejor rail — USDC on-chain o un payout local.

# Pagar a un proveedor

Qopper no es solo para agentes que cobran. **La otra mitad es una empresa que paga a sus proveedores.** Una compañía fondea un saldo en USDC y paga a proveedores internacionales con el flujo completo de cuentas por pagar: `invoice → verify → quote → approve → execute → reconcile`.

Al igual que el lado agente, la empresa entra desde la consola; todo queda acotado a tu cuenta (`ownerId`).

## El flujo

```
crear empresa → fondear (USDC) → dar de alta proveedor → crear factura
   → verificar → quote (routing) → aprobar → ejecutar → conciliar
```

Cada paso es su propio endpoint, para poder mostrarle al CFO el quote y obtener su aprobación humana antes de mover dinero.

## 1. Fondear la cuenta de la empresa

```bash theme={null}
curl -X POST https://api.qopper.com/api/business \
  -H "Authorization: Bearer <console JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp" }'
```

Toma el `businessId` y abónalo:

```bash theme={null}
curl -X POST https://api.qopper.com/api/business/<businessId>/topup \
  -H "Authorization: Bearer <console JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "amountUsdMinor": 5000000 }'   # $50.000,00
```

> El abono es idempotente: reenviar el mismo `idempotencyKey` no abona dos veces.

## 2. Dar de alta un proveedor

Un proveedor es una **cuenta de banco** (recibe moneda local, p. ej. COP) o una **wallet** (recibe USDC). Qopper detecta un cambio en los datos del banco y sube `bankRev`, lo que obliga a re-verificar antes del siguiente pago.

```bash theme={null}
curl -X POST https://api.qopper.com/api/vendors \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "<businessId>",
    "name": "Proveedor Bogotá",
    "country": "CO",
    "receivingCurrency": "COP",
    "destinationType": "bank",
    "bankDetails": { "bank": "Bancolombia", "account_number": "123456789" }
  }'
```

## 3. Crear y verificar una factura

```bash theme={null}
curl -X POST https://api.qopper.com/api/invoices \
  -H "Content-Type: application/json" \
  -d '{ "businessId": "<businessId>", "vendorId": "<vendorId>",
        "invoiceNumber": "INV-001", "amountMinor": 2500000, "currency": "USD" }'

curl -X POST https://api.qopper.com/api/invoices/<invoiceId>/verify
```

El agente de cuentas por pagar revisa duplicados, un proveedor sin verificar, un cambio de banco e importes inválidos, y devuelve un arreglo `riskFlags`. Sin riesgos, la factura pasa a `verified`.

## 4. Quote, aprobar, ejecutar

```bash theme={null}
# Quote: elige el mejor rail (coste, FX, velocidad, confiabilidad)
curl -X POST https://api.qopper.com/api/invoices/<invoiceId>/quote
# → { payment, quote: { best: { provider, feeMinor, fxRate, vendorReceivesMinor, etaMs, ... } } }

# Aprobación humana (CFO)
curl -X POST https://api.qopper.com/api/payments/<paymentId>/approve \
  -d '{ "approvedBy": "cfo@acme.com" }'

# Ejecutar: debita la empresa, enruta el rail, concilia
curl -X POST https://api.qopper.com/api/payments/<paymentId>/execute
```

```json theme={null}
// 200 — ejecutado (payout local)
{
  "paymentId": "pay_...",
  "provider": "offramp",
  "network": "local",
  "status": "payout_sent",
  "feeMinor": 12500,
  "fxRate": 4242,
  "vendorReceivesMinor": 10551975000,
  "payoutRef": "lpr_...",
  "reconciliation": { "matched": true }
}
```

## El routing engine

El quote lo produce `integrations/routing-engine.js`. Los rails son adaptadores; hoy hay dos:

* **on-chain (`onchain`)** — USDC directo a la wallet del proveedor. Sin FX, sin fee para el proveedor, en minutos.
* **off-ramp (`offramp`)** — USDC → moneda local a una cuenta de banco (COP, MXN, ...). Aplica un spread FX y un fee.

El router puntúa cada candidato por coste, velocidad y confiabilidad, y devuelve el mejor. Configura FX y corridors con `QOPPER_FX_USD_COP`, `QOPPER_OFFRAMP_CORRIDORS` (JSON) y el proveedor real de payouts con `QOPPER_OFFRAMP_EXECUTOR_URL`.

## Pagos en lote (Mass Payments)

Paga a **N destinatarios en una operación**: la empresa se debita una vez por el total, y el rail es `chain.batchSendUsdc` (transferencias secuenciales desde la cuenta `qopper-treasury`).

```bash theme={null}
curl -X POST https://api.qopper.com/api/business/<businessId>/payouts/batch \
  -H "Authorization: Bearer <console JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "items": [
        { "toAddress": "0xaaa", "amountMinor": 500000, "ref": "inv-1" },
        { "toAddress": "0xbbb", "amountMinor": 1000000, "ref": "inv-2" }
      ] }'
```

```json theme={null}
// 201
{ "batchId": "pb_...", "status": "completed", "totalMinor": 1500000,
  "count": 2, "txHash": "0xbatch", "items": [ { "status": "sent" }, { "status": "sent" } ] }
```

Lístalos con `GET /api/business/:id/payouts/batches`. El lote es idempotente por `idempotencyKey`; si el rail falla, el saldo de la empresa se repone y el lote queda `failed`.

## Fondear con Onramp (fiat → USDC)

Abona USDC real. El servidor firma el token de sesión de Coinbase (la clave secreta de CDP nunca llega al navegador) y devuelve un `onrampUrl` de un solo uso que abres en pestaña nueva.

```bash theme={null}
curl -X POST https://api.qopper.com/api/business/<businessId>/onramp/session \
  -H "Authorization: Bearer <console JWT>" -d '{ "paymentAmount": "50", "paymentCurrency": "USD" }'
# → { "depositAddress": "0x...", "onrampUrl": "https://pay.coinbase.com/buy?sessionToken=...", "sessionToken": "..." }
```

Tras la compra, reclama el USDC on-chain al saldo interno (idempotente por delta):

```bash theme={null}
curl -X POST https://api.qopper.com/api/business/<businessId>/onramp/claim
# → { "creditedMinor": 5000000, "balanceUsdMinor": 5000000 }
```

**Wallets de agente (Product B)** se fondean igual: `POST /agents/:id/onramp/session` — el watcher de depósitos acredita el saldo del agente automáticamente cuando llega el USDC.

> Para demos, define `QOPPER_ONRAMP_SANDBOX=1`: la compra siempre "triunfa" y tu tarjeta nunca se carga.

## Facturar a clientes (Invoicing / AR)

El mismo negocio también puede **cobrar**: emite una factura a un cliente, comparte el link y el dinero llega a tu saldo cuando paga.

```bash theme={null}
curl -X POST https://api.qopper.com/api/business/<businessId>/invoicing \
  -H "Authorization: Bearer <console JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "Partner Ltd", "amountMinor": 250000, "description": "Suscripción anual" }'
# → { "invoice": { "status": "issued", "paymentToken": "inv_..." }, "paymentUrl": "https://api.qopper.com/business/invoice/inv_..." }
```

Comparte `paymentUrl`. El cliente paga desde una wallet de agente (autenticada con su `qp_sk_`) o on-chain en USDC (x402):

```bash theme={null}
# Wallet de agente
curl -X POST https://api.qopper.com/api/public/invoice/inv_.../pay \
  -H "Authorization: Bearer qp_sk_..."            # debita ese agente, acredita al negocio

# USDC on-chain (x402)
curl https://api.qopper.com/api/public/invoice/inv_.../x402      # → 402 + requisitos de pago
curl -X POST .../x402 -H "X-PAYMENT: <firmado>"                    # → liquida, acredita al negocio
```

Al pagar, la factura pasa a `paid` y `businesses.balance_minor` se acredita — de forma idempotente (una factura paga una sola vez). Lístalas con `GET /api/business/:id/invoicing`.