# SYSCOM API v1 — Documentación completa

> API REST para integrar el catálogo y las operaciones de SYSCOM: productos, precios, existencias, facturas, carrito y más. Incluye búsqueda semántica de productos en lenguaje natural, ideal para agentes de IA. Autenticación OAuth2 client_credentials + Bearer. Base de la API: https://developers.syscom.mx/api/v1

## Autenticación

La API usa OAuth2 `client_credentials`. Genera tus credenciales en https://developers.syscom.mx/clients, solicita un token con `POST /api/v1/oauth/token` y envíalo en cada llamada protegida como `Authorization: Bearer <token>`. Los tokens duran 365 días. Rutas públicas (sin token): `tipocambio`, `banners`, `cursos`.

### POST /api/v1/oauth/token
**Auth:** Público

Genera el token de acceso (válido por un año) que debes enviar en cada llamada protegida. Solo necesitas tu identificador y tu secreto de aplicación.

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `grant_type` | string | sí | Único valor admitido: client_credentials. |
| `client_id` | string | sí | Identificador de tu aplicación (panel “Mis credenciales”). |
| `client_secret` | string | sí | Secreto de tu aplicación. Se muestra una sola vez al generarlo. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Token emitido correctamente. |
| 400 | Faltan o son inválidos grant_type, client_id o client_secret. |
| 401 | Credenciales inválidas o cuenta sin acceso a la API. |
| 429 | Demasiadas solicitudes de token (límite por client_id / IP); incluye Retry-After. |
| 500 | Error interno al emitir el token. |

```bash
curl -X POST https://developers.syscom.mx/api/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=TU_CLIENT_ID&client_secret=TU_CLIENT_SECRET'
```

```json
{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "TU_TOKEN"
}
```

## Categorías

_Bearer_

Las categorías del catálogo, para armar menús y navegación.

### GET /api/v1/categorias
**Auth:** Bearer · caché: 1 h

Lista las categorías principales del catálogo.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Arreglo plano de categorías de nivel 1. |
| 401 | Token ausente, inválido o revocado. |
| 403 | La cuenta no pasa el gate de acceso. |
| 429 | Límite de peticiones por cliente excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/categorias' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  { "id": "21", "nombre": "Videovigilancia", "nivel": 1 }
]
```

### GET /api/v1/categorias/{id}
**Auth:** Bearer · caché: 2 h

Muestra una categoría junto con la ruta de categorías a la que pertenece y sus subcategorías.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la categoría (entero positivo). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Categoría con origen y subcategorías. |
| 400 | id no es un entero positivo. |
| 401 | Bearer ausente o inválido. |
| 403 | La cuenta no pasa el gate de acceso. |
| 404 | Categoría inexistente o de nivel 0. |
| 429 | Límite de peticiones por cliente excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/categorias/21' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "id": "21",
  "nombre": "Videovigilancia",
  "nivel": "1",
  "origen": [],
  "subcategorias": [
    { "id": "210", "nombre": "Cámaras IP", "nivel": "2" }
  ]
}
```

## Carrito

_Bearer · scope carrito_

Cotiza y genera órdenes, sube guías de envío y administra las direcciones de tus clientes.

### POST /api/v1/carrito/generar
**Auth:** Bearer · scope: carrito

