From 96f4af36b414aeacb8226b8cb254c346b51c543e Mon Sep 17 00:00:00 2001 From: javorosas Date: Wed, 4 Nov 2026 19:58:52 +0100 Subject: [PATCH 1/2] feat(catalogs): document product category navigation --- website/openapi_v2.en.yaml | 111 ++++++++++++++++++++++++++++++++++++- website/openapi_v2.yaml | 111 ++++++++++++++++++++++++++++++++++++- 2 files changed, 220 insertions(+), 2 deletions(-) diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml index 528820477..1bb749e96 100644 --- a/website/openapi_v2.en.yaml +++ b/website/openapi_v2.en.yaml @@ -12444,6 +12444,67 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' + /catalogs/product-categories: + get: + operationId: listProductCategories + tags: [sat_keys] + summary: List product category roots + description: Returns the Products and Services roots. Use a root key to explore its divisions. + security: + - SecretLiveKey: [] + - SecretTestKey: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ProductCategoryList' + '401': + $ref: '#/components/responses/Unauthenticated' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/UnexpectedError' + /catalogs/product-categories/{key}: + get: + operationId: getProductCategory + tags: [sat_keys] + summary: Explore a product category or resolve a product path + description: Explore the SAT product/service category tree. Category keys use 2, 4 or 6 digits. Full 8-digit keys resolve the product and its category path; trailing zeroes are never removed. The special key 01010101 has no category. A class includes a paginated products result. + parameters: + - in: path + name: key + required: true + schema: + type: string + pattern: '^(products|services|[0-9]{2}|[0-9]{4}|[0-9]{6}|[0-9]{8})$' + description: Root, category prefix or complete product/service key. + - $ref: '#/components/parameters/SearchPagination' + - $ref: '#/components/parameters/SearchAfter' + - $ref: '#/components/parameters/SearchBefore' + - $ref: '#/components/parameters/SearchPage' + - $ref: '#/components/parameters/SearchLimit' + security: + - SecretLiveKey: [] + - SecretTestKey: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ProductCategoryDetail' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/UnexpectedError' /catalogs/products: get: operationId: searchProducts @@ -12501,6 +12562,12 @@ paths: "q" => "ukelele" ]); parameters: + - in: query + name: category + schema: + type: string + pattern: '^[0-9]{2}([0-9]{2}){0,2}$' + description: Category prefix of 2, 4 or 6 digits. Includes descendants and can be combined with q. With no q, lists the category products. - $ref: "#/components/parameters/SearchPagination" - $ref: "#/components/parameters/SearchAfter" - $ref: "#/components/parameters/SearchBefore" @@ -12509,7 +12576,7 @@ paths: name: q schema: type: string - description: Text search. Text to search in the product/service classification description. + description: Searches key prefixes, descriptions, similar words and category names, ignoring case and diacritics. - $ref: "#/components/parameters/SearchPage" - $ref: "#/components/parameters/SearchLimit" security: @@ -12532,6 +12599,7 @@ paths: $ref: "#/components/responses/RateLimited" "500": $ref: "#/components/responses/UnexpectedError" + /catalogs/units: get: operationId: searchUnits @@ -13775,6 +13843,47 @@ components: items: $ref: "#/components/schemas/UnitCatalogResult" + ProductCategory: + type: object + required: [key, description, parent] + properties: + key: + type: string + example: '432115' + description: + type: string + example: Computadores + parent: + type: [string, 'null'] + example: '4321' + ProductCategoryList: + type: object + required: [data] + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + ProductCategoryDetail: + type: object + required: [category, ancestors, children] + properties: + category: + anyOf: + - $ref: '#/components/schemas/ProductCategory' + - type: 'null' + ancestors: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + children: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + product: + $ref: '#/components/schemas/CatalogEntry' + products: + $ref: '#/components/schemas/CatalogEntrySearchResult' CatalogEntry: type: object required: diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml index 3f4704f05..c8e42ea8c 100644 --- a/website/openapi_v2.yaml +++ b/website/openapi_v2.yaml @@ -12396,6 +12396,67 @@ paths: $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/UnexpectedError' + /catalogs/product-categories: + get: + operationId: listProductCategories + tags: [sat_keys] + summary: Listar categorías raíz de productos y servicios + description: Devuelve las raíces Productos y Servicios. Consulta una raíz por su clave para explorar sus divisiones. + security: + - SecretLiveKey: [] + - SecretTestKey: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ProductCategoryList' + '401': + $ref: '#/components/responses/Unauthenticated' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/UnexpectedError' + /catalogs/product-categories/{key}: + get: + operationId: getProductCategory + tags: [sat_keys] + summary: Explorar una categoría o consultar la ruta de una clave + description: Explora el árbol de categorías de productos y servicios del SAT. Las categorías usan claves de 2, 4 o 6 dígitos. Una clave completa de 8 dígitos devuelve el producto y su ruta; nunca se eliminan ceros finales. La clave especial 01010101 no tiene categoría. Una clase incluye un resultado paginado de productos. + parameters: + - in: path + name: key + required: true + schema: + type: string + pattern: '^(products|services|[0-9]{2}|[0-9]{4}|[0-9]{6}|[0-9]{8})$' + description: Raíz, prefijo de categoría o clave completa de producto/servicio. + - $ref: '#/components/parameters/SearchPagination' + - $ref: '#/components/parameters/SearchAfter' + - $ref: '#/components/parameters/SearchBefore' + - $ref: '#/components/parameters/SearchPage' + - $ref: '#/components/parameters/SearchLimit' + security: + - SecretLiveKey: [] + - SecretTestKey: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ProductCategoryDetail' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '404': + $ref: '#/components/responses/NotFound' + '429': + $ref: '#/components/responses/RateLimited' + '500': + $ref: '#/components/responses/UnexpectedError' /catalogs/products: get: operationId: searchProducts @@ -12453,6 +12514,12 @@ paths: "q" => "ukelele" ]); parameters: + - in: query + name: category + schema: + type: string + pattern: '^[0-9]{2}([0-9]{2}){0,2}$' + description: Prefijo de categoría de 2, 4 o 6 dígitos. Incluye descendientes y se combina con q. Sin q, lista los productos de la categoría. - $ref: "#/components/parameters/SearchPagination" - $ref: "#/components/parameters/SearchAfter" - $ref: "#/components/parameters/SearchBefore" @@ -12461,7 +12528,7 @@ paths: name: q schema: type: string - description: Consulta. Texto a buscar en la descripción de la clasificación. + description: Busca prefijos de claves, descripciones, palabras similares y nombres de categorías, sin distinguir mayúsculas ni diacríticos. - $ref: "#/components/parameters/SearchPage" - $ref: "#/components/parameters/SearchLimit" security: @@ -12484,6 +12551,7 @@ paths: $ref: "#/components/responses/RateLimited" "500": $ref: "#/components/responses/UnexpectedError" + /catalogs/units: get: operationId: searchUnits @@ -13341,6 +13409,47 @@ components: type: string description: Nombre sugerido del archivo. example: invoice.pdf + ProductCategory: + type: object + required: [key, description, parent] + properties: + key: + type: string + example: '432115' + description: + type: string + example: Computadores + parent: + type: [string, 'null'] + example: '4321' + ProductCategoryList: + type: object + required: [data] + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + ProductCategoryDetail: + type: object + required: [category, ancestors, children] + properties: + category: + anyOf: + - $ref: '#/components/schemas/ProductCategory' + - type: 'null' + ancestors: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + children: + type: array + items: + $ref: '#/components/schemas/ProductCategory' + product: + $ref: '#/components/schemas/CatalogEntry' + products: + $ref: '#/components/schemas/CatalogEntrySearchResult' CatalogEntry: type: object required: From fb9921573b3d7c46a1d7f2c6e350c6861afe4cbf Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 5 Nov 2026 19:31:09 +0100 Subject: [PATCH 2/2] fix(catalogs): clarify product path lookup responses --- website/openapi_v2.en.yaml | 2 +- website/openapi_v2.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml index 1bb749e96..75d26497b 100644 --- a/website/openapi_v2.en.yaml +++ b/website/openapi_v2.en.yaml @@ -12471,7 +12471,7 @@ paths: operationId: getProductCategory tags: [sat_keys] summary: Explore a product category or resolve a product path - description: Explore the SAT product/service category tree. Category keys use 2, 4 or 6 digits. Full 8-digit keys resolve the product and its category path; trailing zeroes are never removed. The special key 01010101 has no category. A class includes a paginated products result. + description: Explore the SAT product/service category tree. Category keys use 2, 4 or 6 digits. Full 8-digit keys resolve the product and its category path; trailing zeroes are never removed. The special key 01010101 has no category. A six-digit class lookup includes a paginated products result. An eight-digit key lookup returns its path without listing other products in the class. parameters: - in: path name: key diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml index c8e42ea8c..89f6f6d79 100644 --- a/website/openapi_v2.yaml +++ b/website/openapi_v2.yaml @@ -12423,7 +12423,7 @@ paths: operationId: getProductCategory tags: [sat_keys] summary: Explorar una categoría o consultar la ruta de una clave - description: Explora el árbol de categorías de productos y servicios del SAT. Las categorías usan claves de 2, 4 o 6 dígitos. Una clave completa de 8 dígitos devuelve el producto y su ruta; nunca se eliminan ceros finales. La clave especial 01010101 no tiene categoría. Una clase incluye un resultado paginado de productos. + description: Explora el árbol de categorías de productos y servicios del SAT. Las categorías usan claves de 2, 4 o 6 dígitos. Una clave completa de 8 dígitos devuelve el producto y su ruta; nunca se eliminan ceros finales. La clave especial 01010101 no tiene categoría. Consultar una clase de 6 dígitos incluye un resultado paginado de productos. Consultar una clave de 8 dígitos devuelve su ruta sin listar otros productos de la clase. parameters: - in: path name: key