rlacerda83/submarino-sdk

SDK Não Oficial para integração a partir de aplicações PHP com as APIs do Submarino Marketplace

submarino-sdk

SDK Não Oficial para integração a partir de aplicações PHP com as APIs da B2W Marketplace (Submarino, Shoptime, Americanas.com)

Requisitos para uso

• PHP >= 5.6
• curl extension
• Composer Dependency Manager

Este componente não é uma aplicação Stand Alone e seu objetivo é ser utilizado como biblioteca. Sua implantação deve ser feita por desenvolvedores experientes.

Isto não é um Plugin!

As opções que funcionam no modo de comando apenas servem para depuração em modo de desenvolvimento.

A documentação mais importante está nos testes unitários. Se você não consegue ler os testes unitários, eu recomendo que não utilize esta biblioteca.

Direitos autorais e de licença

Este componente está sob a licença MIT

Para a informação dos direitos autorais e de licença você deve ler o arquivo de licença que é distribuído com este código-fonte.

Resumo da licença

Exigido:

• Aviso de licença e direitos autorais

Permitido:

• Uso comercial
• Modificação
• Distribuição
• Sublicenciamento
• Proibido

Proibido:

• Responsabilidade Assegurada

---

Indicadores de qualidade

---

Instalação

Adicione o pacote submarino-sdk ao seu projeto utilizando composer:

composer require gpupo/submarino-sdk

Este exemplo demonstra o uso simplificado a partir do Factory:

<?php

use Gpupo\SubmarinoSdk\Factory;

$submarinoSdk = Factory::getInstance()->setup([
    'token'     => '7Ao82svbm#6',
    'version'   => 'sandbox',
]);

Exemplos de uso

Acesso a lista de produtos cadastrados

<?php
//...
$manager = $submarinoSdk->factoryManager('product'));
$produtosCadastrados = $manager->fetch(); // Collection de Objetos Product

Acesso a informações de um produto específico

<?php
//...
$produto = $manager->findById(9));
echo $product->getName();

Criação de um produto

Veja o formato de $data em Resources/fixture/Products.json

<?php
//...
$data = [];
$product = $submarinoSdk->createProduct($data);

foreach ($data['sku'] as $item) {
    $sku = $submarinoSdk->createSku($item);
    $product->getSku()->add($sku);
}

$manager->save($product);

Exemplos de manutenção de Produtos

<?php
//...
$manager = $submarinoSdk->factoryManager('product'));

// Acesso a lista de produtos cadastrados:
$produtosCadastrados = $manager->fetch(); // Collection de Objetos Product

// Acesso a informações de um produto cadastrado e com identificador conhecido:
$produto = $manager->findById(9)); // Objeto Produto
echo $product->getName(); // Acesso ao nome do produto #9


// Criação de um produto:
$data = []; // Veja o formato de $data em Resources/fixture/Products.json
$product = $submarinoSdk->createProduct($data);

foreach ($data['sku'] as $item) {
    $sku = $submarinoSdk->createSku($item);
    $product->getSku()->add($sku);
}

$manager->save($product);

//Adicionando SKU ao produto:
$skuData = []; // Defina o valor deste array conforme o esquema disponível em Resources/
$novoSku = $submarinoSdk->createSku($skuData);
$product->getSku()->add($novoSku);
$manager->save($product);

Exemplos de manutenção de Pedidos

<?php
//...
$manager = $submarinoSdk->factoryManager('order'));

$orderList = $manager->fetch(); //Recebe uma coleção ``\Gpupo\SubmarinoSdk\Entity\Order\Order``

foreach ($orderList as $order) {
	//Atualizando dados de ENVIO do pedido:
   	$order->getStatus()->setStatus('DELIVERED')
   		->getDelivered()->setDeliveredCustomerDate(date('Y-m-d H:i:s'))
   		->setTrackingProtocol('RE983737722BR')
        ->setEstimatedDelivery('2015-12-25 01:00:00');
	$manager->saveStatus($order);
}

//Acessando informações de um pedido específico

$order = $manager->findById(339938882);
echo $order->getId(); //339938882
echo $order->getSiteId(); // 03-589-01
echo $order->getStore(); // SUBMARINO
echo $order->getStatus(); // PROCESSING

//Movendo pedido de situação na B2W:
$order->getStatus()->setStatus('PROCESSING');
$manager->saveStatus($order);

Uso de cache para otimização de updates

<?php
//...
use Gpupo\Cache\CacheItem;
use Gpupo\Cache\CacheItemPool;
use Gpupo\SubmarinoSdk\Entity\Product\Factory;

$data = []; //Your SKU array!

$sku = Factory::createSku($data);

