From 7ece726bfb9fc22f246b66b5a1f659dc11c6ed19 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Mon, 2 Nov 2026 18:07:02 +0100
Subject: [PATCH 1/6] feat(catalogs): document address and fiscal catalog
 endpoints

---
 website/openapi_v2.en.yaml | 291 ++++++++++++++++++++++++++++++++++--
 website/openapi_v2.yaml    | 292 +++++++++++++++++++++++++++++++++++--
 2 files changed, 557 insertions(+), 26 deletions(-)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 0514d3d7d..1b6545f19 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -1046,7 +1046,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1122,7 +1121,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1215,7 +1213,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key`, `airline_name` or `icao_designator`.
         - in: query
           name: page
@@ -1315,7 +1312,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1414,7 +1410,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1514,7 +1509,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key`, `right_of_passage` or `concessionaire`.
         - in: query
           name: page
@@ -1614,7 +1608,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1714,7 +1707,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1814,7 +1806,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -1914,7 +1905,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key`, `description` or `class_division`.
         - in: query
           name: page
@@ -2014,7 +2004,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key`.
         - in: query
           name: page
@@ -2124,7 +2113,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key`, `description` or `iata_designator`.
         - in: query
           name: page
@@ -2224,7 +2212,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefix to match against `key` or `description`.
         - in: query
           name: page
@@ -12231,6 +12218,214 @@ paths:
           $ref: "#/components/responses/RateLimited"
         "500":
           $ref: "#/components/responses/UnexpectedError"
+  /catalogs/countries:
+    get:
+      operationId: searchCountries
+      tags:
+      - sat_keys
+      summary: Search countries
+      description: Search countries by three-letter ISO code or name. Search ignores accents and case.
+      parameters:
+      - name: q
+        in: query
+        description: Code or search text.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/tax-systems:
+    get:
+      operationId: searchTaxSystems
+      tags:
+      - sat_keys
+      summary: Search tax regimes
+      description: Look up tax regimes supported by the API. The receiver must declare their regime; this
+        search does not determine it.
+      parameters:
+      - name: q
+        in: query
+        description: Code or search text.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/invoice-uses:
+    get:
+      operationId: searchInvoiceUses
+      tags:
+      - sat_keys
+      summary: Search CFDI uses
+      description: Look up CFDI-use codes by code or description. The receiver must declare the use.
+      parameters:
+      - name: q
+        in: query
+        description: Code or search text.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/zip-codes:
+    get:
+      operationId: searchZipCodes
+      tags:
+      - sat_keys
+      summary: Search postal codes
+      description: Search Mexican postal codes by full code or numeric prefix, ordered by code. Neighborhoods
+        are available in the detail endpoint. City-name search is not supported.
+      parameters:
+      - name: q
+        in: query
+        description: Full code or numeric prefix.
+        schema:
+          type: string
+          pattern: ^[0-9]{1,5}$
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      - name: state
+        in: query
+        description: Three-letter state code (for example ZAC).
+        schema:
+          type: string
+          minLength: 3
+          maxLength: 3
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipCodeSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/zip-codes/{code}:
+    get:
+      operationId: getZipCode
+      tags:
+      - sat_keys
+      summary: Get postal code
+      description: Return address data and neighborhoods for a Mexican postal code.
+      parameters:
+      - name: code
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^[0-9]{5}$
+      responses:
+        '200':
+          description: Postal code
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipCodeDetail'
+        '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
@@ -13562,6 +13757,76 @@ components:
               items:
                 $ref: "#/components/schemas/UnitCatalogResult"
 
+    CatalogEntry:
+      type: object
+      required:
+      - key
+      - description
+      properties:
+        key:
+          type: string
+        description:
+          type: string
+    CatalogEntrySearchResult:
+      allOf:
+      - $ref: '#/components/schemas/SearchResult'
+      - type: object
+        required:
+        - data
+        properties:
+          data:
+            type: array
+            items:
+              $ref: '#/components/schemas/CatalogEntry'
+    ZipCode:
+      type: object
+      required:
+      - key
+      - country
+      - state
+      - municipality
+      - locality
+      properties:
+        key:
+          type: string
+          pattern: ^[0-9]{5}$
+        country:
+          $ref: '#/components/schemas/CatalogEntry'
+        state:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+        municipality:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+        locality:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+    ZipCodeDetail:
+      allOf:
+      - $ref: '#/components/schemas/ZipCode'
+      - type: object
+        required:
+        - neighborhoods
+        properties:
+          neighborhoods:
+            type: array
+            items:
+              $ref: '#/components/schemas/CatalogEntry'
+    ZipCodeSearchResult:
+      allOf:
+      - $ref: '#/components/schemas/SearchResult'
+      - type: object
+        required:
+        - data
+        properties:
+          data:
+            type: array
+            items:
+              $ref: '#/components/schemas/ZipCode'
+
     SearchKeyDescriptionResult:
       allOf:
         - $ref: "#/components/schemas/SearchResult"
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index a183e5963..f29ea03ff 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -1017,7 +1017,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1093,7 +1092,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1186,7 +1184,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key`, `airline_name` o `icao_designator`.
         - in: query
           name: page
