### List Products using Bling ERP API in PHP

Source: https://github.com/alexandrebellas/bling-erp-api-php/blob/main/README.md

An example of how to list all products from Bling ERP using the established API connection. It accesses the 'produtos' entity and calls the 'get' method.

```php
use AleBatistella\BlingErpApi\Bling;

$apiKey = "sua_api_key";
$blingConnection = new Bling($apiKey);

$products = $blingConnection->produtos->get();

var_dump($products);
```

--------------------------------

### Installation

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Install the Bling ERP API PHP package using Composer.

```APIDOC
## Installation

Install the package via Composer for PHP 8.2+ projects.

```bash
composer require alebatistella/bling-erp-api
```
```

--------------------------------

### Connection Setup

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Initialize the connection to the Bling API using your OAuth2 access token.

```APIDOC
## Criação de Conexão

Inicialização da conexão com a API do Bling utilizando o access token OAuth2.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

// O access_token é obtido através do fluxo OAuth2 do Bling
$accessToken = "seu_access_token_aqui";

// Cria a conexão com o Bling
$bling = new Bling($accessToken);

// Agora você pode acessar qualquer entidade
// Exemplo: listar produtos
$produtos = $bling->produtos->get();
```
```

--------------------------------

### Run Project Tests with PHPUnit

Source: https://github.com/alexandrebellas/bling-erp-api-php/blob/main/README.md

Executes the project's automated tests using PHPUnit. This command assumes the project dependencies have been installed.

```bash
vendor/phpunit/phpunit/phpunit -c phpunit.xml
```

--------------------------------

### GET /produtos/{id}

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Retrieve complete details of a specific product by its ID.

```APIDOC
## Produtos - Buscar por ID

Obtém os detalhes completos de um produto específico pelo seu ID.

### Method
GET

### Endpoint
/produtos/{id}

### Path Parameters
- **id** (int) - Required - The ID of the product to retrieve.

### Request Example
```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$idProduto = 12345678;
$produto = $bling->produtos->find($idProduto);

// Acessar dados do produto
echo "Nome: ".$produto->data->nome."\n";
echo "Código: ".$produto->data->codigo."\n";
echo "Preço: ".$produto->data->preco."\n";
echo "Preço Custo: ".$produto->data->precoCusto."\n";
echo "Unidade: ".$produto->data->unidade."\n";
echo "Tipo: ".$produto->data->tipo."\n";
echo "Situação: ".$produto->data->situacao."\n";
```

### Response
#### Success Response (200)
- **data** (object) - Object containing product details.
  - **id** (int) - Product ID.
  - **nome** (string) - Product name.
  - **codigo** (string) - Product code.
  - **preco** (float) - Product price.
  - **precoCusto** (float) - Product cost price.
  - **unidade** (string) - Product unit of measure.
  - **tipo** (string) - Product type ('P' for Product, 'S' for Service).
  - **situacao** (string) - Product status ('A' for Active).

#### Response Example
```json
{
  "data": {
    "id": 12345678,
    "nome": "Camiseta Básica Preta",
    "codigo": "CAM-001-P",
    "preco": 79.90,
    "precoCusto": 25.00,
    "unidade": "UN",
    "tipo": "P",
    "situacao": "A"
  }
}
```
```

--------------------------------

### Install Bling ERP API PHP Package

Source: https://github.com/alexandrebellas/bling-erp-api-php/blob/main/README.md

Installs the Bling ERP API PHP package using Composer. This is the primary method for adding the library to your PHP project.

```bash
composer require alebatistella/bling-erp-api
```

--------------------------------

### List Products from Bling ERP API

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Retrieves a list of products registered in Bling, supporting filtering and pagination. The example shows how to fetch all products and how to apply specific criteria like page number, limit, and product type.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// List all products
$produtos = $bling->produtos->get();

// List with filters
$produtosFiltrados = $bling->produtos->get([
    'pagina' => 1,
    'limite' => 100,
    'criterio' => 1, // 1 = Active
    'tipo' => 'P'    // P = Product, S = Service
]);

// Access the data
foreach ($produtos->data as $produto) {
    echo "ID: {$produto->id}\n";
    echo "Name: {$produto->nome}\n";
    echo "Code: {$produto->codigo}\n";
    echo "Price: {$produto->preco}\n";
}

```

