Saltar al contenido

Privacidad y analítica

Utilizamos cookies técnicas necesarias y, solo si das tu consentimiento, analítica y pixels de marketing para mejorar la web y medir campañas.

Política de privacidadPolítica de cookies
Docs
GuíasDesarrolladores
Español
EspañolEnglishFrançaisDeutschItalianoPortuguês

Empezar a desarrollar

  • Tu primera llamada a la API
  • Límites, versiones y cabeceras
  • API para vendedores

API

  • API de marca

MCP

  • Servidor MCP

Conectores

  • Conectores de una marca
Empezar a desarrollar
Guía11 min de lectura

API para vendedores

Conecta tu sistema a Nömad Medios con una cuenta de servicio; lleva tu stock, tus precios y tus reservas, sube justificantes y recibe webhooks, con ejemplos en curl.

Русский
한국어
日本語
中文
हिन्दी
Abrir la app
Dónde
Nömad Medios › API
Quién puede
PropietarioAdministrador
En esta página
  • 1. Crea una cuenta de servicio
  • 2. Llamar a la API
  • 3. Lista tus espacios
  • 4. Abre y cierra fechas
  • 5. Cambia tus precios
  • 6. Lista las reservas por responder
  • 7. Acepta o rechaza una reserva
  • 8. Sube el justificante
  • 9. Recibe webhooks
  • Lo que solo se hace en el portal
  • Errores frecuentes

Esta guía es para quien integra el sistema de un vendedor (su gestor de inventario, su ERP o un script) con Nömad Medios. Todo lo que haces en tu portal es una operación de la API con los mismos permisos: abrir y cerrar fechas, cambiar precios, atender reservas y subir justificantes sin entrar en la pantalla.

Lo que necesitas:

  • Una cuenta de vendedor en Nömad Medios. Antes de que Nömad apruebe tu alta ya puedes preparar soportes, espacios y calendario, pero no publicar.
  • Ser propietario o administrador de esa cuenta, para crear la cuenta de servicio.
  • curl o cualquier cliente HTTP.

Nota

Medios no tiene MCP para vendedores: las operaciones de vendedor solo salen por la API HTTP.

1. Crea una cuenta de servicio

Una cuenta de servicio es una identidad de tu organización, no de una persona: sigue funcionando aunque quien la creó se vaya.

  1. En Nömad Medios › API (app.nomad.ooo/seller/<id>/api), crea una cuenta de servicio con un nombre que diga qué sistema la usa, por ejemplo «Inventario».
  2. Emítele un token. En los permisos, dale en el área Medios consultar (adspaces.read) y cambiar (adspaces.write). No lo limites a marcas: un token limitado a marcas no puede llamar a operaciones de tu cuenta de vendedor (403 token_brand_restricted).
  3. Copia el token: solo se muestra una vez. Tiene la forma nmw_live_v1_….
  4. En Nömad Medios › Equipo, la cuenta de servicio aparece como Miembro. Dale las funciones que necesita: Editor de espacios para el stock, los precios y los espacios, y Comercial de espacios para las reservas, el material y los justificantes.

Sin funciones, la cuenta de servicio solo puede leer y las escrituras responden 403 forbidden. Crear, rotar y revocar tokens está en Tokens y cuentas de servicio.

export NOMAD_TOKEN="nmw_live_v1_…"

2. Llamar a la API

Qué Valor
Base https://app.nomad.ooo/api/v1
Llamar a una operación POST /api/v1/<operación>, por ejemplo POST /api/v1/adspaces.seller.listings.list
Autenticación Authorization: Bearer nmw_live_v1_…
Cuerpo JSON con la entrada de la operación y workspace: el identificador (UUID) de tu cuenta de vendedor
Escrituras Envía Idempotency-Key en cada escritura que puedas reintentar
Respuesta correcta { "data": … }
Error application/problem+json con un code estable y, en los rechazos de Medios, el motivo en detail

Averigua el workspace con la propia credencial:

curl https://app.nomad.ooo/api/v1/me \
  -H "Authorization: Bearer $NOMAD_TOKEN"

Para una cuenta de servicio, data.credential.workspace_id es tu cuenta de vendedor:

export SELLER="3f6c0c1e-…"

Comprueba que esa cuenta vende espacios y en qué estado está su alta:

curl https://app.nomad.ooo/api/v1/adspaces.seller.access.get \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"workspace\": \"$SELLER\" }"
{ "data": { "enabled": true, "status": "approved" } }

Reglas que valen para todas las operaciones de vendedor:

  • Importes en céntimos, sin IVA. unitCostMinor: 45000 son 450,00 €. De momento todo es en euros.
  • Fechas en YYYY-MM-DD.
  • Listas paginadas: limit de 1 a 50 (20 por defecto); si nextCursor no es null, pásalo como cursor.
  • Lo que no ves: ninguna respuesta lleva lo que paga la marca ni el margen de Nömad. earnsMinor es lo que cobras tú.