@@ -1285,7 +1282,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1385,7 +1381,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1485,7 +1480,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key`, `right_of_passage` o `concessionaire`.
         - in: query
           name: page
@@ -1585,7 +1579,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1685,7 +1678,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1785,7 +1777,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -1885,7 +1876,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key`, `description` o `class_division`.
         - in: query
           name: page
@@ -1985,7 +1975,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key`.
         - in: query
           name: page
@@ -2095,7 +2084,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key`, `description` o `iata_designator`.
         - in: query
           name: page
@@ -2195,7 +2183,6 @@ paths:
           name: q
           schema:
             type: string
-          required: true
           description: Prefijo para buscar en `key` o `description`.
         - in: query
           name: page
@@ -12182,6 +12169,215 @@ paths:
           $ref: "#/components/responses/RateLimited"
         "500":
           $ref: "#/components/responses/UnexpectedError"
+  /catalogs/countries:
+    get:
+      operationId: searchCountries
+      tags:
+      - sat_keys
+      summary: Buscar países
+      description: Busca países por código ISO de tres letras o nombre. La búsqueda ignora acentos y mayúsculas.
+      parameters:
+      - name: q
+        in: query
+        description: Código o texto a buscar.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Resultados de búsqueda
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/tax-systems:
+    get:
+      operationId: searchTaxSystems
+      tags:
+      - sat_keys
+      summary: Buscar regímenes fiscales
+      description: Consulta los regímenes fiscales admitidos por la API. El receptor debe declarar su régimen;
+        esta búsqueda no lo determina.
+      parameters:
+      - name: q
+        in: query
+        description: Código o texto a buscar.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Resultados de búsqueda
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/invoice-uses:
+    get:
+      operationId: searchInvoiceUses
+      tags:
+      - sat_keys
+      summary: Buscar usos CFDI
+      description: Consulta claves de uso CFDI por código o descripción. El uso debe ser declarado por el
+        receptor.
+      parameters:
+      - name: q
+        in: query
+        description: Código o texto a buscar.
+        schema:
+          type: string
+          maxLength: 100
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      responses:
+        '200':
+          description: Resultados de búsqueda
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CatalogEntrySearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/zip-codes:
+    get:
+      operationId: searchZipCodes
+      tags:
+      - sat_keys
+      summary: Buscar códigos postales
+      description: Busca códigos postales mexicanos por código completo o prefijo numérico, ordenados por
+        código. Las colonias se consultan en el detalle. No admite búsqueda por nombre de ciudad.
+      parameters:
+      - name: q
+        in: query
+        description: Código o prefijo numérico.
+        schema:
+          type: string
+          pattern: ^[0-9]{1,5}$
+      - name: page
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          default: 1
+      - name: limit
+        in: query
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+      - name: state
+        in: query
+        description: Clave de estado de tres letras (por ejemplo ZAC).
+        schema:
+          type: string
+          minLength: 3
+          maxLength: 3
+      responses:
+        '200':
+          description: Resultados de búsqueda
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipCodeSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '429':
+          $ref: '#/components/responses/RateLimited'
+        '500':
+          $ref: '#/components/responses/UnexpectedError'
+  /catalogs/zip-codes/{code}:
+    get:
+      operationId: getZipCode
+      tags:
+      - sat_keys
+      summary: Consultar código postal
+      description: Devuelve los datos de domicilio y las colonias de un código postal mexicano.
+      parameters:
+      - name: code
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^[0-9]{5}$
+      responses:
+        '200':
+          description: Código postal
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ZipCodeDetail'
+        '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
@@ -13127,6 +13323,76 @@ components:
           type: string
           description: Nombre sugerido del archivo.
           example: invoice.pdf
