Download the PHP package tepuilabs/mini-meli without Composer

mini-meli

Librería completa para Mercado Libre con OAuth 2.0 PKCE, refresh tokens y gestión de aplicaciones. Implementa todas las mejores prácticas de seguridad y funcionalidades de la API oficial.

🚀 Características

• ✅ OAuth 2.0 PKCE - Autenticación segura con Proof Key for Code Exchange
• ✅ Refresh Tokens - Renovación automática de tokens con offline_access
• ✅ Multi-Site Support - Soporte para todos los sitios de Mercado Libre
• ✅ App Management - Gestión completa de aplicaciones y permisos
• ✅ Security First - Validación robusta y protección CSRF
• ✅ PHP 8.3+ - Aprovecha las últimas funcionalidades del lenguaje
• ✅ Type Safety - Tipado estricto y union types
• ✅ Readonly Properties - Inmutabilidad donde sea apropiado
• ✅ Match Expressions - Lógica más clara y eficiente
• ✅ Named Arguments - Mejor legibilidad del código
• ✅ First-class Callable Syntax - Sintaxis moderna para callbacks
• ✅ Improved Error Handling - Manejo de errores más específico
• ✅ Backward Compatibility - Compatible con versiones anteriores

📦 Instalación

⚙️ Configuración

Variables de Entorno

Agrega en tu archivo de configuración:

[!NOTE] Estos datos los debes configurar en Mercado Libre cuando crees una aplicación. Solo necesitas el client_id y client_secret.

🔐 Uso

1. Autenticación OAuth 2.0 PKCE

2. Intercambio de Código por Token

3. Refresh Tokens

4. Llamadas a la API

5. Gestión de Aplicaciones

🌍 Sitios Soportados

La librería soporta todos los sitios de Mercado Libre:

🔑 Scopes y Permisos

🛡️ Seguridad

PKCE (Proof Key for Code Exchange)

La librería implementa PKCE para prevenir ataques de interceptación de código:

State Protection

Protección CSRF con parámetros state aleatorios:

Validación Robusta

📚 API Reference

MeliServices

Métodos Estáticos

• fromArray(array $params): self - Crear desde array
• fromEnvironment(): self - Crear desde variables de entorno

Métodos de Instancia

• generateAccessToken(): MeliResponse - Generar token
• refreshAccessToken(string $refreshToken): MeliResponse - Renovar token
• getAuthorizationUrl(string $site, array $params = []): string - Generar URL de autorización
• get(string $endpoint, string $accessToken): array - GET request
• post(string $endpoint, string $accessToken, array $data = []): array - POST request
• put(string $endpoint, string $accessToken, array $data = []): array - PUT request
• delete(string $endpoint, string $accessToken): array - DELETE request
• getApplicationDetails(string $accessToken, string $appId): array - Detalles de app
• getUserApplications(string $accessToken, string $userId): array - Apps del usuario
• getApplicationGrants(string $accessToken, string $appId): array - Usuarios conectados
• revokeUserAuthorization(string $accessToken, string $userId, string $appId): array - Revocar autorización

MeliConfig

Métodos Estáticos

• fromArray(array $params): self - Crear desde array
• fromEnvironment(): self - Crear desde variables de entorno
• forAuthorization(...): self - Crear para URLs de autorización
• generatePkce(): array - Generar PKCE
• generateState(): string - Generar state

Métodos de Instancia

• toArray(): array - Convertir a array
• isValid(): bool - Verificar si es válido
• hasPkce(): bool - Verificar si tiene PKCE
• hasState(): bool - Verificar si tiene state
• hasRefreshToken(): bool - Verificar si tiene refresh token
• isForTokenExchange(): bool - Verificar si es para intercambio
• getScopesString(): string - Obtener scopes como string
• hasOfflineAccess(): bool - Verificar offline access
• hasReadPermission(): bool - Verificar permiso de lectura
• hasWritePermission(): bool - Verificar permiso de escritura

MeliResponse

Propiedades

• data: array - Datos de la respuesta
• statusCode: int - Código de estado HTTP

Métodos

• getAccessToken(): ?string - Obtener access token
• getRefreshToken(): ?string - Obtener refresh token
• getTokenType(): ?string - Obtener tipo de token
• getExpiresIn(): ?int - Obtener tiempo de expiración
• getScope(): ?string - Obtener scope
• getUserId(): ?int - Obtener ID de usuario
• hasAccessToken(): bool - Verificar si tiene access token
• hasRefreshToken(): bool - Verificar si tiene refresh token
• toArray(): array - Convertir a array
• toJson(): string - Convertir a JSON
• isSuccessful(): bool - Verificar si la respuesta es exitosa
• getErrorMessage(): ?string - Obtener mensaje de error
• getErrorDescription(): ?string - Obtener descripción del error

MeliScopes

Constantes

• READ - Permiso de lectura
• WRITE - Permiso de escritura
• OFFLINE_ACCESS - Permiso offline (refresh tokens)

Métodos Estáticos

• getAll(): array - Obtener todos los scopes
• getDefault(): array - Obtener scopes por defecto
• getOfflineAccess(): array - Obtener scopes con offline access
• isValid(string $scope): bool - Validar scope
• validateScopes(array $scopes): bool - Validar múltiples scopes
• toString(array $scopes): string - Convertir a string
• toArray(string $scopes): array - Convertir a array
• hasOfflineAccess(array|string $scopes): bool - Verificar offline access
• hasRead(array|string $scopes): bool - Verificar lectura
• hasWrite(array|string $scopes): bool - Verificar escritura

MeliSites

Constantes

• MLA - Argentina
• MLB - Brasil
• MLM - México
• MLC - Chile
• MCO - Colombia
• MPE - Perú
• MLU - Uruguay
• MLV - Venezuela

Métodos Estáticos

• getAll(): array - Obtener todos los sitios
• getSite(string $siteId): ?array - Obtener información del sitio
• getDomain(string $siteId): string - Obtener dominio
• getName(string $siteId): string - Obtener nombre
• getFlag(string $siteId): string - Obtener bandera
• isValid(string $siteId): bool - Validar sitio
• getAuthorizationUrl(string $siteId): string - Obtener URL de autorización
• getApiUrl(): string - Obtener URL base de la API
• getOAuthTokenEndpoint(): string - Obtener endpoint de tokens

🚨 Manejo de Errores

La librería incluye manejo de errores específico:

Tipos de Error

• 400 - Solicitud inválida
• 401 - Credenciales inválidas
• 403 - Acceso denegado
• 404 - Endpoint no encontrado
• 429 - Demasiadas solicitudes
• 5xx - Error del servidor

Errores Específicos de OAuth

• invalid_client - Client ID o Secret inválidos
• invalid_grant - Código o refresh token inválido/expirado
• invalid_scope - Scope inválido
• invalid_request - Parámetros faltantes o inválidos
• unsupported_grant_type - Grant type no soportado
• forbidden - Acceso denegado
• local_rate_limited - Demasiadas solicitudes
• unauthorized_client - Cliente no autorizado
• unauthorized_application - Aplicación bloqueada

🧪 Testing

📝 Ejemplo Completo

🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE.md para más detalles.

🔗 Enlaces Útiles

• Documentación oficial de Mercado Libre
• Recomendaciones de seguridad
• Gestión de aplicaciones