--------------------------------

### Manage Logistics Configurations with Bling ERP API (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Illustrates how to manage logistics configurations and carriers using the Bling ERP API. The examples cover listing all logistics settings, finding a specific one by ID, creating new logistics entries (e.g., Correios services), updating existing configurations, and deleting them. An access token is necessary to use these functions.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar logísticas
$logisticas = $bling->logisticas->get();

// Buscar logística específica
$idLogistica = 7788;
$logistica = $bling->logisticas->find($idLogistica);

// Criar nova logística
$novaLogistica = $bling->logisticas->create([
    'descricao' => 'Correios - PAC',
    'servico' => 'PAC',
    'tipo' => 'C', // C = Correios
    'prazoEntrega' => 10
]);

// Atualizar logística
$bling->logisticas->update($idLogistica, [
    'descricao' => 'Correios - SEDEX',
    'prazoEntrega' => 5
]);

// Excluir logística
$bling->logisticas->delete($idLogistica);

```

--------------------------------

### GET /produtos

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Retrieve a list of registered products in Bling with support for filters and pagination.

```APIDOC
## Produtos - Listar

Obtém a lista de produtos cadastrados no Bling com suporte a filtros e paginação.

### Method
GET

### Endpoint
/produtos

### Query Parameters
- **pagina** (int) - Optional - Page number for pagination.
- **limite** (int) - Optional - Number of items per page.
- **criterio** (int) - Optional - Filter criterion (e.g., 1 for Active).
- **tipo** (string) - Optional - Type filter (e.g., 'P' for Product, 'S' for Service).

### Request Example
```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar todos os produtos
$produtos = $bling->produtos->get();

// Listar com filtros
$produtosFiltrados = $bling->produtos->get([
    'pagina' => 1,
    'limite' => 100,
    'criterio' => 1, // 1 = Ativos
    'tipo' => 'P'    // P = Produto, S = Serviço
]);

// Acessar os dados
foreach ($produtos->data as $produto) {
    echo "ID: ".$produto->id."\n";
    echo "Nome: ".$produto->nome."\n";
    echo "Código: ".$produto->codigo."\n";
    echo "Preço: ".$produto->preco."\n";
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of product objects.
  - **id** (int) - Product ID.
  - **nome** (string) - Product name.
  - **codigo** (string) - Product code.
  - **preco** (float) - Product price.

#### Response Example
```json
{
  "data": [
    {
      "id": 12345678,
      "nome": "Camiseta Básica Preta",
      "codigo": "CAM-001-P",
      "preco": 79.90
    }
  ]
}
```
```

--------------------------------

### Query Sellers with Bling ERP API (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Provides examples for querying registered sellers in the Bling ERP system. It shows how to list sellers with pagination and filtering (e.g., by status), and how to find a specific seller by their ID. The code requires an access token for the Bling API.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar vendedores
$vendedores = $bling->vendedores->get([
    'pagina' => 1,
    'limite' => 100,
    'situacao' => 'A' // A = Ativo
]);

foreach ($vendedores->data as $vendedor) {
    echo "ID: {$vendedor->id}\n";
    echo "Nome: {$vendedor->nome}\n";
    echo "Comissão: {$vendedor->comissao}%\n";
}

// Buscar vendedor específico
$idVendedor = 5566778;
$vendedor = $bling->vendedores->find($idVendedor);

echo "Nome: {$vendedor->data->nome}\n";
echo "Comissão: {$vendedor->data->comissao}%\n";

```

--------------------------------

### POST /produtos

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Register a new product in Bling with all necessary information.

```APIDOC
## Produtos - Criar

Cadastra um novo produto no Bling com todas as informações necessárias.

### Method
POST

### Endpoint
/produtos