Los límites de peticiones y el tamaño máximo están en Límites, versiones y cabeceras. La entrada y la salida exactas de cada operación están en la especificación OpenAPI (GET /api/v1/openapi.json, con tu token).

3. Lista tus espacios

curl https://app.nomad.ooo/api/v1/adspaces.seller.listings.list \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"workspace\": \"$SELLER\", \"status\": \"published\", \"limit\": 50 }"
{
  "data": {
    "items": [
      {
        "id": "8b1e…", "propertyId": "c2a4…", "propertyName": "Diario de Ejemplo", "channel": "digital",
        "title": "Billboard de portada", "status": "published", "isActive": true, "hasPendingChanges": false,
        "saleUnit": "period", "periodUnit": "week", "availabilityMode": "exclusive", "capacity": null,
        "currency": "EUR", "unitCostMinor": 45000, "listPriceMinor": 60000, "updatedAt": "2026-11-18T09:12:00Z"
      }
    ],
    "nextCursor": null
  }
}

Filtra por propertyId o por status (draft, in_review, published, paused, rejected). El espacio completo, con su version, sus límites y sus reglas de precio, está en adspaces.seller.listings.get con listingId.

4. Abre y cierra fechas

adspaces.seller.availability.upsert crea o actualiza ventanas del calendario de un espacio, al momento y sin revisión. Manda en cada ventana tu propio identificador en externalRef: si ya existe, se actualiza esa ventana en lugar de crear otra, así que repetir la sincronización no duplica nada.

curl https://app.nomad.ooo/api/v1/adspaces.seller.availability.upsert \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-8b1e-2026-11-18" \
  -d "{
    \"workspace\": \"$SELLER\",
    \"listingId\": \"8b1e…\",
    \"windows\": [
      { \"externalRef\": \"erp-closed-2026-12-24\", \"kind\": \"closed\", \"startsOn\": \"2026-12-24\", \"endsOn\": \"2026-12-26\", \"note\": \"Cierre de Navidad\" },
      { \"externalRef\": \"erp-open-2027-02\", \"kind\": \"open\", \"startsOn\": \"2027-02-01\", \"endsOn\": \"2027-02-28\", \"capacity\": 3 }
    ]
  }"
{
  "data": {
    "windows": [
      { "id": "e41f…", "kind": "closed", "startsOn": "2026-12-24", "endsOn": "2026-12-26", "capacity": null, "note": "Cierre de Navidad", "externalRef": "erp-closed-2026-12-24" },
      { "id": "9a07…", "kind": "open", "startsOn": "2027-02-01", "endsOn": "2027-02-28", "capacity": 3, "note": null, "externalRef": "erp-open-2027-02" }
    ]
  }
}
  • closed bloquea fechas. open las abre (necesario si el espacio solo vende las fechas que se abren, calendarMode: "listed") y puede llevar su propio capacity; un capacity en una ventana closed se rechaza.
  • De 1 a 200 ventanas por llamada.
  • Para quitarlas: adspaces.seller.availability.remove con listingId e ids o externalRefs. Devuelve removed; los identificadores que no existen se ignoran.
  • Para leer el calendario y los días que ocupan las reservas: adspaces.seller.availability.list con listingId y, si quieres, from y to (por defecto, hoy y los doce meses siguientes).

Quitar o cerrar fechas no toca las reservas: una reserva ya aceptada conserva sus fechas.

5. Cambia tus precios

El precio base de un espacio se cambia con adspaces.seller.listings.save. Manda expectedVersion (la version que leíste) para no pisar un cambio de otra persona: si no coincide, responde 409 revision_conflict.

curl https://app.nomad.ooo/api/v1/adspaces.seller.listings.save \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: price-8b1e-v7" \
  -d "{ \"workspace\": \"$SELLER\", \"listingId\": \"8b1e…\", \"expectedVersion\": 7, \"unitCostMinor\": 48000 }"

Solo cambia lo que envías. El precio, el cupo, las cantidades y los plazos se aplican al momento; los campos editoriales (título, textos, ficha técnica, plantillas, imágenes) de un espacio publicado esperan la revisión de Nömad y vuelven en pending.

Las reglas de precio se sustituyen de una vez con adspaces.seller.rates.set. La lista que envías reemplaza la anterior; una lista vacía las borra todas.

