NODO para desarrolladores · API v1

API de catálogo

Todos los distribuidores de tu comercio en una sola API: ficha completa, fotos, precio con impuestos y tu margen, stock y frescura de cada dato. Para tu tienda online, tu ERP, Google Merchant o Meta.

Base URL https://api.nodohub.appJSON · UTF-8 · OpenAPI 3.0Incluida en todos los planes de NODO
Índice

Introducción

La API expone el catálogo de tu comercio tal como lo ves en NODO: los distribuidores que tenés conectados, con tus precios, tus percepciones y tu margen. Cada key es de una organización y nunca ve el catálogo de otra.

Actualizada todo el día

Precio y stock salen de la última sincronización con cada distribuidor, que NODO corre de forma continua.

Sin caídas ni datos a medias

Si un distribuidor se cae, la API sigue respondiendo con el último dato bueno y te dice qué tan fresco es.

Se integra con todo

REST con JSON, webhooks firmados, cambios incrementales, exportación y feeds de Google y Meta.

Las keys se crean en NODO, en Configuración → API de catálogo. Ahí también elegís qué ve cada key: qué distribuidores, si se ve el costo, qué margen aplicar, en qué moneda y si se muestra el nombre del distribuidor.

Inicio rápido

Activá el módulo y creá una key

En Configuración → API de catálogo. Al crearla vas a ver el secret una sola vez: guardalo en una variable de entorno (NODO_API_SECRET).

Hacé el primer pedido

curl "https://api.nodohub.app/v1/products?limit=20&inStock=true" \
  -H "X-Api-Key: nodo_pk_4fK9wQ2mZx7LcT1vB8nR0aYs" \
  -H "X-Api-Secret: $NODO_API_SECRET"

Recibís productos con todas sus ofertas

200 OK · application/json
{
  "data": [
    {
      "id": "prd_Yt5Wc9KqA2mN7xV1pL3sD8",
      "name": "Placa de video ASUS Dual GeForce RTX 5070 12GB",
      "brand": { "id": "brd_asus", "name": "ASUS" },
      "category": { "id": "cat_gpu", "name": "Placas de video", "path": ["Componentes", "Placas de video"] },
      "ean": "4711387759411",
      "partNumber": "DUAL-RTX5070-O12G",
      "description": "…",
      "images": [{ "url": "https://…/rtx5070.jpg", "source": "provider" }],
      "specs": { "warranty": "36 meses", "weight": { "value": 1.1, "unit": "kg" } },
      "availability": { "inStock": true, "totalStock": 34, "offers": 3 },
      "priceRange": { "min": 698.5, "max": 731.2 },
      "bestOffer": { "id": "off_8hQ2vX1mT9cLk3PzR7aB4n", "…": "ver Oferta" },
      "offers": [ "…" ],
      "updatedAt": "2026-10-05T14:32:10Z"
    }
  ],
  "pagination": { "nextCursor": "eyJ1IjoiMjAyNi0xMC0wNVQxNDozMjoxMFoiLCJpIjo…", "hasMore": true, "limit": 100 },
  "meta": {
    "currency": "USD",
    "fx": null,
    "generatedAt": "2026-10-05T14:35:02Z"
  }
}

Autenticación

Cada key tiene una parte pública (nodo_pk_…) y un secret (nodo_sk_…). Mandalos en cada pedido por HTTPS de cualquiera de estas dos formas, que son equivalentes:

  • Headers X-Api-Key y X-Api-Secret.
  • HTTP Basic: usuario = key, contraseña = secret. Sirve para herramientas que solo aceptan Basic.
curl -u "nodo_pk_4fK9wQ2mZx7LcT1vB8nR0aYs:$NODO_API_SECRET" "https://api.nodohub.app/v1/me"

El secret es de tu servidor. Nunca lo pongas en el código que corre en el navegador o en una app: cualquiera podría leerlo. Si tu tienda necesita el catálogo en el navegador, pasalo por tu backend.

Permisos (scopes)

