API de Gestión de Marcas

La API de Gestión de Marcas permite administrar la información de marcas en la plataforma Nilo. Estos endpoints ayudan a crear, actualizar y recuperar datos de marcas, incluyendo detalles y estado de las marcas.

Entendiendo las Marcas

Las marcas en Nilo representan los fabricantes o propietarios de marcas comerciales de productos:

Estructura de Marca
- Código interno único para identificación
- Nombre e imagen para visualización
- Peso para controlar el orden de visualización
- Estado para habilitar/deshabilitar visibilidad
- Metadatos opcionales para información adicional
Jerarquía de Marca
- Entidades independientes no vinculadas a categorías
- Pueden estar asociadas a múltiples productos
- Mantienen su propio estado y visibilidad
- Soportan operaciones por lotes para actualizaciones masivas

Consideraciones Importantes

Códigos Únicos: Cada marca requiere un código interno único para identificación
Gestión de Imágenes: Las imágenes de marca deben seguir pautas específicas de formato y tamaño
Sistema de Pesos: Controla el orden de aparición en listados y búsquedas
Control de Estado: Las marcas pueden ser habilitadas o deshabilitadas sin eliminación
Operaciones por Lotes: Soporte para actualizaciones masivas para gestionar múltiples marcas eficientemente

Operaciones Individuales de Marca

Crear Marca

POST/brand

Crea una nueva marca en la plataforma Nilo. Este endpoint se utiliza para registrar todos los detalles de la marca, incluyendo:

Brand information (name, internal code)
Brand image and weight

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Yes	Nombre de la marca
internalCode	string	Yes	Código de la marca (identificador único)
weight	integer	No	Posición en la lista de ordenación
image	string	No	URL de la imagen de la marca

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png"
}

Códigos de Respuesta

Código	Descripción
200	Marca creada exitosamente
404	Marca no encontrada

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Marca 1",
  internalCode: "1235",
  weight: 1,
  image: "/qa/brand/12442.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Marca 1",
    "internalCode": "1235",
    "weight": 1,
    "image": "/qa/brand/12442.png"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Obtener Todas las Marcas

GET/brand

Recupera una lista paginada de todas las marcas. Este endpoint es útil para:

Navegar por el catálogo de marcas
Implementar paginación en tu aplicación
Filtrar marcas por estado habilitado

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
take	number	No	Número de items por página (predeterminado: 50, máx: 50)
page	string	No	Número de página (predeterminado: 1)
enabled	boolean	No	Filtrar marcas por estado habilitado (true para activo, false para inactivo)
cursor	string	No	Cursor para paginación. Primer llamado usar 0, luego usar el cursor de la respuesta anterior

Ejemplo de Respuesta

