# Integração com o Bling

## Diretrizes

- A integração usará exclusivamente a API oficial do Bling.
- A autenticação usará OAuth 2.0.
- `client_id` e `client_secret` ficarão somente em variáveis de ambiente e serão expostos à aplicação por configuração.
- Access tokens e refresh tokens deverão ser armazenados com proteção adequada e nunca poderão aparecer em logs.
- Endpoints, campos e comportamentos não podem ser inferidos ou inventados.
- Toda implementação deve consultar a documentação oficial atual correspondente à fase em desenvolvimento.
- Uma Ordem de Serviço somente poderá ser criada depois de confirmação explícita do usuário.
- A proteção contra duplicidade e a idempotência serão implementadas antes da criação real de ordens ser disponibilizada.

## OAuth 2.0 implementado

O ServiceGPT usa Authorization Code. `GET /api/integrations/bling/authorize` cria um state aleatório no cache com expiração curta e redireciona para `https://www.bling.com.br/Api/v3/oauth/authorize`. O callback consome o state uma única vez e troca o code imediatamente (o code expira em cerca de 30 segundos).

O token endpoint é `https://api.bling.com.br/Api/v3/oauth/token`. As trocas e renovações usam POST form-urlencoded, Basic Auth do aplicativo e `enable-jwt: 1`. JWT é tratado como credencial opaca; claims não são usados pela aplicação.

Os tokens usam casts `encrypted`, ficam ocultos na serialização e nunca são logados. `token_expires_at` deriva de `expires_in`; a margem `BLING_TOKEN_REFRESH_MARGIN` antecipa o refresh. `BlingAuthService::validAccessToken()` centraliza a decisão, usa lock de cache e só persiste resposta válida, preservando tokens em falhas.

## Configuração e teste manual

Configure `BLING_CLIENT_ID`, `BLING_CLIENT_SECRET` e `BLING_REDIRECT_URI` no `.env`, após cadastrar o aplicativo e seu link de redirecionamento na Central de Extensões do Bling. Acesse `/api/integrations/bling/authorize`, autorize o aplicativo e confirme o retorno do callback; então verifique a conexão ativa no banco. Nunca inclua credenciais reais nesta documentação ou no repositório.

## Consulta de clientes (Fase 3)

A URL base é `https://api.bling.com.br/Api/v3`. O recurso externo é Contatos: o domínio ServiceGPT o apresenta como Customer. As operações de leitura são `GET /contatos` e `GET /contatos/{idContato}`, sempre com Bearer token. A busca usa o filtro oficial `pesquisa`; a paginação usa `pagina` e `limite`. O DTO interno normaliza somente id, nome, situação, documento, telefone, celular e tipo.

Em 401, a chamada renova o token e repete a requisição uma única vez. 403, 404, 429, 5xx e falhas de conexão retornam mensagens seguras; 429 propaga `Retry-After` numérico. A API possui limite de 3 requisições por segundo e 120.000 por dia. Não há nenhuma operação de escrita de contatos nesta fase.
## Ordem de serviço (Fase 4)

O endpoint interno estruturado `POST /api/integrations/bling/service-orders` encaminha a criação para `POST https://api.bling.com.br/Api/v3/ordens/servico`, com JSON e Bearer token. Ele exige `customer_id`, convertido para `contato.id`; não aceita payload bruto do Bling nem linguagem natural.

Os campos suportados são datas, equipamento e número de série, descrição do problema, observações, garantia, técnico e orçamento. Itens em `services` sempre exigem `product_id`, convertido para `produto.id`; itens em `parts` exigem `product_id` e `quantity`. Parcelas, busca ou criação de produtos e financeiro permanecem fora do escopo.

Falhas 400, 401, 403, 404, 422, 429 e 5xx recebem respostas normalizadas, sem payload bruto. O `Retry-After` numérico é propagado em 429. POST não recebe retry automático: um 401 é retornado de forma controlada e timeout retorna que o resultado da criação é desconhecido, pois uma repetição poderia duplicar a OS. Idempotência, reconciliação e confirmação explícita pertencem à Fase 5.

## Clientes de IA (Fase 6)

`POST /api/ai/service-order-requests` não chama o Bling. Ele apenas valida e armazena uma solicitação estruturada para o fluxo de confirmação da Fase 5. Não há criação direta de OS por IA, interpretação de texto, integração com OpenAI ou WhatsApp nesta fase. Depois de pronta, a solicitação usa o mesmo endpoint de confirmação, lock, idempotência e tratamento de `UNKNOWN` já estabelecidos.
