# Integrações

## Padrão Adapter

O domínio trabalha com contratos internos; cada fornecedor possui adapter. Exemplo:

```php
interface MarketplaceAdapter
{
    public function refreshAuthorization(Connection $connection): AuthorizationResult;
    public function publishListing(PublishListingCommand $command): ExternalResult;
    public function updateInventory(UpdateInventoryCommand $command): ExternalResult;
    public function fetchOrder(string $externalId): ExternalOrderDTO;
}
```

DTOs externos são traduzidos para modelos internos. Não espalhar campos específicos do Mercado Livre nas tabelas centrais.

## Mercado Livre — primeira fase

### Autorização

- OAuth por empresa/conta vendedora;
- `state` assinado, curto e de uso único;
- access token e refresh token criptografados;
- renovação centralizada;
- desconexão controlada;
- escopos mínimos.

### Capacidades

- identificar vendedor e conta;
- consultar categorias e atributos;
- validar dados antes de publicar;
- publicar/alterar anúncio e variações;
- imagens;
- preço e quantidade;
- status/pausa;
- importar pedidos;
- dados logísticos necessários;
- notificações;
- reconciliação.

### Mapeamento

Cada anúncio guarda conexão, item externo, variante externa, SKU interno, categoria, atributos, política de preço, política de estoque, buffer e estado da última sincronização.

### Webhooks

- endpoint mínimo e rápido;
- armazenar headers e payload com limites;
- deduplicar;
- responder e processar em fila;
- buscar recurso oficial antes de confiar no payload;
- manter eventos desconhecidos para diagnóstico;
- retenção e mascaramento definidos.

### Estoque publicável

```text
disponível interno
- reservas ainda não refletidas
- estoque de segurança do canal
- exclusões por lote/status
= quantidade publicável, limitada às regras do canal
```

Atualizações são coalescidas: se houver 10 mudanças rápidas, publicar o estado mais recente, preservando a ordem por anúncio.

### Resiliência

- timeout de conexão e total;
- retry somente para falhas transitórias;
- backoff exponencial com jitter;
- respeitar `Retry-After` e limites;
- circuit breaker simples por conexão/operação;
- dead-letter após tentativas;
- botão reprocessar com idempotência;
- reconciliação de estoque e pedidos em agenda.

## NFePHP/SEFAZ

- encapsular NFePHP em `FiscalProvider`;
- nunca chamar biblioteca diretamente de controllers;
- versão da biblioteca travada em `composer.lock`;
- schemas versionados;
- certificado A1 criptografado, senha protegida e acesso mínimo;
- separar homologação/produção;
- filas fiscais por empresa/série quando necessário;
- salvar XMLs e respostas brutas com proteção;
- monitorar vencimento de certificado;
- relógio do servidor sincronizado.

## Impressão

Fase inicial:

- gerar PDF para documentos comuns;
- gerar ZPL para etiquetas quando impressora compatível;
- imprimir pelo navegador onde suficiente;
- fila e histórico de impressão.

Fase posterior: N4STi Print Agent local para descobrir impressoras, receber jobs autenticados e enviar RAW/ZPL/ESC-POS. O servidor web não deve acessar impressoras da rede do cliente diretamente.

## API pública futura

Preparar IDs públicos e serviços, mas não expor API completa na primeira fase. Quando criada:

- OAuth2/API keys por integração;
- scopes;
- rate limiting;
- idempotency key em POST crítico;
- versionamento `/api/v1`;
- webhooks assinados;
- portal de logs sem segredos.

## Contrato de integração

Toda tentativa deve registrar:

- integração/conexão;
- operação;
- entidade interna/externa;
- correlation ID;
- início/fim;
- resultado HTTP/código externo;
- tentativa;
- payload sanitizado ou hash;
- erro classificado;
- próximo retry.

## Ambientes simulados

Criar fakes locais para Mercado Livre e SEFAZ. Testes automatizados nunca dependem da internet. Contract tests podem rodar separadamente em sandbox/homologação com credenciais próprias.