{
  "data": [
    {
      "name": "Marca 1",
      "internalCode": "1235",
      "weight": 1,
      "image": "/qa/brand/12442.png"
    }
  ],
  "page": {
    "pageBased": {
      "count": 100
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand?take=10&page=1&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"
params = {
    "take": 10,
    "page": 1,
    "enabled": True
}

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers, params=params)
print(response.text)

Upsert Brand

PUT/brand

Crea o actualiza una marca en la plataforma Nilo. Este endpoint es útil cuando necesitas:

Crear una nueva marca si no existe
Actualizar una marca existente con nueva información

Parámetros del Cuerpo de la Solicitud

Parameter	Type	Required	Description
name	string	Yes	Brand name
internalCode	string	Yes	Brand code (unique identifier)
weight	integer	No	Order positioning in listings
image	string	No	URL de la imagen de la marca
enabled	boolean	Yes	Si la marca está activa

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png",
  "enabled": true
}

Códigos de Respuesta

Código	Descripción
200	Marca actualizada exitosamente
404	Marca no encontrada

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Marca 1",
  internalCode: "1235",
  weight: 1,
  image: "/qa/brand/12442.png",
  enabled: true,
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Marca 1",
    "internalCode": "1235",
    "weight": 1,
    "image": "/qa/brand/12442.png",
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Obtener Detalles de la Marca

GET/brand/{code}

Obtiene información detallada sobre una marca específica. Este endpoint devuelve:

Metadatos de la marca
Imagen y peso de la marca

Parámetros de Ruta

Parámetro	Tipo	Descripción
code	string	Código interno de la marca (identificador único)

Ejemplo de Respuesta

{
  "name": "Marca 1",
  "internalCode": "1235",
  "weight": 1,
  "image": "/qa/brand/12442.png"
}

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235", {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Actualizar Marca

PUT/brand/{code}

Actualiza la información de una marca existente. Este endpoint te permite modificar:

Nombre de la marca
Imagen de la marca
Peso de la marca para ordenamiento

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la marca (identificador único)

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre de la marca
weight	integer	No	Posición en la lista de ordenación
image	string	No	URL de la imagen de la marca

Ejemplo del Cuerpo de la Solicitud

{
  "name": "Nombre de Marca Actualizado",
  "weight": 2,
  "image": "/qa/brand/imagen-actualizada.png"
}

Códigos de Respuesta

Código	Descripción
200	Marca actualizada exitosamente
404	Marca no encontrada

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  name: "Nombre de Marca Actualizado",
  weight: 2,
  image: "/qa/brand/imagen-actualizada.png",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "name": "Nombre de Marca Actualizado",
    "weight": 2,
    "image": "/qa/brand/imagen-actualizada.png"
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Cambiar Estado de la Marca

PUT/brand/{code}/status

Actualiza el estado de una marca. Este endpoint te permite:

Habilitar/deshabilitar una marca

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la marca (identificador único)

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Si la marca debe estar habilitada

Ejemplo del Cuerpo de la Solicitud

{
  "enabled": true
}

Códigos de Respuesta

Código	Descripción
200	Estado actualizado exitosamente
404	Marca no encontrada

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/brand/1235/status"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Operaciones por Lotes

Actualización/Creación de Marcas por Lotes

POST/batch/brand

Realiza operaciones masivas en marcas. Este endpoint te permite:

Actualizar o crear múltiples marcas (actualizar o crear si no existen)

La operación por lotes se procesa de forma asíncrona, lo que significa que recibirás una confirmación inmediata de la solicitud, y las actualizaciones se procesarán en segundo plano.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Descripción
upsert	array	Array de marcas para actualizar o crear si es necesario

Ejemplo del Cuerpo de la Solicitud

{
  "upsert": [
    {
      "name": "Marca 1",
      "internalCode": "1235",
      "weight": 1,
      "image": "/qa/brand/12442.png",
      "enabled": true
    }
  ]
}

Códigos de Respuesta

Código	Descripción
202	Solicitud por lotes aceptada para procesamiento
402	Solicitud incorrecta

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: [
    {
      name: "Marca 1",
      internalCode: "1235",
      weight: 1,
      image: "/qa/brand/12442.png",
      enabled: true,
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/brand",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/brand"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "upsert": [
        {
            "name": "Marca 1",
            "internalCode": "1235",
            "weight": 1,
            "image": "/qa/brand/12442.png",
            "enabled": True
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Tipos de Respuesta

Respuesta de Éxito

{
  "code": 200,
  "message": "Operación exitosa"
}

Respuesta de Operación por Lotes

{
  "code": 202,
  "batchIds": {
    "upsert": ["550e8400-e29b-41d4-a716-446655440000"]
  },
  "message": "Procesamiento por lotes iniciado"
}

Respuesta de Error

{
  "code": 400,
  "message": "Parámetros de solicitud inválidos"
}

Mejores Prácticas

Gestión de Marcas
- Usar convenciones de nombres consistentes
- Mantener imágenes de marca de alta calidad
- Implementar gestión adecuada de estados
- Mantener información de marca actualizada
Estructura de Códigos
- Crear códigos internos significativos
- Usar patrones de código consistentes
- Documentar convenciones de código
- Validar códigos antes de usar
Manejo de Imágenes
- Usar formatos de imagen optimizados
- Mantener dimensiones de imagen consistentes
- Implementar caché de imágenes
- Manejar actualizaciones de imágenes eficientemente
Optimización de Rendimiento
- Usar operaciones por lotes para múltiples actualizaciones
- Implementar estrategias de caché adecuadas
- Optimizar entrega de imágenes
- Monitorear patrones de uso de API

Casos de Uso Comunes

Configuración Inicial de Marca
- Crear perfiles de marca
- Subir imágenes de marca
- Establecer pesos iniciales
- Configurar estado de marca
Mantenimiento de Marca
- Actualizar información de marca
- Gestionar visibilidad de marca
- Ajustar orden de visualización
- Actualizar imágenes de marca
Operaciones Masivas
- Importar múltiples marcas
- Actualizar estados de marca
- Modificar pesos de marca
- Sincronizar datos de marca
Integración de Marca
- Conectar con catálogo de productos
- Implementar filtrado de marcas
- Configurar búsqueda de marcas
- Configurar visualización de marcas

Tipos de Respuesta

Respuesta Exitosa

{
  "code": 200,
  "message": "Operación exitosa",
  "data": {
    "name": "Marca Ejemplo",
    "internalCode": "BRD-001",
    "image": "/brands/ejemplo.png",
    "enabled": true,
    "weight": 1
  }
}

Ejemplos de Respuesta de Error

No Encontrado

{
  "code": 404,
  "message": "Marca no encontrada"
}

Error de Validación

{
  "code": 400,
  "message": "Datos de marca inválidos",
  "errors": [
    {
      "field": "internalCode",
      "message": "El código interno es requerido"
    }
  ]
}

Error de Duplicado

{
  "code": 409,
  "message": "Ya existe una marca con este código interno"
}

Guías de Implementación

Creación de Marca
- Validar campos requeridos
- Verificar códigos duplicados
- Procesar imágenes de marca
- Establecer valores predeterminados
Actualizaciones de Marca
- Verificar existencia de marca
- Manejar actualizaciones parciales
- Gestionar cambios de imagen
- Actualizar marcas de tiempo
Gestión de Estado
- Manejar transiciones de estado
- Actualizar productos relacionados
- Mantener registros de auditoría
- Notificar sistemas relevantes
Procesamiento por Lotes
- Validar datos por lotes
- Manejar fallos parciales
- Implementar rollback
- Reportar resultados por lotes

Seguridad

Todos los endpoints de la API requieren dos tipos de autenticación:

API Key en el encabezado: x-api-key
Token de autorización en el encabezado: Authorization

Permisos Requeridos

Para los endpoints de gestión de marcas, se requieren los siguientes permisos:

Para operaciones de lectura: supplier/brand.read
Para operaciones de escritura: supplier/brand.write

Manejo de Errores

Validación de Entrada
- Validar todos los campos requeridos
- Verificar tipos y formatos de datos
- Verificar especificaciones de imagen
- Validar códigos internos
Respuestas de Error
- Usar códigos de estado HTTP apropiados
- Proporcionar mensajes de error detallados
- Incluir errores a nivel de campo
- Agregar códigos de seguimiento de error
Procedimientos de Recuperación
- Manejar fallos de red
- Implementar lógica de reintentos
- Mantener consistencia de datos
- Registrar detalles de error
Monitoreo
- Rastrear tasas de error
- Monitorear rendimiento de API
- Alertar sobre errores críticos
- Analizar patrones de error

Entendiendo las Marcas​

Consideraciones Importantes​

Operaciones Individuales de Marca​

Crear Marca​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Obtener Todas las Marcas​

Parámetros de Consulta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Upsert Brand​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Obtener Detalles de la Marca​

Parámetros de Ruta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Actualizar Marca​

Parámetros de Ruta​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Cambiar Estado de la Marca​

Parámetros de Ruta​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Operaciones por Lotes​

Actualización/Creación de Marcas por Lotes​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Tipos de Respuesta​

Respuesta de Éxito​

Respuesta de Operación por Lotes​

Respuesta de Error​

Mejores Prácticas​

Casos de Uso Comunes​

Tipos de Respuesta​

Respuesta Exitosa​

Ejemplos de Respuesta de Error​

No Encontrado​

Error de Validación​

Error de Duplicado​

Guías de Implementación​

Seguridad​

Permisos Requeridos​

Manejo de Errores​

Entendiendo las Marcas

Consideraciones Importantes

Operaciones Individuales de Marca

Crear Marca

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Obtener Todas las Marcas

Parámetros de Consulta

Ejemplo de Respuesta

Ejemplo de Uso

Upsert Brand

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Obtener Detalles de la Marca

Parámetros de Ruta

Ejemplo de Respuesta

Ejemplo de Uso

Actualizar Marca

Parámetros de Ruta

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Cambiar Estado de la Marca

Parámetros de Ruta

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Operaciones por Lotes

Actualización/Creación de Marcas por Lotes

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Tipos de Respuesta

Respuesta de Éxito

Respuesta de Operación por Lotes

Respuesta de Error

Mejores Prácticas

Casos de Uso Comunes

Tipos de Respuesta

Respuesta Exitosa

Ejemplos de Respuesta de Error

No Encontrado

Error de Validación

Error de Duplicado

Guías de Implementación

Seguridad

Permisos Requeridos

Manejo de Errores