+    CatalogEntry:
+      type: object
+      required:
+      - key
+      - description
+      properties:
+        key:
+          type: string
+        description:
+          type: string
+    CatalogEntrySearchResult:
+      allOf:
+      - $ref: '#/components/schemas/SearchResult'
+      - type: object
+        required:
+        - data
+        properties:
+          data:
+            type: array
+            items:
+              $ref: '#/components/schemas/CatalogEntry'
+    ZipCode:
+      type: object
+      required:
+      - key
+      - country
+      - state
+      - municipality
+      - locality
+      properties:
+        key:
+          type: string
+          pattern: ^[0-9]{5}$
+        country:
+          $ref: '#/components/schemas/CatalogEntry'
+        state:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+        municipality:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+        locality:
+          anyOf:
+          - $ref: '#/components/schemas/CatalogEntry'
+          - type: 'null'
+    ZipCodeDetail:
+      allOf:
+      - $ref: '#/components/schemas/ZipCode'
+      - type: object
+        required:
+        - neighborhoods
+        properties:
+          neighborhoods:
+            type: array
+            items:
+              $ref: '#/components/schemas/CatalogEntry'
+    ZipCodeSearchResult:
+      allOf:
+      - $ref: '#/components/schemas/SearchResult'
+      - type: object
+        required:
+        - data
+        properties:
+          data:
+            type: array
+            items:
+              $ref: '#/components/schemas/ZipCode'
+
     SearchKeyDescriptionResult:
       allOf:
         - $ref: "#/components/schemas/SearchResult"

From 76a4b3bde05acc4123c5cdb8893ec1a67ff4ac0d Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Mon, 2 Nov 2026 22:14:22 +0100
Subject: [PATCH 2/6] feat(catalogs): document postal cursor pagination

---
 website/openapi_v2.en.yaml | 3 +++
 website/openapi_v2.yaml    | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 1b6545f19..42e304cc0 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -12354,6 +12354,9 @@ paths:
       description: Search Mexican postal codes by full code or numeric prefix, ordered by code. Neighborhoods
         are available in the detail endpoint. City-name search is not supported.
       parameters:
+      - $ref: '#/components/parameters/SearchPagination'
+      - $ref: '#/components/parameters/SearchAfter'
+      - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
         description: Full code or numeric prefix.
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index f29ea03ff..952b9b207 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -12306,6 +12306,9 @@ paths:
       description: Busca códigos postales mexicanos por código completo o prefijo numérico, ordenados por
         código. Las colonias se consultan en el detalle. No admite búsqueda por nombre de ciudad.
       parameters:
+      - $ref: '#/components/parameters/SearchPagination'
+      - $ref: '#/components/parameters/SearchAfter'
+      - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
         description: Código o prefijo numérico.

From 619421d062e4384c18412c164b6f5b3220e34483 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Wed, 4 Nov 2026 12:27:45 +0100
Subject: [PATCH 3/6] fix(catalogs): declare authentication for new operations

