**Funcionalidad en desarrollo y pruebas:** este servicio está disponible en el ambiente de pruebas y todavía no debe usarse en producción. El funcionamiento, los campos y los mensajes de error pueden cambiar antes del despliegue definitivo.

**¿Para qué sirve este servicio?** Úsalos cuando necesites **traducir los identificadores de nuby** a datos legibles, o al revés, sin mantener copias propias de la configuración. Los casos de uso más frecuentes son:

- **Elegir la resolución de venta** que vas a enviar en `resolucion_id` al crear o editar una factura. - **Obtener el `concepto_id`** de las notas de crédito y de las notas débito que vas a crear. - **Tomar los impuestos del producto** (`tipo_iva_id`, `por_iva` y sus equivalentes de retención y reteICA) y enviarlos en `items[]` de una factura o de una nota. - **Traducir el `estado_id`** de una factura al significado que ves en la interfaz de nuby. - **Evitar identificadores fijos** en tu plataforma: los conceptos y productos dependen de la configuración de tu instancia. ---

Método	Recurso	Catálogo que devuelve
`GET`	`/invoices/sales/resolutions`	Resoluciones de venta
`GET`	`/masters/note-concepts`	Conceptos de nota
`GET`	`/masters/products`	Productos e impuestos
`GET`	`/masters/invoice-statuses`	Estados de factura

**Importante:** no incluyas `https://` ni barras diagonales (`/`) al final. La dirección se compone así: `https://` + tu instancia + `/service/v2/public/` + la ruta del catálogo.

Encabezado	Valor
`Authorization`	`Bearer `, con el token obtenido en el servicio Login.

**¿Por qué `catalogs:read` y no un permiso de facturas?** Las lecturas de la API usan `catalogs:read` porque el cliente `nuby-clientes` no tiene un scope de lectura de facturas y exigirlo dejaría los endpoints inutilizables. En tu cliente OAuth los permisos de consulta disponibles son `catalogs:read`, `invoices:create`, `invoices:update`, `notes:create` y `third-parties:create`; leer se autoriza con `catalogs:read`.