### Request Body
- **nome** (string) - Required - Product name.
- **codigo** (string) - Required - Product code.
- **preco** (float) - Required - Product price.
- **precoCusto** (float) - Optional - Product cost price.
- **tipo** (string) - Required - Product type ('P' for Product, 'S' for Service).
- **situacao** (string) - Required - Product status ('A' for Active).
- **formato** (string) - Optional - Product format ('S' for Simple).
- **unidade** (string) - Optional - Unit of measure.
- **pesoLiquido** (float) - Optional - Net weight.
- **pesoBruto** (float) - Optional - Gross weight.
- **gtin** (string) - Optional - GTIN.
- **gtinEmbalagem** (string) - Optional - Package GTIN.
- **largura** (int) - Optional - Width.
- **altura** (int) - Optional - Height.
- **profundidade** (int) - Optional - Depth.
- **estoque** (object) - Optional - Stock information.
  - **minimo** (int) - Minimum stock.
  - **maximo** (int) - Maximum stock.
  - **crossdocking** (int) - Cross-docking stock.
  - **localizacao** (string) - Stock location.
- **categoria** (object) - Optional - Category information.
  - **id** (int) - Category ID.

### Request Example
```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$novoProduto = $bling->produtos->create([
    'nome' => 'Camiseta Básica Preta',
    'codigo' => 'CAM-001-P',
    'preco' => 79.90,
    'precoCusto' => 25.00,
    'tipo' => 'P', // P = Produto
    'situacao' => 'A', // A = Ativo
    'formato' => 'S', // S = Simples
    'unidade' => 'UN',
    'pesoLiquido' => 0.2,
    'pesoBruto' => 0.25,
    'gtin' => '7891234567890',
    'gtinEmbalagem' => '17891234567890',
    'largura' => 30,
    'altura' => 2,
    'profundidade' => 40,
    'estoque' => [
        'minimo' => 10,
        'maximo' => 100,
        'crossdocking' => 0,
        'localizacao' => 'A1-P2'
    ],
    'categoria' => [
        'id' => 12345 // ID da categoria
    ]
]);

echo "Produto criado com ID: ".$novoProduto->data->id."\n";
```

### Response
#### Success Response (200)
- **data** (object) - Object containing the created product's details.
  - **id** (int) - The ID of the newly created product.

#### Response Example
```json
{
  "data": {
    "id": 98765432
  }
}
```
```

--------------------------------

### Create Bling ERP API Connection in PHP

Source: https://github.com/alexandrebellas/bling-erp-api-php/blob/main/README.md

Demonstrates how to create a new connection to the Bling ERP API using an API key. The Bling class is instantiated with the provided API key.

```php
use AleBatistella\BlingErpApi\Bling;

$apiKey = "sua_api_key";
$blingConnection = new Bling($apiKey);
```

--------------------------------

### Create New Product in Bling ERP API

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Registers a new product in Bling with all necessary information, including pricing, stock levels, and dimensions. The response includes the ID of the newly created product.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$novoProduto = $bling->produtos->create([
    'nome' => 'Black Basic T-Shirt',
    'codigo' => 'CAM-001-P',
    'preco' => 79.90,
    'precoCusto' => 25.00,
    'tipo' => 'P', // P = Product
    'situacao' => 'A', // A = Active
    'formato' => 'S', // S = Simple
    'unidade' => 'UN',
    'pesoLiquido' => 0.2,
    'pesoBruto' => 0.25,
    'gtin' => '7891234567890',
    'gtinEmbalagem' => '17891234567890',
    'largura' => 30,
    'altura' => 2,
    'profundidade' => 40,
    'estoque' => [
        'minimo' => 10,
        'maximo' => 100,
        'crossdocking' => 0,
        'localizacao' => 'A1-P2'
    ],
    'categoria' => [
        'id' => 12345 // Category ID
    ]
]);

echo "Product created with ID: {$novoProduto->data->id}\n";

```

--------------------------------

