Í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
{
"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-KeyyX-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)
| Scope | Para qué |
|---|---|
catalog:read | Leer productos, ofertas y taxonomía |
changes:read | Leer cambios incrementales |
export:read | Exportar el catálogo (CSV, XLSX, JSON) |
feeds:read | Feeds de Google Merchant y Meta |
webhooks:manage | Administrar 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).
{
"error": {
"code": "insufficient_scope",
"message": "Esta key no tiene el permiso export:read.",
"requestId": "req_9Gx2kLm4Qa",
"docs": "https://nodohub.app/developers#errores"
}
}| code | HTTP | Qué pasó |
|---|---|---|
missing_credentials | 401 | Faltan la key o el secret. |
invalid_credentials | 401 | La key no existe o el secret no coincide. |
key_revoked | 401 | La key fue revocada. |
key_expired | 401 | La key venció. |
addon_required | 402 | La organización no tiene activo el módulo de API de catálogo. |
subscription_suspended | 402 | La suscripción de la organización está suspendida. |
ip_not_allowed | 403 | La IP del pedido no está en la lista permitida de la key. |
insufficient_scope | 403 | La key no tiene el permiso que pide el endpoint. |
not_found | 404 | El recurso no existe o no es visible para esta key. |
invalid_parameter | 400 | Un parámetro tiene un valor inválido. El mensaje dice cuál. |
invalid_cursor | 400 | El cursor está mal formado o es de otro endpoint. |
cursor_expired | 410 | El cursor de cambios tiene más de 30 días: hacé un export completo y arrancá de nuevo. |
feed_link_required | 422 | Para los feeds hace falta configurar el link de producto de tu tienda. |
rate_limited | 429 | Pasaste el límite por minuto. Esperá lo que indica Retry-After. |
internal_error | 500 | Error 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: 1791214380Si 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ámetro | Qué hace |
|---|---|
q | Texto libre: nombre, marca, SKU, part number o EAN. |
brand · category · subcategory | Id o nombre canónico (los de /v1/brands y /v1/categories). |
provider | Id del distribuidor (prv_…). Varios separados por coma. |
inStock | true para solo productos con stock. |
minPrice · maxPrice | Sobre el precio de venta con impuestos, en la moneda de la key. |
ean · partNumber | Búsqueda exacta (normalizada). |
updatedSince | ISO 8601. Solo lo que cambió desde esa fecha. |
sort | relevance · name · price · -price · updatedAt · -updatedAt (el - invierte). |
limit | De 1 a 500. Por defecto 100. |
view | products 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.
netsin impuestos,taxescon cada impuesto desglosado (IVA, impuestos internos y tus percepciones, con alícuota y monto) ygrossfinal. - 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:truesi pasó más tiempo del normal sin poder actualizarlo.freshness.providerSync:ok,error(reintentando) opaused./v1/providerstrae 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.
| Endpoint | Scope | Devuelve |
|---|---|---|
GET /v1/me | — | Tu key: nombre, permisos, configuración efectiva, límites y estado del módulo. |
GET /v1/products | catalog:read | Productos agrupados (mismo producto de varios distribuidores en una fila). |
GET /v1/products/{productId} | catalog:read | Un producto con todas sus ofertas. |
GET /v1/offers | catalog:read | Una fila por producto y distribuidor. |
GET /v1/offers/{offerId} | catalog:read | Una oferta. |
GET /v1/offers/{offerId}/price-history | catalog:read | Cambios de precio de los últimos 12 meses. |
GET /v1/changes | changes:read | Feed de cambios desde un cursor. |
GET /v1/brands | catalog:read | Marcas con cantidad de productos. |
GET /v1/categories | catalog:read | Árbol de categorías con conteos. |
GET /v1/providers | catalog:read | Tus distribuidores (o sus alias) y el estado de su sincronización. |
GET /v1/fx | — | Cotizaciones disponibles y la que usa tu key. |
GET /v1/export | export:read | Catálogo completo en CSV, XLSX o JSON. |
GET /v1/feeds/{feedToken}/google.xml | feeds:read | Feed de Google Merchant. |
GET /v1/feeds/{feedToken}/meta.csv | feeds:read | Feed del catálogo de Meta. |
GET /v1/webhooks | webhooks:manage | Tus webhooks. |
POST /v1/webhooks | webhooks:manage | Crear un webhook. |
PATCH /v1/webhooks/{id} | webhooks:manage | Cambiar URL, eventos o pausarlo. |
DELETE /v1/webhooks/{id} | webhooks:manage | Borrar un webhook. |
POST /v1/webhooks/{id}/test | webhooks:manage | Mandar un evento ping de prueba. |
GET /v1/openapi.json | público | Especificació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.
| Evento | Cuándo |
|---|---|
offer.created | Entra un producto |
offer.updated | Cambia un producto (cualquier dato) |
offer.removed | Sale un producto |
price.changed | Cambia un precio |
stock.changed | Cambia el stock |
provider.sync_paused | Un distribuidor pausó su sincronización |
provider.sync_resumed | Un distribuidor volvió a sincronizar |
ping | Prueba manual desde NODO. |
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.staleantes de vender algo online. - Ante
429o5xx, reintentá con backoff exponencial y jitter. - Mandá el
X-Request-Idcuando 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.
| Fecha | Cambio |
|---|---|
| Octubre 2026 | Lanzamiento de v1: productos y ofertas, cambios incrementales, webhooks, exportación y feeds de Google y Meta. |
