Add PostalCodes resource (#421)

* Add PostalCodes resource to exports

* Add tests

* Refactor postal code tests to use parameterized testing and remove obsolete cassette files

* Update cuenca-validations to version 2.1.8.dev7 and bump internal version to 2.1.5.dev1

* Update version to 2.1.5 for stable release

* Update user profession and add verification IDs in tests

* Update cuenca-validations to version 2.1.8 in requirements.txt

Author: gmorales96

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
 pydantic-extra-types==2.10.2

tests/conftest.py

@@ -3,6 +3,7 @@
 
 import pytest
 from cuenca_validations.types import Country, Gender, State
+from cuenca_validations.types.enums import Profession
 
 import cuenca
 
@@ -49,15 +50,15 @@ def user_request() -> dict:
         curp='LOHJ660606HDFPRS02',
         phone_number='+525511223344',
         email_address='jose@test.com',
-        profession='employee',
+        profession=Profession.empleado,
         address=dict(
             street='calle 1',
             ext_number='2',
             int_number='3',
-            postal_code='09900',
-            state=State.DF.value,
-            country=Country.MX,
+            postal_code_id='PC2ygq9j2bS9-9tsuVawzErA',
         ),
+        phone_verification_id='VERdkuqOCjSA2PSS-VCj7HhQ',
+        email_verification_id='VERppwdqsQSAQFFF-CDsWD8s',
     )
     return user_dict
 

tests/resources/cassettes/test_postal_codes_retrieve[00000-0].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=00000
+  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[40100-1].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/cassettes/test_postal_codes_retrieve[40106-2].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/test_postal_codes.py

@@ -0,0 +1,17 @@
+import pytest
+
+from cuenca.resources import PostalCodes
+
+
+@pytest.mark.vcr
+@pytest.mark.parametrize(
+    "postal_code,expected_count",
+    [
+        ("40100", 1),
+        ("40106", 2),
+        ("00000", 0),
+    ],
+)
+def test_postal_codes_retrieve(postal_code: str, expected_count: int) -> None:
+    postal_codes = list(PostalCodes.all(postal_code=postal_code))
+    assert len(postal_codes) == expected_count