ScopePara qué
catalog:readLeer productos, ofertas y taxonomía
changes:readLeer cambios incrementales
export:readExportar el catálogo (CSV, XLSX, JSON)
feeds:readFeeds de Google Merchant y Meta
webhooks:manageAdministrar webhooks por API

Rotar el secret sin cortes

Al rotar, NODO te da un secret nuevo y el anterior sigue funcionando 24 horas. Actualizá tus sistemas en ese rato. También podés limitar cada key a ciertas IPs (acepta rangos CIDR) y ponerle vencimiento.

Errores

Los errores usan los códigos HTTP de siempre y un cuerpo con un code estable para que tu código decida, un mensaje en español y el requestId del pedido (también en el header X-Request-Id).

403 Forbidden
{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta key no tiene el permiso export:read.",
    "requestId": "req_9Gx2kLm4Qa",
    "docs": "https://nodohub.app/developers#errores"
  }
}
codeHTTPQué pasó
missing_credentials401Faltan la key o el secret.
invalid_credentials401La key no existe o el secret no coincide.
key_revoked401La key fue revocada.
key_expired401La key venció.
addon_required402La organización no tiene activo el módulo de API de catálogo.
subscription_suspended402La suscripción de la organización está suspendida.
ip_not_allowed403La IP del pedido no está en la lista permitida de la key.
insufficient_scope403La key no tiene el permiso que pide el endpoint.
not_found404El recurso no existe o no es visible para esta key.
invalid_parameter400Un parámetro tiene un valor inválido. El mensaje dice cuál.
invalid_cursor400El cursor está mal formado o es de otro endpoint.
cursor_expired410El cursor de cambios tiene más de 30 días: hacé un export completo y arrancá de nuevo.
feed_link_required422Para los feeds hace falta configurar el link de producto de tu tienda.
rate_limited429Pasaste el límite por minuto. Esperá lo que indica Retry-After.
internal_error500Error nuestro. Reintentá con backoff; el requestId nos ayuda a encontrarlo.

Límites

Cada key puede hacer 120 pedidos por minuto por defecto (si necesitás más, escribinos). Cada respuesta dice cuántos te quedan:

HTTP/1.1 200 OK
X-Request-Id: req_9Gx2kLm4Qa
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1791214380

Si te pasás, recibís 429 rate_limited con el header Retry-After en segundos. Para traer todo el catálogo usá limit=500 o el export, no miles de pedidos chicos.

Paginación

Las listas se paginan con cursor: pedís, y si pagination.hasMore es true, volvés a pedir concursor=pagination.nextCursor. El cursor es opaco (no lo armes a mano) y mantiene el orden aunque el catálogo cambie mientras recorrés.

async function* allProducts() {
  let cursor;
  do {
    const url = new URL("https://api.nodohub.app/v1/products");
    url.searchParams.set("limit", "500");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers });
    const body = await res.json();
    yield* body.data;
    cursor = body.pagination.hasMore ? body.pagination.nextCursor : null;
  } while (cursor);
}

for await (const product of allProducts()) {
  // guardar en tu base
}

Productos y ofertas

El catálogo se puede leer de dos formas. Cada key tiene una vista por defecto y podés pisarla con ?view=.

  • Productos (/v1/products): el mismo producto de varios distribuidores es una sola fila, con la mejor oferta, el rango de precios, el stock sumado y la lista de ofertas. Ideal para una tienda online.
  • Ofertas (/v1/offers): una fila por producto y distribuidor, como la búsqueda de NODO. Ideal para un ERP o para comparar.

Dos ofertas son el mismo producto cuando comparten EAN válido o, si no lo tienen, la misma marca y part number normalizados. Un producto trae la ficha completa: nombre, marca y categoría canónicas, EAN, part number, SKU, descripciones, todas las fotos, garantía, peso, medidas y etiquetas.

Una oferta