Cotiza un carrito con precios, descuentos y costo de envío ya calculados. En modo de prueba obtienes la cotización completa sin generar el pedido.

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `productos` | array | sí | `[{ "id": 223114, "cantidad": 2, "tipo": "nuevo" }, ...]` Lista de objetos JSON, máximo 50 productos por orden: • id — ID del producto en SYSCOM, el mismo que devuelve /productos; número o texto numérico ("223114"). • cantidad — piezas de ese producto; entero desde 1, número o texto numérico. • tipo — condición de la pieza: nuevo o caja abierta (a, b, c); ver más en la [Política Caja Abierta](https://conocimiento.syscom.mx/articulo/politica-de-clasificacion-de-productos). Si algún producto no existe o no está a la venta, el pedido no se crea: responde 400 (productos_no_encontrados) indicando cuáles. Si algún producto no tiene existencia no se creará el pedido, salvo que se active el parámetro "forzar", que genera el pedido ignorando los productos sin existencias. |
| `tipo_entrega` | string | sí | sucursal, domicilio u ocurre. |
| `direccion` | object\|string | no | Objeto (o string JSON) con la dirección. Obligatoria y completa en entregas a domicilio u ocurre (salvo que envíes con tu propia guía: fletera=guia_cliente); con tipo_entrega=sucursal solo requiere { sucursal, atencion_a } (sucursal = código de /carrito/sucursales). domicilio/ocurre → { atencion_a, calle, num_ext, num_int, colonia, ciudad, estado, pais, codigo_postal, telefono }. estado es el código SAT del estado (ver estado_sat en /carrito/estados, p.ej. 08); el municipio del CP sobrescribe ciudad. |
| `fletera` | string | no | Código de fletera (ver /carrito/fleteras). Obligatoria en entregas a domicilio; en sucursal/ocurre se ignora. |
| `moneda` | string | no | usd (def.) o mxn. |
| `uso_cfdi` | string | sí | Código de uso de CFDI (ver /carrito/cfdi). |
| `metodo_pago` | string | sí | Clave del método de pago (ver /carrito/pago): transferencia, paynet, sucursal-*, credito-* (1/7/15/30/45/60/75/90). |
| `tipo_pago` | string | no | PUE (def.) o PPD; afecta forma_pago. En crédito se fuerza a PPD. |
| `orden_compra` | string | no | Referencia de orden de compra del cliente (opcional). |
| `ordenar` | flag | no | true → convierte la cotización en pedido real (genera folio_pedido y aparta existencias); requiere stock suficiente. Default: false (solo cotización). |
| `forzar` | flag | no | Con ordenar=true: crea el pedido aunque no haya existencia suficiente (omite la validación de stock). |
| `testmode` | flag | no | true → solo cotiza, no genera el pedido (recomendado para pruebas). |
| `pdf_guia` | file | no | Solo en entregas a domicilio y enviando el body como multipart/form-data: adjunta tu guía prepagada, el pedido se envía con tu paquetería y no se cobra flete. jpg/png/jpeg/doc/docx/pdf, máx. 6 MB. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Cotización calculada (o error de validación de negocio en { error }). |
| 400 | Algún dato del pedido es inválido o falta: la respuesta incluye detalles[] con el campo, el problema y un ejemplo. También cuando un producto no existe o no está a la venta (code: productos_no_encontrados). |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 405 | Método no permitido (usar POST). |
| 429 | Límite de peticiones excedido. |
| 501 | Pedido real (sin testmode) deshabilitado en el servidor. |
| 500 | Error interno. |

```bash
curl -X POST https://developers.syscom.mx/api/v1/carrito/generar \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "testmode": true,
    "tipo_entrega": "sucursal",
    "direccion": { "sucursal": "chihuahua", "atencion_a": "PRUEBA API" },
    "metodo_pago": "transferencia",
    "tipo_pago": "PUE",
    "moneda": "usd",
    "uso_cfdi": "G01",
    "productos": [{ "id": 210627, "cantidad": 1, "tipo": "nuevo" }]
  }'
```

```json
{
  "error": "",
  "cliente": {
    "num_cliente": "12345",
    "rfc": "XAXX010101000",
    "whatsapp": "6141234567",
    "email": "cliente@ejemplo.mx",
    "telefono": "6141234567",
    "direccion": {
      "calle": "AV. EJEMPLO",
      "num_exterior": "123",
      "num_interior": "",
      "colonia": "CENTRO",
      "ciudad": "CHIHUAHUA",
      "estado": "CHIH",
      "pais": "MEX"
    }
  },
  "resumen": {
    "peso_total": 1.634,
    "peso_vol_total": 2.79,
    "moneda": "USD",
    "forma_pago": 1,            /* 2 en crédito (PPD) */
    "tipo_cambio": "17.32",
    "plazo": 0,                 /* string con los días en crédito, p.ej. "30" */
    "codigo_pago": "03",        /* "99" en crédito */
    "folio": "TESTMODE",        /* folio real con escritura habilitada */
    "folio_pedido": "TESTMODE",
    "fecha_creacion": "2026-06-13 04:33:44",
    "iva_aplicado": 16,
    "guia_prepagada": "Sin guia"
  },
  "datos_entrega": {
    "atencion_a": "PRUEBA API",
    "calle": "AV. EJEMPLO",
    "num_exterior": "123",
    "num_interior": "",
    "colonia": "CENTRO",
    "ciudad": "CHIHUAHUA",
    "estado": "CHIHUAHUA",
    "pais": "MEXICO"
  },
  "productos": [
    {
      "id": 210627,
      "cantidad": 1,
      "tipo": "nuevo",
      "modelo": "DS-KIS604-P(C)",
      "titulo": "Kit de Videoportero IP PoE ...",
      "marca": "HIKVISION",
      "link": "https://www.syscom.mx/producto/DS-KIS604-P(C)-HIKVISION-210627.html",
      "imagen": "https://ftp3.syscom.mx/usuarios/fotos/.../DSKIS604P(C)-i.PNG",
      "precio_lista": "0.1",
      "precio_oferta": "0.1",
      "precio_unitario": "0.1",
      "almacenes": { "Chihuahua": 0 },
      "importe": "0.1",
      "descuentos": { "distribucion": 20, "clasificacion": "20", "volumen": 0, "financiero": 4 },
      "componentes": [ { "cantidad": "1", "codigo": "DS-KD8003-IME1" } ] /* solo si el producto es kit */
    }
  ],
  "totales": { "subtotal": 0.1, "flete": 0.1, "iva": 0.1, "total": 0.1 } /* flete > 0 solo en domicilio */
}
```

### POST /api/v1/carrito/guia
**Auth:** Bearer · scope: carrito

Sube tu guía de envío prepagada a tus pedidos: el pedido queda marcado para enviarse con tu paquetería (sin mensajería de SYSCOM). Acepta imágenes y PDF de hasta 6 MB.

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `folio` | string | sí | Folio de tu pedido o cotización. También funciona el folio de un pedido que ya se procesó. |
| `pdf_guia` | file | sí | Archivo de la guía (jpg/png/jpeg/doc/docx/pdf, máx. 6 MB). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Guía registrada (o { error } si: no encontramos ese folio en tu cuenta, el pedido tiene entrega en sucursal, o el formato del archivo es inválido). |
| 400 | folio vacío o ausente, o pdf_guia ausente. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X POST https://developers.syscom.mx/api/v1/carrito/guia \
  -H 'Authorization: Bearer TU_TOKEN' \
  -F 'folio=000000' \
  -F 'pdf_guia=@guia.pdf'
```

```json
{
  "error": "",
  "datos": {
    "folio": "000000",
    "id_cot": 1234567,
    "via_embarque": 373,
    "tipo_entrega": "Domicilio"
  }
}
```

### GET /api/v1/carrito/direcciones
**Auth:** Bearer · scope: carrito

Lista las direcciones de envío guardadas del cliente.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Direcciones del cliente (arreglo). |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/direcciones' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "id": 901,
    "atencion_a": "JUAN PEREZ",
    "calle": "AV. TECNOLOGICO",
    "num_ext": "1234",
    "num_int": "",
    "colonia": "CENTRO",
    "codigo_postal": "31000",
    "id_pais": 152,
    "pais": "MEX",
    "codigo_estado": "08",
    "estado": "08",
    "ciudad": "CHIHUAHUA",
    "telefono": "6141234567",
    "id_cliente": 12345,
    "id_subcuenta": 0,
    "tipo": "domicilio"
  }
]
```

### POST /api/v1/carrito/direcciones
**Auth:** Bearer · scope: carrito

Guarda una nueva dirección de envío. Valida el país y, para México, el estado según el código postal.

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `atencion_a` | string | sí | Persona/atención. |
| `calle` | string | sí | Calle. |
| `num_ext` | string | sí | Número exterior. |
| `num_int` | string | no | Número interior (opcional). |
| `colonia` | string | sí | Colonia. |
| `ciudad` | string | sí | Ciudad. |
| `estado` | string | sí | Código SAT del estado (ver estado_sat en /carrito/estados, p.ej. 08 para Chihuahua). En México se valida contra el CP. |
| `pais` | string | sí | Código de país (ver /carrito/paises, p.ej. MEX). |
| `codigo_postal` | string | sí | Código postal. |
| `telefono` | string | sí | Teléfono. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Dirección creada (o { error } si falla la validación de país/CP). |
| 400 | Faltan parámetros obligatorios de la dirección. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X POST https://developers.syscom.mx/api/v1/carrito/direcciones \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "atencion_a": "Juan Perez",
    "calle": "Av. Tecnologico",
    "num_ext": "1234",
    "colonia": "Centro",
    "ciudad": "Chihuahua",
    "estado": "08",
    "pais": "MEX",
    "codigo_postal": "31000",
    "telefono": "6141234567"
  }'
```

```json
{
  "id": 902,
  "atencion_a": "JUAN PEREZ",
  "calle": "AV. TECNOLOGICO",
  "num_ext": "1234",
  "num_int": "",
  "colonia": "CENTRO",
  "codigo_postal": "31000",
  "id_pais": 152,
  "pais": "MEX",
  "codigo_estado": "08",
  "estado": "08",
  "ciudad": "CHIHUAHUA",
  "telefono": "6141234567",
  "id_cliente": 12345,
  "id_subcuenta": 0,
  "tipo": "domicilio"
}
```

### PUT /api/v1/carrito/direcciones/{id}
**Auth:** Bearer · scope: carrito

Actualiza una dirección de envío. Debes enviar todos los datos, porque reemplaza la dirección completa.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la dirección. |

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `atencion_a` | string | sí | Persona/atención. |
| `calle` | string | sí | Calle. |
| `num_ext` | string | sí | Número exterior. |
| `num_int` | string | no | Número interior (opcional). |
| `colonia` | string | sí | Colonia. |
| `ciudad` | string | sí | Ciudad. |
| `estado` | string | sí | Código SAT del estado (ver estado_sat en /carrito/estados). En México se valida contra el CP. |
| `pais` | string | sí | Código de país (ver /carrito/paises). |
| `codigo_postal` | string | sí | Código postal. |
| `telefono` | string | sí | Teléfono. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Dirección actualizada (o { error } si falla la validación de país/CP). |
| 400 | id inválido o faltan parámetros obligatorios. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X PUT https://developers.syscom.mx/api/v1/carrito/direcciones/901 \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "atencion_a": "Juan Perez",
    "calle": "Av. Tecnologico",
    "num_ext": "1234",
    "colonia": "Centro",
    "ciudad": "Chihuahua",
    "estado": "08",
    "pais": "MEX",
    "codigo_postal": "31000",
    "telefono": "6149876543"
  }'
```

