> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/configuracao/integracao-comercial/sincronizacao-e-mail-e-fallback.md).

# Sincronização, e-mail e fallback

### Fluxo compatível

1. Frontend chama `GET /api/proxy/plans`.
2. DigitalSac consulta o endpoint externo de planos.
3. Frontend chama `GET /api/proxy/default-server-id`.
4. DigitalSac consulta o ID do servidor padrão.
5. Frontend chama `POST /api/proxy/register`.
6. DigitalSac envia o cadastro ao sistema comercial com `serverId`.
7. O sistema comercial responde `success=true`.
8. O e-mail é enviado pelo provedor configurado.

As rotas públicas `/api/proxy/*` possuem rate limit.

### Sincronização de planos

Com `SYNC_EXTERNAL_PLANS=true`, o DigitalSac replica o contrato externo na tabela local `Plans`.

* ID inteiro positivo: upsert pelo ID.
* ID não numérico: associação pelo nome; mantenha nomes únicos.
* Planos locais ausentes na API externa não são apagados.
* Tenants existentes e seus `planId` não são alterados automaticamente.
* Falha de sincronização é registrada, mas não derruba a listagem.
* Campos omitidos assumem `0` ou `false` e podem sobrescrever valores existentes.

{% hint style="warning" %}
Envie sempre o contrato completo de cada plano. O vínculo usado pelo DigitalSac é `Tenant.planId` → `Plan.id`.
{% endhint %}

### Envio de e-mail

| Valor                                | Responsável                      |
| ------------------------------------ | -------------------------------- |
| `REGISTER_EMAIL_PROVIDER=digitalsac` | DigitalSac envia após o cadastro |
| `REGISTER_EMAIL_PROVIDER=custom`     | Sistema comercial envia          |

Quando o sistema comercial controla o cadastro, prefira `custom` para evitar duplicidade.

### Fallback

Recomendação:

```
COMMERCIAL_PROVIDER_FALLBACK_TO_PERFEX=false
```

Se estiver `true`, o DigitalSac pode tentar o Perfex quando o sistema próprio falhar. Isso pode cadastrar o cliente no destino errado; habilite somente com decisão comercial explícita.

### Timeouts e testes

* Endpoints `GET`: 10 segundos.
* Cadastro `POST`: 30 segundos.
* Evite chamadas repetidas durante testes por causa do rate limit.
* Implemente idempotência no cadastro para suportar retentativas seguras.