{
  "id": "off_8hQ2vX1mT9cLk3PzR7aB4n",
  "productId": "prd_Yt5Wc9KqA2mN7xV1pL3sD8",
  "provider": { "id": "prv_3Jd8sK2qLm9xV0aT", "name": "Proveedor 1" },
  "sku": "DUAL-RTX5070-O12G",
  "stock": { "quantity": 12, "status": "in_stock", "minThresholdApplied": 2 },
  "price": {
    "currency": "USD",
    "cost": {
      "net": 698.5,
      "taxes": [
        { "type": "iva", "label": "IVA", "percent": 10.5, "amount": 73.34 },
        { "type": "perception", "label": "Percepción IIBB", "percent": 3, "amount": 20.96 }
      ],
      "gross": 792.8
    },
    "sale": { "net": 838.2, "gross": 951.36, "markupPercent": 20 },
    "listSource": "api"
  },
  "freshness": { "syncedAt": "2026-10-05T14:32:10Z", "stale": false, "providerSync": "ok" }
}

Filtros y orden

/v1/products y /v1/offers aceptan los mismos parámetros. Se combinan con AND.

ParámetroQué hace
qTexto libre: nombre, marca, SKU, part number o EAN.
brand · category · subcategoryId o nombre canónico (los de /v1/brands y /v1/categories).
providerId del distribuidor (prv_…). Varios separados por coma.
inStocktrue para solo productos con stock.
minPrice · maxPriceSobre el precio de venta con impuestos, en la moneda de la key.
ean · partNumberBúsqueda exacta (normalizada).
updatedSinceISO 8601. Solo lo que cambió desde esa fecha.
sortrelevance · name · price · -price · updatedAt · -updatedAt (el - invierte).
limitDe 1 a 500. Por defecto 100.
viewproducts u offers. Pisa la vista por defecto de la key.

Ids estables

Los ids no cambian entre pedidos ni entre sincronizaciones: usalos como clave en tu base.

  • off_… identifica una oferta (producto de un distribuidor). No revela qué distribuidor es.
  • prd_… identifica un producto agrupado. Si un producto que estaba solo suma una oferta de otro distribuidor con el mismo EAN, mantiene su id.
  • prv_… identifica a un distribuidor. Con el nombre oculto, sale como «Proveedor 1, 2…» con un id que no cambia, para que tu web no muestre de quién comprás.

Precios e impuestos

Según la configuración de la key, cada oferta trae:

  • cost: lo que te cobra el distribuidor. net sin impuestos, taxes con cada impuesto desglosado (IVA, impuestos internos y tus percepciones, con alícuota y monto) y gross final.
  • sale: tu precio de venta = costo más tu margen (el que usás en NODO para cada distribuidor, o uno fijo para la key), redondeado como elijas.

Los impuestos se calculan con la misma lógica que la pantalla de NODO: lo que ves en el sistema y lo que devuelve la API siempre coinciden. Si una key alimenta una web pública, apagá el costo y dejá solo el precio de venta.

Monedas y cotización

Los precios salen en USD o en ARS. En pesos, la key usa la cotización que elijas (oficial, blue, MEP, tarjeta o una fija). La cotización se actualiza cada 10 minutos y cada respuesta dice cuál usó en meta.fx. Si el servicio de cotizaciones no responde, se usa la última conocida y meta.fx.stale vale true.

Frescura de los datos

La API nunca devuelve datos a medias. Los portales de algunos distribuidores se caen o responden incompleto; NODO no expone ese estado intermedio. Mientras un distribuidor no responde, sus ofertas siguen con el último dato bueno y te avisamos que no está al día.

  • freshness.syncedAt: cuándo se confirmó ese precio y stock con el distribuidor.
  • freshness.stale: true si pasó más tiempo del normal sin poder actualizarlo.
  • freshness.providerSync: ok, error (reintentando) o paused. /v1/providers trae el detalle por distribuidor.

Con esto podés decidir, por ejemplo, no vender online lo que esté stale, o mostrarlo como «a confirmar».

Endpoints

Todos bajo https://api.nodohub.app. El detalle de cada uno, con parámetros y esquemas, está en la referencia interactiva.