```json
{
  "id": 901,
  "atencion_a": "JUAN PEREZ",
  "calle": "AV. TECNOLOGICO",
  "num_ext": "1234",
  "num_int": "",
  "colonia": "CENTRO",
  "codigo_postal": "31000",
  "id_pais": 152,
  "pais": "MEX",
  "codigo_estado": "08",
  "estado": "08",
  "ciudad": "CHIHUAHUA",
  "telefono": "6149876543",
  "id_cliente": 12345,
  "id_subcuenta": 0,
  "tipo": "domicilio"
}
```

### DELETE /api/v1/carrito/direcciones/{id}
**Auth:** Bearer · scope: carrito

Elimina una dirección de envío del cliente.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la dirección. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Dirección eliminada. |
| 400 | id inválido. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Cuenta sin acceso o sin scope carrito. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X DELETE https://developers.syscom.mx/api/v1/carrito/direcciones/901 \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{ "error": "" }
```

## Facturas

_Bearer_

Facturas del cliente, guías de envío y el detalle de cada factura. Solo consulta.

### GET /api/v1/facturas
**Auth:** Bearer

Lista las facturas del cliente con el avance de su entrega. Puedes filtrar por año o por folio. Solo consulta.

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `anio` | number | no | Año a consultar (rango 01-ene → 31-dic). Default: año actual. Se ignora si se envía `busqueda`. |
| `pagina` | number | no | Página (15 por página). Default 1. |
| `busqueda` | string | no | Anula `anio`. Año (`2026`), año-mes (`2026-04`) o fecha (`2026-04-29`) → filtra por rango de fecha; cualquier otro texto → filtra por folio / folio_pedido (LIKE prefijo). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Listado paginado (puede venir vacío). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Distribuidor sin acceso a la API. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/facturas?anio=2026&pagina=1' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "total_facturas": "2",
  "pagina": 1,
  "paginas": 1,
  "mostrando": 2,
  "facturas": [
    {
      "folio_factura": "FA26/000000",
      "fecha": "2026-04-29",
      "total": "0.1",
      "texto": "Cincho de Nylon 6.6 StrongHold-, 300mm largo x 3.6mm ancho, ...",
      "moneda": "MXN",
      "pago_aplicado": 0.1,
      "estatus_fiscal": "Activa",
      "estatus": "Activa",
      "plazo": "0",
      "folio_pedido": "576-000000/26",
      "entrega": {
        "creacion": { "mensaje": "El folio fue creado por Página Web a las 09:04:30 am", "fecha": "2026-04-29 09:04:30" },
        "generar_orden": { "mensaje": "Fecha de Orden 2026-04-29 Se generó la orden de compra ...", "fecha": "2026-04-29 09:04:30" },
        "orden_compra": { "mensaje": "Fecha de autorización 2026-04-29 La orden de compra fue autorizada ...", "fecha": "2026-04-29 09:04:30" },
        "facturacion": { "mensaje": "Fecha de facturación 2026-04-29 El pedido fue facturado a las 10:40:56 am", "fecha": "2026-04-29 10:40:56" },
        "espera": { "mensaje": " La orden fue autorizada y se encuentra en proceso de facturación. ", "fecha": "En proceso" },
        "proceso_entrega": [
          { "mensaje": "En Proceso de entrega", "fecha": "0", "guias": "Esperando movimiento o firma", "fletera": "TERRESTRE SUC. CUU", "estado": "Simple" }
        ]
        /* si la factura está cancelada: en vez de espera/proceso_entrega aparece "cancelado": { "mensaje": "Cancelado ---Pedido cancelado. ", "fecha": "---" } */
      },
      "uuid": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
```

### GET /api/v1/facturas/guias
**Auth:** Bearer

Lista las guías de envío del cliente. Puedes pedir las de facturas específicas o las más recientes.

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `facturas` | string (CSV) | no | Folios específicos separados por coma (p. ej. `FA26/000000,FA26/000001`). Quita el límite de 30. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Arreglo de guías (puede venir vacío). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Distribuidor sin acceso a la API. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/facturas/guias' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "folio_guia": "GUIA000000000",
    "fletera": "PAQUETEXPRESS",
    "folio_factura": "FA25/000000",
    "fecha_factura": "15-10-2025 11:06:45",
    "id_cliente": "12345"
  }
]
```

### GET /api/v1/facturas/{id}
**Auth:** Bearer

Muestra el detalle completo de una factura: datos de envío, guías, productos y totales. Búscala por su folio. El costo de envío se muestra por separado en `envio`; el subtotal ya no lo incluye.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | string | sí | Folio o folio_pedido de la factura (sin slash o URL-encoded). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Detalle fiscal de la factura. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Distribuidor sin acceso a la API. |
| 404 | Factura no encontrada para este cliente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/facturas/000000' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "nom_vendedor": "Syscom ERP ",
  "guias": [
    {
      "guia": "",
      "estatus": "En Sucursal",
      "envio": "00000000",
      "fletera": "TERRESTRE SUC. CUU",
      "factura": "FA26/000000",
      "firma": "0",
      "id_fletera": "165",
      "fecha_guia": "0",
      "estado": "Simple"
    }
  ],
  "productos": [
    {
      "precio_lista": "0.1",
      "precio": "0.1",
      "cod_art": "S1240C",
      "descuento_cliente": "20.0000",
      "descuento_clasificacion": "22.0000",
      "descuento_financiero": "4.0000",
      "cantidad": "1",
      "descuento_volumen": "0.0000",
      "producto_id": "162242",
      "asterisco": "",
      "titulo": "Cincho de Nylon 6.6 StrongHold&trade;, 300mm largo x 3.6mm ancho, ...",
      "imagen": "https://ftp3.syscom.mx/.../PANDUIT/S1240C/S1240C-i.PNG",
      "marca": "PANDUIT",
      "link": "/producto/PANDUIT-S1240C-162242.html",
      "precio_unitario": "0.1",
      "importe": "0.1",
      "precio_oferta": "0.1"
    }
  ],
  "mail_vendedor": "",
  "ext_vendedor": "6100",
  "calle_emb": "AV. EJEMPLO",
  "no_ext_emb": "123",
  "no_int_emb": "",
  "colonia_emb": "CENTRO",
  "cp_emb": "31000",
  "ciudad_emb": "CHIHUAHUA",
  "estado_emb": "CHIHUAHUA",
  "pais_emb": "Mexico",
  "atencion_a": "JUAN PEREZ",
  "nom_guia": "TERRESTRE SUC. CUU",
  "metodo_pago": "04",
  "estatus": "Activa",
  "fiscal": "Activa",
  "moneda": "MXN",
  "iva_porcent": "16",
  "uuid": "00000000-0000-0000-0000-000000000000",
  "folio_factura": "FA26/000000",
  "folio_pedido": "576-000000/26",
  "sub_total": 0.1,
  "envio": 0.1,
  "iva": 0.1,
  "total": 0.1,
  "metodo_txt": "Tarjeta de Crédito"
}
```

### GET /api/v1/facturas/{anio}/{id}
**Auth:** Bearer

