228 lines
9.3 KiB
HTML
228 lines
9.3 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="pl">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Manual API - send_email_api.php</title>
|
|
<style>
|
|
:root {
|
|
--bg: #f4f7fb;
|
|
--card: #ffffff;
|
|
--text: #122033;
|
|
--muted: #4f6277;
|
|
--border: #d7e0ea;
|
|
--accent: #0b66c3;
|
|
--ok: #1f8b4c;
|
|
--err: #b02a37;
|
|
--code-bg: #0f1b2a;
|
|
--code-text: #e5f0ff;
|
|
}
|
|
* { box-sizing: border-box; }
|
|
body {
|
|
margin: 0;
|
|
background: var(--bg);
|
|
color: var(--text);
|
|
font-family: "Segoe UI", Tahoma, sans-serif;
|
|
line-height: 1.55;
|
|
}
|
|
.container { max-width: 1100px; margin: 0 auto; padding: 28px 16px 48px; }
|
|
.header {
|
|
background: linear-gradient(120deg, #d9ecff 0%, #f7fbff 60%, #ffffff 100%);
|
|
border: 1px solid var(--border);
|
|
border-radius: 14px;
|
|
padding: 20px;
|
|
margin-bottom: 16px;
|
|
}
|
|
h1, h2, h3 { margin: 0 0 10px; }
|
|
h1 { font-size: 1.7rem; }
|
|
h2 { font-size: 1.25rem; margin-top: 20px; }
|
|
h3 { font-size: 1.05rem; margin-top: 16px; }
|
|
.card {
|
|
background: var(--card);
|
|
border: 1px solid var(--border);
|
|
border-radius: 14px;
|
|
padding: 18px;
|
|
margin-top: 14px;
|
|
}
|
|
.muted { color: var(--muted); }
|
|
.badge {
|
|
display: inline-block;
|
|
padding: 4px 9px;
|
|
border-radius: 999px;
|
|
font-size: 0.82rem;
|
|
font-weight: 600;
|
|
border: 1px solid var(--border);
|
|
background: #fff;
|
|
margin-right: 8px;
|
|
}
|
|
.badge.post { border-color: #9ac6f2; color: #084f97; }
|
|
.badge.json { border-color: #98d7ad; color: #166838; }
|
|
.badge.auth { border-color: #f4c28b; color: #8a4b00; }
|
|
table { width: 100%; border-collapse: collapse; margin-top: 10px; }
|
|
th, td {
|
|
border-bottom: 1px solid var(--border);
|
|
text-align: left;
|
|
padding: 9px 7px;
|
|
vertical-align: top;
|
|
font-size: 0.95rem;
|
|
}
|
|
th { background: #f7fafe; font-weight: 600; }
|
|
code {
|
|
background: #eef4fb;
|
|
border: 1px solid #dbe8f5;
|
|
border-radius: 6px;
|
|
padding: 1px 6px;
|
|
font-family: Consolas, "Courier New", monospace;
|
|
font-size: 0.9em;
|
|
}
|
|
pre {
|
|
margin: 10px 0 0;
|
|
background: var(--code-bg);
|
|
color: var(--code-text);
|
|
border-radius: 10px;
|
|
padding: 14px;
|
|
overflow-x: auto;
|
|
font-size: 0.9rem;
|
|
}
|
|
.ok { color: var(--ok); font-weight: 600; }
|
|
.err { color: var(--err); font-weight: 600; }
|
|
ul { margin-top: 8px; }
|
|
li { margin-bottom: 6px; }
|
|
@media (max-width: 700px) {
|
|
h1 { font-size: 1.35rem; }
|
|
th, td { font-size: 0.9rem; }
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<section class="header">
|
|
<h1>Manual programisty: send_email_api.php</h1>
|
|
<p class="muted">Dokumentacja endpointu do wysyłki e-mail przez SMTP (PHPMailer).</p>
|
|
<span class="badge post">POST</span>
|
|
<span class="badge json">application/json</span>
|
|
<span class="badge auth">Auth: Bearer token w Authorization</span>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>1. Endpoint</h2>
|
|
<table>
|
|
<tr><th>Adres</th><td><code>https://api.softspm.pl/send_email_api.php</code></td></tr>
|
|
<tr><th>Metoda HTTP</th><td><code>POST</code></td></tr>
|
|
<tr><th>Preflight</th><td><code>OPTIONS</code> zwraca <code>204</code></td></tr>
|
|
<tr><th>Content-Type</th><td><code>application/json</code></td></tr>
|
|
<tr><th>Kodowanie</th><td>UTF-8</td></tr>
|
|
</table>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>2. Autoryzacja</h2>
|
|
<p>Klucz API należy przekazać w nagłówku <code>Authorization</code> jako Bearer token:</p>
|
|
<pre>Authorization: Bearer TWÓJ_KLUCZ_API</pre>
|
|
<p class="muted">Uwaga: token musi znajdować się na liście kluczy <code>API_KEYS['send_email_api.php']</code> po stronie serwera.</p>
|
|
<p class="muted">Brak nagłówka lub błędny token zwraca HTTP 401.</p>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>3. Parametry wejściowe (JSON body)</h2>
|
|
<table>
|
|
<thead><tr><th>Parametr</th><th>Typ</th><th>Wymagany</th><th>Opis</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>to</code></td><td>string</td><td>tak</td><td>Adres e-mail odbiorcy. Musi przejść walidację <code>FILTER_VALIDATE_EMAIL</code>.</td></tr>
|
|
<tr><td><code>subject</code> lub <code>title</code> lub <code>tytul</code></td><td>string</td><td>tak</td><td>Tytuł wiadomości. Max 255 znaków.</td></tr>
|
|
<tr><td><code>message</code> lub <code>body</code> lub <code>content</code> lub <code>tresc</code></td><td>string</td><td>tak</td><td>Treść wiadomości. Max 20000 znaków.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Przykładowe body</h3>
|
|
<pre>{
|
|
"to": "jan.kowalski@example.com",
|
|
"title": "Przypomnienie",
|
|
"body": "Wydarzenie odbędzie się jutro o 10:00."
|
|
}</pre>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>4. Przykład request (cURL)</h2>
|
|
<pre>curl -X POST "https://api.softspm.pl/send_email_api.php" \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer TWÓJ_KLUCZ_API" \
|
|
-d '{
|
|
"to":"jan.kowalski@example.com",
|
|
"tytul":"Test API mail",
|
|
"tresc":"To jest test wiadomości e-mail"
|
|
}'</pre>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>5. Przykład request (JavaScript / fetch)</h2>
|
|
<pre>const response = await fetch("https://api.softspm.pl/send_email_api.php", {
|
|
method: "POST",
|
|
headers: {
|
|
"Content-Type": "application/json",
|
|
"Authorization": "Bearer TWÓJ_KLUCZ_API"
|
|
},
|
|
body: JSON.stringify({
|
|
to: "jan.kowalski@example.com",
|
|
title: "Powiadomienie",
|
|
content: "Treść wiadomości"
|
|
})
|
|
});
|
|
|
|
const data = await response.json();
|
|
console.log(response.status, data);</pre>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>6. Odpowiedzi API</h2>
|
|
|
|
<h3 class="ok">6.1 Sukces (HTTP 200)</h3>
|
|
<pre>{
|
|
"success": "Message has been sent"
|
|
}</pre>
|
|
|
|
<h3 class="err">6.2 Błędy</h3>
|
|
<table>
|
|
<thead><tr><th>HTTP</th><th>Komunikat</th><th>Znaczenie</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>400</td><td><code>Empty JSON payload.</code></td><td>Puste body.</td></tr>
|
|
<tr><td>400</td><td><code>Invalid JSON payload.</code></td><td>Niepoprawna składnia JSON.</td></tr>
|
|
<tr><td>400</td><td><code>Missing required fields: to, subject/title/tytul, message/body/content/tresc</code></td><td>Brak wymaganych pól.</td></tr>
|
|
<tr><td>400</td><td><code>Invalid recipient e-mail address.</code></td><td>Niepoprawny adres e-mail odbiorcy.</td></tr>
|
|
<tr><td>400</td><td><code>Subject is too long.</code></td><td>Przekroczono limit 255 znaków.</td></tr>
|
|
<tr><td>400</td><td><code>Message is too long.</code></td><td>Przekroczono limit 20000 znaków.</td></tr>
|
|
<tr><td>401</td><td><code>Unauthorized - Invalid or missing API key.</code></td><td>Brak lub błędny Bearer token.</td></tr>
|
|
<tr><td>405</td><td><code>Only POST requests are allowed.</code></td><td>Użyto innej metody HTTP niż POST.</td></tr>
|
|
<tr><td>500</td><td><code>Mailer Error: message could not be sent.</code></td><td>Błąd SMTP/PHPMailer po stronie serwera.</td></tr>
|
|
<tr><td>204</td><td>(pusta odpowiedź)</td><td>Poprawny preflight <code>OPTIONS</code>.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>7. Uwagi implementacyjne</h2>
|
|
<ul>
|
|
<li>Endpoint ustawia nagłówki CORS: <code>Access-Control-Allow-Origin: *</code>, <code>Allow-Methods: POST, OPTIONS</code>, <code>Allow-Headers: Content-Type, Authorization</code>.</li>
|
|
<li>Wiadomość jest wysyłana jako HTML oraz alternatywnie jako plain text (<code>AltBody</code>).</li>
|
|
<li>Tytuł i treść są sanityzowane przed osadzeniem w szablonie HTML.</li>
|
|
<li>Szczegóły błędów SMTP są logowane po stronie serwera (nie są zwracane klientowi).</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>8. Checklista testów integracyjnych</h2>
|
|
<ul>
|
|
<li>Poprawny request z Bearer tokenem zwraca HTTP 200.</li>
|
|
<li>Brak <code>Authorization</code> zwraca HTTP 401.</li>
|
|
<li>Błędny token zwraca HTTP 401.</li>
|
|
<li>Brak pola <code>to</code>, tytułu (<code>subject/title/tytul</code>) lub treści (<code>message/body/content/tresc</code>) zwraca HTTP 400.</li>
|
|
<li>Niepoprawny e-mail odbiorcy zwraca HTTP 400.</li>
|
|
<li>Za długie <code>subject</code>/<code>message</code> zwracają HTTP 400.</li>
|
|
<li>Żądanie metodą GET zwraca HTTP 405.</li>
|
|
<li>Żądanie OPTIONS zwraca HTTP 204.</li>
|
|
</ul>
|
|
</section>
|
|
</div>
|
|
</body>
|
|
</html>
|