---
 website/openapi_v2.en.yaml | 15 +++++++++++++++
 website/openapi_v2.yaml    | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 42e304cc0..90dd1642d 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -12245,6 +12245,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Search results
@@ -12288,6 +12291,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Search results
@@ -12330,6 +12336,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Search results
@@ -12383,6 +12392,9 @@ paths:
           type: string
           minLength: 3
           maxLength: 3
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Search results
@@ -12412,6 +12424,9 @@ paths:
         schema:
           type: string
           pattern: ^[0-9]{5}$
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Postal code
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index 952b9b207..7cf9822f1 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -12196,6 +12196,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Resultados de búsqueda
@@ -12239,6 +12242,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Resultados de búsqueda
@@ -12282,6 +12288,9 @@ paths:
           minimum: 1
           maximum: 100
           default: 20
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Resultados de búsqueda
@@ -12335,6 +12344,9 @@ paths:
           type: string
           minLength: 3
           maxLength: 3
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Resultados de búsqueda
@@ -12364,6 +12376,9 @@ paths:
         schema:
           type: string
           pattern: ^[0-9]{5}$
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
       responses:
         '200':
           description: Código postal

From 7760d3ea2c91ac1bc3c658c0f8ef65548dfd9efb Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Wed, 4 Nov 2026 14:55:11 +0100
Subject: [PATCH 4/6] feat(catalogs): document unified postal address search

---
 website/openapi_v2.en.yaml | 8 ++++----
 website/openapi_v2.yaml    | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 90dd1642d..476433dcc 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -12360,18 +12360,18 @@ paths:
       tags:
       - sat_keys
       summary: Search postal codes
-      description: Search Mexican postal codes by full code or numeric prefix, ordered by code. Neighborhoods
-        are available in the detail endpoint. City-name search is not supported.
+      description: Search Mexican postal codes. A query of 1 to 5 digits searches by code or numeric prefix; text searches neighborhood, locality/city, or municipality names, ignoring case and diacritics. Exact name matches precede partial matches. Each postal code appears once. The state filter applies to both modes. Without a query, list postal codes. Supports pages and cursors; textual search totals may be capped, indicated by totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
       - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
-        description: Full code or numeric prefix.
+        description: Full code or numeric prefix of 1 to 5 digits, or a neighborhood, locality/city, or municipality name.
         schema:
           type: string
-          pattern: ^[0-9]{1,5}$
+          minLength: 1
+          maxLength: 100
       - name: page
         in: query
         schema:
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index 7cf9822f1..50f2a1e21 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -12312,18 +12312,18 @@ paths:
       tags:
       - sat_keys
       summary: Buscar códigos postales
-      description: Busca códigos postales mexicanos por código completo o prefijo numérico, ordenados por
-        código. Las colonias se consultan en el detalle. No admite búsqueda por nombre de ciudad.
+      description: Busca códigos postales mexicanos. Una consulta de 1 a 5 dígitos busca por código o prefijo; el texto busca nombres de colonia, localidad/ciudad o municipio, sin distinguir mayúsculas ni diacríticos. Las coincidencias exactas de nombre preceden a las parciales. Cada código postal aparece una sola vez. El filtro de estado se aplica en ambos casos. Sin consulta, lista códigos postales. Admite páginas y cursores; los totales de búsquedas textuales pueden estar limitados, indicado por totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
       - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
-        description: Código o prefijo numérico.
+        description: Código o prefijo de 1 a 5 dígitos, o nombre de colonia, localidad/ciudad o municipio.
         schema:
           type: string
-          pattern: ^[0-9]{1,5}$
+          minLength: 1
+          maxLength: 100
       - name: page
         in: query
         schema:

From 43c696fbe20f568368bc023b6bc5be5b3ec47b92 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Wed, 4 Nov 2026 15:20:08 +0100
Subject: [PATCH 5/6] feat(catalogs): include neighborhoods in postal search
 results