Igual que el detalle de factura, pero para folios que incluyen el año (por ejemplo FA26/000000). El costo de envío se muestra por separado en `envio`; el subtotal ya no lo incluye.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `anio` | string | sí | Prefijo del folio (p. ej. `FA26`). |
| `id` | string | sí | Parte numérica del folio (p. ej. `000000`). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Detalle fiscal de la factura. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Distribuidor sin acceso a la API. |
| 404 | Factura no encontrada para este cliente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/facturas/FA26/000000' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "nom_vendedor": "Syscom ERP ",
  "guias": [ /* ...igual que /facturas/{id} */ ],
  "productos": [ /* ...igual que /facturas/{id} */ ],
  "mail_vendedor": "",
  "ext_vendedor": "6100",
  "calle_emb": "AV. EJEMPLO",
  "no_ext_emb": "123",
  "no_int_emb": "",
  "colonia_emb": "CENTRO",
  "cp_emb": "31000",
  "ciudad_emb": "CHIHUAHUA",
  "estado_emb": "CHIHUAHUA",
  "pais_emb": "Mexico",
  "atencion_a": "JUAN PEREZ",
  "nom_guia": "TERRESTRE SUC. CUU",
  "metodo_pago": "04",
  "estatus": "Activa",
  "fiscal": "Activa",
  "moneda": "MXN",
  "iva_porcent": "16",
  "uuid": "00000000-0000-0000-0000-000000000000",
  "folio_factura": "FA26/000000",
  "folio_pedido": "576-000000/26",
  "sub_total": 0.1,
  "envio": 0.1,
  "iva": 0.1,
  "total": 0.1,
  "metodo_txt": "Tarjeta de Crédito"
}
```

## Marcas

_Bearer_

Las marcas del catálogo: listado, información de cada marca y sus productos.

### GET /api/v1/marcas
**Auth:** Bearer · caché: 1 h

Lista todas las marcas del catálogo, para filtros y navegación por marca.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK; arreglo de marcas. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso (gate de distribuidor). |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/marcas' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  { "id": "hikvision", "nombre": "HIKVISION" },
  { "id": "ubiquiti", "nombre": "UBIQUITI" }
]
```

### GET /api/v1/marcas/{marca}
**Auth:** Bearer · caché: 1 h

Muestra la información de una marca: nombre, descripción, logo y las categorías donde tiene productos.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `marca` | string | sí | Slug de la marca (p. ej. hikvision). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK; detalle de la marca. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso (gate de distribuidor). |
| 404 | Marca no encontrada. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/marcas/hikvision' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "descripcion": "Hikvision es el principal proveedor mundial de productos y soluciones de videovigilancia...",  /* opcional: ausente si la marca no tiene ficha */
  "titulo": "HIKVISION Digital Technology Co., Ltd. is",                                                          /* opcional: ausente si la marca no tiene ficha */
  "logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
  "categorias": [
    {
      "nombre": "Cámaras IP y NVRs",
      "id": "214",
      "imagen": "https://ftp3.syscom.mx/usuarios/fotos/DS9632NII8/DS9632NII8.jpg",
      "cantidad": 721
    }
  ]
}
```

### GET /api/v1/marcas/{marca}/productos
**Auth:** Bearer

Lista los productos de una marca (hasta 60 por página), con su precio y disponibilidad.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `marca` | string | sí | Slug de la marca (p. ej. hikvision). |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `limit` | number | no | Resultados por página. Tope 60. Default 60. |
| `pagina` | number | no | Página. Default 1. |
| `orden` | string | no | relevancia (def.), precio:asc, precio:desc, modelo:asc, marca, bestseller… |
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el ajuste financiero al precio. Acepta true/false, 1/0. |
| `stock` | flag | no | stock=true (o 1) → solo productos con existencia. Acepta true/false, 1/0 (no basta con solo enviarlo). |
| `stock_nuevo` | flag | no | stock_nuevo=true (o 1) → solo productos con existencia nueva (no cuenta caja abierta). Acepta true/false, 1/0. No se combina con stock=true. |
| `descripcion` | flag | no | descripcion=true (o 1) → agrega el campo descripcion (HTML) a cada producto. |
| `inventarios` | flag | no | inventarios=true (o 1) → llena existencia.detalle[] con el desglose por almacén. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |
| `agrupar` | flag | no | agrupar=1 o agrupar=true. Aceptado por compatibilidad, sin efecto en este endpoint (las variantes salen siempre en atributos). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK; página de productos de la marca. |
| 400 | Parámetros inválidos (p. ej. combinar stock y stock_nuevo). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso (gate de distribuidor). |
| 404 | Marca no encontrada. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/marcas/hikvision/productos?limit=20&orden=precio:asc' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "cantidad": 2721,
  "pagina": 1,
  "paginas": 273,
  "todo": true,
  "productos": [
    {
      "producto_id": "210627",
      "modelo": "DS-KIS604-P(C)",
      "total_existencia": 0,
      "titulo": "Kit de Videoportero IP PoE Estándar...",
      "marca": "HIKVISION",
      "garantia": "5 años",
      "sat_key": "43221525",
      "sat_description": "Sistemas de intercomunicación",
      "img_portada": "https://ftp3.syscom.mx/usuarios/fotos/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [
        { "id": "37", "nombre": "Control de Acceso", "nivel": 1 }
      ],
      "categorias_producto_todas": [
        [ { "id": "37", "nombre": "Control de Acceso", "nivel": 1 } ]
      ],
      "pvol": "2.79",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-KIS604-P(C)-HIKVISION-210627.html",
      "imagen_360": [],
      "iconos": [],                            /* objeto { sup_izq, sup_der, inf_der } cuando hay íconos; [] si no */
      "peso": "1.63",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "15",
      "largo": "38",
      "ancho": "25",
      "descripcion": "...",                    /* solo con descripcion (truthy) */
      "caracteristicas": [ "Video HD 1080p", "Apertura remota vía app" ],
      "proyecto": true,                        /* solo si el producto es de "proyecto" (marca/costo/clasificación) */
      "atributos": {                           /* solo si el producto pertenece a un grupo de variantes */
        "Color": { "Negro": { "producto_id": "210628", "detalle": "Negro" } }
      },
      "precios": {                             /* objeto; [] si el cliente no tiene distribución del producto */
        "precio_1": "0.1",
        "precio_especial": "0.1",
        "precio_descuento": "0.1",
        "volumen": { "2": "0.1", "3": "0.1" },
        "precio_map": "0.1",
        "precio_lista": "0.1"
      },
      "existencia": {
        "nuevo": 0,
        "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 },
        "detalle": []                          /* poblado solo con inventarios (truthy) */
      },
      "nota": "SOLICITAR DISTRIBUCIÓN"          /* solo cuando el cliente no tiene distribución (precios = []) */
    }
  ]
}
```

## Productos

_Bearer · scope ver-productos_

Consulta el catálogo: busca productos y revisa su ficha, precio y disponibilidad según tu cuenta.

### GET /api/v1/productos
**Auth:** Bearer · scope: ver-productos