### Listar Entidades Disponíveis na Bling ERP API (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Este snippet demonstra como acessar e listar todas as entidades disponíveis na Bling ERP API utilizando a biblioteca PHP. Ele inicializa a conexão com a API usando um access token e, em seguida, acessa cada entidade como uma propriedade do objeto Bling.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Entidades disponíveis:
$bling->borderos;               // Borderôs
$bling->camposCustomizados;     // Campos Customizados
$bling->canaisDeVenda;          // Canais de Venda
$bling->categoriasLojas;        // Categorias - Lojas
$bling->categoriasProdutos;     // Categorias - Produtos
$bling->categoriasReceitasDespesas; // Categorias - Receitas e Despesas
$bling->contasPagar;            // Contas a Pagar
$bling->contasReceber;          // Contas a Receber
$bling->contasContabeis;        // Contas Contábeis
$bling->contatos;               // Contatos
$bling->contatosTipos;          // Tipos de Contatos
$bling->contratos;              // Contratos
$bling->depositos;              // Depósitos
$bling->empresas;               // Empresas
$bling->estoques;               // Estoques
$bling->formasDePagamentos;     // Formas de Pagamento
$bling->gruposDeProdutos;       // Grupos de Produtos
$bling->homologacao;            // Homologação
$bling->logisticas;             // Logísticas
$bling->logisticasEtiquetas;    // Logísticas - Etiquetas
$bling->logisticasObjetos;      // Logísticas - Objetos
$bling->logisticasRemessas;     // Logísticas - Remessas
$bling->logisticasServicos;     // Logísticas - Serviços
$bling->naturezasDeOperacoes;   // Naturezas de Operações
$bling->nfces;                  // NFC-e (Notas Fiscais de Consumidor)
$bling->nfses;                  // NFS-e (Notas Fiscais de Serviço)
$bling->nfes;                   // NF-e (Notas Fiscais Eletrônicas)
$bling->notificacoes;           // Notificações
$bling->ordensDeProducao;       // Ordens de Produção
$bling->pedidosCompras;         // Pedidos de Compras
$bling->pedidosVendas;          // Pedidos de Vendas
$bling->produtos;               // Produtos
$bling->produtosEstruturas;     // Produtos - Estruturas
$bling->produtosFornecedores;   // Produtos - Fornecedores
$bling->produtosLojas;          // Produtos - Lojas
$bling->produtosVariacoes;      // Produtos - Variações
$bling->propostasComerciais;    // Propostas Comerciais
$bling->situacoes;              // Situações
$bling->situacoesModulos;       // Situações - Módulos
$bling->situacoesTransicoes;    // Situações - Transições
$bling->usuarios;               // Usuários
$bling->vendedores;             // Vendedores

```

--------------------------------

### Gerenciar Notas Fiscais Eletrônicas (NF-e) - Listar, Buscar, Criar, Enviar (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Gerencia notas fiscais eletrônicas (NF-e) no Bling ERP. Permite listar NF-es com filtros por data e limite, buscar uma NF-e específica pelo ID, criar novas NF-es com detalhes como tipo, contato, natureza da operação e itens, e enviar NF-es para a SEFAZ. Requer um token de acesso e IDs relevantes.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar NF-es
$nfes = $bling->nfes->get([
    'pagina' => 1,
    'limite' => 100,
    'dataEmissaoInicial' => '2024-01-01',
    'dataEmissaoFinal' => '2024-12-31'
]);

// Buscar NF-e específica
$idNfe = 11223344;
$nfe = $bling->nfes->find($idNfe);

echo "Número: {$nfe->data->numero}\n";
echo "Série: {$nfe->data->serie}\n";
echo "Chave: {$nfe->data->chaveAcesso}\n";
echo "Situação: {$nfe->data->situacao}\n";

// Criar NF-e
$novaNfe = $bling->nfes->create([
    'tipo' => 1, // 1 = Saída, 0 = Entrada
    'contato' => ['id' => 98765432],
    'naturezaOperacao' => ['id' => 12345],
    'itens' => [
        [
            'produto' => ['id' => 12345678],
            'quantidade' => 1,
            'valor' => 100.00
        ]
    ]
]);

// Enviar NF-e para SEFAZ
$resultado = $bling->nfes->send($novaNfe->data->id);
echo "NF-e enviada! Protocolo: {$resultado->data->protocolo}\n";

// Lançar estoque da NF-e
$bling->nfes->postStock($idNfe);

// Lançar contas da NF-e
$bling->nfes->postAccounts($idNfe);

// Excluir múltiplas NF-es
$bling->nfes->deleteMany([11223344, 11223345]);

```

--------------------------------

### Sales Orders - Create

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Creates a new sales order with items and shipping information.