EndpointScopeDevuelve
GET /v1/me—Tu key: nombre, permisos, configuración efectiva, límites y estado del módulo.
GET /v1/productscatalog:readProductos agrupados (mismo producto de varios distribuidores en una fila).
GET /v1/products/{productId}catalog:readUn producto con todas sus ofertas.
GET /v1/offerscatalog:readUna fila por producto y distribuidor.
GET /v1/offers/{offerId}catalog:readUna oferta.
GET /v1/offers/{offerId}/price-historycatalog:readCambios de precio de los últimos 12 meses.
GET /v1/changeschanges:readFeed de cambios desde un cursor.
GET /v1/brandscatalog:readMarcas con cantidad de productos.
GET /v1/categoriescatalog:readÁrbol de categorías con conteos.
GET /v1/providerscatalog:readTus distribuidores (o sus alias) y el estado de su sincronización.
GET /v1/fx—Cotizaciones disponibles y la que usa tu key.
GET /v1/exportexport:readCatálogo completo en CSV, XLSX o JSON.
GET /v1/feeds/{feedToken}/google.xmlfeeds:readFeed de Google Merchant.
GET /v1/feeds/{feedToken}/meta.csvfeeds:readFeed del catálogo de Meta.
GET /v1/webhookswebhooks:manageTus webhooks.
POST /v1/webhookswebhooks:manageCrear un webhook.
PATCH /v1/webhooks/{id}webhooks:manageCambiar URL, eventos o pausarlo.
DELETE /v1/webhooks/{id}webhooks:manageBorrar un webhook.
POST /v1/webhooks/{id}/testwebhooks:manageMandar un evento ping de prueba.
GET /v1/openapi.jsonpúblicoEspecificación OpenAPI 3.0.

Cambios incrementales

Para mantener tu base al día sin bajar todo el catálogo, usá /v1/changes. Cada cambio es un offer.created, offer.updated u offer.removed con la oferta completa (o solo su id si salió). Una oferta sale cuando el distribuidor la da de baja, se queda sin stock (si tu key no incluye sin stock) o desconectás al distribuidor.

// 1. La primera vez: export completo y guardás el cursor actual.
let cursor = (await nodo("/v1/changes")).pagination.nextCursor;

// 2. Cada 1–5 minutos: traés solo lo que cambió.
async function sync() {
  let hasMore = true;
  while (hasMore) {
    const body = await nodo(`/v1/changes?cursor=${encodeURIComponent(cursor)}&limit=500`);
    for (const change of body.data) {
      if (change.type === "offer.removed") await removeOffer(change.offer.id);
      else await upsertOffer(change.offer);
    }
    cursor = body.pagination.nextCursor; // guardalo en tu base
    hasMore = body.pagination.hasMore;
  }
}

/v1/changes sin cursor te devuelve el cursor de ahora. El flujo recomendado: pedís el cursor, hacés el export completo y después consumís cambios desde ese cursor. Un cursor de más de 30 días responde 410 cursor_expired.

Webhooks

En vez de preguntar, NODO te avisa. Configurás una URL https y los eventos que te interesan (desde la pantalla de la key o por API con webhooks:manage). Los cambios llegan en lotes de hasta 100 en un evento catalog.changes, más o menos un minuto después de que NODO los detecta.

EventoCuándo
offer.createdEntra un producto
offer.updatedCambia un producto (cualquier dato)
offer.removedSale un producto
price.changedCambia un precio
stock.changedCambia el stock
provider.sync_pausedUn distribuidor pausó su sincronización
provider.sync_resumedUn distribuidor volvió a sincronizar
pingPrueba manual desde NODO.
Lo que recibe tu servidor
POST /webhooks/nodo HTTP/1.1
Content-Type: application/json
Nodo-Event-Id: evt_5Kq9mX2vT8aLc1Pz
Nodo-Event-Type: catalog.changes
Nodo-Signature: t=1791214330,v1=6f1c0e…b9a2