$pool = new CacheItemPool('Memcached');
$key = 'sku-foo';
$item = new CacheItem($key);
$item->set($sku, 60);
$pool->save($item);

// mude o mundo... e pense que está em uma nova execução, alguns minutos depois ...
$sku = Factory::createSku($data);
$previousSku = $pool->getItem($key)->get();
$sku->setPrevious($previousSku);
$sku->save();

Uso de confirmação ou rejeição de um pedido

<?php
//...
/**
 * https://api-sandbox.bonmarketplace.com.br/docs/confirmacaoPedido.shtml
 *
 * @var \Gpupo\SubmarinoSdk\Entity\Order\Manager $sdkOrderManager
 * @var \Gpupo\SubmarinoSdk\Entity\Order\Order   $order
 * @var \My\Awesome\Order\Creator                $yourOrderCreator
 */
foreach ($sdkOrderManager->fetch() as $order) {
    // Sua implementação de criação de pedido
    $successfully = $yourOrderCreator->createOrder($order);
    // POST para: http://api-marketplace.bonmarketplace.com.br/order/{ORDER_ID}/confirm
    $sdkOrderManager->confirm(
        $order->getId(),
        $successfully,
        $successfully ? 'Success' : 'Failure'
    );
}

---

---

Console

Lista de comandos disponíveis:

./bin/main

Você pode verificar suas credenciais Cnova na linha de comando:

./bin/main credential

---

Links

• Documentação oficial
• Submarino-sdk Composer Package no packagist.org
• Marketplace-bundle Composer Package - Integração deste pacote com Symfony
• Outras SDKs para o Ecommerce do Brasil

---

Desenvolvimento

git clone --depth=1  git@github.com:gpupo/submarino-sdk.git

cd submarino-sdk;

ant;

Personalize a configuração do phpunit:

cp phpunit.xml.dist phpunit.xml;

Personalize os parâmetros!

Dica: Verifique os logs gerados em var/log/main.log

---

Propriedades dos objetos

---

Propriedades dos objetos

SubmarinoSdk\Client

• Gerencia uri de recurso
• Acesso a lista de pedidos
• Acesso a lista de produtos
• Acesso a lista de skus
• Retorna informacoes do sku informado
• Atualiza estoque do sku informado
• Atualiza preco do sku informado

SubmarinoSdk\Entity\Order\Customer\Customer

• Cada cliente possui endereco de entrega como objeto
• Cada cliente possui colecao de telefones
• Cada cliente possui objeto pessoa fisica
• Cada cliente possui objeto pessoa juridica
• Possui método getPf() para acessar Pf
• Possui método setPf() que define Pf
• Possui método getPj() para acessar Pj
• Possui método setPj() que define Pj
• Possui método getTelephones() para acessar Telephones
• Possui método setTelephones() que define Telephones
• Possui método getDeliveryAddress() para acessar DeliveryAddress
• Possui método setDeliveryAddress() que define DeliveryAddress

SubmarinoSdk\Entity\Order\Customer\Telephones\Telephones

• Cada cliente possui colecao de telefones

SubmarinoSdk\Entity\Order\Manager

• Obtem lista pedidos
• Obtém a lista de pedidos recém aprovados e que esperam processamento
• Recupera informacoes de um pedido especifico
• Atualiza status de um pedido
• Atualiza dados de envio de um pedido
• Atualiza dados de entrega de um pedido

SubmarinoSdk\Entity\Order\Order