```APIDOC
## POST /pedidosVendas

### Description
Creates a new sales order with items and shipping information.

### Method
POST

### Endpoint
/pedidosVendas

### Parameters
#### Request Body
- **numero** (integer) - Required - The order number.
- **data** (string) - Required - The order date (YYYY-MM-DD).
- **dataSaida** (string) - Optional - The shipping date (YYYY-MM-DD).
- **dataPrevista** (string) - Optional - The expected delivery date (YYYY-MM-DD).
- **contato** (object) - Required - Contact information.
  - **id** (integer) - Required - The contact ID.
- **itens** (array) - Required - An array of items in the order.
  - **produto** (object) - Required - Product details.
    - **id** (integer) - Required - The product ID.
  - **quantidade** (integer) - Required - The quantity of the product.
  - **valor** (float) - Required - The unit price of the product.
  - **desconto** (object) - Optional - Discount information.
    - **valor** (float) - Required - The discount amount.
    - **tipo** (string) - Required - The discount type ('PERCENTUAL' or 'VALOR').
- **transporte** (object) - Optional - Shipping information.
  - **fretePorConta** (integer) - Required - Who pays for shipping (0 = Issuer, 1 = Receiver).
  - **frete** (float) - Optional - The shipping cost.
  - **transportador** (object) - Optional - Carrier information.
    - **id** (integer) - Required - The carrier ID.
- **vendedor** (object) - Optional - Salesperson information.
  - **id** (integer) - Required - The salesperson ID.
- **observacoes** (string) - Optional - Order notes.
- **observacoesInternas** (string) - Optional - Internal order notes.

### Request Example
```json
{
  "numero": 1001,
  "data": "2024-01-15",
  "dataSaida": "2024-01-16",
  "dataPrevista": "2024-01-20",
  "contato": {
    "id": 98765432
  },
  "itens": [
    {
      "produto": {"id": 12345678},
      "quantidade": 2,
      "valor": 79.90,
      "desconto": {
        "valor": 10,
        "tipo": "PERCENTUAL"
      }
    },
    {
      "produto": {"id": 12345679},
      "quantidade": 1,
      "valor": 149.90
    }
  ],
  "transporte": {
    "fretePorConta": 0,
    "frete": 25.00,
    "transportador": {
      "id": 11223344
    }
  },
  "vendedor": {
    "id": 5566778
  },
  "observacoes": "Pedido urgente - entregar pela manhã",
  "observacoesInternas": "Cliente VIP"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created order details.
  - **id** (integer) - The ID of the created sales order.

#### Response Example
```json
{
  "data": {
    "id": 123456789
  }
}
```
```

--------------------------------

### Operações de Estoque e Contas para Pedidos de Vendas (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Realiza operações de estoque e contas financeiras associadas a um pedido de venda. Permite lançar e estornar estoque (com opção de depósito específico), lançar e estornar contas a receber, e alterar a situação do pedido. Requer o ID do pedido e, para algumas operações, o ID de um depósito ou situação.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$idPedido = 55667788;

// Lançar estoque (baixa no estoque)
$bling->pedidosVendas->postStock($idPedido);
echo "Estoque lançado!\n";

// Lançar estoque em depósito específico
$idDeposito = 1234;
$bling->pedidosVendas->postStockToDeposit($idPedido, $idDeposito);
echo "Estoque lançado no depósito!\n";

// Estornar estoque (devolução)
$bling->pedidosVendas->reverseStock($idPedido);
echo "Estoque estornado!\n";

// Lançar contas a receber
$bling->pedidosVendas->postAccounts($idPedido);
echo "Contas lançadas!\n";

// Estornar contas
$bling->pedidosVendas->reverseAccounts($idPedido);
echo "Contas estornadas!\n";

// Alterar situação do pedido
$idSituacao = 9; // ID da nova situação
$bling->pedidosVendas->changeSituation($idPedido, $idSituacao);
echo "Situação alterada!\n";

```

--------------------------------

### Sales Orders - Stock and Accounts Operations

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Handles stock and financial account postings and reversals for sales orders.

```APIDOC
## Sales Orders - Stock and Accounts Operations

### Description
Performs stock and financial account postings and reversals for sales orders.

### Method
POST

### Endpoints
- `/pedidosVendas/{id}/estoque` (Post Stock)
- `/pedidosVendas/{id}/estoque/deposito/{idDeposito}` (Post Stock to Deposit)
- `/pedidosVendas/{id}/estornarEstoque` (Reverse Stock)
- `/pedidosVendas/{id}/contas` (Post Accounts)
- `/pedidosVendas/{id}/estornarContas` (Reverse Accounts)
- `/pedidosVendas/{id}/alterarSituacao` (Change Situation)

### Parameters
#### Path Parameters
- **id** (integer) - Required - The sales order ID.
- **idDeposito** (integer) - Required - The deposit ID (for posting stock to a specific deposit).
- **idSituacao** (integer) - Required - The ID of the new situation (for changing situation).

### Actions
- **Post Stock**: Posts stock for the sales order (decreases inventory).
- **Post Stock to Deposit**: Posts stock for the sales order to a specific deposit.
- **Reverse Stock**: Reverses the stock posting for the sales order (returns to inventory).
- **Post Accounts**: Posts financial accounts receivable for the sales order.
- **Reverse Accounts**: Reverses the financial accounts posting for the sales order.
- **Change Situation**: Changes the situation of the sales order.

### Request Example (Post Stock)
```php
$bling->pedidosVendas->postStock(55667788);
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the operation.

#### Response Example
```json
{
  "message": "Estoque lançado!"
}
```
```

--------------------------------

### Manage Product Categories with Bling ERP API (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Demonstrates how to manage product categories using the Bling ERP API. This includes listing all categories, finding a specific category by ID, creating new categories and subcategories, updating existing categories, and deleting categories. It requires an active Bling API access token.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar categorias
$categorias = $bling->categoriasProdutos->get();

foreach ($categorias->data as $categoria) {
    echo "ID: {$categoria->id}\n";
    echo "Nome: {$categoria->descricao}\n";
}

// Buscar categoria específica
$idCategoria = 12345;
$categoria = $bling->categoriasProdutos->find($idCategoria);

// Criar categoria
$novaCategoria = $bling->categoriasProdutos->create([
    'descricao' => 'Eletrônicos',
    'categoriaPai' => ['id' => 0] // 0 = categoria raiz
]);

// Criar subcategoria
$subCategoria = $bling->categoriasProdutos->create([
    'descricao' => 'Smartphones',
    'categoriaPai' => ['id' => $novaCategoria->data->id]
]);

// Atualizar categoria
$bling->categoriasProdutos->update($idCategoria, [
    'descricao' => 'Eletrônicos e Acessórios'
]);

// Excluir categoria
$bling->categoriasProdutos->delete($idCategoria);

```

--------------------------------

### Handle Bling ERP API Errors Gracefully (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Demonstrates robust error handling for Bling ERP API interactions using PHP. It shows how to catch specific exceptions like `BlingApiException` (for API-returned errors with details) and `BlingInternalException` (for library-level issues), as well as general exceptions. This pattern helps in diagnosing and responding to problems during API calls.

```php
<?php

use AleBatistella\BlingErpApi\Bling;
use AleBatistella\BlingErpApi\Exceptions\BlingApiException;
use AleBatistella\BlingErpApi\Exceptions\BlingInternalException;

$bling = new Bling($accessToken);

try {
    $produto = $bling->produtos->find(99999999);
} catch (BlingApiException $e) {
    // Erro retornado pela API do Bling
    echo "Erro da API: " . $e->getMessage() . "\n";
    echo "Código: " . $e->getCode() . "\n";

    // Detalhes do erro
    $errors = $e->getErrors();
    foreach ($errors as $error) {
        echo "Campo: {$error->campo}\n";
        echo "Mensagem: {$error->mensagem}\n";
    }
} catch (BlingInternalException $e) {
    // Erro interno da biblioteca
    echo "Erro interno: " . $e->getMessage() . "\n";
} catch (\Exception $e) {
    // Outros erros
    echo "Erro: " . $e->getMessage() . "\n";
}

```

--------------------------------

### Gerenciar Depósitos com Bling ERP API PHP

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Exemplos de como gerenciar depósitos (almoxarifados) usando a Bling ERP API em PHP. Permite listar todos os depósitos, buscar um depósito específico, criar novos depósitos e atualizar depósitos existentes.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Listar depósitos
$depositos = $bling->depositos->get();

foreach ($depositos->data as $deposito) {
    echo "ID: {$deposito->id}\n";
    echo "Descrição: {$deposito->descricao}\n";
    echo "Situação: {$deposito->situacao}\n";
}

// Buscar depósito específico
$idDeposito = 1234;
$deposito = $bling->depositos->find($idDeposito);

// Criar novo depósito
$novoDeposito = $bling->depositos->create([
    'descricao' => 'Depósito Centro de Distribuição',
    'situacao' => 'A', // A = Ativo
    'padrao' => false,
    'desconsiderarSaldo' => false
]);

echo "Depósito criado com ID: {$novoDeposito->data->id}\n";

// Atualizar depósito
$bling->depositos->update($idDeposito, [
    'descricao' => 'CD Principal - Atualizado',
    'situacao' => 'A'
]);

```

--------------------------------

### Create Bling ERP API Connection with Access Token

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Initializes a connection to the Bling ERP API using a pre-obtained OAuth2 access token. The `$accessToken` is crucial for authenticating your requests to the API. After instantiation, you can access various Bling entities like 'produtos' (products).

```php
<?php

use AleBatistella\BlingErpApi\Bling;

// The access_token is obtained through the Bling OAuth2 flow
$accessToken = "seu_access_token_aqui";

// Create the connection with Bling
$bling = new Bling($accessToken);

// Now you can access any entity
// Example: list products
$produtos = $bling->produtos->get();

```

--------------------------------

### Criar Pedido de Venda com Itens e Informações de Entrega (PHP)

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Cria um novo pedido de venda no Bling ERP. Este método requer um token de acesso e permite especificar detalhes do pedido, como número, datas, informações de contato, itens com seus respectivos valores e descontos, detalhes de transporte e vendedor. Retorna o ID do pedido criado.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$novoPedido = $bling->pedidosVendas->create([
    'numero' => 1001,
    'data' => '2024-01-15',
    'dataSaida' => '2024-01-16',
    'dataPrevista' => '2024-01-20',
    'contato' => [
        'id' => 98765432
    ],
    'itens' => [
        [
            'produto' => ['id' => 12345678],
            'quantidade' => 2,
            'valor' => 79.90,
            'desconto' => [
                'valor' => 10,
                'tipo' => 'PERCENTUAL' // ou 'VALOR'
            ]
        ],
        [
            'produto' => ['id' => 12345679],
            'quantidade' => 1,
            'valor' => 149.90
        ]
    ],
    'transporte' => [
        'fretePorConta' => 0, // 0 = Emitente, 1 = Destinatário
        'frete' => 25.00,
        'transportador' => [
            'id' => 11223344
        ]
    ],
    'vendedor' => [
        'id' => 5566778
    ],
    'observacoes' => 'Pedido urgente - entregar pela manhã',
    'observacoesInternas' => 'Cliente VIP'
]);

echo "Pedido criado com ID: {$novoPedido->data->id}\n";

```

--------------------------------

### Product Categories API

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Manage product categories for organizing products. This includes listing, finding, creating, updating, and deleting categories.

```APIDOC
## Product Categories API

### Description
Manages product categories for organizing products within the Bling ERP system.

### Method
GET, POST, PUT, DELETE

### Endpoint
`/categoriasProdutos`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the category to find, update, or delete.

#### Query Parameters
- **pagina** (integer) - Optional - The page number for listing categories.
- **limite** (integer) - Optional - The number of categories to return per page.

#### Request Body
##### Create/Update Category
- **descricao** (string) - Required - The name of the category.
- **categoriaPai** (object) - Optional - An object containing the parent category ID. `{'id': 0}` for root categories.

### Request Example
```php
// Listar categorias
$categorias = $bling->categoriasProdutos->get();

// Criar categoria
$novaCategoria = $bling->categoriasProdutos->create([
    'descricao' => 'Eletrônicos',
    'categoriaPai' => ['id' => 0]
]);

// Atualizar categoria
$bling->categoriasProdutos->update(12345, [
    'descricao' => 'Eletrônicos e Acessórios'
]);

// Excluir categoria
$bling->categoriasProdutos->delete(12345);
```

### Response
#### Success Response (200)
- **data** (array) - A list of category objects, each containing `id` and `descricao`.
- **data** (object) - A single category object when finding, creating, or updating.

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "descricao": "Categoria Exemplo"
    }
  ]
}
```
```

--------------------------------

### Gerenciar Estoques com Bling ERP API PHP

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Exemplos de como gerenciar saldos e movimentações de estoque usando a Bling ERP API em PHP. Permite obter saldos de produtos, saldos por depósito, criar movimentações de entrada/saída e atualizar registros de estoque.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

// Obter saldo de estoque de produtos
$saldos = $bling->estoques->getBalances([12345678, 12345679]);

foreach ($saldos->data as $saldo) {
    echo "Produto ID: {$saldo->produto->id}\n";
    echo "Saldo Físico: {$saldo->saldoFisicoTotal}\n";
    echo "Saldo Virtual: {$saldo->saldoVirtualTotal}\n";
}

// Obter saldo por depósito
$idDeposito = 1234;
$saldoDeposito = $bling->estoques->findBalance($idDeposito, [12345678]);

// Criar movimentação de estoque
$movimentacao = $bling->estoques->create([
    'produto' => ['id' => 12345678],
    'deposito' => ['id' => 1234],
    'operacao' => 'E', // E = Entrada, S = Saída
    'quantidade' => 10,
    'preco' => 50.00,
    'custo' => 30.00,
    'observacoes' => 'Entrada de mercadoria - NF 12345'
]);

echo "Movimentação criada!\n";

// Atualizar registro de estoque
$idEstoque = 9876;
$bling->estoques->update($idEstoque, [
    'quantidade' => 15,
    'observacoes' => 'Ajuste de inventário'
]);

```

--------------------------------

### OAuth2 Authentication Flow

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Complete OAuth2 authentication flow to obtain the necessary access token.

```APIDOC
## Autenticação OAuth2

Fluxo completo de autenticação OAuth2 para obtenção do access token necessário para a biblioteca.

```php
<?php

// Passo 1: Redirecionar o usuário para autorização
$clientId = "seu_client_id";
$clientSecret = "seu_client_secret";
$redirectUri = "https://seusite.com/callback";
$state = bin2hex(random_bytes(16));

$authUrl = "https://www.bling.com.br/Api/v3/oauth/authorize?" . http_build_query([
    'response_type' => 'code',
    'client_id' => $clientId,
    'state' => $state,
    'redirect_uri' => $redirectUri
]);

// Redireciona o usuário para $authUrl

// Passo 2: No callback, trocar o código pelo access_token
$code = $_GET['code']; // Código recebido no callback

$ch = curl_init('https://www.bling.com.br/Api/v3/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => "$clientId:$clientSecret",
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'authorization_code',
        'code' => $code
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$accessToken = $response['access_token'];
// Use este $accessToken para criar a conexão Bling
```
```

--------------------------------

### Create Contact - PHP

Source: https://context7.com/alexandrebellas/bling-erp-api-php/llms.txt

Registers a new contact, which can be a customer or a supplier, in the Bling ERP system. It requires detailed information including personal/business data, contact details, and address. The `create` method returns the ID of the newly created contact.

```php
<?php

use AleBatistella\BlingErpApi\Bling;

$bling = new Bling($accessToken);

$novoContato = $bling->contatos->create([
    'nome' => 'João da Silva',
    'codigo' => 'CLI-001',
    'situacao' => 'A',
    'numeroDocumento' => '123.456.789-00',
    'telefone' => '(11) 99999-9999',
    'celular' => '(11) 98888-8888',
    'fantasia' => 'João Comercial',
    'tipoPessoa' => 'F', // F = Física, J = Jurídica
    'contribuinte' => 9, // 9 = Não contribuinte
    'email' => 'joao@email.com',
    'endereco' => [
        'endereco' => 'Rua das Flores',
        'numero' => '123',
        'complemento' => 'Apto 45',
        'bairro' => 'Centro',
        'cep' => '01234-567',
        'municipio' => 'São Paulo',
        'uf' => 'SP',
        'pais' => 'Brasil'
    ],
    'tiposContato' => [
        ['id' => 1], // Cliente
        ['id' => 2]  // Fornecedor
    ]
]);

echo "Contato criado com ID: {$novoContato->data->id}\n";

```