Add PostalCodes resource

cuenca/__init__.py

@@ -44,6 +44,7 @@
     'JwtToken',
     'TermsOfService',
     'UserTOSAgreement',
+    'PostalCodes',
 ]
 
 from . import http
@@ -73,6 +74,7 @@
     LoginToken,
     Otp,
     Platform,
+    PostalCodes,
     Questionnaires,
     Saving,
     ServiceProvider,

cuenca/resources/__init__.py

@@ -40,6 +40,7 @@
     'JwtToken',
     'TermsOfService',
     'UserTOSAgreement',
+    'PostalCodes',
 ]
 
 from .accounts import Account
@@ -67,6 +68,7 @@
 from .login_tokens import LoginToken
 from .otps import Otp
 from .platforms import Platform
+from .postal_codes import PostalCodes
 from .questionnaires import Questionnaires
 from .resources import RESOURCES
 from .savings import Saving
@@ -126,6 +128,7 @@
     WhatsappTransfer,
     Webhook,
     Platform,
+    PostalCodes,
     JwtToken,
     TermsOfService,
     UserTOSAgreement,

cuenca/resources/postal_codes.py

@@ -0,0 +1,21 @@
+import datetime as dt
+from typing import ClassVar
+
+from cuenca_validations.types import Country, PostalCodeQuery, State
+
+from .base import Queryable, Retrievable
+
+
+class PostalCodes(Retrievable, Queryable):
+    _resource: ClassVar = 'postal_codes'
+    _query_params: ClassVar = PostalCodeQuery
+
+    id: str
+    created_at: dt.datetime
+    postal_code: str
+    colonia: str
+    city: str
+    state: State
+    state_name: str
+    country: Country
+    country_name: str

cuenca/version.py

@@ -1,3 +1,3 @@
-__version__ = '2.1.4'
+__version__ = '2.1.5'
 CLIENT_VERSION = __version__
 API_VERSION = '2020-03-19'

requirements.txt

@@ -1,3 +1,3 @@
 requests==2.32.3
-cuenca-validations==2.1.5
+cuenca-validations==2.1.8.dev2
 pydantic-extra-types==2.10.2

tests/resources/cassettes/test_postal_codes_retrieve_multiple_colony.yaml

@@ -0,0 +1,42 @@
+interactions:
+- request:
+    body: null
+    headers:
+      User-Agent:
+      - cuenca-python/2.1.5
+      X-Cuenca-Api-Version:
+      - '2020-03-19'
+    method: GET
+    uri: https://sandbox.cuenca.com/postal_codes?postal_code=40106
+  response:
+    body:
+      string: "{\"items\":[{\"id\":\"PCqpCtquNnTTWj4afusCWbXQ\",\"created_at\":\"2025-06-25T18:44:14.409000\",\"postal_code\":\"40106\",\"colonia\":\"El
+        Naranjo\",\"city\":\"Iguala de la Independencia\",\"state\":\"GR\",\"state_name\":\"Guerrero\",\"country\":\"MX\",\"country_name\":\"M\xE9xico\"},{\"id\":\"PCN2-h_t4ASn-yr46-5C352g\",\"created_at\":\"2025-06-25T18:44:14.409000\",\"postal_code\":\"40106\",\"colonia\":\"Ficus\",\"city\":\"Iguala
+        de la Independencia\",\"state\":\"GR\",\"state_name\":\"Guerrero\",\"country\":\"MX\",\"country_name\":\"M\xE9xico\"}],\"next_page_uri\":null}"
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '495'
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 03 Jul 2025 18:44:22 GMT
+      X-Request-Time:
+      - 'value: 0.045'
+      x-amz-apigw-id:
+      - NJVdFHJXCYcEPzw=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '495'
+      x-amzn-Remapped-Date:
+      - Thu, 03 Jul 2025 18:44:22 GMT
+      x-amzn-Remapped-Server:
+      - nginx/1.28.0
+      x-amzn-RequestId:
+      - 3ff50d45-d63b-4244-9bba-9f7dc776d4bb
+    status:
+      code: 200
+      message: OK
+version: 1

tests/resources/cassettes/test_postal_codes_retrieve_not_found.yaml

@@ -0,0 +1,40 @@
+interactions:
+- request:
+    body: null
+    headers:
+      User-Agent:
+      - cuenca-python/2.1.5
+      X-Cuenca-Api-Version:
+      - '2020-03-19'
+    method: GET
+    uri: https://sandbox.cuenca.com/postal_codes?postal_code=401000
+  response:
+    body:
+      string: '{"items":[],"next_page_uri":null}'
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '33'
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 03 Jul 2025 18:44:22 GMT
+      X-Request-Time:
+      - 'value: 0.044'
+      x-amz-apigw-id:
+      - NJVdIFzWCYcEQnA=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '33'
+      x-amzn-Remapped-Date:
+      - Thu, 03 Jul 2025 18:44:22 GMT
+      x-amzn-Remapped-Server:
+      - nginx/1.28.0
+      x-amzn-RequestId:
+      - 00d3f3a3-2fb5-4b74-8fbf-8ac6dc615ae7
+    status:
+      code: 200
+      message: OK
+version: 1

tests/resources/cassettes/test_postal_codes_retrieve_one_colony.yaml

@@ -0,0 +1,41 @@
+interactions:
+- request:
+    body: null
+    headers:
+      User-Agent:
+      - cuenca-python/2.1.5
+      X-Cuenca-Api-Version:
+      - '2020-03-19'
+    method: GET
+    uri: https://sandbox.cuenca.com/postal_codes?postal_code=40100
+  response:
+    body:
+      string: "{\"items\":[{\"id\":\"PCHOECy9u6QQeXPR6HdR5Bgw\",\"created_at\":\"2025-06-25T18:44:14.409000\",\"postal_code\":\"40100\",\"colonia\":\"Metlapa\",\"city\":\"Iguala
+        de la Independencia\",\"state\":\"GR\",\"state_name\":\"Guerrero\",\"country\":\"MX\",\"country_name\":\"M\xE9xico\"}],\"next_page_uri\":null}"
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '263'
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 03 Jul 2025 18:42:12 GMT
+      X-Request-Time:
+      - 'value: 0.046'
+      x-amz-apigw-id:
+      - NJVIwHRyCYcEeIw=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '263'
+      x-amzn-Remapped-Date:
+      - Thu, 03 Jul 2025 18:42:12 GMT
+      x-amzn-Remapped-Server:
+      - nginx/1.28.0
+      x-amzn-RequestId:
+      - 75a527b3-8a33-42ed-8633-23dd2b1ddeff
+    status:
+      code: 200
+      message: OK
+version: 1

tests/resources/test_postal_codes.py

@@ -0,0 +1,21 @@
+import pytest
+
+from cuenca.resources import PostalCodes
+
+
+@pytest.mark.vcr
+def test_postal_codes_retrieve_one_colony() -> None:
+    postal_codes = list(PostalCodes.all(postal_code='40100'))
+    assert len(postal_codes) == 1
+
+
+@pytest.mark.vcr
+def test_postal_codes_retrieve_multiple_colony() -> None:
+    postal_codes = list(PostalCodes.all(postal_code='40106'))
+    assert len(postal_codes) > 1
+
+
+@pytest.mark.vcr
+def test_postal_codes_retrieve_not_found() -> None:
+    postal_codes = list(PostalCodes.all(postal_code='401000'))
+    assert len(postal_codes) == 0