• Cada item de uma lista e um objeto
• Cada pedido possui objeto cliente
• Cada pedido possui objeto com dados de cobrança
• Cada pedido possui colecao de produtos
• Cada pedido possui colecao de metodos de pagamento
• Cada pedido possui objeto com dados de entrega
• Cada pedido possui objeto status
• Possui loja de origem
• Possui valor total do pedido
• Possui valor total do frete
• Possui valor total de desconto
• Possui valor total de juros
• Possui valor total do pedido descontado juros
• O total real contém produtos somado a frete menos o desconto
• O total real possui mesmo valor de total amount se não houver juros
• O total real contém total menos juros
• Possui método setId() que define Id
• Possui método getSiteId() para acessar SiteId
• Possui método setSiteId() que define SiteId
• Possui método getStore() para acessar Store
• Possui método setStore() que define Store
• Possui método getPurchaseDate() para acessar PurchaseDate
• Possui método setPurchaseDate() que define PurchaseDate
• Possui método getLastUpdate() para acessar LastUpdate
• Possui método setLastUpdate() que define LastUpdate
• Possui método getPurchaseTimestamp() para acessar PurchaseTimestamp
• Possui método setPurchaseTimestamp() que define PurchaseTimestamp
• Possui método getLastUpdateTimestamp() para acessar LastUpdateTimestamp
• Possui método setLastUpdateTimestamp() que define LastUpdateTimestamp
• Possui método getStatus() para acessar Status
• Possui método setStatus() que define Status
• Possui método getInvoiced() para acessar Invoiced
• Possui método setInvoiced() que define Invoiced
• Possui método getEstimatedDeliveryDate() para acessar EstimatedDeliveryDate
• Possui método setEstimatedDeliveryDate() que define EstimatedDeliveryDate
• Possui método getCustomer() para acessar Customer
• Possui método setCustomer() que define Customer
• Possui método getPayer() para acessar Payer
• Possui método setPayer() que define Payer
• Possui método getTotalAmount() para acessar TotalAmount
• Possui método setTotalAmount() que define TotalAmount
• Possui método getTotalFreight() para acessar TotalFreight
• Possui método setTotalFreight() que define TotalFreight
• Possui método getTotalDiscount() para acessar TotalDiscount
• Possui método setTotalDiscount() que define TotalDiscount
• Possui método getTotalInterest() para acessar TotalInterest
• Possui método setTotalInterest() que define TotalInterest
• Possui método getProducts() para acessar Products
• Possui método setProducts() que define Products
• Possui método getShipping() para acessar Shipping
• Possui método setShipping() que define Shipping
• Possui método getPaymentMethods() para acessar PaymentMethods
• Possui método setPaymentMethods() que define PaymentMethods

SubmarinoSdk\Entity\Order\Payer\Payer

• Cada pagador possui endereco de cobrança como objeto
• Cada pagador possui colecao de telefones
• Cada pagador possui objeto pessoa fisica
• Cada pagador possui objeto pessoa juridica

SubmarinoSdk\Entity\Order\PaymentMethods\PaymentMethod

• Cada pedido possui uma coleção de objetos payment method
• Possui método getSequential() para acessar Sequential
• Possui método setSequential() que define Sequential
• Possui método getId() para acessar Id
• Possui método setId() que define Id
• Possui método getValue() para acessar Value
• Possui método setValue() que define Value

SubmarinoSdk\Entity\Order\Products\Product

• Cada pedido possui uma coleção de objetos produto
• Possui método getLink() para acessar Link
• Possui método setLink() que define Link
• Possui método getQuantity() para acessar Quantity
• Possui método setQuantity() que define Quantity
• Possui método getPrice() para acessar Price
• Possui método setPrice() que define Price
• Possui método getFreight() para acessar Freight
• Possui método setFreight() que define Freight
• Possui método getDiscount() para acessar Discount
• Possui método setDiscount() que define Discount

SubmarinoSdk\Entity\Order\Shipping

• Possui método getShippingEstimateId() para acessar ShippingEstimateId
• Possui método setShippingEstimateId() que define ShippingEstimateId
• Possui método getShippingMethodId() para acessar ShippingMethodId
• Possui método setShippingMethodId() que define ShippingMethodId
• Possui método getShippingMethodName() para acessar ShippingMethodName
• Possui método setShippingMethodName() que define ShippingMethodName
• Possui método getCalculationType() para acessar CalculationType
• Possui método setCalculationType() que define CalculationType
• Possui método getShippingMethodDisplayName() para acessar ShippingMethodDisplayName
• Possui método setShippingMethodDisplayName() que define ShippingMethodDisplayName

SubmarinoSdk\Entity\Order\Status\Status

• Cada status pode ser impresso como string
• Cada status possui objeto invoiced
• Cada status possui objeto shipped
• Cada status possui objeto shipment exception
• Cada status possui objeto delivered
• Cada status possui objeto unavailable
• Falha ao marcar como faturado sem possuir objeto invoiced valido
• Sucesso ao marcar como faturado informando objeto invoiced valido
• Falha ao marcar como remetido sem possuir objeto shipped valido
• Sucesso ao marcar como remetido informando objeto shipped valido
• Falha ao marcar como falha na entrega sem possuir objeto shipment exception valido
• Sucesso ao marcar como falha na entrega informando objeto shipment exception valido
• Falha ao marcar como entregue sem possuir objeto delivered valido
• Sucesso ao marcar como entregue informando objeto delivered valido
• Falha ao marcar como indisponivel sem possuir objeto unavailable valido
• Sucesso ao marcar como indisponivel informando objeto unavailable valido

SubmarinoSdk\Entity\Product\Manager

• Obtem lista de produtos cadastrados
• Recupera informacoes de um produto especifico
• Gerencia update

SubmarinoSdk\Entity\Product\Product

