Feed del mercado (webhooks)

Si tu integración pregunta cada pocos segundos si el mercado cambió, el feed es la respuesta: te avisamos nosotros. Un evento por cada oferta publicada, pausada, reactivada, aplicada, pagada, completada o cancelada, y por cada cambio en lo que queda de una oferta por rango.

Se contrata por app desde qvapay.com/dev, en la sección Feed del mercado P2P. $10 por 30 días, cobrados del saldo de la cuenta dueña de la app.

Con la misma suscripción tienes también el stream en vivo, que es la alternativa si prefieres no montar un endpoint público.

EventosCopy Anchor Link

Ofertas por rangoCopy Anchor Link

Estos tres solo llegan si los marcas: una oferta por rango se toma por partes y apply exige amount, así que una integración que no las conoce no las recibe. Ver Ofertas por rango en el feed.

Elegir qué llega a cada canalCopy Anchor Link

Por defecto llegan los ocho eventos de ofertas fijas, al webhook y al stream. En el panel, en Eventos que recibes, eliges por separado qué llega a cada canal: por ejemplo, el stream solo con p2p.created, p2p.reopened y p2p.range_created para que tu bot reaccione, y el webhook con todo para analítica. Si un canal se queda sin ninguno marcado, recibe los ocho de ofertas fijas.

El payloadCopy Anchor Link

{
  "event": "p2p.created",
  "sent_at": "2026-09-20T18:00:00Z",
  "data": {
    "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "sell",
    "coin": "USDT",
    "amount": "100.00",
    "receive": "39500.00",
    "status": "open",
    "updated_at": "2026-09-20T18:00:00Z",
    "only_vip": false,
    "offer_kind": "fixed",
    "available_amount": null,
    "order_min": null,
    "order_max": null,
    "owner_uuid": "3f1b2a90-5c7d-4e8f-9a01-2b3c4d5e6f70",
    "owner_vip": true,
    "requirements": { "min_completed": 25 },
    "change": null,
    "pause": null
  }
}

El campo event va siempre: no tienes que deducir el tipo por la forma del objeto.

Las características de la oferta van en todos los eventos, para que filtres antes de aplicar:

Las ofertas privadas no se publican en el feed.

Ofertas por rango en el feedCopy Anchor Link

{
  "event": "p2p.range_updated",
  "sent_at": "2026-10-13T23:06:20Z",
  "data": {
    "uuid": "0d4c57ca-7508-48d6-bcf1-3beb2d609b70",
    "type": "sell",
    "coin": "CLASICA",
    "amount": "660",
    "receive": "749.05",
    "status": "open",
    "updated_at": "2026-10-13T23:06:19Z",
    "only_vip": false,
    "offer_kind": "flexible",
    "available_amount": "545",
    "order_min": "20",
    "order_max": "660",
    "owner_uuid": "b49bb2e6-b4c8-4623-8102-b734fca402c2",
    "owner_vip": false,
    "requirements": null,
    "change": "taken",
    "pause": null
  }
}

• Lo que se puede tomar es available_amount, no amount (el total con el que se publicó).
• La tasa es receive / amount, igual que en una oferta fija.
• Para aplicar, manda amount entre order_min y el menor de order_max y available_amount. Sin amount, apply responde 400 FLEXIBLE_AMOUNT_REQUIRED y no se mueve dinero.
• Trata range_created y range_updated como un upsert: guarda la oferta con su available_amount actual. range_closed la saca del libro. Una oferta cerrada porque se quedó sin cupo puede volver si una parte se cancela; entonces llega un range_updated con status open.
• Pueden llegar varios range_updated seguidos de la misma oferta. Si se acumulan antes de que tu endpoint los reciba, el webhook entrega solo el más reciente, que es el estado que importa.
• Una oferta por rango pausada sale como range_closed con change paused (y pause con el motivo), aunque su status siga open. Vuelve con range_updated y change resumed. Si una parte vuelve mientras está pausada, ese returned también llega como range_closed/paused: lo que queda por tomar lo traerá el resumed.

