> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashea.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Resumen

> Cómo operar la API Inventario: ambientes, orden de las operaciones, errores y reglas de cuotas y envío

La API te permite gestionar tu catálogo en el marketplace de Cashea de forma programática: consultar el árbol de categorías y sus atributos, listar marcas comerciales, y crear, actualizar y consultar productos.

Se autentica con **API Key** y cada request queda acotado a la tienda online asociada a esa API Key.

## Base URL y ambientes

| Ambiente | Base URL |
| - | - |
| Sandbox | `https://sandbox.external.cashea.app` |
| Producción | `https://external.cashea.app` |

> [!NOTE]
>
> Para pedir tus credenciales de la API Inventario, escribe a [inventarios@cashea.app](mailto:inventarios@cashea.app).

### Sandbox

Sandbox es el ambiente de pruebas donde integras y validas antes de pasar a producción. Su catálogo es independiente: los productos que cargues ahí no aparecen en el marketplace real.

Cada ambiente tiene su propia API Key — la de Sandbox no sirve en producción, ni viceversa. Ver [Autenticación](https://docs.cashea.app/apis/authentication.md).

## Cómo operar la API

Las operaciones tienen un orden: un producto necesita una categoría válida, los atributos de esa categoría y una marca comercial antes de poder crearse.

**1. Elige la categoría**

[Listar categorías](https://docs.cashea.app/apis/inventory/get-categories.md) para navegar el árbol o buscar por nombre. Elige una categoría hoja (`hasChildren: false`) y guarda su `uuid`.

**2. Trae sus atributos (opcional)**

No todas las categorías tienen atributos. [Obtener categoría por ID](https://docs.cashea.app/apis/inventory/get-category-by-id.md) te dice cuáles tiene, cuáles son obligatorios y qué valores aceptan. De ahí salen los pares `attributeId` / `valueId`.

**3. Elige la marca comercial**

[Listar marcas comerciales](https://docs.cashea.app/apis/inventory/list-commercial-brands.md) devuelve las habilitadas de tu tienda. Sus `uuid` van en `commercialBrands`.

**4. Carga los productos**

[Crear productos](https://docs.cashea.app/apis/inventory/create-products-async.md) encola un job y responde `202` con un `jobId`. No devuelve los productos creados.

**5. Consulta el job**

[Obtener job por ID](https://docs.cashea.app/apis/inventory/get-job.md) hasta que el estado sea `COMPLETED` o `FAILED`. Revisa siempre el array `errors`: un job `COMPLETED` puede traer ítems fallidos.

**6. Verifica el resultado**

[Obtener producto por SKU](https://docs.cashea.app/apis/inventory/get-product.md) o [Buscar productos](https://docs.cashea.app/apis/inventory/search-products.md) para confirmar qué quedó cargado.

Para modificar productos ya cargados el flujo es el mismo, pero con [Actualizar productos](https://docs.cashea.app/apis/inventory/update-products-async.md), que los identifica por `sku` y también devuelve un `jobId`.

## Manejo de errores

Los errores se devuelven en el siguiente formato:

```json theme={null}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "limit must be at most 200",
  "timestamp": "2026-07-08T13:08:00.912Z",
  "path": "/v2/inventory/categories?limit=999"
}
```

### Common status codes

| Código | Significado |
| - | - |
| `400` | Parámetros o body inválidos. El campo `message` indica la validación que falló. |
| `401` | No autenticado: API Key ausente, con formato inválido, inexistente o deshabilitada. |
| `403` | Autenticado pero sin autorización. |
| `404` | El recurso no existe. |
| `500` | Error inesperado del servidor. |

Cada endpoint puede tener errores propios además de estos; están en su sección **Errors**.

***

## Planes de cuotas

`bestInstallmentPlan` es un **techo, no una asignación**. Al crear o actualizar un producto declaras el máximo de cuotas que quieres ofrecer (`3`, `6`, `9` o `12`) y Cashea le otorga todos los planes elegibles hasta ese valor, nunca por encima.

La elegibilidad la define el **precio**: cada plan tiene un monto mínimo, y un producto recibe solamente los planes cuyo mínimo alcanza. Por eso **el valor que devuelve la API puede ser menor al que enviaste**.

***

## Cashea Envíos

`freeShipping` lo calcula Cashea en base al peso del producto y a las opciones de envío configuradas para tu comercio. **No es un campo que puedas enviar** al crear ni al actualizar productos: aparece solo en las respuestas de [Obtener producto por SKU](https://docs.cashea.app/apis/inventory/get-product.md) y [Buscar productos](https://docs.cashea.app/apis/inventory/search-products.md), y como filtro en el body de búsqueda.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.