meli-python-sdk 1.0.0a1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- meli_python_sdk-1.0.0a1/LICENSE +21 -0
- meli_python_sdk-1.0.0a1/PKG-INFO +449 -0
- meli_python_sdk-1.0.0a1/README.md +418 -0
- meli_python_sdk-1.0.0a1/pyproject.toml +57 -0
- meli_python_sdk-1.0.0a1/setup.cfg +4 -0
- meli_python_sdk-1.0.0a1/src/meli_python_sdk.egg-info/PKG-INFO +449 -0
- meli_python_sdk-1.0.0a1/src/meli_python_sdk.egg-info/SOURCES.txt +37 -0
- meli_python_sdk-1.0.0a1/src/meli_python_sdk.egg-info/dependency_links.txt +1 -0
- meli_python_sdk-1.0.0a1/src/meli_python_sdk.egg-info/requires.txt +9 -0
- meli_python_sdk-1.0.0a1/src/meli_python_sdk.egg-info/top_level.txt +1 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/__init__.py +43 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/_version.py +1 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/actions.py +85 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/bills.py +123 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/client.py +523 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/exceptions.py +34 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/items.py +257 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/metrics.py +77 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/orders.py +222 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/py.typed +0 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/session.py +92 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/shipments.py +26 -0
- meli_python_sdk-1.0.0a1/src/meli_sdk/storage.py +119 -0
- meli_python_sdk-1.0.0a1/tests/test_bills.py +218 -0
- meli_python_sdk-1.0.0a1/tests/test_client.py +176 -0
- meli_python_sdk-1.0.0a1/tests/test_items.py +390 -0
- meli_python_sdk-1.0.0a1/tests/test_legacy.py +109 -0
- meli_python_sdk-1.0.0a1/tests/test_legacy_shim.py +72 -0
- meli_python_sdk-1.0.0a1/tests/test_oauth.py +222 -0
- meli_python_sdk-1.0.0a1/tests/test_orders.py +325 -0
- meli_python_sdk-1.0.0a1/tests/test_package.py +76 -0
- meli_python_sdk-1.0.0a1/tests/test_refresh_lock.py +251 -0
- meli_python_sdk-1.0.0a1/tests/test_retries.py +369 -0
- meli_python_sdk-1.0.0a1/tests/test_session.py +153 -0
- meli_python_sdk-1.0.0a1/tests/test_storage.py +58 -0
- meli_python_sdk-1.0.0a1/tests/test_token.py +147 -0
- meli_python_sdk-1.0.0a1/tests/test_transport.py +133 -0
- meli_python_sdk-1.0.0a1/tests/test_unauthorized_retry.py +144 -0
- meli_python_sdk-1.0.0a1/tests/test_user_agent.py +100 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Camilo Andrés Rodríguez
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,449 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: meli-python-sdk
|
|
3
|
+
Version: 1.0.0a1
|
|
4
|
+
Summary: Unofficial Python SDK for the Mercado Libre API
|
|
5
|
+
Author-email: Camilo Andrés Rodríguez Higuera <hola@camilordz.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/camilordz1/meli-sdk
|
|
8
|
+
Project-URL: Source, https://github.com/camilordz1/meli-sdk
|
|
9
|
+
Project-URL: Issues, https://github.com/camilordz1/meli-sdk/issues
|
|
10
|
+
Keywords: python,mercado libre,mercadolibre,api client,sdk
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: requests>=2.31
|
|
23
|
+
Requires-Dist: python-dotenv>=1.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
26
|
+
Requires-Dist: responses>=0.25; extra == "dev"
|
|
27
|
+
Requires-Dist: freezegun>=1.4; extra == "dev"
|
|
28
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# Meli SDK
|
|
33
|
+
|
|
34
|
+
[](https://github.com/camilordz1/meli-sdk/actions/workflows/ci.yml)
|
|
35
|
+
|
|
36
|
+
`meli-sdk` es un cliente moderno y robusto para interactuar con la API de Mercado Libre en Python. Diseñado con una arquitectura modular basada en composición, soporta el manejo de múltiples sesiones concurrentes, renovación automática de tokens, y almacenamiento flexible de credenciales (archivos locales, memoria o bases de datos), conservando la interfaz clásica para los desarrollos existentes.
|
|
37
|
+
|
|
38
|
+
> **Nota:** el paquete se llamaba anteriormente `MeliAPIClient`. El nombre de importación actual es `meli_sdk` y la distribución se publica en PyPI como `meli-python-sdk` (el nombre `meli-sdk` no está disponible en PyPI).
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Características Clave
|
|
43
|
+
|
|
44
|
+
* **Doble Interfaz**: Interfaz clásica (Legacy) para compatibilidad con código existente, e interfaz moderna (Composición) para nuevos desarrollos.
|
|
45
|
+
* **Gestión Eficiente de Tokens**: Renovación automática y transparente de tokens expirados antes de cada petición HTTP.
|
|
46
|
+
* **Almacenamiento Personalizado (`TokenStorage`)**: Guarda tus tokens en archivos JSON locales, en memoria, o directamente en tu base de datos (PostgreSQL, SQLite, MySQL, Redis, etc.) mediante funciones callback.
|
|
47
|
+
* **Multi-cuenta / Multisesión**: Capacidad de gestionar múltiples cuentas de Mercado Libre en paralelo sin colisiones.
|
|
48
|
+
* **Recursos Completos**: Gestión de órdenes, facturas, envíos, publicaciones (stock/precios), reputación, tendencias y opiniones de productos.
|
|
49
|
+
* **Excepciones Específicas**: Manejo preciso de errores de red y respuestas del API de Mercado Libre.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Instalación
|
|
54
|
+
|
|
55
|
+
Instala el módulo directamente desde el entorno local de tu proyecto:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install --pre meli-python-sdk
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Uso Básico (Interfaz Clásica)
|
|
64
|
+
|
|
65
|
+
Si ya tienes un script que utiliza el formato tradicional de tres archivos JSON (`ml_keys.json`, `ml_token.json`, `ml_user.json`), puedes continuar usándolo exactamente igual. El módulo renovará automáticamente el token de acceso usando el motor moderno de fondo.
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
from meli_sdk import Session, Order, Bill, Ship
|
|
69
|
+
|
|
70
|
+
def run():
|
|
71
|
+
# Inicialización tradicional
|
|
72
|
+
session = Session("ml_keys.json", "ml_token.json", "ml_user.json")
|
|
73
|
+
|
|
74
|
+
# Instanciación clásica de recursos
|
|
75
|
+
orders_api = Order(session)
|
|
76
|
+
bills_api = Bill(session)
|
|
77
|
+
ship_api = Ship(session)
|
|
78
|
+
|
|
79
|
+
# Listado de órdenes del vendedor
|
|
80
|
+
mis_ordenes = orders_api.list(year=2026, month=6)
|
|
81
|
+
print("Órdenes:", mis_ordenes)
|
|
82
|
+
|
|
83
|
+
# Detalle de envío
|
|
84
|
+
info_envio = ship_api.info("4028374928")
|
|
85
|
+
print("Envío:", info_envio)
|
|
86
|
+
|
|
87
|
+
if __name__ == "__main__":
|
|
88
|
+
run()
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Uso Avanzado (Interfaz Moderna)
|
|
94
|
+
|
|
95
|
+
El diseño moderno utiliza la composición a través de un único cliente centralizado (`MeliClient`) y propiedades perezosas para acceder a los recursos.
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from meli_sdk import MeliClient, FileTokenStorage
|
|
99
|
+
|
|
100
|
+
# 1. Definir dónde almacenar el token de esta sesión específica
|
|
101
|
+
storage = FileTokenStorage("tokens/cuenta_1.json")
|
|
102
|
+
|
|
103
|
+
# 2. Inicializar el cliente
|
|
104
|
+
client = MeliClient(
|
|
105
|
+
client_id="TU_CLIENT_ID",
|
|
106
|
+
client_secret="TU_CLIENT_SECRET",
|
|
107
|
+
token_storage=storage
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
# 3. Consultar recursos usando nomenclatura estándar y tipado estático
|
|
111
|
+
# Ejemplo: Obtener información detallada de una publicación
|
|
112
|
+
producto = client.items.get("MCO123456789")
|
|
113
|
+
print(f"Producto: {producto['title']} | Precio: {producto['price']}")
|
|
114
|
+
|
|
115
|
+
# Actualizar stock de un producto
|
|
116
|
+
client.items.update_stock("MCO123456789", nuevo_stock=15)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Sesión persistente y timeout
|
|
120
|
+
|
|
121
|
+
Cada `MeliClient` usa una `requests.Session` propia y aplica un timeout de 30 segundos a todas las
|
|
122
|
+
peticiones y a la renovación del token. Puedes cambiar el timeout, compartir una sesión entre
|
|
123
|
+
clientes o cerrarla automáticamente con un context manager:
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import requests
|
|
127
|
+
from meli_sdk import FileTokenStorage, MeliClient
|
|
128
|
+
|
|
129
|
+
storage = FileTokenStorage("tokens/cuenta_1.json")
|
|
130
|
+
|
|
131
|
+
# Timeout propio: 5 s para conectar y 20 s para leer
|
|
132
|
+
client = MeliClient(
|
|
133
|
+
client_id="TU_CLIENT_ID",
|
|
134
|
+
client_secret="TU_CLIENT_SECRET",
|
|
135
|
+
token_storage=storage,
|
|
136
|
+
timeout=(5, 20),
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
# Compartir una sesión (el cliente no la cierra)
|
|
140
|
+
shared = requests.Session()
|
|
141
|
+
client = MeliClient(
|
|
142
|
+
client_id="TU_CLIENT_ID",
|
|
143
|
+
client_secret="TU_CLIENT_SECRET",
|
|
144
|
+
token_storage=storage,
|
|
145
|
+
session=shared,
|
|
146
|
+
)
|
|
147
|
+
|
|
148
|
+
# Cerrar la sesión al terminar
|
|
149
|
+
with MeliClient(
|
|
150
|
+
client_id="TU_CLIENT_ID",
|
|
151
|
+
client_secret="TU_CLIENT_SECRET",
|
|
152
|
+
token_storage=storage,
|
|
153
|
+
timeout=10,
|
|
154
|
+
) as client:
|
|
155
|
+
client.items.get("MCO123456789")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
El timeout también se puede sobrescribir por llamada con `client.request(..., timeout=5)`.
|
|
159
|
+
|
|
160
|
+
### Reintentos seguros
|
|
161
|
+
|
|
162
|
+
El cliente reintenta automáticamente los fallos transitorios sin duplicar operaciones:
|
|
163
|
+
|
|
164
|
+
| Respuesta | Métodos que se reintentan |
|
|
165
|
+
| --- | --- |
|
|
166
|
+
| `429 Too Many Requests` | todos |
|
|
167
|
+
| `500`, `502`, `503`, `504` | solo idempotentes: `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE` |
|
|
168
|
+
| `ConnectionError` / `Timeout` | solo idempotentes |
|
|
169
|
+
| cualquier otra (4xx, otros 5xx) | nunca |
|
|
170
|
+
|
|
171
|
+
La espera usa el encabezado `Retry-After` cuando está presente (segundos o fecha HTTP) y, si no,
|
|
172
|
+
un backoff exponencial. Los valores se limitan a `max_backoff`:
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
client = MeliClient(
|
|
176
|
+
client_id="TU_CLIENT_ID",
|
|
177
|
+
client_secret="TU_CLIENT_SECRET",
|
|
178
|
+
token_storage=storage,
|
|
179
|
+
max_retries=3, # 0 desactiva los reintentos
|
|
180
|
+
backoff_factor=0.5, # espera base: backoff_factor * 2 ** intento
|
|
181
|
+
max_backoff=60.0, # tope de espera en segundos
|
|
182
|
+
)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
En el peor caso, una petición puede tardar hasta `(max_retries + 1) × timeout` más las esperas del
|
|
186
|
+
backoff (unos 2 minutos con los valores por defecto) antes de fallar. Para acotar ese tiempo, reduce
|
|
187
|
+
`max_retries` o `timeout`.
|
|
188
|
+
|
|
189
|
+
### Concurrencia y refresh del token
|
|
190
|
+
|
|
191
|
+
Los refresh tokens de Mercado Libre son de un solo uso: al canjear uno, deja de ser válido. Para
|
|
192
|
+
evitar que varias peticiones simultáneas quemen el mismo refresh token, el cliente serializa las
|
|
193
|
+
renovaciones por instancia y por almacenamiento. Si otro hilo u otro cliente ya renovó el token, se
|
|
194
|
+
reutiliza el nuevo sin volver a llamar a `/oauth/token`.
|
|
195
|
+
|
|
196
|
+
`MemoryTokenStorage` y `FileTokenStorage` incluyen un lock. En `FileTokenStorage` el lock es por ruta
|
|
197
|
+
absoluta dentro del mismo proceso, así que **no coordina procesos separados**. Para varios procesos,
|
|
198
|
+
usa `CallbackTokenStorage` con un lock de base de datos:
|
|
199
|
+
|
|
200
|
+
```python
|
|
201
|
+
import contextlib
|
|
202
|
+
from meli_sdk import CallbackTokenStorage, MeliClient
|
|
203
|
+
|
|
204
|
+
@contextlib.contextmanager
|
|
205
|
+
def db_lock():
|
|
206
|
+
# Pseudocódigo: advisory lock o transacción SELECT ... FOR UPDATE
|
|
207
|
+
# with connection.transaction():
|
|
208
|
+
# connection.execute("SELECT pg_advisory_lock(42)")
|
|
209
|
+
# try:
|
|
210
|
+
yield
|
|
211
|
+
# finally:
|
|
212
|
+
# connection.execute("SELECT pg_advisory_unlock(42)")
|
|
213
|
+
|
|
214
|
+
storage = CallbackTokenStorage(
|
|
215
|
+
load_callback=load_token_from_db,
|
|
216
|
+
save_callback=save_token_to_db,
|
|
217
|
+
lock_callback=db_lock,
|
|
218
|
+
)
|
|
219
|
+
client = MeliClient(
|
|
220
|
+
client_id="TU_CLIENT_ID",
|
|
221
|
+
client_secret="TU_CLIENT_SECRET",
|
|
222
|
+
token_storage=storage,
|
|
223
|
+
)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Además, si una petición responde `401`, el cliente renueva el token una vez y reintenta la petición
|
|
227
|
+
con el nuevo token. Un segundo `401` se reporta como error.
|
|
228
|
+
|
|
229
|
+
### Autorización (OAuth)
|
|
230
|
+
|
|
231
|
+
Para obtener el primer token de un usuario, genera un `state` impredecible y redirige al usuario a la
|
|
232
|
+
URL de autorización. El `redirect_uri` debe ser exactamente el registrado en la aplicación de
|
|
233
|
+
Mercado Libre, y el `state` debe validarse en el callback (protección CSRF):
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
import secrets
|
|
237
|
+
from meli_sdk import FileTokenStorage, MeliClient
|
|
238
|
+
|
|
239
|
+
storage = FileTokenStorage("tokens/cuenta_1.json")
|
|
240
|
+
client = MeliClient(
|
|
241
|
+
client_id="TU_CLIENT_ID",
|
|
242
|
+
client_secret="TU_CLIENT_SECRET",
|
|
243
|
+
token_storage=storage,
|
|
244
|
+
)
|
|
245
|
+
|
|
246
|
+
state = secrets.token_urlsafe(32)
|
|
247
|
+
url = client.get_authorization_url(
|
|
248
|
+
"https://tu-app.example.com/callback",
|
|
249
|
+
state=state,
|
|
250
|
+
site_id="MCO",
|
|
251
|
+
)
|
|
252
|
+
# Redirige al usuario a `url`.
|
|
253
|
+
|
|
254
|
+
# En el callback:
|
|
255
|
+
# if request.args["state"] != state: abort(400)
|
|
256
|
+
token = client.exchange_code(
|
|
257
|
+
request.args["code"],
|
|
258
|
+
"https://tu-app.example.com/callback",
|
|
259
|
+
)
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
`get_authorization_url` también acepta `code_challenge` y agrega automáticamente
|
|
263
|
+
`code_challenge_method=S256` si usas PKCE. `exchange_code` funciona incluso con un almacenamiento
|
|
264
|
+
vacío y guarda el token igual que la renovación.
|
|
265
|
+
|
|
266
|
+
Si quieres identificarte ante Mercado Libre, pasa `user_agent="TuApp/1.0"`: el SDK lo antepone al
|
|
267
|
+
valor por defecto `meli-sdk/<versión> python-requests/<versión>`.
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Persistencia en Bases de Datos (Estrategia `CallbackTokenStorage`)
|
|
272
|
+
|
|
273
|
+
Si quieres guardar los tokens de acceso en una base de datos (por ejemplo, en un modelo de Django, SQLAlchemy, o en Redis) en lugar de archivos JSON locales, utiliza `CallbackTokenStorage` inyectando funciones de carga y guardado:
|
|
274
|
+
|
|
275
|
+
```python
|
|
276
|
+
from meli_sdk import MeliClient, CallbackTokenStorage
|
|
277
|
+
|
|
278
|
+
# Supongamos que tienes un modelo Django o SQLAlchemy para las credenciales
|
|
279
|
+
def load_token_from_db():
|
|
280
|
+
credential = CredencialMercadoLibre.objects.get(id=1)
|
|
281
|
+
return {
|
|
282
|
+
"access_token": credential.access_token,
|
|
283
|
+
"refresh_token": credential.refresh_token,
|
|
284
|
+
"expires_in": credential.expires_in,
|
|
285
|
+
"created_at": credential.created_at,
|
|
286
|
+
"expires_at": credential.expires_at,
|
|
287
|
+
"user_id": credential.user_id,
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
def save_token_to_db(token_data):
|
|
291
|
+
# Esta función es llamada automáticamente por el cliente cada vez que el token se renueva
|
|
292
|
+
CredencialMercadoLibre.objects.update_or_create(
|
|
293
|
+
id=1,
|
|
294
|
+
defaults={
|
|
295
|
+
"access_token": token_data.get("access_token"),
|
|
296
|
+
"refresh_token": token_data.get("refresh_token"),
|
|
297
|
+
"expires_in": token_data.get("expires_in"),
|
|
298
|
+
"created_at": token_data.get("created_at"),
|
|
299
|
+
"expires_at": token_data.get("expires_at"),
|
|
300
|
+
"user_id": token_data.get("user_id"),
|
|
301
|
+
}
|
|
302
|
+
)
|
|
303
|
+
|
|
304
|
+
# Inicializar con almacenamiento de base de datos
|
|
305
|
+
db_storage = CallbackTokenStorage(load_callback=load_token_from_db, save_callback=save_token_to_db)
|
|
306
|
+
|
|
307
|
+
client = MeliClient(
|
|
308
|
+
client_id="TU_CLIENT_ID",
|
|
309
|
+
client_secret="TU_CLIENT_SECRET",
|
|
310
|
+
token_storage=db_storage
|
|
311
|
+
)
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## Desarrollo
|
|
317
|
+
|
|
318
|
+
Crea un entorno virtual e instala el proyecto en modo editable junto con las dependencias de
|
|
319
|
+
desarrollo:
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
python3 -m venv .venv
|
|
323
|
+
. .venv/bin/activate
|
|
324
|
+
pip install -e ".[dev]"
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Ejecuta la suite de pruebas con pytest:
|
|
328
|
+
|
|
329
|
+
```bash
|
|
330
|
+
python -m pytest
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Guía de Recursos Disponibles
|
|
336
|
+
|
|
337
|
+
### 1. Órdenes (`client.orders`)
|
|
338
|
+
* `orders.get(order_id)`: Obtiene el detalle de una orden.
|
|
339
|
+
* `orders.search(seller_id=None, year=None, month=None, *, status=None, sort="date_asc",
|
|
340
|
+
utc_offset="-05:00", extra_params=None)`: Busca órdenes de un periodo de tiempo.
|
|
341
|
+
* `orders.iter_all(seller_id=None, year=None, month=None, *, status=None, sort="date_asc",
|
|
342
|
+
utc_offset="-05:00", page_size=50, extra_params=None)`: Generador que recorre todas las páginas.
|
|
343
|
+
* `orders.get_pack(pack_id)`: Obtiene información de un paquete de envíos.
|
|
344
|
+
|
|
345
|
+
El rango de fechas se calcula en la zona horaria del vendedor. Colombia (`MCO`) usa `-05:00` sin
|
|
346
|
+
horario de verano; si vendes en otro país, pasa su offset:
|
|
347
|
+
|
|
348
|
+
```python
|
|
349
|
+
# Órdenes pagadas de febrero de 2026 en Colombia
|
|
350
|
+
client.orders.search(year=2026, month=2, status="paid")
|
|
351
|
+
|
|
352
|
+
# Mismo rango en UTC, ordenado de más reciente a más antiguo
|
|
353
|
+
client.orders.search(year=2026, month=2, sort="date_desc", utc_offset="+00:00")
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
`orders.iter_all` recorre todas las páginas y respeta el máximo de 50 órdenes por página. La
|
|
357
|
+
validación de `page_size` ocurre al consumir el generador, así que puedes encadenarlo con `break`
|
|
358
|
+
sin descargar el resto:
|
|
359
|
+
|
|
360
|
+
```python
|
|
361
|
+
for order in client.orders.iter_all(year=2026, month=11, status="paid"):
|
|
362
|
+
print(order["id"])
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
### 2. Facturas (`client.bills`)
|
|
366
|
+
* `bills.get_billing_info(order_id)`: Detalles de facturación del cliente.
|
|
367
|
+
* `bills.has_fiscal_document(pack_id)`: Verifica si el paquete tiene una factura adjunta; una
|
|
368
|
+
lista vacía se considera sin factura.
|
|
369
|
+
* `bills.upload_fiscal_document(pack_id, document, *, filename=None)`: Sube una factura. Solo se
|
|
370
|
+
aceptan archivos PDF.
|
|
371
|
+
|
|
372
|
+
```python
|
|
373
|
+
# Desde una ruta
|
|
374
|
+
client.bills.upload_fiscal_document(4028374928, "facturas/factura-123.pdf")
|
|
375
|
+
|
|
376
|
+
# Desde bytes, sin escribir un archivo temporal
|
|
377
|
+
with open("facturas/factura-123.pdf", "rb") as f:
|
|
378
|
+
pdf_bytes = f.read()
|
|
379
|
+
client.bills.upload_fiscal_document(4028374928, pdf_bytes, filename="factura-123.pdf")
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
El documento debe empezar por `%PDF-`; también se acepta un objeto de archivo binario.
|
|
383
|
+
|
|
384
|
+
### 3. Envíos (`client.shipments`)
|
|
385
|
+
* `shipments.get(shipment_id)`: Obtiene toda la información de tracking de un envío.
|
|
386
|
+
|
|
387
|
+
### 4. Publicaciones (`client.items`)
|
|
388
|
+
* `items.create(body)`: Publica un nuevo producto.
|
|
389
|
+
* `items.get(item_id)`: Detalle completo de una publicación.
|
|
390
|
+
* `items.update(item_id, body)`: Actualización masiva de campos.
|
|
391
|
+
* `items.update_price(item_id, nuevo_precio)`: Actualiza el precio del producto.
|
|
392
|
+
* `items.update_stock(item_id, nuevo_stock)`: Actualiza el stock disponible.
|
|
393
|
+
* `items.get_visits(item_id)`: Cantidad de visitas de una publicación.
|
|
394
|
+
* `items.iter_all(seller_id=None, *, page_size=100, extra_params=None)`: Generador que recorre los
|
|
395
|
+
IDs de todas las publicaciones con `search_type=scan`. El `scroll_id` caduca a los 5 minutos, así
|
|
396
|
+
que consúmelo sin pausas largas.
|
|
397
|
+
* `items.get_many(item_ids, *, attributes=None, include_errors=False)`: Descarga los detalles en
|
|
398
|
+
lotes de 20 IDs y conserva el orden de entrada.
|
|
399
|
+
|
|
400
|
+
```python
|
|
401
|
+
from itertools import islice
|
|
402
|
+
|
|
403
|
+
# Primeras 100 publicaciones, para no mantener el scroll abierto demasiado tiempo
|
|
404
|
+
ids = list(islice(client.items.iter_all(), 100))
|
|
405
|
+
items = client.items.get_many(
|
|
406
|
+
ids, attributes=["id", "title", "price", "available_quantity"]
|
|
407
|
+
)
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
`get_many` descarta por defecto las entradas con error; pasa `include_errors=True` para recibir
|
|
411
|
+
también los `{"code", "body"}` fallidos. El SDK siempre solicita el atributo `id`, aunque no lo
|
|
412
|
+
incluyas en `attributes`, para poder conservar el orden de entrada.
|
|
413
|
+
|
|
414
|
+
### 5. Métricas e Inteligencia (`client.metrics`)
|
|
415
|
+
* `metrics.get_seller_info(seller_id=None)`: Datos públicos del vendedor.
|
|
416
|
+
* `metrics.get_seller_reputation(seller_id=None)`: Termómetro de reputación (reclamos, cancelaciones, retrasos).
|
|
417
|
+
* `metrics.get_item_reviews(item_id)`: Calificaciones por estrellas y comentarios de productos.
|
|
418
|
+
* `metrics.get_trends(site_id, category_id=None)`: Palabras clave más buscadas en un país (ej. `MCO`) o categoría.
|
|
419
|
+
* `metrics.get_questions(seller_id=None, item_id=None, status=None)`: Preguntas recibidas por el vendedor.
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## Control de Errores
|
|
424
|
+
|
|
425
|
+
El módulo define excepciones claras que heredan de `MeliError`:
|
|
426
|
+
|
|
427
|
+
```python
|
|
428
|
+
from meli_sdk.exceptions import MeliAPIError, MeliTokenExpiredError
|
|
429
|
+
|
|
430
|
+
try:
|
|
431
|
+
client.items.update_price("MCO999999", 5000)
|
|
432
|
+
except MeliAPIError as e:
|
|
433
|
+
print(f"Error del API ({e.status_code}): {e.message} | Código: {e.error_code}")
|
|
434
|
+
except MeliTokenExpiredError:
|
|
435
|
+
print("El refresh token ha expirado. Es necesario re-autenticar la aplicación manualmente.")
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
---
|
|
439
|
+
|
|
440
|
+
## Créditos y Contribuciones
|
|
441
|
+
|
|
442
|
+
* **Autor**: Camilo Andrés Rodríguez
|
|
443
|
+
* **Portal de Desarrolladores**: [Mercado Libre Developers](https://developers.mercadolibre.com/)
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## Licencia
|
|
448
|
+
|
|
449
|
+
Este proyecto está bajo la Licencia [MIT](LICENSE).
|