Kod parowania i QR

Parowanie dotyczy połączeń qr. Numer cloud_api niczego nie skanuje i odpowiada 409 not_supported_for_provider.

Ścieżka QR

POST /connections zwraca początkowy kod QR jako obraz PNG w formacie data-URI.

Ta sama zasada dotyczy idempotentnego powtórzenia: gdy POST /connections zwraca 200 z nagłówkiem Idempotency-Replayed: true, kod qr w tej odpowiedzi został pobrany ponownie, a nie odtworzony z pamięci — właśnie dlatego, że zapisany kod nie dałby się już zeskanować.

Ścieżka kodu parowania

Kod QR wymaga dwóch urządzeń: ekranu, który go pokazuje, i telefonu, który go fotografuje. Duża część rzeczywistych wdrożeń klientów odbywa się na jednym urządzeniu — klient kończy Państwa proces na tym samym telefonie, na którym działa WhatsApp, i nie może sfotografować własnego ekranu. Dla takich osób ścieżka QR nie jest niewygodna, tylko niemożliwa.

curl -X POST https://developers.wasync.app/api/v1/connections/conn_8f3a21/pairing-code \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"40740267964"}'

{
  "code": "7S59-1KZP"
}

Klient otwiera WhatsApp → Ustawienia → Połączone urządzenia → Połącz za pomocą numeru telefonu i wpisuje kod.

phoneNumber ma format E.164 bez początkowego + — wyłącznie cyfry. Każda inna wartość zostaje odrzucona z odpowiedzią 400 { "error": "invalid_phone_number" }, zamiast być po cichu poprawiona: samowolna zmiana przesłanego numeru to prosta droga do sparowania konta, o które nikt nie prosił. Wymaga uprawnienia whatsapp.manage, tak samo jak utworzenie połączenia.

Prośba o kolejny kod

Na tym samym połączeniu można zażądać kolejnego kodu: zwracany jest nowy kod, a sesja nie jest odbudowywana, więc przycisk „Wyślij mi kolejny kod” jest bezpieczny.

Limit wynosi 5 na połączenie na 15 minut; po jego przekroczeniu otrzymają Państwo 429 { "error": "rate_limited" } wraz z nagłówkiem Retry-After, którego należy przestrzegać. Limit nie jest biurokracją — wielokrotne żądanie kodów dla jednego numeru to dokładnie to, na co reagują mechanizmy antynadużyciowe WhatsApp, a zagrożony jest numer Państwa klienta.

Nic dodatkowego nie jest zużywane

Parowanie kodem zajmuje ten sam płatny slot i uruchamia ten sam 7-dniowy bezpłatny okres próbny co skanowanie kodu QR: licencja jest przypisywana, gdy numer faktycznie się sparuje, niezależnie od sposobu parowania.

Śledzenie powodzenia też się nie zmienia. Nie ma zdarzenia „kod zaakceptowany”, więc proszę odpytywać GET /connections/{id}, aż status przyjmie wartość "connected", i/lub nasłuchiwać webhooka connection.connected.

Warto obsłużyć dwie odmowy:

• 409 already_connected — sesja jest aktywna, nie ma czego parować.
• 409 not_supported_for_provider — numer cloud_api. Kody parowania dotyczą wyłącznie qr i nigdy się tu nie stosują, więc nie należy ponawiać próby.

Ponowne parowanie

Sesja qr może zerwać się sama. Informuje o tym connection.disconnected, a pole needs_reconnect jest tym, według którego należy sterować interfejsem. Kodu QR celowo nie ma w tym ładunku — to dane uwierzytelniające do logowania przez skanowanie — dlatego proszę pobrać go z GET /connections/{id} i pokazać właścicielowi numeru dokładnie tak jak podczas pierwszej konfiguracji. Zob. Webhooks.