{
  "id": "evt_5Kq9mX2vT8aLc1Pz",
  "type": "catalog.changes",
  "createdAt": "2026-10-05T14:32:10Z",
  "data": {
    "items": [
      { "type": "price.changed", "productId": "prd_Yt5W…", "offer": { "id": "off_8hQ2…", "…": "oferta completa" }, "at": "2026-10-05T14:32:09Z" },
      { "type": "offer.removed", "productId": "prd_Ab3d…", "offer": { "id": "off_Zx81…" }, "at": "2026-10-05T14:32:09Z" }
    ]
  }
}

Verificar la firma

Cada evento viene firmado en Nodo-Signature con HMAC-SHA256 de {t}.{cuerpo} y el signing secret del webhook. Verificala siempre con el cuerpo crudo, antes de parsear el JSON, y rechazá eventos de más de 5 minutos para evitar repeticiones.

import crypto from "node:crypto";

/** rawBody: el cuerpo tal cual llegó (string), antes de parsear el JSON. */
export function verifyNodoSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post("/webhooks/nodo", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyNodoSignature(req.body.toString("utf8"), req.get("Nodo-Signature"), process.env.NODO_WEBHOOK_SECRET))
//     return res.sendStatus(400);
//   res.sendStatus(200); // respondé rápido y procesá en segundo plano
// });

Reintentos

Tu servidor tiene que responder 2xx en menos de 10 segundos (respondé rápido y procesá en segundo plano). Si no, reintentamos a los 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Usá Nodo-Event-Id para no procesar dos veces el mismo evento. Tras 20 fallos seguidos el webhook se deshabilita y le avisamos al dueño de la cuenta; después de arreglarlo, se reactiva desde NODO y se ponen al día los cambios pendientes.

Exportar

GET /v1/export?format=csv|xlsx|json&view=products|offers devuelve el catálogo completo con la configuración de la key y los mismos filtros que las listas. Se envía en stream: empieza a llegar enseguida aunque sean decenas de miles de filas. El CSV va en UTF-8 con BOM (abre bien en Excel) y acepta delimiter=;.

Feeds de Google y Meta

Para publicar el catálogo en Google Shopping o en el catálogo de Meta/Instagram, cada key tiene dos links privados (no necesitan headers, porque Google y Meta no los mandan):

  • /v1/feeds/{feedToken}/google.xml: RSS 2.0 con los campos de Google Merchant (g:id, g:price, g:availability, g:gtin, g:mpn, g:brand…).
  • /v1/feeds/{feedToken}/meta.csv: CSV con las columnas del administrador de catálogos de Meta.

El precio es tu precio de venta con impuestos. Hace falta configurar en la key el link de cada producto en tu tienda (con {id}, {sku}, {ean}, {partNumber} o {slug}). Si el link se filtra, generá uno nuevo desde NODO.

Buenas prácticas

  • Una key por sistema: si una se filtra, la revocás sin cortar las demás.
  • Guardá el secret en variables de entorno o un gestor de secretos; nunca en el repositorio.
  • Para el arranque, export completo; después, webhooks o /v1/changes. No recorras todo el catálogo cada hora.
  • Usá los ids (prd_, off_) como clave, no el nombre ni el SKU del distribuidor.
  • Mirá freshness.stale antes de vender algo online.
  • Ante 429 o 5xx, reintentá con backoff exponencial y jitter.
  • Mandá el X-Request-Id cuando nos escribas por un problema.

Referencia interactiva

Todos los endpoints con sus parámetros, esquemas y ejemplos, generados desde la especificación OpenAPI. Podés probarlos con tu key desde el navegador.

Cambios de versión

La API está versionada en la ruta (/v1). Dentro de v1 solo agregamos campos, parámetros y eventos: nunca sacamos ni cambiamos el significado de algo existente. Ignorá los campos que no conozcas.

FechaCambio
Octubre 2026Lanzamiento de v1: productos y ofertas, cambios incrementales, webhooks, exportación y feeds de Google y Meta.