Contrato de producción de la API #

La v1 de Nova es pequeña a propósito. Integra siguiendo estas reglas:

• Una ruta base: toda ruta autenticada vive bajo /api/v1.
• Un tipo de auth: envía Authorization: Bearer <clave>. No envíes claves de API desde código de navegador.
• Una superficie de SDK: los SDKs públicos deben llamar solo a /api/v1/*. /api/wallet/* es para la SPA Nova con sesión y usa cookies con CSRF.
• Respuesta directa en éxito: las respuestas exitosas devuelven el recurso. Los errores siempre usan el mismo envelope { "error": ... }.
• Reintentos seguros: los POSTs que mueven dinero requieren Idempotency-Key. También se acepta X-Idempotency-Key.
• Webhooks firmados: verifica Nova-Signature con el cuerpo crudo antes de confiar en un evento.

Acceso a la API #

Necesitas tres cosas:

1. Una cuenta Nova. Crea una si todavía no tienes.
2. Aprobación para usar la API. Abre la app Nova, ve a Cuenta → Desarrollador, llena la solicitud y espera la aprobación (normalmente menos de un día hábil).
3. Una clave de API. Tras la aprobación, la misma pantalla te deja crear una. Copia el secreto al instante — solo guardamos el hash y nunca lo volvemos a mostrar.

Comprueba que todo está conectado:

curl -H "Authorization: Bearer $NOVA_API_KEY" https://novadao.app/api/v1/ping

Deberías recibir un JSON con el id de tu clave, el tier y la hora del servidor. Si te llega 401, revisa la clave. Si te llega 403 hablando de un dominio, ve a Llamadas desde navegador (CORS).

Genera tu primer cobro PIX de R$ 1 (usa una dirección Liquid real que controles):

curl -X POST https://novadao.app/api/v1/pix/charges \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_in_cents": 100,
    "depix_address": "lq1..."
  }'

Vas a recibir un id, una cadena qr_copy_paste (pégala en cualquier app bancaria brasileña) y una qr_image_url con la marca de Nova. Paga el QR y verás el cobro pasar a paid.

Paquete SDK #

El paquete TypeScript @novadao/sdk es delgado: un transporte HTTP, grupos tipados por recurso, errores tipados, idempotencia como opción explícita y verificación de webhooks incluida. No oculta reintentos de POST si quien llama no mandó una clave de idempotencia.

Instala desde npm:

npm install @novadao/sdk

Página del paquete: @novadao/sdk en npm.

type NovaApiError = {
  status: number;
  code: string;
  message: string;
  requestId: string;
};

type PixCharge = {
  id: string;
  status: 'pending' | 'paid' | 'expired' | 'failed';
  amountInCents: number | null;
  qrCopyPaste: string | null;
  qrImageUrl: string | null;
  blockchainTxId: string | null;
  createdAt: string;
};

type PaymentLink = {
  id: string;
  name: string;
  mode: 'fixed' | 'range' | 'open';
  status: 'active' | 'paused';
  url: string;
  handle: string;
  slug: string;
  amountBrl: number | null;
  minBrl: number | null;
  maxBrl: number | null;
  depixAddress: string;
  createdAt: string;
};

type WebhookEndpoint = {
  id: number;
  url: string;
  events: string[];
  status: 'active' | 'disabled';
  createdAt: string;
};

type CreatedWebhookEndpoint = WebhookEndpoint & {
  signingSecret: string;
};

type NovaClient = {
  pix: {
    createCharge(
      input: { amountInCents: number; depixAddress: string },
      options: { idempotencyKey: string },
    ): Promise<PixCharge>;
    getCharge(id: string): Promise<PixCharge>;
  };
  paymentLinks: {
    create(input: CreatePaymentLink, options?: { idempotencyKey?: string }): Promise<PaymentLink>;
    get(id: string): Promise<PaymentLink>;
    pause(id: string): Promise<PaymentLink>;
  };
  webhooks: {
    list(): Promise<WebhookEndpoint[]>;
    create(
      input: CreateWebhookEndpoint,
      options: { idempotencyKey: string },
    ): Promise<CreatedWebhookEndpoint>;
    remove(id: number): Promise<{ id: number; deleted: true }>;
    test(id: number): Promise<{ deliveryId: string; queuedAt: string }>;
    verifySignature(
      rawBody: string | Uint8Array,
      header: string,
      secret: string,
      options?: { toleranceSeconds?: number },
    ): Promise<boolean>;
  };
};

Uso recomendado:

import { NovaClient, createIdempotencyKey } from '@novadao/sdk';

const nova = new NovaClient({
  apiKey: process.env.NOVA_API_KEY!,
});

const charge = await nova.pix.createCharge(
  { amountInCents: 100, depixAddress: 'lq1...' },
  { idempotencyKey: createIdempotencyKey('pix') },
);

Reglas de implementación:

• Lanza un NovaApiError con status, code, message y requestId cuando la API devuelva un envelope de error.
• Tipa fallas usando status y code. El mismo código puede aparecer con distinto status HTTP.
• Reintenta solo errores de red, 408, 429 y 5xx. Respeta Retry-After.
• Nunca reintentes POST /pix/charges sin clave de idempotencia. Para la misma solicitud lógica, reintenta con la misma clave; usa una clave nueva solo para un cobro nuevo.
• Exige clave de idempotencia en webhooks.create en el SDK, aunque la API cruda la acepte como opcional.
• Acepta snake_case de la API, pero expón tipos camelCase en TypeScript.

Autenticación #

Una clave de API es una cadena secreta que demuestra que la solicitud viene de ti. Trátala como una contraseña: nunca la pongas en código que corre en el navegador, nunca le hagas commit en GitHub, y cámbiala si sospechas que se filtró.

Envía tu clave en el encabezado Bearer estándar:

Authorization: Bearer nv_live_8aXk3rT9...

¿Qué significa “aprobación”?

La API hace cosas reales — genera cobros PIX, crea enlaces de pago — así que aprobamos a mano cada cuenta antes de que pueda crear claves. El formulario en la app pregunta qué estás construyendo y cuánto volumen esperas. La mayoría se revisa en un día hábil.

Lista de IPs permitidos

Si configuras una lista de IPs en tu cuenta de desarrollador (también en Cuenta → Desarrollador), la API rechaza cualquier solicitud cuyo IP de origen no esté en la lista. Es opcional, pero muy recomendado para servidores en producción.

Llamadas desde navegador (CORS) #

Por defecto, la API de Nova solo acepta llamadas servidor-a-servidor. Si intentas llamar a /api/v1/* desde un navegador, la respuesta es 403 browser_origin_disallowed.

Es intencional. Una clave de API en el navegador es una clave de API en las devtools de cada visitante. Si necesitas absolutamente llamar desde un navegador (por ejemplo, una integración híbrida donde la misma clave firma llamadas servidor y cliente), puedes registrar dominios permitidos específicos para esa clave. El panel muestra una advertencia clara cuando lo haces.

Límites de tasa #

Dos presupuestos, ambos por clave de API:

• Por minuto — 60 (tier1, por defecto) o 600 (tier2, bajo demanda).
• Por día — 10.000 (tier1) o 200.000 (tier2).

Algunos endpoints tienen sub-límites propios — revisa las notas de cada uno abajo. Toda respuesta autenticada incluye:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1714000060
X-RateLimit-Daily-Limit: 10000
X-RateLimit-Daily-Remaining: 9842
X-RateLimit-Daily-Reset: 1714086400

En 429 rate_limited también recibes Retry-After (en segundos). Espera y reintenta — no entres en bucle.

Idempotencia #

Los hipos de red existen. Si tu solicitud POST /pix/charges se queda en timeout, no sabes si el cobro se creó o no. Las claves de idempotencia hacen que reintentar sea seguro.

Envía un encabezado Idempotency-Key único (1..255 caracteres ASCII, lo que generes) en cada POST reintentable. Si la misma clave llega dos veces con el mismo cuerpo, devolvemos la respuesta cacheada con X-Idempotent-Replay: true en vez de crear un segundo cobro. Si la misma clave llega con un cuerpo distinto, devolvemos 409 idempotency_key_reused para que sepas que algo está raro.

Las respuestas cacheadas viven 24 horas. Los errores del servidor (5xx) nunca se cachean, así que siempre puedes reintentar una falla transitoria con la misma clave.

• Obligatorio en POST /pix/charges (dinero real).
• Opcional en POST /payment-links y POST /webhooks. Manda uno si quieres reintentos seguros.

Errores #

Todos los errores comparten el mismo envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "You are sending requests too quickly. Slow down and try again.",
    "request_id": "req_8aXk3rT9...",
    "docs_url": "https://novadao.app/devs/errors#rate_limited"
  }
}

El request_id es único por solicitud. Inclúyelo en cualquier ticket de soporte — nos permite encontrar el log del servidor al instante.

Endpoints #

URL base: https://novadao.app. Toda ruta autenticada está bajo /api/v1/.

curl https://novadao.app/api/v1/health

const res = await fetch('https://novadao.app/api/v1/health');
const data = await res.json();
console.log(data);

import httpx

res = httpx.get('https://novadao.app/api/v1/health')
print(res.json())

{
  "ok": true,
  "service": "nova-public-api",
  "server_time": "2026-04-25T12:34:56.000Z"
}

curl -H "Authorization: Bearer $NOVA_API_KEY" \
  https://novadao.app/api/v1/ping

const res = await fetch('https://novadao.app/api/v1/ping', {
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
console.log(await res.json());

import os, httpx

res = httpx.get(
    'https://novadao.app/api/v1/ping',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
print(res.json())

{
  "ok": true,
  "key_id": 42,
  "tier": "tier1",
  "allowed_domains": [],
  "server_time": "2026-04-25T12:34:56.000Z",
  "request_id": "req_8aXk..."
}

curl -X POST https://novadao.app/api/v1/pix/charges \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_in_cents": 5000,
    "depix_address": "lq1..."
  }'

import { randomUUID } from 'node:crypto';

const res = await fetch('https://novadao.app/api/v1/pix/charges', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOVA_API_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount_in_cents: 5000,
    depix_address: 'lq1...',
  }),
});
const charge = await res.json();
console.log(charge.id, charge.qr_copy_paste);

import os, uuid, httpx

res = httpx.post(
    'https://novadao.app/api/v1/pix/charges',
    headers={
        'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'amount_in_cents': 5000,
        'depix_address': 'lq1...',
    },
)
charge = res.json()
print(charge['id'], charge['qr_copy_paste'])

{
  "id": "ch_a8b3...",
  "status": "pending",
  "amount_in_cents": 5000,
  "qr_copy_paste": "00020126580014BR.GOV.BCB.PIX...",
  "qr_image_url": "https://novadao.app/api/v1/pix/charges/ch_a8b3.../qr.png",
  "blockchain_tx_id": null,
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -H "Authorization: Bearer $NOVA_API_KEY" \
  https://novadao.app/api/v1/pix/charges/ch_a8b3

const res = await fetch('https://novadao.app/api/v1/pix/charges/ch_a8b3', {
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
const charge = await res.json();
console.log(charge.status);

import os, httpx

res = httpx.get(
    'https://novadao.app/api/v1/pix/charges/ch_a8b3',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
charge = res.json()
print(charge['status'])

{
  "id": "ch_a8b3...",
  "status": "paid",
  "amount_in_cents": 5000,
  "qr_copy_paste": "00020126580014BR.GOV.BCB.PIX...",
  "qr_image_url": "https://novadao.app/api/v1/pix/charges/ch_a8b3.../qr.png",
  "blockchain_tx_id": "7f4a...",
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -X POST https://novadao.app/api/v1/payment-links \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pizza margherita",
    "mode": "fixed",
    "amount_brl": 25,
    "depix_address": "lq1..."
  }'

const res = await fetch('https://novadao.app/api/v1/payment-links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOVA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Pizza margherita',
    mode: 'fixed',
    amount_brl: 25,
    depix_address: 'lq1...',
  }),
});
const link = await res.json();
console.log(link.url);

import os, httpx

res = httpx.post(
    'https://novadao.app/api/v1/payment-links',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
    json={
        'name': 'Pizza margherita',
        'mode': 'fixed',
        'amount_brl': 25,
        'depix_address': 'lq1...',
    },
)
link = res.json()
print(link['url'])

{
  "id": "lk_HQKFuN22r39cc1Dp",
  "name": "Pizza margherita",
  "mode": "fixed",
  "status": "active",
  "url": "https://novadao.app/c/myshop/pizza-margherita",
  "handle": "myshop",
  "slug": "pizza-margherita",
  "amount_brl": 25,
  "min_brl": null,
  "max_brl": null,
  "depix_address": "lq1...",
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -H "Authorization: Bearer $NOVA_API_KEY" \
  https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp

const res = await fetch('https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp', {
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
const link = await res.json();
console.log(link.status, link.url);

import os, httpx

res = httpx.get(
    'https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
link = res.json()
print(link['status'], link['url'])

{
  "id": "lk_HQKFuN22r39cc1Dp",
  "name": "Pizza margherita",
  "mode": "fixed",
  "status": "active",
  "url": "https://novadao.app/c/myshop/pizza-margherita",
  "handle": "myshop",
  "slug": "pizza-margherita",
  "amount_brl": 25,
  "min_brl": null,
  "max_brl": null,
  "depix_address": "lq1...",
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -X DELETE https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp \
  -H "Authorization: Bearer $NOVA_API_KEY"

const res = await fetch('https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
const link = await res.json();
console.log(link.status);

import os, httpx

res = httpx.delete(
    'https://novadao.app/api/v1/payment-links/lk_HQKFuN22r39cc1Dp',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
link = res.json()
print(link['status'])

{
  "id": "lk_HQKFuN22r39cc1Dp",
  "name": "Pizza margherita",
  "mode": "fixed",
  "status": "paused",
  "url": "https://novadao.app/c/myshop/pizza-margherita",
  "handle": "myshop",
  "slug": "pizza-margherita",
  "amount_brl": 25,
  "min_brl": null,
  "max_brl": null,
  "depix_address": "lq1...",
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -H "Authorization: Bearer $NOVA_API_KEY" \
  https://novadao.app/api/v1/webhooks

const res = await fetch('https://novadao.app/api/v1/webhooks', {
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
const data = await res.json();
console.log(data.webhooks.length);

import os, httpx

res = httpx.get(
    'https://novadao.app/api/v1/webhooks',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
data = res.json()
print(len(data['webhooks']))

{
  "webhooks": [
    {
      "id": 7,
      "url": "https://yourshop.com/webhooks/nova",
      "events": ["pix.charge.paid", "payment_link.paid"],
      "status": "active",
      "created_at": "2026-04-25T12:34:56.000Z"
    }
  ]
}

curl -X POST https://novadao.app/api/v1/webhooks \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Idempotency-Key: webhook-paid-events-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourshop.com/webhooks/nova",
    "events": ["pix.charge.paid", "payment_link.paid"]
  }'

const res = await fetch('https://novadao.app/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOVA_API_KEY}`,
    'Idempotency-Key': 'webhook-paid-events-v1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://yourshop.com/webhooks/nova',
    events: ['pix.charge.paid', 'payment_link.paid'],
  }),
});
const wh = await res.json();
console.log('Save this signing secret:', wh.signing_secret);

import os, httpx

res = httpx.post(
    'https://novadao.app/api/v1/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}',
        'Idempotency-Key': 'webhook-paid-events-v1',
    },
    json={
        'url': 'https://yourshop.com/webhooks/nova',
        'events': ['pix.charge.paid', 'payment_link.paid'],
    },
)
wh = res.json()
print('Save this signing secret:', wh['signing_secret'])

{
  "id": 7,
  "url": "https://yourshop.com/webhooks/nova",
  "events": ["pix.charge.paid", "payment_link.paid"],
  "status": "active",
  "signing_secret": "Rll0hXsdn2hzp1G6...",
  "created_at": "2026-04-25T12:34:56.000Z"
}

curl -X DELETE https://novadao.app/api/v1/webhooks/7 \
  -H "Authorization: Bearer $NOVA_API_KEY"

const res = await fetch('https://novadao.app/api/v1/webhooks/7', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
console.log(await res.json());

import os, httpx

res = httpx.delete(
    'https://novadao.app/api/v1/webhooks/7',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
print(res.json())

{
  "id": 7,
  "deleted": true
}

curl -X POST https://novadao.app/api/v1/webhooks/7/test \
  -H "Authorization: Bearer $NOVA_API_KEY"

const res = await fetch('https://novadao.app/api/v1/webhooks/7/test', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.NOVA_API_KEY}` },
});
const delivery = await res.json();
console.log(delivery.delivery_id);

import os, httpx

res = httpx.post(
    'https://novadao.app/api/v1/webhooks/7/test',
    headers={'Authorization': f'Bearer {os.environ["NOVA_API_KEY"]}'},
)
delivery = res.json()
print(delivery['delivery_id'])

{
  "delivery_id": "whd_abc123",
  "queued_at": "2026-04-25T12:34:56.000Z"
}

Webhooks: eventos #

Nova publica un payload JSON a la URL de tu webhook cuando algo le pasa a uno de tus cobros o enlaces de pago. Suscríbete a los eventos que te importan al crear el webhook.

Para cobros PIX D+2, usa pix.charge.received para confirmar que el pagador completó el PIX en el riel bancario. Un pago delayed llega con status: "delayed", settlement_status: "delayed", delay_until, confirmed_at y blockchain_tx_id: null. Usa pix.charge.paid solo para la liquidación final en Liquid con blockchain_tx_id, y sigue escuchando pix.charge.failed para cobros reembolsados, cancelados o con error.

• pix.charge.created

  Se acaba de crear un cobro PIX. Útil para registrar la creación en tu propia base de datos.

• pix.charge.received

  Un cliente pagó el cobro PIX en el riel bancario. Los cobros D+2 pueden llegar con `status: "delayed"`, `settlement_status: "delayed"`, `delay_until`, `confirmed_at` y `blockchain_tx_id: null`, y liquidar después vía `pix.charge.paid`.

• pix.charge.paid

  El cobro PIX liquidó en Liquid e incluye el id de la transacción de liquidación.

• pix.charge.expired

  Un cobro PIX expiró antes de ser pagado.

• pix.charge.failed

  Un cobro PIX falló (cancelado, reembolsado o rechazado por la red). Sigue escuchando este evento incluso después de `pix.charge.received`.

• payment_link.paid

  Un checkout de enlace de pago se completó. Se dispara junto con `pix.charge.paid` cuando el cobro vino de un enlace.

Cada entrega incluye estos encabezados:

Nova-Signature: t=1714000000,v1=8a7c3b...
Nova-Event: pix.charge.paid
Nova-Delivery-Id: whd_abc123
Nova-Api-Version: 2026-04-24

Webhooks: verificar la firma #

Te mandamos un sello; tú confirmas que el sello coincide antes de confiar en el mensaje. Sin verificación, cualquiera que conozca tu URL podría enviarte eventos falsos. El encabezado Nova-Signature tiene dos partes: t (timestamp Unix en segundos) y v1 (HMAC-SHA256 en hex). La cadena firmada es t + "." + raw_body. Calcula el HMAC con tu signing_secret (devuelto una sola vez al crear el webhook) y compara.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyNovaWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  if (expected.length !== v1.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

import hmac, hashlib, time

def verify_nova_webhook(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    try:
        t = int(parts['t']); v1 = parts['v1']
    except KeyError:
        return False
    if abs(int(time.time()) - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

function verify_nova_webhook(string $body, string $header, string $secret, int $tolerance = 300): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $t = (int) ($parts['t'] ?? 0); $v1 = $parts['v1'] ?? '';
    if (!$t || !$v1) return false;
    if (abs(time() - $t) > $tolerance) return false;
    $expected = hash_hmac('sha256', $t . '.' . $body, $secret);
    return hash_equals($expected, $v1);
}

Webhooks: política de retry #

Si tu endpoint responde 2xx en menos de 15 segundos, la entrega se marca como completa. Cualquier otra respuesta es una falla. Las fallas reintentan seis veces con backoff:

Tras el último intento, la entrega se marca como failed. Tu panel la muestra bajo "Entregas de webhook" con un botón de replay manual. La app Nova también deja una notificación en tu bandeja.

Versionado #

La versión actual es /api/v1/. La tratamos como un contrato permanente. Los campos y tipos de evento nuevos son aditivos y no requieren que cambies nada. Si alguna vez sale un cambio rompedor, aterriza en /api/v2/ y v1 sigue viva al menos 12 meses. Durante la ventana de sunset, toda respuesta de v1 carga un encabezado Deprecation: true y una fecha Sunset.

Cada payload de webhook también incluye un campo api_version para que los suscriptores puedan ramificar el código sin clavar fechas.

Bug bounty y divulgación responsable #

Nova recibe reportes de seguridad sobre superficies del producto y de la API. Envía hallazgos en privado a hello@novadao.app con el asunto [security] <descripción corta>. No abras issues públicas ni publiques detalles hasta que Nova confirme que la divulgación está permitida.

Alcance

• Superficies de producción de Nova bajo https://novadao.app, incluyendo /app, /api/v1/*, flujos de cuenta y autenticación, enlaces de pago, firma y entrega de webhooks, y problemas del sitio o la documentación con impacto de seguridad.
• Reportes probados solo contra cuentas, claves, webhooks, enlaces de pago y datos que sean tuyos o que tengas autorización explícita para probar.

Reglas

• Incluye una descripción clara, impacto, URL o endpoint afectado, pasos para reproducir y cualquier prueba de concepto necesaria para validar el problema.
• Mantén las pruebas al mínimo necesario. No accedas, modifiques, borres ni extraigas datos de otros usuarios. Si aparecen datos sensibles, detén la prueba y reporta de inmediato.
• La investigación de buena fe que sigue estas reglas está cubierta por safe harbor: Nova no tomará acción legal por pruebas autorizadas dentro de este programa.

Fuera de alcance

• Denial-of-service, pruebas de carga, brute force automatizado, ingeniería social, phishing, ataques físicos, spam o campañas de abuso.
• Proveedores externos, sistemas de partners, extensiones de navegador, dispositivos de usuarios y entornos que no sean producción, salvo autorización explícita de Nova.
• Duplicados conocidos, salida de scanner sin impacto demostrado, problemas teóricos sin prueba de concepto práctica y problemas que solo afectan navegadores o plataformas desactualizados.

Recompensas

Los reportes validados pueden ser elegibles para recompensas discrecionales. La decisión considera severidad, impacto real, reproducibilidad, explotabilidad, calidad del reporte y si el problema ya era conocido.