Busca productos del catálogo por categoría, marca o palabra clave. Cada resultado muestra su precio y disponibilidad según tu cuenta. Indica al menos una categoría, marca o palabra para realizar la búsqueda.

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `categoria` | string (CSV) | no | Uno o varios IDs de categoría: 21,30. Une niveles 1/2/3. Solo dígitos y comas. |
| `marca` | string (CSV) | no | Uno o varios slugs de marca: hikvision,ubiquiti (solo [a-z0-9,]). Slug inexistente → 404. |
| `busqueda` | string | no | Búsqueda por texto (motor de tags interno). |
| `orden` | string | no | relevancia (def.), precio:asc, precio:desc, modelo:asc, modelo:desc, marca:asc, marca:desc, bestseller, topseller. También admite los alias sueltos marca, precio, modelo. |
| `pagina` | number | no | Página (1–1000). Default 1. |
| `limit` | number | no | Resultados por página (10–1000). Default 60. |
| `stock` | flag | no | stock=true (o 1) → solo productos con existencia. Acepta true/false, 1/0 (no basta con solo enviarlo). |
| `stock_nuevo` | flag | no | stock_nuevo=true (o 1) → solo productos con existencia nueva (no cuenta caja abierta). Acepta true/false, 1/0. No se combina con stock=true. |
| `sucursal` | string (CSV) | no | Filtra por existencia en uno o varios almacenes (slug de sucursal: mexico, guadalajara…). Slug inexistente → 404. |
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el descuento financiero al precio. Acepta true/false, 1/0. |
| `inventarios` | flag | no | inventarios=true (o 1) → agrega existencia.detalle (desglose por almacén y condición); sin él, detalle es []. |
| `descripcion` | flag | no | descripcion=true (o 1) → incluye el campo descripcion (HTML) en cada resultado. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK. |
| 400 | Parámetros inválidos o faltan categoria/marca/busqueda. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Scope ver-productos insuficiente o cuenta sin acceso. |
| 404 | Marca o sucursal no encontrada. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/productos?categoria=21,30&inventarios=true&pagina=1&limit=1000' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "cantidad": 573,
  "pagina": 1,
  "paginas": 1,
  "todo": false,
  "productos": [
    {
      "producto_id": "215182",
      "modelo": "DS-2FA1205-C8/K",
      "total_existencia": 0,
      "titulo": "Fuente de Poder Regulada 12 Vcc ...",
      "marca": "HIKVISION",
      "garantia": "5 años",
      "sat_key": "39121004",
      "sat_description": "Unidades de suministro de energia",
      "img_portada": "https://ftp3.syscom.mx/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ],
      "categorias_producto_todas": [ [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ] ],
      "pvol": "0",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-2FA1205-C8-K-HIKVISION-215182.html",
      "imagen_360": [],
      "iconos": [], /* {} con iconos (sup_izq/sup_der/inf_der); [] si no hay */
      "peso": "0.15",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "1",
      "largo": "1",
      "ancho": "1",
      "descripcion": "<div>...</div>", /* solo con descripcion=1 */
      "caracteristicas": [ "Protección contra sobrecarga" ],
      "proyecto": true, /* solo si el producto es de "proyecto" */
      "nota": "SOLICITAR DISTRIBUCIÓN", /* solo sin distribución; entonces precios es [] */
      "precios": { /* objeto; [] sin distribución */
        "precio_1": "0.1",
        "precio_especial": "0.1",
        "precio_descuento": "0.1",
        "volumen": { "10": "0.1", "25": "0.1" },
        "precio_map": "0.1",
        "precio_lista": "0.1"
      },
      "existencia": {
        "nuevo": 0,
        "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 },
        "detalle": { /* desglose por almacén; aparece porque se pidió inventarios=true ([] si no se pide) */
          "nuevo": { "guadalajara": "0", "mexico": "0" }
        }
      }
    }
  ]
}
```

### GET /api/v1/productos/busqueda-ia
**Auth:** Bearer · scope: ver-productos

Busca productos por intención en lenguaje natural (con IA), no solo por palabras exactas: describe lo que necesitas —"cámara domo para exterior con visión nocturna"— y obtén los más relevantes, con su precio y disponibilidad. Ideal para asistentes de IA (Claude Code, Cursor, Codex).

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `q` | string | sí | Consulta en lenguaje natural (3–256 caracteres). Ej.: "radio portátil uhf para brigada de rescate". |
| `pagina` | number | no | Página (1–1000). Default 1. |
| `limit` | number | no | Resultados por página (1–60). Default 20. |
| `stock` | flag | no | stock=true (o 1) → solo productos con existencia. Acepta true/false, 1/0 (no basta con solo enviarlo). |
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el descuento financiero al precio. Acepta true/false, 1/0. |
| `inventarios` | flag | no | inventarios=true (o 1) → agrega existencia.detalle (desglose por almacén y condición). |
| `descripcion` | flag | no | descripcion=true (o 1) → incluye el campo descripcion (HTML) en cada resultado. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK. Sin coincidencias → productos: []. |
| 400 | Parámetro q ausente o fuera de 3–256 caracteres. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Scope ver-productos insuficiente o cuenta sin acceso. |
| 429 | Límite de peticiones de búsqueda con IA excedido (Retry-After). |
| 503 | Servicio de búsqueda con IA no disponible temporalmente. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/productos/busqueda-ia?q=camara+domo+exterior+vision+nocturna&limit=10' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "cantidad": 10,
  "pagina": 1,
  "paginas": 1,
  "todo": false,
  "productos": [
    {
      "producto_id": "215182",
      "modelo": "DS-2CD2143G2-I",
      "titulo": "Cámara Domo IP 4 Megapíxel / Lente 2.8 mm / Exterior IP67 ...",
      "marca": "HIKVISION",
      "precios": { "precio_1": "0.1", "precio_especial": "0.1", "precio_lista": "0.1" },
      "existencia": { "nuevo": 12 }
      /* ...mismos campos que /api/v1/productos... */
    }
  ]
}
```

### GET /api/v1/productos/{id}
**Auth:** Bearer · scope: ver-productos

Muestra la ficha completa de un producto: precio, disponibilidad, descripción, características, imágenes y documentos. Puedes consultar varios productos a la vez.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | string (CSV) | sí | ID de producto, o varios separados por coma (hasta 300). |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el descuento financiero al precio. Acepta true/false, 1/0. |
| `inventarios` | flag | no | inventarios=true (o 1) → agrega existencia.detalle (desglose por almacén y condición); sin él, detalle es []. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK (objeto si 1 ID, arreglo si varios). |
| 400 | id inválido. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Scope ver-productos insuficiente o cuenta sin acceso. |
| 404 | Ningún producto disponible (product_not_available). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/productos/210627?iva=1&inventarios=1' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "producto_id": "210627",
  "modelo": "DS-KIS604-P(C)",
  "total_existencia": 0,
  "titulo": "Kit de Videoportero IP PoE Estandar ...",
  "marca": "HIKVISION",
  "garantia": "5 años",
  "sat_key": "43221525",
  "sat_description": "Sistemas de intercomunicacion",
  "img_portada": "https://ftp3.syscom.mx/...",
  "link_privado": "https://www.productos-info.com/s/syscom/es/...",
  "categorias": [ { "id": "37", "nombre": "Control de Acceso", "nivel": 1 } ],
  "categorias_producto_todas": [ [ { "id": "37", "nombre": "Control de Acceso", "nivel": 1 } ] ],
  "pvol": "2.79",
  "proyecto": true, /* solo si el producto es de "proyecto" */
  "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
  "link": "/producto/DS-KIS604-P(C)-HIKVISION-210627.html",
  "descripcion": "<div>...</div>",
  "imagen_360": [],
  "iconos": { "sup_izq": "https://ftp3.syscom.mx/...", "sup_der": "https://ftp3.syscom.mx/..." }, /* {} con iconos; [] si no hay */
  "peso": "1.63",
  "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
  "alto": "15",
  "largo": "38",
  "ancho": "25",
  "precios": { /* objeto; [] sin distribución (entonces aparece "nota": "SOLICITAR DISTRIBUCIÓN") */
    "precio_1": "0.1",
    "precio_especial": "0.1",
    "precio_descuento": "0.1",
    "volumen": { "2": "0.1", "3": "0.1" },
    "precio_map": "0.1",
    "precio_lista": "0.1"
  },
  "existencia": {
    "nuevo": 0,
    "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 },
    "detalle": { /* objeto por almacén/condición solo con inventarios=1; [] sin él */
      "nuevo": { "puebla": "0", "guadalajara": "0", "mexico": "0" },
      "b": { "queretaro": "0" },
      "c": { "mexico": "0" }
    }
  },
  "caracteristicas": [ "Acceso remoto vía app Hik-Connect" ],
  "imagenes": [ { "imagen": "https://ftp3.syscom.mx/...", "orden": "0" } ],
  "recursos": [ { "recurso": "Ficha_tecnica", "path": "https://ftp3.syscom.mx/..." } ]
}
```

### GET /api/v1/productos/{id}/relacionados
**Auth:** Bearer · scope: ver-productos

Lista los productos relacionados con uno dado, ideales para sugerir alternativas. Solo incluye los que tienen disponibilidad.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID del producto base. |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el descuento financiero. Acepta true/false, 1/0. |
| `inventarios` | flag | no | inventarios=true (o 1) → agrega existencia.detalle (desglose por almacén); sin él, detalle es []. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK (arreglo, vacío si no hay relacionados). |
| 400 | id inválido. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Scope ver-productos insuficiente o cuenta sin acceso. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/productos/210627/relacionados' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "producto_id": "158799",
    "modelo": "DS-1LN5E-S",
    "total_existencia": 0,
    "titulo": "Bobina de Cable UTP 305 Metros ...",
    "marca": "HIKVISION",
    "garantia": "5 años",
    "sat_key": "26121609",
    "sat_description": "Cable de redes",
    "img_portada": "https://ftp3.syscom.mx/...",
    "link_privado": "https://www.productos-info.com/s/syscom/es/...",
    "categorias": [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ],
    "categorias_producto_todas": [ [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ] ],
    "pvol": "0",
    "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
    "link": "/producto/DS-1LN5E-S-HIKVISION-158799.html",
    "imagen_360": [],
    "iconos": [], /* {} con iconos; [] si no hay */
    "peso": "15.00",
    "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
    "alto": "30",
    "largo": "30",
    "ancho": "30",
    "caracteristicas": [ "Cable UTP Cat6 100% cobre" ],
    "precios": { "precio_1": "0.1", "precio_descuento": "0.1", "precio_map": "0.1", "precio_lista": "0.1" }, /* [] sin distribución (+ "nota") */
    "existencia": { "nuevo": 0, "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 }, "detalle": [] } /* detalle: objeto solo con inventarios=1 */
  }
]
```

