Merge pull request #19 from AlexandreBellas/develop

feat: atualizar para v300

README.md

@@ -6,7 +6,7 @@
 Pacote de integração com a [API v3 do ERP Bling](https://developer.bling.com.br)
 para PHP 8.2+. O mais completo existente.
 
-Atualizado com a versão `v296` da API ([veja o registro de alterações](https://developer.bling.com.br/changelogs#2024-03-13)).
+Atualizado com a versão `v300` da API ([veja o registro de alterações](https://developer.bling.com.br/changelogs#2024-03-13)).
 
 ## Instalação
 
@@ -40,6 +40,7 @@ Todas as entidades do Bling atualmente são permitidas para interação. São el
 
 - [x] Borderos (`->borderos`)
 - [x] Campos customizados (`->camposCustomizados`)
+- [x] Canais de Venda (`->canaisDeVenda`)
 - [x] Categorias - Lojas (`->categoriasLojas`)
 - [x] Categorias - Produtos (`->categoriasProdutos`)
 - [x] Categorias - Receitas e Despesas (`->categoriasReceitasDespesas`)

composer.json

@@ -2,7 +2,7 @@
   "name": "alebatistella/bling-erp-api",
   "description": "Pacote de integração com a API do Bling ERP",
   "type": "library",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "license": "MIT",
   "autoload": {
     "psr-4": {

src/Entities/CanaisDeVenda/CanaisDeVenda.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda;
+
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Get\GetParams;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Find\FindResponse;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Get\GetResponse;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\GetTypes\GetTypesParams;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\GetTypes\GetTypesResponse;
+use AleBatistella\BlingErpApi\Entities\Shared\BaseEntity;
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Request\RequestOptions;
+use AleBatistella\BlingErpApi\Exceptions\BlingApiException;
+use AleBatistella\BlingErpApi\Exceptions\BlingInternalException;
+
+/**
+ * Entidade para interação com canais de venda.
+ *
+ * @see https://developer.bling.com.br/referencia#/Canais%20de%20Venda
+ */
+class CanaisDeVenda extends BaseEntity
+{
+    /**
+     * Obtém canais de venda.
+     *
+     * @param GetParams|array|null $params Parâmetros para a busca
+     * 
+     * @return GetResponse
+     * @throws BlingApiException|BlingInternalException
+     *
+     * @see https://developer.bling.com.br/referencia#/Canais%20de%20Venda/get_canais_venda
+     */
+    public function get(GetParams|array|null $params = null): GetResponse
+    {
+        $response = $this->repository->index(
+            new RequestOptions(
+                endpoint: "canais-venda",
+                queryParams: $params
+            )
+        );
+
+        return GetResponse::fromResponse($response);
+    }
+
+    /**
+     * Obtém um canal de venda.
+     * 
+     * @param int $idCanalVenda ID do canal de venda
+     * 
+     * @return FindResponse
+     * @throws BlingApiException|BlingInternalException
+     * 
+     * @see https://developer.bling.com.br/referencia#/Canais%20de%20Venda/get_canais_venda__idCanalVenda_
+     */
+    public function find(int $idCanalVenda): FindResponse
+    {
+        $response = $this->repository->show(
+            new RequestOptions(
+                endpoint: "canais-venda/$idCanalVenda",
+            )
+        );
+
+        return FindResponse::fromResponse($response);
+    }
+
+    /**
+     * Obtém os tipos de canais de venda.
+     *
+     * @param GetTypesParams|array|null $params Parâmetros para a busca
+     * 
+     * @return GetTypesResponse
+     * @throws BlingApiException|BlingInternalException
+     *
+     * @see https://developer.bling.com.br/referencia#/Canais%20de%20Venda/get_canais_venda_tipos
+     */
+    public function getTypes(GetTypesParams|array|null $params = null): GetTypesResponse
+    {
+        $response = $this->repository->index(
+            new RequestOptions(
+                endpoint: "canais-venda/tipos",
+                queryParams: $params
+            )
+        );
+
+        return GetTypesResponse::fromResponse($response);
+    }
+}

src/Entities/CanaisDeVenda/Enum/Agrupador.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum;
+
+/**
+ * Enumerador de agrupador de um canal de venda.
+ */
+enum Agrupador: int
+{
+    case LOJA_VIRTUAL = 1;
+    case HUB = 2;
+    case MARKETPLACE = 3;
+    case API = 4;
+}

src/Entities/CanaisDeVenda/Enum/Situacao.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum;
+
+/**
+ * Enumerador da situação de um canal de venda.
+ */
+enum Situacao: int
+{
+    case HABILITADO = 1;
+    case DESABILITADO = 2;
+}

src/Entities/CanaisDeVenda/Schema/Find/FindResponse.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Find;
+
+use AleBatistella\BlingErpApi\Entities\Shared\BaseResponseRootObject;
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Request\ResponseOptions;
+
+/**
+ * Resposta da busca de um canal de venda pelo ID.
+ */
+readonly final class FindResponse extends BaseResponseRootObject
+{
+    /**
+     * Constrói o objeto.
+     *
+     * @param FindResponseData $data
+     */
+    public function __construct(
+        public FindResponseData $data
+    ) {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public static function fromResponse(ResponseOptions $response): static
+    {
+        if (is_null($response->body?->content)) {
+            static::throwForInconsistentResponseOptions($response);
+        }
+
+        return self::from($response->body->content);
+    }
+}

src/Entities/CanaisDeVenda/Schema/Find/FindResponseData.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Find;
+
+use AleBatistella\BlingErpApi\Entities\Shared\BaseResponseObject;
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Schema\Id;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum\Situacao;
+
+readonly final class FindResponseData extends BaseResponseObject
+{
+    /**
+     * Constrói o objeto.
+     *
+     * @param ?int $id
+     * @param ?string $descricao
+     * @param ?string $tipo
+     * @param ?Situacao $situacao
+     * @param ?FindResponseDataFiliais[] $filiais
+     */
+    public function __construct(
+        public ?int $id,
+        public ?string $descricao,
+        public ?string $tipo,
+        public ?Situacao $situacao,
+        public ?array $filiais,
+    ) {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected static function fromRules(): array
+    {
+        return [
+            'filiais' => FindResponseDataFiliais::class
+        ];
+    }
+}

src/Entities/CanaisDeVenda/Schema/Find/FindResponseDataFiliais.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Find;
+
+use AleBatistella\BlingErpApi\Entities\Shared\BaseResponseObject;
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Schema\Id;
+
+readonly final class FindResponseDataFiliais extends BaseResponseObject
+{
+    /**
+     * Constrói o objeto.
+     *
+     * @param ?string $cnpj
+     * @param ?string $unidadeNegocio
+     * @param ?Id $deposito
+     * @param ?bool $padrao
+     */
+    public function __construct(
+        public ?string $cnpj,
+        public ?string $unidadeNegocio,
+        public ?Id $deposito,
+        public ?bool $padrao,
+    ) {
+    }
+}

src/Entities/CanaisDeVenda/Schema/Get/GetParams.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Get;
+
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Request\QueryParams;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum\Situacao;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum\Agrupador;
+
+/**
+ * Parâmetros da busca de canais de venda paginados.
+ */
+readonly final class GetParams extends QueryParams
+{
+    public ?int $situacao;
+    public ?int $agrupador;
+
+    /**
+     * Constrói o objeto.
+     * 
+     * @param ?int $pagina N° da página da listagem
+     * @param ?int $limite Quantidade de registros que devem ser exibidos por página
+     * @param ?string[] $tipos Parâmetro para filtrar os registros através de uma lista de tipos de canal de venda
+     * @param Situacao|int|null $situacao Parâmetro para filtrar os registros através da situação
+     * @param Agrupador|int|null $agrupador Agrupador do canal de venda
+     */
+    public function __construct(
+        public ?int $pagina = null,
+        public ?int $limite = null,
+        public ?array $tipos = null,
+        Situacao|int|null $situacao = null,
+        Agrupador|int|null $agrupador = null,
+    ) {
+        $this->situacao = ($situacao instanceof Situacao) ? $situacao->value : $situacao;
+        $this->agrupador = ($agrupador instanceof Agrupador) ? $agrupador->value : $agrupador;
+
+        parent::__construct(objectToArray($this));
+    }
+}

src/Entities/CanaisDeVenda/Schema/Get/GetResponse.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Get;
+
+use AleBatistella\BlingErpApi\Entities\Shared\BaseResponseRootObject;
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Request\ResponseOptions;
+
+/**
+ * Resposta da listagem de canais de venda paginados.
+ */
+readonly final class GetResponse extends BaseResponseRootObject
+{
+    /**
+     * Constrói o objeto.
+     *
+     * @param GetResponseData[] $data
+     */
+    public function __construct(
+        public array $data
+    ) {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected static function fromRules(): array
+    {
+        return [
+            'data' => GetResponseData::class,
+        ];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public static function fromResponse(ResponseOptions $response): static
+    {
+        if (is_null($response->body?->content)) {
+            static::throwForInconsistentResponseOptions($response);
+        }
+
+        return self::from($response->body->content);
+    }
+}

src/Entities/CanaisDeVenda/Schema/Get/GetResponseData.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\Get;
+
+use AleBatistella\BlingErpApi\Entities\Shared\BaseResponseObject;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum\Situacao;
+
+readonly final class GetResponseData extends BaseResponseObject
+{
+    /**
+     * Constrói o objeto.
+     *
+     * @param ?int $id
+     * @param ?string $descricao
+     * @param ?string $tipo
+     * @param ?Situacao $situacao
+     */
+    public function __construct(
+        public ?int $id,
+        public ?string $descricao,
+        public ?string $tipo,
+        public ?Situacao $situacao,
+    ) {
+    }
+}

src/Entities/CanaisDeVenda/Schema/GetTypes/GetTypesParams.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Schema\GetTypes;
+
+use AleBatistella\BlingErpApi\Entities\Shared\DTO\Request\QueryParams;
+use AleBatistella\BlingErpApi\Entities\CanaisDeVenda\Enum\Agrupador;
+
+/**
+ * Parâmetros da busca de tipos de canais de venda paginados.
+ */
+readonly final class GetTypesParams extends QueryParams
+{
+    public ?int $agrupador;
+
+    /**
+     * Constrói o objeto.
+     * 
+     * @param Agrupador|int|null $agrupador Agrupador do canal de venda
+     */
+    public function __construct(
+        Agrupador|int|null $agrupador = null,
+    ) {
+        $this->agrupador = ($agrupador instanceof Agrupador) ? $agrupador->value : $agrupador;
+
+        parent::__construct(objectToArray($this));
+    }
+}