diff --git a/mercadopago/resources/__init__.py b/mercadopago/resources/__init__.py index fa0fb18..6075c7a 100644 --- a/mercadopago/resources/__init__.py +++ b/mercadopago/resources/__init__.py @@ -66,6 +66,7 @@ ShipmentFreeMethod, ShipmentRequest, ) +from mercadopago.resources.store import Store from mercadopago.resources.subscription import Subscription from mercadopago.resources.user import User @@ -118,6 +119,7 @@ 'Preference', 'Refund', 'RequestOptions', + 'Store', 'Subscription', 'User', 'order_request_to_dict', diff --git a/mercadopago/resources/store.py b/mercadopago/resources/store.py new file mode 100644 index 0000000..c5a87cc --- /dev/null +++ b/mercadopago/resources/store.py @@ -0,0 +1,129 @@ +"""Store resource for the MercadoPago API. + +Wraps the store endpoints: + +- ``POST /users/{user_id}/stores`` +- ``GET /stores/{id}`` +- ``GET /users/{user_id}/stores/search`` +- ``PUT /users/{user_id}/stores/{id}`` +- ``DELETE /users/{user_id}/stores/{id}`` + +`API reference +`_ +""" +from mercadopago.core import MPBase + + +class Store(MPBase): + """Manages physical stores for in-person (Point) payments. + + Stores group point-of-sale devices under a business location and are + identified by the seller's ``user_id``. + """ + + def create(self, user_id, store_object, request_options=None): + """Creates a new store for the given user. + + Args: + user_id: Identifier of the seller (collector) user. + store_object: Dict describing the store (name, location, etc.). + request_options: Per-call configuration overrides. + + Raises: + ValueError: If *store_object* is not a ``dict``. + + Returns: + dict: Created store including its ``id``. + + Reference: https://www.mercadopago.com/developers/en/reference + """ + if not isinstance(store_object, dict): + raise ValueError("Param store_object must be a Dictionary") + + return self._post( + uri="/users/" + self._path_param(user_id) + "/stores", + data=store_object, + request_options=request_options, + ) + + def get(self, store_id, request_options=None): + """Retrieves a store by its ID. + + Args: + store_id: Unique store identifier. + request_options: Per-call configuration overrides. + + Returns: + dict: Full store object. + + Reference: https://www.mercadopago.com/developers/en/reference + """ + return self._get( + uri="/stores/" + self._path_param(store_id), + request_options=request_options, + ) + + def search(self, user_id, filters=None, request_options=None): + """Searches the stores of a given user. + + Args: + user_id: Identifier of the seller (collector) user. + filters: Query-string parameters (e.g. ``external_id``). + request_options: Per-call configuration overrides. + + Returns: + dict: Paginated list of matching stores. + + Reference: https://www.mercadopago.com/developers/en/reference + """ + return self._get( + uri="/users/" + self._path_param(user_id) + "/stores/search", + filters=filters, + request_options=request_options, + ) + + def update(self, user_id, store_id, store_object, request_options=None): + """Updates an existing store. + + Args: + user_id: Identifier of the seller (collector) user. + store_id: Identifier of the store to update. + store_object: Dict with the fields to modify. + request_options: Per-call configuration overrides. + + Raises: + ValueError: If *store_object* is not a ``dict``. + + Returns: + dict: Updated store object. + + Reference: https://www.mercadopago.com/developers/en/reference + """ + if not isinstance(store_object, dict): + raise ValueError("Param store_object must be a Dictionary") + + return self._put( + uri="/users/" + self._path_param(user_id) + + "/stores/" + self._path_param(store_id), + data=store_object, + request_options=request_options, + ) + + def delete(self, user_id, store_id, request_options=None): + """Deletes a store by its ID. + + Args: + user_id: Identifier of the seller (collector) user. + store_id: Identifier of the store to delete. + request_options: Per-call configuration overrides. + + Returns: + dict: API response for the deletion. + + Reference: https://www.mercadopago.com/developers/en/reference + """ + return self._delete( + uri="/users/" + self._path_param(user_id) + + "/stores/" + self._path_param(store_id), + request_options=request_options, + ) diff --git a/mercadopago/sdk.py b/mercadopago/sdk.py index 1b0b899..517a6a7 100644 --- a/mercadopago/sdk.py +++ b/mercadopago/sdk.py @@ -35,6 +35,7 @@ PreApproval, Preference, Refund, + Store, Subscription, User, ) @@ -189,6 +190,11 @@ def plan(self, request_options=None): return Plan(request_options is not None and request_options or self.request_options, self.http_client) + def store(self, request_options=None): + """Creates a :class:`Store` resource for in-person payment stores.""" + return Store(request_options is not None and request_options + or self.request_options, self.http_client) + @property def request_options(self): """Default :class:`RequestOptions` applied to all resource instances.""" diff --git a/tests/resources/mocks/store_create.json b/tests/resources/mocks/store_create.json new file mode 100644 index 0000000..c372540 --- /dev/null +++ b/tests/resources/mocks/store_create.json @@ -0,0 +1,20 @@ +{ + "id": 1234567, + "name": "Sucursal Instore", + "business_hours": { + "monday": [{"open": "08:00", "close": "18:00"}], + "tuesday": [{"open": "08:00", "close": "18:00"}] + }, + "location": { + "address_line": "Av Caseros 3039", + "reference": "3er piso", + "city": {"id": "TUxBQ0NBUGZlZG1zY3VA", "name": "Belgrano"}, + "latitude": -34.571148, + "longitude": -58.459713, + "zip_code": "1425" + }, + "external_id": "STORE-001", + "user_id": 843382748, + "date_created": "2024-01-15T10:30:00.000-03:00", + "date_last_updated": "2024-01-15T10:30:00.000-03:00" +} diff --git a/tests/resources/mocks/store_delete.json b/tests/resources/mocks/store_delete.json new file mode 100644 index 0000000..c2d377a --- /dev/null +++ b/tests/resources/mocks/store_delete.json @@ -0,0 +1,3 @@ +{ + "id": 1234567 +} diff --git a/tests/resources/mocks/store_get.json b/tests/resources/mocks/store_get.json new file mode 100644 index 0000000..74075f9 --- /dev/null +++ b/tests/resources/mocks/store_get.json @@ -0,0 +1,21 @@ +{ + "id": 1234567, + "name": "Loja Teste", + "business_hours": { + "monday": {"open": "08:00", "close": "18:00"}, + "tuesday": {"open": "08:00", "close": "18:00"} + }, + "external_id": "store-001", + "user_id": 843382748, + "location": { + "address_line": "Av Paulista, 1000", + "city_name": "São Paulo", + "state_name": "SP", + "zip_code": "01313000", + "country_name": "Brasil", + "latitude": -23.5613, + "longitude": -46.6565 + }, + "date_created": "2024-01-15T10:30:00.000-03:00", + "date_last_updated": "2024-01-15T10:30:00.000-03:00" +} diff --git a/tests/resources/mocks/store_search.json b/tests/resources/mocks/store_search.json new file mode 100644 index 0000000..7834f3f --- /dev/null +++ b/tests/resources/mocks/store_search.json @@ -0,0 +1,22 @@ +{ + "results": [ + { + "id": 1234567, + "name": "Loja Teste", + "external_id": "store-001", + "user_id": 843382748, + "business_hours": { + "monday": {"open": "08:00", "close": "18:00"} + }, + "location": { + "address_line": "Av Paulista 1000", + "city_name": "São Paulo", + "state_name": "SP", + "zip_code": "01313000", + "country_name": "Brasil" + }, + "date_created": "2024-01-15T10:30:00.000-03:00" + } + ], + "paging": {"total": 1, "limit": 10, "offset": 0} +} diff --git a/tests/resources/mocks/store_update.json b/tests/resources/mocks/store_update.json new file mode 100644 index 0000000..d4facd3 --- /dev/null +++ b/tests/resources/mocks/store_update.json @@ -0,0 +1,21 @@ +{ + "id": 1234567, + "name": "Loja Teste", + "user_id": 843382748, + "external_id": "store-001", + "location": { + "address_line": "Av Paulista, 1000", + "city_name": "São Paulo", + "state_name": "SP", + "zip_code": "01313000", + "latitude": -23.5613, + "longitude": -46.6565, + "country_name": "Brasil" + }, + "business_hours": { + "monday": {"open": "08:00", "close": "18:00"}, + "tuesday": {"open": "08:00", "close": "18:00"} + }, + "date_created": "2024-01-15T10:30:00.000-03:00", + "date_last_updated": "2024-01-15T11:00:00.000-03:00" +} diff --git a/tests/test_store.py b/tests/test_store.py new file mode 100644 index 0000000..2dfc0d8 --- /dev/null +++ b/tests/test_store.py @@ -0,0 +1,103 @@ +"""Unit tests for the Store resource using a mock HTTP client.""" +import unittest + +from tests.base_client_test import BaseClientTest + + +class TestStore(BaseClientTest): + """Test Module: Store""" + + def test_create(self): + fixture = self.load_fixture("store_create.json") + self.mock_post(fixture, status=201) + store_object = { + "name": "Sucursal Instore", + "external_id": "STORE-001", + "location": { + "address_line": "Av Caseros 3039", + "reference": "3er piso", + "city": {"id": "TUxBQ0NBUGZlZG1zY3VA", "name": "Belgrano"}, + "latitude": -34.571148, + "longitude": -58.459713, + "zip_code": "1425", + }, + } + result = self.sdk.store().create(843382748, store_object) + self.assertEqual(201, result["status"]) + resp = result["response"] + self.assertEqual(1234567, resp["id"]) + self.assertEqual("Sucursal Instore", resp["name"]) + self.assertEqual("STORE-001", resp["external_id"]) + self.assertEqual(843382748, resp["user_id"]) + self.assertIn("location", resp) + self.assertIn("date_created", resp) + self.mock_http.post.assert_called_once() + url = self.mock_http.post.call_args.kwargs["url"] + self.assertEqual("https://api.mercadopago.com/users/843382748/stores", url) + + def test_get(self): + fixture = self.load_fixture("store_get.json") + self.mock_get(fixture) + result = self.sdk.store().get(48091823) + self.assertEqual(200, result["status"]) + resp = result["response"] + self.assertEqual(1234567, resp["id"]) + self.assertEqual("Loja Teste", resp["name"]) + self.assertEqual("store-001", resp["external_id"]) + self.assertIn("location", resp) + self.mock_http.get.assert_called_once() + url = self.mock_http.get.call_args.kwargs["url"] + self.assertEqual("https://api.mercadopago.com/stores/48091823", url) + + def test_search(self): + fixture = self.load_fixture("store_search.json") + self.mock_get(fixture) + result = self.sdk.store().search(843382748, {"external_id": "store-001"}) + self.assertEqual(200, result["status"]) + resp = result["response"] + self.assertIn("results", resp) + self.assertEqual(1234567, resp["results"][0]["id"]) + self.assertEqual("Loja Teste", resp["results"][0]["name"]) + self.mock_http.get.assert_called_once() + url = self.mock_http.get.call_args.kwargs["url"] + self.assertEqual( + "https://api.mercadopago.com/users/843382748/stores/search", url) + + def test_update(self): + fixture = self.load_fixture("store_update.json") + self.mock_put(fixture) + result = self.sdk.store().update( + 843382748, 301, {"name": "Updated Store"}) + self.assertEqual(200, result["status"]) + resp = result["response"] + self.assertEqual(1234567, resp["id"]) + self.assertEqual("Loja Teste", resp["name"]) + self.assertIn("date_last_updated", resp) + self.mock_http.put.assert_called_once() + url = self.mock_http.put.call_args.kwargs["url"] + self.assertEqual( + "https://api.mercadopago.com/users/843382748/stores/301", url) + + def test_delete(self): + fixture = self.load_fixture("store_delete.json") + self.mock_delete(fixture) + result = self.sdk.store().delete(843382748, 3016406555) + self.assertEqual(204, result["status"]) + resp = result["response"] + self.assertEqual(1234567, resp["id"]) + self.mock_http.delete.assert_called_once() + url = self.mock_http.delete.call_args.kwargs["url"] + self.assertEqual( + "https://api.mercadopago.com/users/843382748/stores/3016406555", url) + + def test_create_raises_for_non_dict(self): + with self.assertRaises(ValueError): + self.sdk.store().create(843382748, "not-a-dict") + + def test_update_raises_for_non_dict(self): + with self.assertRaises(ValueError): + self.sdk.store().update(843382748, 301, "not-a-dict") + + +if __name__ == "__main__": + unittest.main()