SDK PHP de la API de Takealot para vendedores – Leer ventas, ofertas, transacciones y saldos

Descripción

Takealot Marketplace API Integration Toolkit es un SDK PHP independiente de framework diseñado para vendedores en Takealot, la mayor plataforma de comercio electrónico de Sudáfrica. Proporciona una interfaz limpia y con tipado seguro para leer tus ventas como vendedor, ofertas, transacciones, saldos, devoluciones, envíos, instalaciones y la información de tu cuenta directamente desde la API de Mercado de Takealot.

Takealot es la principal plataforma de compras en línea de Sudáfrica, con millones de productos en 28 departamentos y una posición dominante entre las plataformas de comercio electrónico locales. La plataforma ofrece envío a nivel nacional, múltiples opciones de pago (incluyendo pago contra reembolso, SnapScan y transferencia electrónica) y un portal de vendedores para gestionar listados y pedidos.

Este SDK envuelve la API pública de Takealot Marketplace en https://marketplace-api.takealot.com/v1 y está construido según la documentación pública actual de la API. Es de solo lectura y seguro — solo accede a los endpoints GET y nunca crea, actualiza o desactiva nada en tu cuenta de vendedor, eliminando el riesgo de cambios accidentales de precios u ofertas desactivadas.

Características clave
Independiente de framework: Usa PSR-18 (cliente HTTP), PSR-17 (fábricas) y PSR-7 (mensajes). Sin Laravel, sin Symfony, sin estado global — solo intégralo en cualquier proyecto PHP moderno.

De solo lectura y seguro: Envuelve solo endpoints GET. Sin riesgo de modificar tu cuenta.

DTOs con tipado seguro: Objetos de respuesta de solo lectura con validación estricta de forma. Las cargas útiles mal formadas aguas arriba fallan de manera explícita en lugar de filtrar matrices sin tipado.

Paginación con token de continuación: Dos formas de paginar — obtener una sola página y seguir el token tú mismo, o usar iterate() con un Generador perezoso que recorre cada página de manera transparente.

Manejo automático de límites de tasa: Las respuestas HTTP 429 se reintentan automáticamente, respetando la cabecera Retry-After con retroceso exponencial como alternativa.

Jerarquía de excepciones tipadas: 400, 401/403, 404 y 429 cada uno se asigna a una subclase de excepción distinta.

Endurecido por defecto: Límite de cuerpo de respuesta de 8 MiB, límite de profundidad JSON de 64 y envolvente de errores de transporte PSR-18 que elimina la cabecera X-API-Key de los mensajes filtrados.

PHPStan nivel 9: Tipos estrictos en todo el código, cero errores de análisis estático.

Qué puedes leer
Endpoint Descripción
Sales Datos de ventas de tu cuenta de vendedor
Offers Tus listados en el mercado con precio y stock
Transactions Historial de transacciones
Balances Información de saldo de cuenta
Returns Solicitudes y estado de devoluciones
Shipments Seguimiento y detalles de envíos
Facilities Regiones y instalaciones habilitadas
Seller Información de la cuenta
Requisitos
PHP 8.2 o superior

Un cliente HTTP PSR-18 (se recomienda Guzzle 7 y se descubre automáticamente mediante php-http/discovery)

Una cuenta de vendedor de Takealot con una clave API generada en el Portal de Vendedores en Configuración → Acceso API

Archivos incluidos
src/ — Archivos fuente del SDK

examples/ — Ejemplos de uso

composer.json — Configuración de Composer

README.md — Documentación completa

LICENSE — Archivo de licencia

Perfecto para
Vendedores de Takealot, desarrolladores de comercio electrónico, integradores de mercado y cualquier persona que construya herramientas para gestionar cuentas de vendedores de Takealot de manera programática.