224 lines
8.6 KiB
HTML
224 lines
8.6 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_sms_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; }
|
|
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_sms_api.php</h1>
|
|
<p class="muted">Dokumentacja endpointu do dodawania wiadomości SMS do kolejki wysyłkowej (tabela outbox).</p>
|
|
<span class="badge post">POST</span>
|
|
<span class="badge json">application/json</span>
|
|
<span class="badge">Auth: api_key w body JSON</span>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>1. Endpoint</h2>
|
|
<table>
|
|
<tr><th>Adres</th><td><code>https://api.softspm.pl/send_sms_api.php</code></td></tr>
|
|
<tr><th>Metoda HTTP</th><td><code>POST</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 wysłać w polu <code>api_key</code> w treści JSON.</p>
|
|
<p class="muted">Uwaga: klucz musi znajdować się na liście <code>API_KEYS['send_sms_api.php']</code> po stronie serwera.</p>
|
|
<pre>{
|
|
"api_key": "TWÓJ_KLUCZ_API",
|
|
"to": "+48XXXYYYZZZ",
|
|
"message": "Treść SMS",
|
|
"creator": "CRM"
|
|
}</pre>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>3. Parametry wejściowe</h2>
|
|
<table>
|
|
<thead>
|
|
<tr><th>Parametr</th><th>Typ</th><th>Wymagany</th><th>Opis</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>api_key</code></td><td>string</td><td>tak</td><td>Klucz API.</td></tr>
|
|
<tr><td><code>to</code></td><td>string</td><td>tak</td><td>Numer odbiorcy. Dozwolone znaki: cyfry, <code>+</code>, spacje, myślniki, nawiasy. Max 30 znaków.</td></tr>
|
|
<tr><td><code>message</code></td><td>string</td><td>tak</td><td>Treść SMS. Max 1530 znaków.</td></tr>
|
|
<tr><td><code>creator</code></td><td>string</td><td>nie</td><td>Źródło wiadomości. Domyślnie <code>API</code>. Max 50 znaków.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>4. Przykład request (cURL)</h2>
|
|
<pre>curl -X POST "https://api.softspm.pl/send_sms_api.php" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"api_key":"TWÓJ_KLUCZ_API",
|
|
"to":"+48XXXYYYZZZ",
|
|
"message":"Przypomnienie o wydarzeniu jutro o 10:00",
|
|
"creator":"HydroNexis"
|
|
}'</pre>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>5. Przykład request (JavaScript / fetch)</h2>
|
|
<pre>const response = await fetch("https://api.softspm.pl/send_sms_api.php", {
|
|
method: "POST",
|
|
headers: { "Content-Type": "application/json" },
|
|
body: JSON.stringify({
|
|
api_key: "TWÓJ_KLUCZ_API",
|
|
to: "+48XXXYYYZZZ",
|
|
message: "Test API SMS",
|
|
creator: "Panel"
|
|
})
|
|
});
|
|
|
|
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>{
|
|
"status": "success",
|
|
"message": "SMS dodany do kolejki."
|
|
}</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>Brak danych JSON w żądaniu.</code></td><td>Puste body.</td></tr>
|
|
<tr><td>400</td><td><code>Niepoprawny JSON.</code></td><td>Niepoprawna składnia JSON.</td></tr>
|
|
<tr><td>400</td><td><code>Brakuje pola 'to' lub 'message'.</code></td><td>Brak wymaganych pól.</td></tr>
|
|
<tr><td>400</td><td><code>Pole to ma nieprawidłowy format.</code></td><td>Nieprawidłowy numer telefonu.</td></tr>
|
|
<tr><td>400</td><td><code>Wiadomość jest zbyt długa.</code></td><td>Przekroczono limit długości <code>message</code>.</td></tr>
|
|
<tr><td>400</td><td><code>Pole creator jest zbyt długie.</code></td><td>Przekroczono limit długości <code>creator</code>.</td></tr>
|
|
<tr><td>401</td><td><code>Nieautoryzowany dostęp.</code></td><td>Błędny lub pusty klucz API.</td></tr>
|
|
<tr><td>405</td><td><code>Dozwolona jest tylko metoda POST.</code></td><td>Użyto innej metody HTTP.</td></tr>
|
|
<tr><td>500</td><td><code>Błąd połączenia z bazą danych.</code></td><td>Problem z połączeniem do DB.</td></tr>
|
|
<tr><td>500</td><td><code>Nie udało się dodać SMS-a.</code></td><td>Błąd przygotowania/wykonania zapytania SQL.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>7. Dobre praktyki po stronie klienta</h2>
|
|
<ul>
|
|
<li>Wysyłaj requesty wyłącznie przez HTTPS.</li>
|
|
<li>Maskuj <code>api_key</code> w logach aplikacyjnych.</li>
|
|
<li>Waliduj numer telefonu przed wysłaniem żądania.</li>
|
|
<li>Przy błędach HTTP 400 nie ponawiaj automatycznie bez korekty danych.</li>
|
|
<li>Przy błędach HTTP 500 wdroż retry z limitem i backoff.</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section class="card">
|
|
<h2>8. Checklista testów integracyjnych</h2>
|
|
<ul>
|
|
<li>Poprawny request zwraca HTTP 200 i status <code>success</code>.</li>
|
|
<li>Brak pola <code>to</code> lub <code>message</code> zwraca HTTP 400.</li>
|
|
<li>Niepoprawny numer <code>to</code> zwraca HTTP 400.</li>
|
|
<li>Za długi <code>message</code> zwraca HTTP 400.</li>
|
|
<li>Niepoprawny <code>api_key</code> zwraca HTTP 401.</li>
|
|
<li>Żądanie metodą GET zwraca HTTP 405.</li>
|
|
</ul>
|
|
</section>
|
|
</div>
|
|
</body>
|
|
</html>
|