Si aún no tienes un token, consulta la página [*Login*](https://docs.nuby.ai/books/api-nuby-v2/page/login) del libro **API nuby V2**.

**Usa este servicio, no el anterior.** El endpoint `GET /invoices/resolutions` sigue existiendo por compatibilidad, pero puede devolver resoluciones de contrato, y la API de venta las rechaza con `422 RESOLUCION_CONTRATO_NO_PERMITIDA`.

Parámetro	Tipo	Requerido	Descripción
`activa`	texto	No	`SI` o `NO`.
`tipo_doc_id`	entero	No	Tipo de documento de la resolución.
`fact_electronica`	texto	No	`SI` o `NO`.
`resolucion_para`	entero	No	`1` factura o `2` documento soporte.
`fecha_desde` / `fecha_hasta`	fecha	No	Rango sobre la fecha de la resolución (`AAAA-MM-DD`).
`fecha_vigencia_desde` / `fecha_vigencia_hasta`	fecha	No	Rango sobre la vigencia (`AAAA-MM-DD`).
`page`	entero	No	Número de página, empezando en 1. Por defecto `1`.
`page_size`	entero	No	Registros por página. Por defecto `10`. Máximo `1000`.

Parámetro	Tipo	Requerido	Descripción
`target`	entero	No	`1` nota crédito o `2` nota débito. Sin filtro devuelve todos.
`page`	entero	No	Número de página, empezando en 1. Por defecto `1`.
`page_size`	entero	No	Registros por página. Por defecto `50`. Máximo `1000`.

Parámetro	Tipo	Requerido	Descripción
`search`	texto	No	Busca coincidencias en el nombre del producto y en su código.
`estado`	entero	No	`1` activos, `0` inactivos. Sin filtro devuelve todos.
`page`	entero	No	Número de página, empezando en 1. Por defecto `1`.
`page_size`	entero	No	Registros por página. Por defecto `50`. Máximo `1000`.

**Parámetros inválidos:** si `page`, `page_size`, `activa`, `tipo_doc_id`, `fact_electronica`, `resolucion_para`, una fecha, `target` o `estado` no tienen un valor válido, la respuesta es `400` con `VALIDATION_ERROR`. `page` y `page_size` deben ser enteros mayores que cero.

Campo	Tipo	Descripción
`status`	integer	Código del estado de la respuesta. `200` cuando la consulta fue exitosa.
`message`	string	`null` cuando la consulta fue exitosa.
`body`	array	Registros del catálogo consultado. En un error, este campo no existe.
`pagination`	object	Resumen de la página: `total_records`, `total_pages`, `current_page`, `page_size`, `current_page_records`, `has_next_page` y `has_previous_page`.
`filters_applied`	object	Filtros que aplicó el servicio (por ejemplo `{"target": 2}`). Llega en `null` cuando la consulta no llevaba filtros.

Si no envías `concepto_id` al crear una nota, nuby aplica el concepto por defecto del tipo. Envíalo solo cuando necesites un concepto específico.

**Los porcentajes no se calculan solos.** Al crear la factura o la nota envía `tipo_iva_id` y `por_iva` (y sus equivalentes de retención) tomados de este catálogo. Si el producto trae `null`, envía `null` y el impuesto no se aplica.

`estado_id`	Estado	Qué significa
1	Facturado	Emitida con consecutivo y enviada a la DIAN.
2	Anulado	Anulada.
3	Pagada	Saldo en cero.
4	Contabilizada	Contabilidad cerrada.
5	Borrador	Creada por la API, editable, aún sin número legal.
6	Anulada por nota crédito	Una nota crédito total la dejó en saldo cero.
7	Anulado por nota ajuste	Anulada por un ajuste.

Puedes consultar este catálogo una vez y guardarlo en tu sistema: los estados son fijos.

Código HTTP	`error_code`	Cuándo ocurre
`400`	`VALIDATION_ERROR`	Un parámetro tiene un valor inválido (por ejemplo `page=0`, `target=3` o una fecha mal formada).
`401`	—	Falta el encabezado `Authorization` o el token no es válido.
`403`	`RECURSO_NO_AUTORIZADO`	El token no tiene el permiso `catalogs:read`.
`500`	`INTERNAL_ERROR`	Fallo interno al consultar la base. Reintenta más tarde.

**Un parámetro inválido rechaza la consulta completa** con `400 VALIDATION_ERROR`. Corrige el valor y repite la petición.

cURL

```bash TOKEN="TU_TOKEN_AQUI" INSTANCIA="mi-inmobiliaria.nuby.app" # 1. Primera página de resoluciones activas curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \ "https://${INSTANCIA}/service/v2/public/invoices/sales/resolutions?activa=SI&page=1&page_size=10" \ -H "Authorization: Bearer ${TOKEN}" # 2. Un parámetro inválido devuelve 400 VALIDATION_ERROR curl --silent --show-error --write-out "\nHTTP %{http_code}\n" \ "https://${INSTANCIA}/service/v2/public/invoices/sales/resolutions?page=0" \ -H "Authorization: Bearer ${TOKEN}" ```

PHP

```php 'SI', 'page' => 1, 'page_size' => 10, ]); $url = "https://{$instancia}/service/v2/public/invoices/sales/resolutions?{$query}"; $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Authorization: Bearer {$token}", ]); $respuesta = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $datos = json_decode($respuesta, true); if ($httpCode === 200) { foreach ($datos['body'] as $resolucion) { echo "{$resolucion['prefijo']} {$resolucion['resolucion_numero']} - " . "{$resolucion['consecutivo_inicial']} a {$resolucion['consecutivo_final']}\n"; } echo "Total: {$datos['pagination']['total_records']}\n"; } elseif ($httpCode === 400) { echo "Parámetro inválido ({$datos['error_code']}): {$datos['message']}\n"; } elseif ($httpCode === 403) { echo "Sin permiso catalogs:read ({$datos['error_code']}): {$datos['message']}\n"; } else { echo "Error HTTP {$httpCode}: {$datos['message']}\n"; } ```

Python

```python import requests # 1. Configura tus datos de acceso instancia = "mi-inmobiliaria.nuby.app" # Reemplaza con tu dirección web completa token = "TU_TOKEN_AQUI" # Token obtenido del servicio Login # 2. Envía la petición con los filtros como parámetros url = f"https://{instancia}/service/v2/public/invoices/sales/resolutions" headers = {"Authorization": f"Bearer {token}"} params = {"activa": "SI", "page": 1, "page_size": 10} respuesta = requests.get(url, headers=headers, params=params, timeout=30) # 3. Procesa la respuesta if respuesta.status_code == 200: datos = respuesta.json() for resolucion in datos["body"]: print(resolucion["prefijo"], resolucion["resolucion_numero"]) print(f"Total: {datos['pagination']['total_records']}") elif respuesta.status_code in (400, 403): error = respuesta.json() print(f"Rechazo {error['error_code']}: {error['message']}") else: print(f"Error HTTP {respuesta.status_code}: {respuesta.text}") ```

JavaScript (Fetch API)

```javascript // 1. Configura tus datos de acceso const instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa const token = 'TU_TOKEN_AQUI'; // Token obtenido del servicio Login // 2. Función que consulta el catálogo de resoluciones de venta async function listarResoluciones(filtros = {}) { const params = new URLSearchParams({ activa: 'SI', page: '1', page_size: '10', ...filtros, }); const url = `https://${instancia}/service/v2/public/invoices/sales/resolutions?${params}`; const response = await fetch(url, { headers: { 'Authorization': `Bearer ${token}` }, }); const datos = await response.json().catch(() => ({})); if (!response.ok) { console.error(`Error HTTP ${response.status} ${datos.error_code ?? ''}: ${datos.message ?? ''}`); return []; } console.log(`Total de resoluciones: ${datos.pagination.total_records}`); return datos.body; } // 3. Consume el catálogo listarResoluciones().then((resoluciones) => { resoluciones.forEach((r) => console.log(`${r.prefijo} ${r.resolucion_numero}`)); }); ```

Los otros tres catálogos se consumen igual, con el mismo encabezado `Authorization` y el mismo permiso `catalogs:read`; solo cambia la ruta: `GET https://{{instancia}}/service/v2/public/masters/note-concepts` para los conceptos de nota (con el filtro opcional `target`), `GET https://{{instancia}}/service/v2/public/masters/products` para los productos e impuestos (con `search` y `estado`) y `GET https://{{instancia}}/service/v2/public/masters/invoice-statuses` para los estados de factura (sin parámetros).

- **Consulta los catálogos una vez y guárdalos.** Cambian poco y son de solo lectura. - **Usa `/invoices/sales/resolutions`** para elegir la resolución de una factura de venta; el endpoint anterior puede devolver resoluciones de contrato. - **Toma los impuestos de `/masters/products`** y envíalos en `items[]`; nuby no los adivina. - **Recorre hasta `total_pages`**, no hasta una página vacía. - **No envíes `page_size` mayor a 1000:** el servidor lo recorta.

- Los catálogos solo devuelven datos de **facturas de venta**. - No exponen datos de contacto de terceros ni información contable. - Los estados de factura son fijos; los conceptos y productos dependen de la configuración de tu instancia.

Si necesitas crear una factura, revisa la página [*Crear Factura Borrador*](https://docs.nuby.ai/books/api-nuby-v2/page/crear-factura-borrador).