### GET /api/v1/productos/{id}/accesorios
**Auth:** Bearer · scope: ver-productos

Lista los accesorios compatibles con un producto (hasta 5), útiles para venta complementaria.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID del producto base. |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=true (o 1). |
| `iva` | flag | no | iva=true (o 1) → precios con IVA. Acepta true/false, 1/0. |
| `financiero` | flag | no | financiero=true (o 1) → aplica el descuento financiero. Acepta true/false, 1/0. |
| `inventarios` | flag | no | inventarios=true (o 1) → agrega existencia.detalle (desglose por almacén); sin él, detalle es []. |
| `informacion_pro` | flag | no | informacion_pro=true → agrega titulo_pro, descripcion_pro y caracteristicas_pro: versiones mejoradas del título, descripción y características. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK (arreglo, vacío si no hay accesorios). |
| 400 | id inválido. |
| 401 | Token ausente, inválido o revocado. |
| 403 | Scope ver-productos insuficiente o cuenta sin acceso. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/productos/210627/accesorios' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "producto_id": "158799",
    "modelo": "DS-1LN5E-S",
    "total_existencia": 0,
    "titulo": "Bobina de Cable UTP 305 Metros ...",
    "marca": "HIKVISION",
    "garantia": "5 años",
    "sat_key": "26121609",
    "sat_description": "Cable de redes",
    "img_portada": "https://ftp3.syscom.mx/...",
    "link_privado": "https://www.productos-info.com/s/syscom/es/...",
    "categorias": [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ],
    "categorias_producto_todas": [ [ { "id": "22", "nombre": "Videovigilancia", "nivel": 1 } ] ],
    "pvol": "5.14",
    "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
    "link": "/producto/DS-1LN5E-S-HIKVISION-158799.html",
    "imagen_360": [],
    "iconos": { "sup_izq": "https://ftp3.syscom.mx/...", "sup_der": "https://ftp3.syscom.mx/..." }, /* {} con iconos; [] si no hay */
    "peso": "9.80",
    "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
    "alto": "21",
    "largo": "35",
    "ancho": "35",
    "caracteristicas": [ "Cable UTP Cat6 100% cobre" ],
    "precios": { "precio_1": "0.1", "precio_descuento": "0.1", "precio_map": "0.1", "precio_lista": "0.1" }, /* [] sin distribución (+ "nota") */
    "existencia": { "nuevo": 0, "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 }, "detalle": [] } /* detalle: objeto solo con inventarios=1 */
  }
]
```

### GET /api/v1/productos?modelo={modelo}
**Auth:** Bearer · scope: ver-productos

Consulta un producto por su modelo/SKU exacto y obtén su precio y disponibilidad. Funciona aunque el modelo lleve diagonal (ej. DS-2FA1205-C8/K).

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `modelo` | string | sí | Modelo comercial o modelo limpio (cod_art). Admite diagonal. |
| `moneda` | string | no | usd (default) \| mxn. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK (objeto si 1 coincidencia, arreglo si varias). |
| 400 | falta modelo (u otro filtro). |
| 401 | Token ausente, inválido o revocado. |
| 404 | Sin coincidencias para ese modelo. |

```bash
curl -G 'https://developers.syscom.mx/api/v1/productos' \
  --data-urlencode 'modelo=DS-2FA1205-C8/K' \
  -H 'Authorization: Bearer TU_TOKEN'
```

## Catálogos de referencia

_Mixto (tipocambio público)_

Datos de apoyo para cotizar y facturar: tipo de cambio, sucursales, países, estados, colonias, formas de pago, paqueterías y uso de CFDI.

### GET /api/v1/tipocambio
**Auth:** Público

Tipo de cambio vigente (normal, preferencial y por plazos) para convertir precios a pesos. Es público: no requiere token.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Tipo de cambio vigente. |
| 404 | No hay tipo de cambio disponible. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/tipocambio'
```

```json
{
  "normal": "17.50",
  "preferencial": "17.30",
  "un_dia": "17.35",
  "una_semana": "17.40",
  "dos_semanas": "17.45",
  "tres_semanas": "17.48",
  "un_mes": "17.55"
}
```

### GET /api/v1/sucursales
**Auth:** Bearer · caché: 1 h

Lista las sucursales de Syscom en México, con su nombre e identificador.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Lista de sucursales. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso (gate de distribuidor). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/sucursales' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  { "sucursal": "Chihuahua", "id": "chihuahua" },
  { "sucursal": "México Norte", "id": "mexico" }
]
```

### GET /api/v1/carrito/paises
**Auth:** Bearer · scope: carrito · caché: 6 h

Países disponibles para las direcciones de envío.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Catálogo de países. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/paises' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "paises": [
    { "codigo": "MX", "id": 156, "nombre": "México" }
  ]
}
```

### GET /api/v1/carrito/estados/{cp}
**Auth:** Bearer · scope: carrito

Devuelve el estado y el municipio que corresponden a un código postal.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `cp` | string | sí | Código postal (4-5 dígitos). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Estado/municipio del código postal. |
| 400 | Código postal inválido (no 4-5 dígitos). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/estados/31000' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "estado": [
    {
      "codigo_postal": "31000",
      "municipio": "CHIHUAHUA",
      "estado_sat": "CHH",
      "zona_extendida": "0",
      "estado_nombre": "CHIHUAHUA",
      "codigo_estado": "CHH"
    }
  ]
}
```

### GET /api/v1/carrito/colonias/{cp}
**Auth:** Bearer · scope: carrito

Lista las colonias de un código postal.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `cp` | string | sí | Código postal (4-5 dígitos). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Colonias del código postal. |
| 400 | Código postal inválido (no 4-5 dígitos). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/colonias/31000' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "colonias": ["CENTRO", "SANTA RITA"]
}
```

