🔐 Regras de Assinatura S2S (Autenticação)

O gateway adota o máximo rigor de arquitetura corporativa. Nenhuma requisição permite credenciais em texto claro na URI (IPs não importam no nosso Traffic Shaping).

Para interagir com as rotas abaixo, certifique-se de injetar os seguintes Headers:

• X-Public-Key: A sua chave pública injetada pelo provedor no ato do cadastro.
• X-Timestamp: Hora atual Unix (Segundos) para prevenção de interceptações temporais (desvio < 5 min).
• X-Nonce: UUID ou string única (Single-Use Token protegido atômicamente no Redis contra Replay Attacks).
• X-Signature: O hash HMAC SHA256 processado com a sua `Secret-Key`. A string do hash antes da criptografia deve ser rigorosamente construída na seguinte ordem:

// Exemplo de Formulação do Hash (PHP)
$stringBase = $timestamp . $nonce . json_encode($body) . json_encode($recipients) . json_encode($attachments);
$x_signature = hash_hmac('sha256', $stringBase, $secretKeyDesteTenant);

🛡️ Camada de Rede (IP Whitelisting e Respostas Estruturadas)

Filtragem de Tráfego: O gateway possui uma tranca extra por IP para prevenir ataques DDoS originados da internet aberta. Apenas os IPs explicitados na chave hosts contida no arquivo config/config.php terão seu handshake efetivado na API.

Proteção Sistêmica de Retorno: Garantia absoluta de ausência de renderização HTML. Qualquer colapso (404 Not Found por rota desativada, ou 500 Error por SMTP falhando com TransportException) gerará uma devolução limpa em formato application/json — mesmo que o seu client não envie o request indicando Accept: application/json. O parseamento no seu frontend/Worker nunca mais irá quebrar.

🚀 Cargas Úteis (Payloads) p/ Postman / Insomnia

Seja você usando Insomnia, Postman ou cURL, lembre-se de que a rota agora aceita requisições de qualquer domínio via API, bastando enviar o identificador do tenant no subdomínio da URL (ex: https://{seu-tenant}.opsmailgw.com.br/...).

1. Enviar E-mails (/v1/emails/send)

{
    "smtp_config": {
        "host": "smtp.mailgun.org",
        "port": 587,
        "username": "api@teste.com",
        "password": "senha_segura",
        "encryption": "tls",
        "from_address": "joao@teste.com"
    },
    "body": {
        "subject": "Sua Fatura Chegou!",
        "content_html": "
Sua Fatura está Aqui!
",
        "content_text": "Sua Fatura está Aqui!"
    },
    "recipients": [
        {"email": "cliente1@dominio.com", "name": "Cliente VIP"},
        {"email": "cliente2@dominio.com", "name": "Cliente Silver"}
    ]
}

2. Teste de Configuração SMTP (/v1/emails/test-smtp)

{
    "smtp_config": {
        "host": "smtp.mailgun.org",
        "port": 587,
        "username": "api@teste.com",
        "password": "senha_segura",
        "encryption": "tls",
        "from_address": "joao@teste.com"
    },
    "test_recipient": "seu_email_pessoal@dominio.com"
}

📊 Analytics & Rastreamento em Tempo Real

Endpoints para extração de métricas e logs de e-mails enviados, permitindo a construção de dashboards e relatórios detalhados.

1. Resumo Agregado de Disparos (GET /v1/stats/summary)

Retorna quantidades totais, taxa de sucesso e tempo médio de execução em um período especificado.

curl --location --request GET 'https://{seu-tenant}.opsmailgw.com.br/v1/stats/summary?period=day&date=2023-01-15' \
--header 'X-Public-Key: sua_chave_publica_aqui' \
--header 'X-Timestamp: 1711285000' \
--header 'X-Nonce: token_nonce_unico_aqui' \
--header 'X-Signature: seu_hash_hmac_aqui' \
--header 'Accept: application/json'

Parâmetros de Query:

• period: day, month, year, hour (default: day)
• date: Data de referência (YYYY-MM-DD)

Exemplo de Resposta:

{
  "total_sent": 1420,
  "total_failed": 12,
  "success_rate_percent": 99.16,
  "average_execution_time_ms": 412.35
}

2. Timeline Detalhada (GET /v1/stats/timeline)

Série temporal detalhada graficamente (enviados vs falhas).

curl --location --request GET 'https://{seu-tenant}.opsmailgw.com.br/v1/stats/timeline?interval=hour&range=24' \
--header 'X-Public-Key: sua_chave_publica_aqui' \
--header 'X-Timestamp: 1711285000' \
--header 'X-Nonce: token_nonce_unico_aqui' \
--header 'X-Signature: seu_hash_hmac_aqui' \
--header 'Accept: application/json'

Parâmetros de Query:

• interval: hour, minute (default: hour)
• range: Retroativo em horas (default: 24)

3. Logs de Sucesso (GET /v1/stats/success)

Extração dos Envios de E-mail consolidados (success) com paginação.

curl --location --request GET 'https://{seu-tenant}.opsmailgw.com.br/v1/stats/success?start=2023-01-01%2000:00:00&end=2023-01-31%2023:59:59' \
--header 'X-Public-Key: sua_chave_publica_aqui' \
--header 'X-Timestamp: 1711285000' \
--header 'X-Nonce: token_nonce_unico_aqui' \
--header 'X-Signature: seu_hash_hmac_aqui' \
--header 'Accept: application/json'

Parâmetros de Query:

• start: Filtro inicial (YYYY-MM-DD HH:MM:SS)
• end: Filtro final (YYYY-MM-DD HH:MM:SS)

4. Erros de Integração SMTP (GET /v1/stats/errors)

Relatório com métricas de troubleshooting.

curl --location --request GET 'https://{seu-tenant}.opsmailgw.com.br/v1/stats/errors?start=2023-01-01%2000:00:00&end=2023-01-31%2023:59:59' \
--header 'X-Public-Key: sua_chave_publica_aqui' \
--header 'X-Timestamp: 1711285000' \
--header 'X-Nonce: token_nonce_unico_aqui' \
--header 'X-Signature: seu_hash_hmac_aqui' \
--header 'Accept: application/json'

Parâmetros de Query:

• start: Filtro inicial (YYYY-MM-DD HH:MM:SS)
• end: Filtro final (YYYY-MM-DD HH:MM:SS)