curl https://app.nomad.ooo/api/v1/adspaces.seller.rates.set \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rates-8b1e-2026-11-18" \
  -d "{
    \"workspace\": \"$SELLER\",
    \"listingId\": \"8b1e…\",
    \"rules\": [
      { \"label\": \"Navidad\", \"startsOn\": \"2026-12-01\", \"endsOn\": \"2027-01-06\", \"unitCostMinor\": 60000 },
      { \"label\": \"Fin de semana\", \"weekdays\": [6, 7], \"unitCostMinor\": 52000 },
      { \"label\": \"Cuatro semanas o más\", \"minQuantity\": 4, \"unitCostMinor\": 40000 }
    ]
  }"

weekdays son días ISO del día en que empieza la reserva (1 = lunes). Cada regla necesita al menos una condición. Si varias coinciden gana la más concreta; sin reglas vale unitCostMinor del espacio. Hasta 50 reglas. Una reserva ya pedida conserva su precio.

6. Lista las reservas por responder

curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.list \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"workspace\": \"$SELLER\", \"state\": \"to_answer\" }"
{
  "data": {
    "items": [
      {
        "id": "5d2c…", "number": "…", "status": "pending_publisher", "materialStatus": "pending",
        "listingId": "8b1e…", "startsOn": "2027-02-01", "endsOn": "2027-02-14", "quantity": 2,
        "currency": "EUR", "materialDueOn": "2027-01-25", "createdAt": "2026-11-18T10:03:00Z",
        "brandName": "Marca de ejemplo", "earnsMinor": 96000, "payoutId": null,
        "snapshot": { "listingTitle": "Billboard de portada", "saleUnit": "period", "periodUnit": "week", "propertyName": "Diario de Ejemplo", "channel": "digital", "…": "…" }
      }
    ],
    "nextCursor": null
  }
}

state es to_answer (espera que aceptes o rechaces), open (en curso) o closed. Puedes filtrar por listingId. Una reserva solo aparece cuando Nömad la ha pasado a tu cuenta (pending_publisher). snapshot guarda lo reservado tal como estaba al pedirlo.

adspaces.seller.bookings.get con bookingId da la reserva completa: el encargo (brief), el material entregado (materials), los justificantes (proofs), la historia (events) y can, lo que puedes hacer ahora (decide, reviewMaterial, deliver).

7. Acepta o rechaza una reserva

curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.decide \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: decide-5d2c" \
  -d "{ \"workspace\": \"$SELLER\", \"bookingId\": \"5d2c…\", \"decision\": \"accept\" }"
{ "data": { "id": "5d2c…", "status": "accepted" } }
  • accept guarda las fechas mientras la marca paga; si no paga a tiempo, la reserva caduca.
  • decline necesita una note, que la marca leerá.
  • Si las fechas se ocuparon mientras tanto: 409 conflict con detail: "dates_unavailable".

Cuando la marca entrega el material, materialStatus pasa a submitted. Descarga cada archivo con adspaces.seller.bookings.file_open (bookingId y fileId = materials[].id; la dirección caduca en minutos) y responde con adspaces.seller.bookings.material_review: decision: "approve", o "changes" con una note que diga qué cambiar.

8. Sube el justificante

Los archivos se suben en dos pasos: pides una dirección de subida y envías los bytes; después pasas la ruta a la operación que los usa.

Paso 1. Pide la dirección con adspaces.seller.uploads.prepare:

curl https://app.nomad.ooo/api/v1/adspaces.seller.uploads.prepare \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"workspace\": \"$SELLER\", \"purpose\": \"proof\", \"fileName\": \"captura-portada.png\", \"mimeType\": \"image/png\", \"sizeBytes\": 482113 }"
{ "data": { "path": "…", "uploadUrl": "https://…", "token": "…", "bucket": "adspace-files", "publicUrl": null } }

No envíes Idempotency-Key aquí: la dirección es un secreto que solo se da una vez, y repetir la llamada con la misma clave responde 409 secret_already_issued. Si falla, pide otra.

Paso 2. Envía los bytes con PUT a uploadUrl. La dirección es de un solo uso:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @captura-portada.png

Paso 3. Entrega el justificante con adspaces.seller.bookings.deliver, con los archivos, las cifras y una nota:

curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.deliver \
  -H "Authorization: Bearer $NOMAD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deliver-5d2c" \
  -d "{
    \"workspace\": \"$SELLER\",
    \"bookingId\": \"5d2c…\",
    \"files\": [ { \"path\": \"…\", \"name\": \"captura-portada.png\", \"mimeType\": \"image/png\", \"sizeBytes\": 482113 } ],
    \"metrics\": [ { \"label\": \"Impresiones\", \"value\": \"184.300\" } ],
    \"note\": \"Emitido del 1 al 14 de febrero en portada.\"
  }"

Solo vale para una reserva pagada que ya ha empezado (si no, 409 conflict con detail: "not_started" o "wrong_status"). Hasta 12 archivos y 12 cifras.

purpose Para Tipos y tamaño Función que pide
logo, cover, gallery Imágenes de la ficha, del soporte o del espacio JPEG, PNG, WebP o AVIF, hasta 10 MB Editor
template Plantillas de un espacio Cualquier tipo, hasta 50 MB Editor
proof Justificantes Cualquier tipo, hasta 50 MB Comercial
invoice Factura de una liquidación Cualquier tipo, hasta 50 MB Cobros

9. Recibe webhooks

Un webhook envía a tu sistema un POST firmado cada vez que cambia algo que puedes leer. Se crea en Nömad Medios › API con una dirección HTTPS pública y los tipos de evento que quieres. Para las operaciones de vendedor, el tipo es el id de la operación que hizo el cambio (adspaces.seller.bookings.decide, adspaces.seller.availability.upsert…), así que adspaces.seller.* los recoge todos.

Hoy esos eventos cuentan los cambios hechos en tu cuenta de vendedor, por tu equipo, por el portal o por tu integración. Para enterarte de reservas nuevas, consulta adspaces.seller.bookings.list con state: "to_answer" cada cierto tiempo.

La firma (Nomad-Signature), los reintentos, cómo evitar procesar dos veces el mismo evento y el código para comprobar la firma están en Eventos y webhooks.

Lo que solo se hace en el portal

Operación Por qué
Darse de alta (adspaces.seller.signup) La hace una persona con su cuenta, nunca un token.
Cambiar la cuenta bancaria (adspaces.seller.payout_account.set) Pide un inicio de sesión reciente de una persona.
Dar funciones al equipo (adspaces.seller.team.duties_set) Lo decide una persona que gestiona el equipo.

Todo lo demás (ficha, redes, soportes, espacios, calendario, tarifas, reservas, material, justificantes, liquidaciones y facturas) tiene su operación adspaces.seller.*. La lista completa está en la referencia de Medios.

Errores frecuentes

Respuesta Qué pasa Qué hacer
403 insufficient_scope El token no tiene adspaces.read o adspaces.write. Emite otro token con esos permisos.
403 token_brand_restricted El token está limitado a marcas. Emite uno sin límite de marcas.
403 forbidden A la cuenta de servicio le falta la función de esa parte. Dale Editor, Comercial o Cobros en Equipo.
404 workspace_not_found El workspace no es tuyo o no existe. Usa credential.workspace_id de GET /api/v1/me.
404 not_found Esa cuenta no vende espacios, o el registro no existe. Comprueba con adspaces.seller.access.get.
409 conflict El estado actual no lo permite; el motivo va en detail (dates_unavailable, wrong_status, not_ready, publisher_not_approved…). Lee el estado con la operación get y vuelve a decidir.
409 revision_conflict Otra persona cambió el espacio antes. Vuelve a leerlo y reenvía con su version.
422 invalid_input Algún campo no es válido; issues dice cuál. Corrige el campo.

Todos los códigos están en Errores.

Sigue leyendo

  • Tu primera llamada a la APICrea un token personal, comprueba quién eres con GET /api/v1/me, lista tus marcas y lee sus trabajos; después conecta un agente por MCP.
  • Límites, versiones y cabecerasLas cifras exactas de la API y del MCP de Nömad (peticiones por minuto, tamaño del cuerpo, paginación, caducidad y número de tokens) y las cabeceras, la versión y los documentos legibles por máquina.
  • MediosEspacios publicitarios de medios aprobados: buscarlos, reservarlos y, para un medio, venderlos y llevar su stock.
  • Eventos y webhooksLo que cambia, en orden, y avisos firmados a tus sistemas.
  • Tokens y cuentas de servicioCrear, limitar, rotar y revocar tokens personales y de la organización.
  • Vender en NömadQué es Nömad Medios para quien vende espacios publicitarios, para quién es, cómo va una reserva de principio a fin y qué hace Nömad en medio.

Actualizado el 18 de noviembre de 2026

AnteriorLímites, versiones y cabecerasSiguienteAPI de marca
¿No encuentras lo que buscas? EscríbenosEscríbenosIr a la app
© 2026 Nömad · Documentación de NömadLinkedInInstagramThreadsFacebookTikTokYouTubeX
Ir a nomad.oooVolver arriba

En esta página

  • 1. Crea una cuenta de servicio
  • 2. Llamar a la API
  • 3. Lista tus espacios
  • 4. Abre y cierra fechas
  • 5. Cambia tus precios
  • 6. Lista las reservas por responder
  • 7. Acepta o rechaza una reserva
  • 8. Sube el justificante
  • 9. Recibe webhooks
  • Lo que solo se hace en el portal
  • Errores frecuentes