### GET /api/v1/carrito/pago
**Auth:** Bearer · scope: carrito · caché: Estático

Formas de pago disponibles para el pedido (transferencia, pago en sucursal, crédito, etc.), con su descuento y plazo.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Catálogo de métodos de pago. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/pago' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "nombre": "Transferencia",
    "metodo": {
      "transferencia": {
        "id": "transferencia",
        "titulo": "Transferencia electrónica de fondos",
        "codigo": "03",
        "descuento": 4,
        "tipo_cambio": "preferencial",
        "plazo": 1,
        "forma": { "PUE": 1, "PPD": 2 }
      }
    }
  }
]
```

### GET /api/v1/carrito/fleteras
**Auth:** Bearer · scope: carrito · caché: Estático

Paqueterías disponibles para el envío, indicando cuáles ofrecen entrega al día siguiente.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Catálogo de fleteras. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/fleteras' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  { "codigo": "estafeta", "dia_siguiente": false, "nombre": "Estafeta" },
  { "codigo": "fedex", "dia_siguiente": false, "nombre": "FedEx" },
  { "codigo": "estafeta_siguiente", "dia_siguiente": true, "nombre": "Estafeta día siguiente" }
]
```

### GET /api/v1/carrito/cfdi
**Auth:** Bearer · scope: carrito · caché: 6 h

Usos de CFDI disponibles para la facturación del pedido.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Catálogo de usos de CFDI. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o scope `carrito` insuficiente. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/carrito/cfdi' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  { "codigo": "G01", "nombre": "Adquisición de mercancías" },
  { "codigo": "G03", "nombre": "Gastos en general" }
]
```

## Contenido

_Público_

Contenido de portada, como los banners promocionales.

### GET /api/v1/banners
**Auth:** Público · caché: 1 h

Banners promocionales de la portada: los fijos y los del carrusel vigentes hoy. Es público: no requiere token.

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `movil` | string | no | `movil=si` → devuelve únicamente los banners marcados para móvil (filtra ambos arreglos). Cualquier otro valor (o ausencia) devuelve los banners de escritorio. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | OK. Banners de portada (arreglos `normal` y `carrusel`). |
| 500 | Error interno al consultar el backend WEB. |

```bash
curl 'https://developers.syscom.mx/api/v1/banners'
```

```json
{
  "normal": [
    {
      "titulo": "Promo de temporada",
      "subtitulo": "Hasta 20% off",
      "link_banner": "https://...",
      "link_pagina": "/ofertas",
      "nueva_ventana": "no"
    }
  ],
  "carrusel": []
}
```

## Wishlists

_Bearer · scope wishlists_

Listas de deseos de tus clientes y los productos que guardan, con su precio y disponibilidad.

### GET /api/v1/wishlists
**Auth:** Bearer · scope: wishlists

Lista las listas de deseos del cliente con los productos que contiene cada una.

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Arreglo de listas ([] si el cliente no tiene ninguna). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/wishlists' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
[
  {
    "id": "12",
    "nombre": "Proyecto escuela",
    "producto_id": ["12345", "67890"]
  }
]
```

### POST /api/v1/wishlists
**Auth:** Bearer · scope: wishlists

Crea una lista de deseos con un nombre y, si quieres, productos iniciales.

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=1. |
| `iva` | flag | no | iva=1 → precios con IVA (×1.16). |
| `financiero` | flag | no | financiero=1 → aplica descuento financiero a los precios. |
| `inventarios` | flag | no | inventarios=1 → llena existencia.detalle (objeto por asterisco → almacén → cantidad); sin él detalle es []. |

**Cuerpo de la petición**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `nombre` | string | sí | Nombre de la lista (10–255 caracteres). |
| `productos` | number[] | sí | IDs de producto iniciales ([] si ninguno). |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 201 | Lista creada con sus productos. |
| 400 | Body inválido (nombre 10–255 y productos[] requeridos). |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno (p. ej. un producto inicial no existe). |

```bash
curl -X POST https://developers.syscom.mx/api/v1/wishlists \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "nombre": "Proyecto escuela", "productos": [12345] }'
```

```json
{
  "id_lista": 12,
  "nombre": "Proyecto escuela",
  "cantidad": 1,
  "productos": [
    {
      "producto_id": "12345",
      "modelo": "DS-2CD1023G0E-I",
      "total_existencia": 0,
      "titulo": "Cámara IP 2 Megapixel ...",
      "marca": "HIKVISION",
      "garantia": "1 años",
      "sat_key": "46171610",
      "sat_description": "Cámaras",
      "img_portada": "https://ftp3.syscom.mx/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }],
      "categorias_producto_todas": [[{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }]],
      "pvol": "1.20",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-2CD1023G0E-I-HIKVISION-12345.html",
      "imagen_360": [],
      "iconos": { "sup_izq": "https://ftp3.syscom.mx/..." }, /* {} si no aplica → se emite [] */
      "peso": "0.40",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "10",
      "largo": "15",
      "ancho": "8",
      "caracteristicas": [ "Resolución 2 Megapixel", "Visión nocturna IR" ],
      "precios": { /* objeto; [] cuando el cliente no tiene distribución o no hay precio */
        "precio_1": "0.1",
        "precio_especial": "0.1",
        "precio_descuento": "0.1",
        "volumen": { "5": "0.1" }, /* solo si hay descuento por volumen */
        "precio_map": "0.1",
        "precio_lista": "0.1"
      },
      "existencia": {
        "nuevo": 0,
        "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 },
        "detalle": [] /* objeto por asterisco→almacén solo con inventarios=1; si no, [] */
      },
      "nota": "SOLICITAR DISTRIBUCIÓN", /* solo cuando el cliente no tiene distribución */
      "proyecto": true, /* solo si el producto es de proyecto (marca/costo/clasificación) */
      "atributos": {} /* solo si el producto pertenece a un grupo de variantes */
    }
  ]
}
```

### GET /api/v1/wishlists/{id}
**Auth:** Bearer · scope: wishlists