• Possui propriedades e objetos
• Possui nbm formatado
• Possui preco formatado
• Possui uma colecao de skus
• Possui objeto manufacturer
• Entrega json

SubmarinoSdk\Entity\Product\Sku\Manager

• Acesso a lista de skus cadastrados
• Acessa a informacoes de um sku

SubmarinoSdk\Entity\Product\Sku\Price

• Possui preço normal
• Possui preço com desconto

SubmarinoSdk\Entity\Product\Sku\Sku

• Envia dados opcionais apenas se preenchidos
• Possui propriedade contendo url da imagem
• Sku possui objeto status
• Sku possui objeto stock

SubmarinoSdk\Factory

• Centraliza acesso a managers
• Centraliza criacao de objetos

Lista de dependências (libraries)

Name	Version	Description
codeclimate/php-test-reporter	v0.4.4	PHP client for reporting test coverage to Code Climate
doctrine/instantiator	1.0.5	A small, lightweight utility to instantiate objects in PHP without invoking their constructors
gpupo/cache	1.3.0	Caching library that implements PSR-6
gpupo/common	1.7.6	Common Objects
gpupo/common-sdk	2.2.15	Componente de uso comum entre SDKs para integração a partir de aplicações PHP com Restful webservices
guzzle/guzzle	v3.9.3	PHP HTTP client. This library is deprecated in favor of https://packagist.org/packages/guzzlehttp/guzzle
monolog/monolog	1.22.1	Sends your logs to files, sockets, inboxes, databases and various web services
myclabs/deep-copy	1.6.0	Create deep copies (clones) of your objects
padraic/humbug_get_contents	1.0.4	Secure wrapper for accessing HTTPS resources with file_get_contents for PHP 5.3+
padraic/phar-updater	1.0.3	A thing to make PHAR self-updating easy and secure.
phpdocumentor/reflection-common	1.0	Common reflection classes used by phpdocumentor to reflect the code structure
phpdocumentor/reflection-docblock	3.1.1	With this component, a library can provide support for annotations via DocBlocks or otherwise retrieve information that is embedded in a DocBlock.
phpdocumentor/type-resolver	0.2.1
phpspec/prophecy	v1.7.0	Highly opinionated mocking framework for PHP 5.3+
phpunit/php-code-coverage	4.0.7	Library that provides collection, processing, and rendering functionality for PHP code coverage information.
phpunit/php-file-iterator	1.4.2	FilterIterator implementation that filters files based on a list of suffixes.
phpunit/php-text-template	1.2.1	Simple template engine.
phpunit/php-timer	1.0.9	Utility class for timing
phpunit/php-token-stream	1.4.11	Wrapper around PHP's tokenizer extension.
phpunit/phpunit	5.7.17	The PHP Unit Testing framework.
phpunit/phpunit-mock-objects	3.4.3	Mock Object library for PHPUnit
psr/cache	1.0.0	Common interface for caching libraries
psr/log	1.0.2	Common interface for logging libraries
satooshi/php-coveralls	v1.0.1	PHP client library for Coveralls API
sebastian/code-unit-reverse-lookup 1.0.1	Looks up which function or method a line of code belongs to
sebastian/comparator	1.2.4	Provides the functionality to compare PHP values for equality
sebastian/diff	1.4.1	Diff implementation
sebastian/environment	2.0.0	Provides functionality to handle HHVM/PHP environments
sebastian/exporter	2.0.0	Provides the functionality to export PHP variables for visualization
sebastian/global-state	1.1.1	Snapshotting of global state
sebastian/object-enumerator	2.0.1	Traverses array structures and object graphs to enumerate all referenced objects
sebastian/peek-and-poke	dev-master a8295	Proxy for accessing non-public attributes and methods of an object
sebastian/recursion-context	2.0.0	Provides functionality to recursively process PHP variables
sebastian/resource-operations	1.0.0	Provides a list of PHP built-in functions that operate on resources
sebastian/version	2.0.1	Library that helps with managing the version number of Git-hosted PHP projects
symfony/config	v3.2.6	Symfony Config Component
symfony/console	v3.2.6	Symfony Console Component
symfony/debug	v3.2.6	Symfony Debug Component
symfony/event-dispatcher	v2.8.18	Symfony EventDispatcher Component
symfony/filesystem	v3.2.6	Symfony Filesystem Component
symfony/polyfill-mbstring	v1.3.0	Symfony polyfill for the Mbstring extension
symfony/stopwatch	v3.2.6	Symfony Stopwatch Component
symfony/yaml	v3.2.6	Symfony Yaml Component
twig/twig	v2.3.0	Twig, the flexible, fast, and secure template language for PHP
webmozart/assert	1.2.0	Assertions to validate method input/output with nice error messages.