diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml index 0514d3d7d..528820477 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,232 @@ 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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. 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, municipality, or state name. + schema: + type: string + minLength: 1 + 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 + - name: state + in: query + description: Three-letter state code (for example ZAC). + schema: + type: string + minLength: 3 + maxLength: 3 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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}$ + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 +13775,73 @@ 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 + - neighborhoods + 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' + neighborhoods: + type: array + description: All neighborhoods for this postal code, even when the query matches another field. + items: + $ref: '#/components/schemas/CatalogEntry' + ZipCodeDetail: + $ref: '#/components/schemas/ZipCode' + 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..3f4704f05 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,233 @@ 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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. 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, municipio o estado. + schema: + type: string + minLength: 1 + 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 + - name: state + in: query + description: Clave de estado de tres letras (por ejemplo ZAC). + schema: + type: string + minLength: 3 + maxLength: 3 + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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}$ + security: + - "SecretLiveKey": [] + - "SecretTestKey": [] + 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 +13341,73 @@ 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 + - neighborhoods + 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' + 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: + $ref: '#/components/schemas/ZipCode' + 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"