Muestra una lista de deseos con sus productos completos, incluyendo precio y disponibilidad.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la lista. |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=1. |
| `iva` | flag | no | iva=1 → precios con IVA (×1.16). |
| `financiero` | flag | no | financiero=1 → aplica descuento financiero a los precios. |
| `inventarios` | flag | no | inventarios=1 → llena existencia.detalle (objeto por asterisco → almacén → cantidad); sin él detalle es []. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Lista con sus productos completos. |
| 400 | id inválido. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 404 | Lista no encontrada (o de otro cliente). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl 'https://developers.syscom.mx/api/v1/wishlists/12?iva=1' \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "id_lista": 12,
  "nombre": "Proyecto escuela",
  "cantidad": 2,
  "productos": [
    {
      "producto_id": "12345",
      "modelo": "DS-2CD1023G0E-I",
      "total_existencia": 0,
      "titulo": "Cámara IP 2 Megapixel ...",
      "marca": "HIKVISION",
      "garantia": "1 años",
      "sat_key": "46171610",
      "sat_description": "Cámaras",
      "img_portada": "https://ftp3.syscom.mx/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }],
      "categorias_producto_todas": [[{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }]],
      "pvol": "1.20",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-2CD1023G0E-I-HIKVISION-12345.html",
      "imagen_360": [],
      "iconos": [],
      "peso": "0.40",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "10",
      "largo": "15",
      "ancho": "8",
      "caracteristicas": [ "Resolución 2 Megapixel", "Visión nocturna IR" ],
      "precios": { /* objeto; [] cuando el cliente no tiene distribución o no hay precio */
        "precio_1": "0.1",
        "precio_especial": "0.1",
        "precio_descuento": "0.1",
        "precio_map": "0.1",
        "precio_lista": "0.1"
      },
      "existencia": {
        "nuevo": 0,
        "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 },
        "detalle": [] /* objeto por asterisco→almacén solo con inventarios=1; si no, [] */
      },
      "nota": "SOLICITAR DISTRIBUCIÓN", /* solo cuando el cliente no tiene distribución */
      "proyecto": true /* solo si el producto es de proyecto */
    }
  ]
}
```

### DELETE /api/v1/wishlists/{id}
**Auth:** Bearer · scope: wishlists

Elimina una lista de deseos del cliente y todos sus productos.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la lista. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Lista eliminada. |
| 400 | id inválido. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 404 | Lista no encontrada (o de otro cliente). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X DELETE https://developers.syscom.mx/api/v1/wishlists/12 \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{ "message": "Lista 12 eliminada correctamente." }
```

### POST /api/v1/wishlists/{id}/productos/{productoId}
**Auth:** Bearer · scope: wishlists

Agrega un producto a una lista de deseos. Si ya estaba, actualiza su precio. Devuelve la lista al día.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la lista. |
| `productoId` | number | sí | ID del producto. |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=1. |
| `iva` | flag | no | iva=1 → precios con IVA (×1.16). |
| `financiero` | flag | no | financiero=1 → aplica descuento financiero a los precios. |
| `inventarios` | flag | no | inventarios=1 → llena existencia.detalle (objeto por asterisco → almacén → cantidad); sin él detalle es []. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Producto agregado; devuelve la lista actualizada. |
| 400 | id o productoId inválidos. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 404 | Lista no encontrada (o de otro cliente). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno (p. ej. el producto no existe). |

```bash
curl -X POST https://developers.syscom.mx/api/v1/wishlists/12/productos/12345 \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "id_lista": 12,
  "nombre": "Proyecto escuela",
  "cantidad": 2,
  "productos": [
    {
      "producto_id": "12345",
      "modelo": "DS-2CD1023G0E-I",
      "total_existencia": 0,
      "titulo": "Cámara IP 2 Megapixel ...",
      "marca": "HIKVISION",
      "garantia": "1 años",
      "sat_key": "46171610",
      "sat_description": "Cámaras",
      "img_portada": "https://ftp3.syscom.mx/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }],
      "categorias_producto_todas": [[{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }]],
      "pvol": "1.20",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-2CD1023G0E-I-HIKVISION-12345.html",
      "imagen_360": [],
      "iconos": [],
      "peso": "0.40",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "10",
      "largo": "15",
      "ancho": "8",
      "caracteristicas": [ "Resolución 2 Megapixel", "Visión nocturna IR" ],
      "precios": { "precio_1": "0.1", "precio_especial": "0.1", "precio_descuento": "0.1", "precio_map": "0.1", "precio_lista": "0.1" }, /* [] sin distribución */
      "existencia": { "nuevo": 0, "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 }, "detalle": [] }
    }
  ]
}
```

### DELETE /api/v1/wishlists/{id}/productos/{productoId}
**Auth:** Bearer · scope: wishlists

Quita un producto de una lista de deseos y devuelve la lista al día.

**Parámetros de ruta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `id` | number | sí | ID de la lista. |
| `productoId` | number | sí | ID del producto. |

**Parámetros de consulta**

| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
| `moneda` | string | no | usd (def.) o mxn. Alias: mxn=1. |
| `iva` | flag | no | iva=1 → precios con IVA (×1.16). |
| `financiero` | flag | no | financiero=1 → aplica descuento financiero a los precios. |
| `inventarios` | flag | no | inventarios=1 → llena existencia.detalle (objeto por asterisco → almacén → cantidad); sin él detalle es []. |

**Códigos de estado**

| Código | Cuándo |
|---|---|
| 200 | Producto quitado; devuelve la lista actualizada. |
| 400 | id o productoId inválidos. |
| 401 | Token ausente, inválido, expirado o revocado. |
| 403 | Cuenta sin acceso o sin scope wishlists. |
| 404 | Lista no encontrada (o de otro cliente). |
| 429 | Límite de peticiones excedido. |
| 500 | Error interno. |

```bash
curl -X DELETE https://developers.syscom.mx/api/v1/wishlists/12/productos/12345 \
  -H 'Authorization: Bearer TU_TOKEN'
```

```json
{
  "id_lista": 12,
  "nombre": "Proyecto escuela",
  "cantidad": 1,
  "productos": [
    {
      "producto_id": "67890",
      "modelo": "DS-2CD1043G2-I",
      "total_existencia": 0,
      "titulo": "Cámara IP 4 Megapixel ...",
      "marca": "HIKVISION",
      "garantia": "1 años",
      "sat_key": "46171610",
      "sat_description": "Cámaras",
      "img_portada": "https://ftp3.syscom.mx/...",
      "link_privado": "https://www.productos-info.com/s/syscom/es/...",
      "categorias": [{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }],
      "categorias_producto_todas": [[{ "id": "22", "nombre": "Videovigilancia", "nivel": 1 }]],
      "pvol": "1.30",
      "marca_logo": "https://ftp3.syscom.mx/usuarios/fotos/logotipos/hikvision.png",
      "link": "/producto/DS-2CD1043G2-I-HIKVISION-67890.html",
      "imagen_360": [],
      "iconos": [],
      "peso": "0.45",
      "unidad_de_medida": { "codigo_unidad": "1", "nombre": "Pieza", "clave_unidad_sat": "H87" },
      "alto": "10",
      "largo": "15",
      "ancho": "8",
      "caracteristicas": [ "Resolución 2 Megapixel", "Visión nocturna IR" ],
      "precios": { "precio_1": "0.1", "precio_especial": "0.1", "precio_descuento": "0.1", "precio_map": "0.1", "precio_lista": "0.1" }, /* [] sin distribución */
      "existencia": { "nuevo": 0, "asterisco": { "a": 0, "b": 0, "c": 0, "d": 0 }, "detalle": [] }
    }
  ]
}
```

## Errores

Todos los endpoints comparten el mismo contrato: un status HTTP semántico y un cuerpo JSON uniforme. Nunca se exponen stack traces, queries ni mensajes internos de la base de datos.

```json
{
  "error": "Parámetros inválidos",
  "code": "invalid_params"
}
```

| Código | Cuándo |
|---|---|
| 200 | Petición exitosa. |
| 201 | Recurso creado (p. ej. POST de wishlists o direcciones). |
| 400 | Parámetros, query o cuerpo inválidos. El cuerpo trae un mensaje genérico, sin detalles internos. |
| 401 | Falta el header Authorization, o el token es inválido, expiró o fue revocado. |
| 403 | La cuenta no está habilitada (gate de distribuidor) o al token le falta el scope requerido. |
| 404 | El recurso solicitado no existe. |
| 405 | El método HTTP no aplica a esa ruta (respuesta automática con header Allow). |
| 429 | Se superó el límite de tasa. Respeta el header Retry-After (segundos) antes de reintentar. |
| 500 | Error interno no controlado. No se exponen detalles. |
| 501 | Funcionalidad deshabilitada por configuración (p. ej. la escritura de carrito). |