Pausas en el feedCopy Anchor Link

Una oferta pausada no se cancela: sigue open, pero no se puede tomar. El feed lo cuenta con sus propios eventos para que no apliques a ciegas:

Si llevas un libro, trata paused como «fuera del libro» y resumed como «dentro», igual que applied y reopened. Si prefieres no esperar al evento, pause.until te dice cuándo volverá sola.

Verificar la firmaCopy Anchor Link

Cada petición llega con x-qvapay-signature (HMAC-SHA256 del cuerpo en crudo) y x-qvapay-timestamp. El secreto está en el panel y es propio del feed: rotarlo no toca las credenciales de tu app.

import crypto from 'node:crypto'

const raw = await request.text()                 // el cuerpo EN CRUDO, sin parsear
const esperada = crypto.createHmac('sha256', process.env.QVAPAY_FEED_SECRET)
	.update(raw)
	.digest('hex')

const recibida = (request.headers.get('x-qvapay-signature') || '').replace('sha256=', '')
const valida = crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(recibida))
if (!valida) return new Response('firma inválida', { status: 401 })

Rechaza también lo que llegue sin firma, y considera inválido un x-qvapay-timestamp de hace más de 5 minutos.

ReintentosCopy Anchor Link

Reintentamos ante error de red, 5xx y 429. No reintentamos ante otros 4xx: si tu endpoint responde 400 o 404 damos por hecho que entendió y rechazó, y machacarlo no lo arregla.

Responde 2xx en cuanto recibas, y procesa después. Si tardas más de 5 segundos cortamos y lo contamos como fallo.

Agotados los cinco intentos, la entrega queda en failed y ese evento no se reenvía.

IdempotenciaCopy Anchor Link

Un mismo evento puede llegarte más de una vez, y una misma oferta puede generar el mismo evento varias veces de verdad (reabre, la toma otra persona, vuelve a reabrir; o cada cambio de una oferta por rango). Usa event + data.uuid + data.updated_at como clave: si ya procesaste esa combinación, ignórala. Si un evento trae un updated_at anterior al que ya tienes para esa oferta, también puedes ignorarlo.

Depurar sin escribirnosCopy Anchor Link

curl -X GET "https://api.qvapay.com/v2/p2p/feed/deliveries" \
  -H "app-id: tu-app-id" -H "app-secret: tu-app-secret"

Devuelve las últimas entregas con el código que devolvió tu endpoint y el error exacto. Casi siempre ahí está la respuesta.

Estado de tu suscripciónCopy Anchor Link

curl -X GET "https://api.qvapay.com/v2/p2p/feed" \
  -H "app-id: tu-app-id" -H "app-secret: tu-app-secret"

{
  "data": { "active": true, "status": "active", "expires_at": "2026-10-20T18:00:00Z",
            "auto_renew": true, "webhook_url": "https://...",
            "webhook_events": ["p2p.created", "p2p.reopened", "p2p.paused", "p2p.resumed", "p2p.applied", "p2p.paid", "p2p.completed", "p2p.cancelled", "p2p.range_created", "p2p.range_updated", "p2p.range_closed"],
            "stream_events": ["p2p.created", "p2p.reopened", "p2p.range_created"],
            "events": ["p2p.created", "p2p.reopened", "p2p.paused", "p2p.resumed", "p2p.applied", "p2p.paid", "p2p.completed", "p2p.cancelled", "p2p.range_created", "p2p.range_updated", "p2p.range_closed"] },
  "meta": { "price_usd": 10, "period_days": 30,
            "all_events": ["…los once…"], "default_events": ["…los ocho de ofertas fijas…"],
            "range_events": ["p2p.range_created", "p2p.range_updated", "p2p.range_closed"] }
}

webhook_events y stream_events son lo que llega a cada canal. events se mantiene por compatibilidad y es igual a webhook_events.

Si el cobro de la renovación falla por saldo, el estado pasa a past_due pero el feed sigue funcionando hasta la fecha de vencimiento: el periodo que ya pagaste no se corta. Recarga antes de esa fecha y se renueva solo.