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

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:

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.

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

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

# 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

// 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).

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" }
      ] }'

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

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):

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.

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):

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

Primeros pasos

Conceptos clave

Guías

Pagar a un proveedor

Pagar a un proveedor

El flujo

1. Fondear la cuenta de la empresa

2. Dar de alta un proveedor

3. Crear y verificar una factura

4. Quote, aprobar, ejecutar

El routing engine

Pagos en lote (Mass Payments)

Fondear con Onramp (fiat → USDC)

Facturar a clientes (Invoicing / AR)

​Pagar a un proveedor

​El flujo

​1. Fondear la cuenta de la empresa

​2. Dar de alta un proveedor

​3. Crear y verificar una factura

​4. Quote, aprobar, ejecutar

​El routing engine

​Pagos en lote (Mass Payments)

​Fondear con Onramp (fiat → USDC)

​Facturar a clientes (Invoicing / AR)

Pagar a un proveedor

El flujo

1. Fondear la cuenta de la empresa

2. Dar de alta un proveedor

3. Crear y verificar una factura

4. Quote, aprobar, ejecutar

El routing engine

Pagos en lote (Mass Payments)

Fondear con Onramp (fiat → USDC)

Facturar a clientes (Invoicing / AR)