# INSTRUCOES.md

Este documento descreve o planejamento de desenvolvimento do sistema de
integração automática entre Vetor e Bling.

## Objetivo Geral

Executar um serviço rodando em segundo plano que: - Atualiza o estoque
do Vetor para o Bling a cada 4 horas. - Importa pedidos faturados do
Bling para o Vetor a cada 15 minutos. - Opera de forma **autônoma**, com
renovação automática de token OAuth do Bling. - Permite visualização
posterior por meio de um painel web opcional (`php artisan serve`).

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

## Arquitetura do Processo

    [ Vetor ERP ] ←→ [ Sistema de Integração Laravel ] ←→ [ Bling ]
             ^                         |
             |                         |
             |                    Banco de Dados

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

## Estratégia de Autenticação

### Vetor (API)

-   A API do Vetor utiliza apenas um header de autorização.
-   Nenhuma autenticação adicional é necessária.

### Bling (OAuth 2.0)

-   Na primeira execução, um comando `php artisan bling:authorize` será
    usado para obter `access_token` e `refresh_token`.
-   O `refresh_token` será armazenado no banco.
-   Toda vez que for necessário fazer uma requisição ao Bling:
    -   Se o token estiver válido → usa normalmente.
    -   Se estiver expirado → um novo `access_token` será obtido
        automaticamente usando o `refresh_token`.

**Resultado:** Nenhuma intervenção manual será necessária após a
primeira autorização.

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

## Estrutura de Banco

### Tabela: `bling_tokens`

  Campo           Tipo       Finalidade
  --------------- ---------- --------------------------------------
  access_token    text       Token atual de acesso
  refresh_token   text       Token para gerar novos access tokens
  expires_at      datetime   Controle de expiração do token

### Tabela: `bling_sync_state`

  Campo           Tipo     Finalidade
  --------------- -------- -----------------------------------------
  last_order_id   bigint   Evita importar pedidos já sincronizados

### Tabela: `integration_logs`

  Campo        Tipo       Finalidade
  ------------ ---------- -------------------
  message      text       O que ocorreu
  context      json       Dados associados
  created_at   datetime   Registro temporal

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

## Scheduler

O sistema será executado continuamente via scheduler:

  -------------------------------------------------------------------------
  Tarefa            Frequência                          Job
  ----------------- ----------------------------------- -------------------
  Atualizar Estoque A cada 4 horas                      `SyncStockJob`
  (Vetor → Bling)                                       

  Importar Pedidos  A cada 15 minutos                   `ImportOrdersJob`
  (Bling → Vetor)                                       
  -------------------------------------------------------------------------

Será utilizado:

    php artisan schedule:work

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

## Variáveis de Ambiente (.env.example)

    # BLING OAuth Client Credentials
    BLING_CLIENT_ID=
    BLING_CLIENT_SECRET=
    BLING_REDIRECT_URI=https://localhost/bling/callback
    BLING_OAUTH_STATE=integracao_erp_autonomo

    # Acesso API Vetor
    VETOR_API_URL=https://api.vetor.com.br
    VETOR_AUTHORIZATION=Bearer SEU_TOKEN_AQUI

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

## Processo Passo a Passo

1.  Configurar `.env`
2.  Executar `php artisan migrate`
3.  Executar `php artisan bling:authorize` para gerar `refresh_token`
4.  Iniciar o scheduler:

```{=html}
<!-- -->
```
    php artisan schedule:work

5.  **Opcional:** iniciar painel web:

```{=html}
<!-- -->
```
    php artisan serve

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

## Futuro Painel Web (Opcional)

Permitirá: - Ver últimas sincronizações - Consultar logs - Testar
conexão com APIs - Forçar sincronização manual
