# Notificacoes de pagamento

O Fluxis pode enviar uma notificacao por email ao comerciante quando o resultado de um pagamento e registrado para uma conta. As notificacoes de venda ficam habilitadas por padrao. Envie `sales_notifications_enabled` como `false` para interrompe-las. Enquanto estao habilitadas, o Fluxis envia para o email de notificacao da conta, ou para o email do dono da organizacao quando esse endereco esta vazio.

## Visao geral

Quando um pagamento atinge seu status final na blockchain, o Fluxis o registra como transacao no seu livro contabil (Hop 3 do ciclo de vida do pagamento) e depois envia um email quando as notificacoes de venda estao habilitadas. Como essa etapa e executada a partir de uma fila, o email pode chegar alguns segundos depois do webhook com o status final. Pagamentos concluidos e pagos em excesso recebem um email de **nova venda**; pagamentos insuficientes recebem um email de **acao necessaria**. Cada email inclui, quando disponiveis:

- **Valor recebido** - o valor efetivamente recebido, com o simbolo do token (ex. `USDC`, `USDT`) e a rede (ex. Polygon, Base)
- **Valor solicitado e diferenca** - o valor faltante em pagamentos insuficientes, o valor extra em pagamentos em excesso
- Nomes do **ponto de venda** e da **conta**
- **Valor da venda** - o valor de referencia (fiat) da solicitacao de pagamento, quando criada com um
- **Referencia do pedido** - o `external_id` definido na solicitacao de pagamento
- **Endereco do pagador** e **hash da transacao**
- **ID do pagamento** - o identificador da solicitacao de pagamento do Fluxis para conciliacao
- Um botao que abre essa transacao no Dashboard do Fluxis (em pagamentos insuficientes, a transacao retida)

Linhas sem dados nao sao incluidas no email.

As notificacoes sao enviadas para pagamentos **concluidos**, **pagos em excesso** e **insuficientes**. Apenas um email e enviado por pagamento. Pagamentos com falha ou ainda pendentes nao geram email.

::::note
Esta funcionalidade requer que o servico de email transacional do Fluxis esteja habilitado para o seu ambiente. Entre em contato com o suporte se os emails nao estiverem chegando.
::::

## Configurar pela API

Use suas credenciais de API de nivel de organizacao para ler ou gravar o email de notificacao e o interruptor de notificacoes de venda de uma conta. Os dois campos sao opcionais na atualizacao: omita um campo para mante-lo inalterado.

### Obter a configuracao atual

```bash
GET /v1/account/notification-email/{accountId}
```

Resposta:

```json
{
  "data": {
    "notification_email": "pagamentos@sua-loja.com",
    "sales_notifications_enabled": true
  }
}
```

Retorna `null` em `notification_email` quando nenhum endereco esta configurado. `sales_notifications_enabled` e `true` quando a conta nao tem um interruptor salvo.

### Definir ou atualizar a configuracao

```bash
PUT /v1/account/notification-email/{accountId}
Content-Type: application/json

{
  "notification_email": "pagamentos@sua-loja.com",
  "sales_notifications_enabled": true
}
```

Envie apenas o campo que deseja alterar. Omitir `notification_email`, inclusive com um corpo vazio `{}`, mantem o endereco salvo. Omitir `sales_notifications_enabled`, ou enviar `null`, mantem o interruptor.

Para interromper os emails de venda do comerciante sem alterar o endereco:

```json
{
  "sales_notifications_enabled": false
}
```

Defina novamente como `true` para retoma-los. Enquanto o interruptor esta ativo, um endereco vazio ainda recebe o email do dono da organizacao.

Para limpar o endereco, envie `null` ou uma string vazia. Limpar o endereco nao desliga as notificacoes de venda:

```json
{
  "notification_email": null
}
```

O endereco e validado como um email padrao RFC 5322. Um endereco invalido retorna HTTP `400`.

Este interruptor afeta apenas os emails de venda do comerciante (concluidos, pagos em excesso e insuficientes). Nao afeta emails de convite de colaboradores nem emails de autenticacao em dois fatores.

## Configurar pelo Dashboard

Usuarios do Dashboard com o papel **Owner** ou **Admin** podem gerenciar o email de notificacao e o interruptor de notificacoes de venda em **Contas** no Dashboard do Fluxis. Os endpoints do dashboard usam o mesmo corpo JSON da API publica.

Endpoints usados pela API do Dashboard:

| Acao | Endpoint |
| ---- | -------- |
| Obter | `GET /dashboard/accounts/notification-email/{accountID}` |
| Definir | `PUT /dashboard/accounts/notification-email/{accountID}` |

## Um email por conta

- Apenas um endereco de email opcional e suportado por conta. Nao e uma lista.
- A configuracao pertence a conta, nao a um Ponto de Venda especifico.
- Todos os pagamentos com status final dessa conta, de qualquer Ponto de Venda, geram uma notificacao para o mesmo endereco enquanto as notificacoes de venda estao habilitadas.

## Pagamentos insuficientes

Quando o valor recebido e menor do que o esperado, o status do pagamento e definido como `underpaid`. O email e marcado como **Acao necessaria** e exibe o valor solicitado, o valor recebido e o valor faltante. Pagamentos insuficientes ficam retidos e nao sao liquidados automaticamente: abra o pagamento pelo botao do email, revise a transacao no Dashboard do Fluxis e decida se deseja aceita-lo como pago ou reembolsa-lo.

## Solucao de problemas

| Problema | O que verificar |
| -------- | --------------- |
| Nenhum email recebido | Verificar se `sales_notifications_enabled` e true e se `notification_email` ou o email do dono da organizacao estao definidos; verificar pasta de spam |
| Erro de endereco invalido | O endereco deve ser um email RFC 5322 valido |
| Nenhum email para pagamento com falha ou pendente | Esperado - apenas `completed`, `overpaid` e `underpaid` geram emails |

## Relacionado

- [Webhooks](/pt/docs/developers/webhooks) - notificacoes HTTP em tempo real para alteracoes de status de pagamento
- [Eventos de webhook](/pt/docs/developers/webhook-events) - lista completa de tipos de eventos de webhook