---
 website/openapi_v2.en.yaml | 19 ++++++++-----------
 website/openapi_v2.yaml    | 19 ++++++++-----------
 2 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 476433dcc..41457b172 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -12360,7 +12360,7 @@ paths:
       tags:
       - sat_keys
       summary: Search postal codes
-      description: Search Mexican postal codes. A query of 1 to 5 digits searches by code or numeric prefix; text searches neighborhood, locality/city, or municipality names, ignoring case and diacritics. Exact name matches precede partial matches. Each postal code appears once. The state filter applies to both modes. Without a query, list postal codes. Supports pages and cursors; textual search totals may be capped, indicated by totals_are_capped.
+      description: Search Mexican postal codes. A query of 1 to 5 digits searches by code or numeric prefix; text searches neighborhood, locality/city, or municipality names, ignoring case and diacritics. Exact name matches precede partial matches. Each postal code appears once and includes all its neighborhoods. The state filter applies to both modes. Without a query, list postal codes. Supports pages and cursors; textual search totals may be capped, indicated by totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
@@ -13804,6 +13804,7 @@ components:
       - state
       - municipality
       - locality
+      - neighborhoods
       properties:
         key:
           type: string
@@ -13822,17 +13823,13 @@ components:
           anyOf:
           - $ref: '#/components/schemas/CatalogEntry'
           - type: 'null'
+        neighborhoods:
+          type: array
+          description: All neighborhoods for this postal code, even when the query matches another field.
+          items:
+            $ref: '#/components/schemas/CatalogEntry'
     ZipCodeDetail:
-      allOf:
-      - $ref: '#/components/schemas/ZipCode'
-      - type: object
-        required:
-        - neighborhoods
-        properties:
-          neighborhoods:
-            type: array
-            items:
-              $ref: '#/components/schemas/CatalogEntry'
+      $ref: '#/components/schemas/ZipCode'
     ZipCodeSearchResult:
       allOf:
       - $ref: '#/components/schemas/SearchResult'
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index 50f2a1e21..3daa2270e 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -12312,7 +12312,7 @@ paths:
       tags:
       - sat_keys
       summary: Buscar códigos postales
-      description: Busca códigos postales mexicanos. Una consulta de 1 a 5 dígitos busca por código o prefijo; el texto busca nombres de colonia, localidad/ciudad o municipio, sin distinguir mayúsculas ni diacríticos. Las coincidencias exactas de nombre preceden a las parciales. Cada código postal aparece una sola vez. El filtro de estado se aplica en ambos casos. Sin consulta, lista códigos postales. Admite páginas y cursores; los totales de búsquedas textuales pueden estar limitados, indicado por totals_are_capped.
+      description: Busca códigos postales mexicanos. Una consulta de 1 a 5 dígitos busca por código o prefijo; el texto busca nombres de colonia, localidad/ciudad o municipio, sin distinguir mayúsculas ni diacríticos. Las coincidencias exactas de nombre preceden a las parciales. Cada código postal aparece una sola vez e incluye todas sus colonias en neighborhoods. El filtro de estado se aplica en ambos casos. Sin consulta, lista códigos postales. Admite páginas y cursores; los totales de búsquedas textuales pueden estar limitados, indicado por totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
@@ -13370,6 +13370,7 @@ components:
       - state
       - municipality
       - locality
+      - neighborhoods
       properties:
         key:
           type: string
@@ -13388,17 +13389,13 @@ components:
           anyOf:
           - $ref: '#/components/schemas/CatalogEntry'
           - type: 'null'
+        neighborhoods:
+          type: array
+          description: Todas las colonias del código postal, aunque la búsqueda coincida por otro campo.
+          items:
+            $ref: '#/components/schemas/CatalogEntry'
     ZipCodeDetail:
-      allOf:
-      - $ref: '#/components/schemas/ZipCode'
-      - type: object
-        required:
-        - neighborhoods
-        properties:
-          neighborhoods:
-            type: array
-            items:
-              $ref: '#/components/schemas/CatalogEntry'
+      $ref: '#/components/schemas/ZipCode'
     ZipCodeSearchResult:
       allOf:
       - $ref: '#/components/schemas/SearchResult'

From 9e0fdd689647a1d60f8d9181038225dd04c12732 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Wed, 4 Nov 2026 15:32:32 +0100
Subject: [PATCH 6/6] feat(catalogs): document postal search by state name

---
 website/openapi_v2.en.yaml | 4 ++--
 website/openapi_v2.yaml    | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
index 41457b172..528820477 100644
--- a/website/openapi_v2.en.yaml
+++ b/website/openapi_v2.en.yaml
@@ -12360,14 +12360,14 @@ paths:
       tags:
       - sat_keys
       summary: Search postal codes
-      description: Search Mexican postal codes. A query of 1 to 5 digits searches by code or numeric prefix; text searches neighborhood, locality/city, or municipality names, ignoring case and diacritics. Exact name matches precede partial matches. Each postal code appears once and includes all its neighborhoods. The state filter applies to both modes. Without a query, list postal codes. Supports pages and cursors; textual search totals may be capped, indicated by totals_are_capped.
+      description: Search Mexican postal codes. A query of 1 to 5 digits searches by code or numeric prefix; text searches neighborhood, locality/city, municipality, or state names, ignoring case and diacritics. Exact name matches precede partial matches. Each postal code appears once and includes all its neighborhoods. The state filter applies to both modes. Without a query, list postal codes. Supports pages and cursors; textual search totals may be capped, indicated by totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
       - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
-        description: Full code or numeric prefix of 1 to 5 digits, or a neighborhood, locality/city, or municipality name.
+        description: Full code or numeric prefix of 1 to 5 digits, or a neighborhood, locality/city, municipality, or state name.
         schema:
           type: string
           minLength: 1
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
index 3daa2270e..3f4704f05 100644
--- a/website/openapi_v2.yaml
+++ b/website/openapi_v2.yaml
@@ -12312,14 +12312,14 @@ paths:
       tags:
       - sat_keys
       summary: Buscar códigos postales
-      description: Busca códigos postales mexicanos. Una consulta de 1 a 5 dígitos busca por código o prefijo; el texto busca nombres de colonia, localidad/ciudad o municipio, sin distinguir mayúsculas ni diacríticos. Las coincidencias exactas de nombre preceden a las parciales. Cada código postal aparece una sola vez e incluye todas sus colonias en neighborhoods. El filtro de estado se aplica en ambos casos. Sin consulta, lista códigos postales. Admite páginas y cursores; los totales de búsquedas textuales pueden estar limitados, indicado por totals_are_capped.
+      description: Busca códigos postales mexicanos. Una consulta de 1 a 5 dígitos busca por código o prefijo; el texto busca nombres de colonia, localidad/ciudad, municipio o estado, sin distinguir mayúsculas ni diacríticos. Las coincidencias exactas de nombre preceden a las parciales. Cada código postal aparece una sola vez e incluye todas sus colonias en neighborhoods. El filtro de estado se aplica en ambos casos. Sin consulta, lista códigos postales. Admite páginas y cursores; los totales de búsquedas textuales pueden estar limitados, indicado por totals_are_capped.
       parameters:
       - $ref: '#/components/parameters/SearchPagination'
       - $ref: '#/components/parameters/SearchAfter'
       - $ref: '#/components/parameters/SearchBefore'
       - name: q
         in: query
-        description: Código o prefijo de 1 a 5 dígitos, o nombre de colonia, localidad/ciudad o municipio.
+        description: Código o prefijo de 1 a 5 dígitos, o nombre de colonia, localidad/ciudad, municipio o estado.
         schema:
           type: string
           minLength: 1