Takealot Seller API PHP SDK – Leitura de Vendas, Ofertas, Transações e Saldo

Descrição

Takealot Marketplace API Integration Toolkit é um SDK PHP independente de framework projetado para vendedores no Takealot, a maior plataforma de e-commerce da África do Sul. Ele fornece uma interface limpa e com segurança de tipos para ler suas vendas, ofertas, transações, saldo, devoluções, remessas, instalações e informações da conta diretamente da API do Takealot Marketplace.

O Takealot é a principal plataforma de compras online da África do Sul, com milhões de produtos em 28 departamentos e uma posição dominante entre as plataformas de e-commerce locais. A plataforma oferece entrega nacional, múltiplas opções de pagamento (incluindo pagamento na entrega, SnapScan e TED) e um portal de vendedores para gerenciar anúncios e pedidos.

Este SDK encapsula a API pública do Takealot Marketplace em https://marketplace-api.takealot.com/v1 e é construído com base na documentação pública atual da API. Ele é somente leitura e seguro — acessa apenas endpoints GET e nunca cria, atualiza ou desativa nada em sua conta de vendedor, eliminando o risco de alterações acidentais de preço ou ofertas desativadas.

Principais Recursos
Independente de framework: Usa PSR-18 (cliente HTTP), PSR-17 (fábricas) e PSR-7 (mensagens). Sem Laravel, sem Symfony, sem estado global — basta integrá-lo a qualquer projeto PHP moderno.

Somente leitura e seguro: Encapsula apenas endpoints GET. Sem risco de modificar sua conta.

DTOs com segurança de tipos: Objetos de resposta somente leitura com validação rigorosa de formato. Cargas úteis malformadas falham de forma explícita em vez de vazar arrays sem tipo.

Paginação com token de continuação: Duas formas de paginar — buscar uma única página e seguir o token você mesmo ou usar iterate() com um Generator preguiçoso que percorre todas as páginas de forma transparente.

Tratamento automático de limite de taxa: Respostas HTTP 429 são retry automático, respeitando o cabeçalho Retry-After com backoff exponencial como fallback.

Hierarquia de exceções tipadas: 400, 401/403, 404 e 429 cada um mapeia para uma subclasse de exceção distinta.

Endurecido por padrão: Limite de 8 MiB para corpo de resposta, profundidade máxima de JSON de 64 e encapsulamento de erros de transporte PSR-18 que remove o cabeçalho X-API-Key de mensagens vazadas.

PHPStan nível 9: Tipos estritos em todo o código, zero erros de análise estática.

O Que Você Pode Ler
Endpoint Descrição
Sales Dados de vendas do vendedor
Offers Seus anúncios no marketplace com preço e estoque
Transactions Histórico de transações
Balances Informações de saldo da conta
Returns Solicitações e status de devolução
Shipments Rastreamento e detalhes de remessas
Facilities Regiões e instalações habilitadas
Seller Informações da conta
Requisitos
PHP 8.2 ou superior

Um cliente HTTP PSR-18 (Guzzle 7 é recomendado e descoberto automaticamente via php-http/discovery)

Uma conta de vendedor Takealot com uma chave de API gerada no Portal do Vendedor em Configurações → Acesso à API

Arquivos Incluídos
src/ — Arquivos-fonte do SDK

examples/ — Exemplos de uso

composer.json — Configuração do Composer

README.md — Documentação completa

LICENSE — Arquivo de licença

Perfeito Para
Vendedores Takealot, desenvolvedores de e-commerce, integradores de marketplace e qualquer pessoa que esteja construindo ferramentas para gerenciar contas de vendedores Takealot programaticamente.