Crear marca

POST /api/v1/marcas

Da de alta una marca del catálogo del tenant, o devuelve la que ya existe con ese nombre. Existe porque idMarca al crear un producto es un id interno de LX CloudPos, y un sistema externo conoce el nombre de sus marcas, no dichos ids.

La marca es opcional en un producto: si la integración no maneja marcas, no debe utilizarse este endpoint y se omite idMarca — el producto queda sin marca y se vende de igual forma.

Autenticación y permisos

Request body

{ "nombre": "Waffle Monkey" }

Respuestas

201 Created — se creó la marca

{ "idMarca": 7, "nombre": "Waffle Monkey", "estado": true }

200 OK — ya existía una marca con ese nombre

Mismo shape. La comparación ignora mayúsculas y espacios al borde: "waffle monkey " encuentra "Waffle Monkey". El alta se distingue de la coincidencia por el status code.

El estado puede venir en false: la búsqueda incluye marcas desactivadas, porque una marca inactiva igual sirve como idMarca de un producto y devolverla es preferible a crear un duplicado con el mismo nombre.

400 Bad Request

{ "error": "Debe indicar 'nombre'." }

Y dos casos borde:

{ "error": "No se pudo guardar la marca." }

{ "error": "La marca se guardó pero no se pudo releer." }

401 / 403 / 429 / 500

Igual que el resto de la API. El 500 de este endpoint responde { "error": "Error interno guardando la marca." }.

Limitación conocida

El nombre de la marca no tiene índice único en la base. Eso significa dos cosas:

1. Si el tenant ya tenía dos marcas con el mismo nombre —creadas desde el POS antes de que existiera este endpoint—, el upsert devuelve siempre la de menor id: la más antigua, que es la que con más probabilidad ya está referenciada por productos.
2. Dos requests simultáneos con el mismo nombre exacto pueden llegar a crear dos filas. En una sincronización de catálogo secuencial —el caso normal— no ocurre.

Esta situación no puede evitarse desde el lado del integrador; se documenta a título informativo.

Modelo de datos

interface MarcaApiRequestDto {
  /** OBLIGATORIO. Se compara sin distinguir mayúsculas y recortando espacios. */
  nombre: string;
}
 
interface MarcaApiResponseDto {
  /** Usar como idMarca al crear un producto. */
  idMarca: number;
  nombre: string;
  estado: boolean;
}