API z ArkanaVoIP.PL

Do każdego zapytania dodaj w headers: Accept: application/json, oraz Authorization: Bearer {token-sprawdz-nizej-jak-wygenerowac-token}.

Uniwersalne błędy/kody odpowiedzi:

• 200 W odpowiedzi otrzymasz dalsze informacje. Wszystko przebiegło prawidłowo.
• 201 Element został utworzony zgodnie z żądaniem.
• 401 Nieautoryzowany dostęp. Wygeneruj Api Token (klucz do API), lub nie masz dostępu do wybranego zasobu.
• 402 Próba uzyskania dostępu do funkcji, która usługa nie została aktywowana/opłacona.
• 403 Próba pobrania zasobów bez uprawnień - dane, do których nie powinieneś mieć dostępu.
• 405 Wybrana metoda GET/POST/PUT/DELETE jest niepoprawna. Sprawdź dokumentację.
• 422 Brak wszystkich wymaganych danych, lub te przesłane są niepoprawne. W odpowiedzi znajdziesz informacje.
• 500 Błędne zapytanie. Zapoznaj się z dokumentacją. Niepoprawnie sformułowane zapytanie, sprawdź dokumentację.

Przykładowy błąd 422:

				
{
	"message": "Pole number jest obowiązkowe (and 1 more error)",
	"errors": {
		"number": [
			Pole number musi składać się z poprawnego numeru telefonu zawierającego dokładnie 9 cyfr"
		],
		"customer_name": [
			"Pole customer_name jest obowiązkowe, musi zawierać dane które odpowiadają danym podanym w Panelu Abonenta"
		]
	}
}
				
			

W różnych przypadkach komunikacja API może przebiegać w dwie strony. W ArkanaVoIP.PL wysyłamy żądania pod adresy wskazane w Panelu Abonenta przez Ciebie z kilku adresów IP:

• 77.237.17.9
• 77.237.17.10
• 57.128.214.251
• 57.128.228.161
• 83.168.71.95

Lista ta może ulec zmianie w każdej chwili. Sprawdzaj tą stronę (przynajmniej raz dziennie) by być na bieżąco i zachować działanie swoich usług przychodzących. Nie ponosimy odpowiedzialności za brak aktualizacji adresów po Twojej stronie.

W celu wygenerowania klucza dostępu do API należy:

• Zalogować się do Panelu Abonenta
• Z lewego meny należy wybrać Moje Konto -> Moje Dane (lub bezpośrednio przejść do Usługi API przez Usługi globalne -> Usługi -> API)
• W zakładce Dostęp do API należy kliknąć Aktywuj. Zostaniesz przeniesiony do usługi API. Jeśli stan usługi jest nieaktywny należy kliknąć Aktywuj usługę.
• Po pomyślnej aktywacji usługi zobaczysz od razu swój klucz API. Klucz możesz w każdej chwili zmienić poprzez opcję Zmień, która zobaczysz od razu po kluczu API.

Adres: https://arkanavoip.pl/api/checkStatus

200 Zapytanie jest poprawne, metoda zwraca status API wraz z czasem serwera.

429 Limit został przekroczony. Możesz wykonać tylko jedno żądanie w ciągu 5 minut, a każde kolejne żądanie w tym czasie blokuje dostęp na 90 minut. Kolejne zapytanie w trakcie trwania okresy blokady wydłuża ten okres o kolejne 90 minut.

Nagłówek Retry-After wskazuje, ile sekund pozostało do końca okresu blokady.

Sprawdź czy działamy prawidłowo. Brak odpowiedz http status 200 oznacza, że mamy problemy.

Jest to jedyna dozwolona metoda do sprawdzania stanu usług, strony www oraz API. Każda inna metoda spotka się z blokadą adresu IP na 30 dni; w przypadku znanych monitoringów nawet pernamentą blokadą wszystkich adresów IP danego monitoringu.
Brak autoryzacji tj. błąd 401, 403, 400 będzie blokował dostęp do API na 15 minut. Z każdą kolejną próbą czas ten będzie dodawany do pierwotnego czassu blokady.

FREE oznacza, że metoda jest dostępna bez konieczności posiadania klucza API.

W odpowiedzi zwrócimy:

W celu zmiany klucza dostępu do API należy:

• Zalogować się do Panelu Abonenta
• Z lewego meny należy wybrać Moje Konto -> Moje Dane (lub bezpośrednio przejść do Usługi API przez Usługi globalne -> Usługi -> API)
• W zakładce Dostęp do API należy kliknąć Zmień. Po przeładowaniu strony zobaczysz nowy klucz API.

Adres: https://arkanavoip.pl/api/user/changeAPIToken

200 W zwrocie otrzymasz jsona z danymi np.

					
{
	"newToken":"string(48)",			// nowy token, którym należy autoryzować się przy kolejnych zapytaniach.
}
					
				

Adres: https://arkanavoip.pl/api/user/getUserId

200 W zwrocie otrzymasz int z usererId (może to być Ci potrzebne do obsługi innych funkcji).

Adres: https://arkanavoip.pl/api/user/update/{userId}

Parametry do obsługi funkcji userUpdate

200 Jeśli w zwrocie otrzymasz pustego jsona i kod odpowiedzi 200 znaczy, że dane zostały poprawnie zaaktualizowane.

Adres: https://arkanavoip.pl/api/user/updatePassword/{userId}

Parametry do obsługi funkcji updatePassword

200 Jeśli w zwrocie otrzymasz pustego jsona i kod odpowiedzi 200 znaczy, że hasło zostało poprawnie zaaktualizowane.

Po zmianie hasła zostanisz natychmiast wylogowany ze wszystkich urządzeń.

Adres: https://arkanavoip.pl/api/user/getUserServices

200 W zwrocie otrzymasz informacje w json z usługami globalnymi jakie masz aktywne na swoim koncie. Przykład odpowiedzi:

				
[
    {
        "name": "API",
        "slug": "api",
        "price": 3500,
        "price_activ": 500
    },
    {
        "name": "SIP TRUNK",
        "slug": "sip-trunk",
        "price": 900,
        "price_activ": 500
    }
]
				
			

Adres: https://arkanavoip.pl/api/services

200 W zwrocie otrzymasz informacje w json z wszystkimi usługami jakie możesz aktywować na swoim koncie.

Przykład odpowiedzi:

				

[
    {
        "name": "API",
        "slug": "api",
        "price": 3500,
        "price_activ": 500
    },
    {
        "name": "Kolejki dla połączeń przychodzących",
        "slug": "kolejki",
        "price": 2200,
        "price_activ": 500
    },
    {
        "name": "Konferencje",
        "slug": "konferencje",
        "price": 1200,
        "price_activ": 500
    },
    {
        "name": "Nagrywanie rozmów przychodzących i wychodzących",
        "slug": "nagrywanie-polaczen",
        "price": 4000,
        "price_activ": 500
    },
    {
        "name": "Odsłuch trwających rozmów",
        "slug": "monitoring-rozmow-lajv",
        "price": 2000,
        "price_activ": 500
    },
    {
        "name": "Zarządzanie prezentacją numeru",
        "slug": "zarzadzanie-prezentacja",
        "price": 100,
        "price_activ": 100
    },
    {
        "name": "SIP TRUNK",
        "slug": "sip-trunk",
        "price": 1000,
        "price_activ": 500
    },
    {
        "name": "Dodatkowe kanały rozmowne",
        "slug": "dodatkowe-kanaly-rozmowne",
        "price": 100,
        "price_activ": 100
    },
    {
        "name": "Dodawanie obcych numerów do prezentacji",
        "slug": "dodawanie-numerow-do-prezentacji",
        "price": 2000,
        "price_activ": 1000
    },
    {
        "name": "Własny host dla usług VoIP",
        "slug": "wlasny-host-dla-uslug-voip",
        "price": 2000,
        "price_activ": 1000
    },
    {
        "name": "Muzyka na czekanie",
        "slug": "muzyka-na-czekanie",
        "price": 0,
        "price_activ": 0
    },
    {
        "name": "Połączenie zdalne",
        "slug": "polaczenie-zdalne",
        "price": 1200,
        "price_activ": 1200
    },
    {
        "name": "Własna nazwa SMS",
        "slug": "nadpis-sms",
        "price": 24,
        "price_activ": 24
    }
]
				
			

Adres: https://arkanavoip.pl/api/user/getUserService/{slug}

200 W zwrocie otrzymasz informacje w json ze szczegółami usługi, o którą pytasz. Slug otrzymasz w getServices. Wskażmy usługę, jeśli jest aktywna na Twoim koncie. Jeśli usługa nie jest aktywna w zwrocie otrzymasz puste: {}.

				
{
    "id": 17,							// ID Twojej usługi - przydatne do np. wyłączenia usługi.
    "service_id": 1,						// ID usługi globalej - przydatne do np. zmiany lub wyłączenia usługi
    "price": 4305,						// koszt w groszach jaki ponosisz miesięcznie dla usługi
    "item": 1,							// ilość usług w danej usłudze np. dodatkowe kanały rozmowne
    "value": "xyz",						// np. api key
    "created_at": "2024-12-05T23:52:43.000000Z",		// data aktywacji usługi
    "updated_at": "2024-12-08T01:37:03.000000Z",		// data ostatniej modyfikacjii usługi
    "deleted_at": null,						// data usunięcia uslugi
    "service": {
        "id": 1,						// ID usługi
        "name": "API",						// nazwa usługi
        "slug": "api",						// slug uługi (przyda się tam, gdzie wymagany {slug} dla usługi)
        "price": 4305,						// kwota w groszach jaki ponosisz za usługę miesięcznie
        "price_activ": 500					// cena aktywacji dla usługi (pierwszy okres rozliczeniowy bezpłatny + obowiązuje cena aktywacji)
    }
}
				
			

Adres: https://arkanavoip.pl/api/finance/invoices

Parametry do obsługi funkcji userUpdate

200 W zwrocie otrzymasz informacje w json z wszystkimi fakturami, które możesz pobrać w PDF. Możesz stosować sortowanie zgodnie z dokumentacją datatables.

					
{
    "current_page": 1,
    "data": [
        {
            "id": 25,
            "title": "12/10/2024",
            "netto": 1500,
            "payed": 1,
            "created_at": "2024-10-28T13:59:43.000000Z",
            "updated_at": "2024-10-28T13:59:43.000000Z"
        },
        {
            "id": 2,
            "title": "5/01/2024",
            "netto": 1869,
            "payed": 1,
            "created_at": "2024-01-06T12:56:03.000000Z",
            "updated_at": "2024-01-06T12:56:03.000000Z"
        }
    ],
    "first_page_url": "https://arkanavoip.pl/api/finance/invoices?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://arkanavoip.pl/api/finance/invoices?page=1",
    "links": [
        {
            "url": null,
            "label": "« Poprzednia",
            "active": false
        },
        {
            "url": "https://arkanavoip.pl/api/finance/invoices?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "Następna »",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "https://arkanavoip.pl/api/finance/invoices",
    "per_page": 100,
    "prev_page_url": null,
    "to": 13,
    "total": 13
}
				
			

Adres: https://arkanavoip.pl/api/finance/invoices/{id}

200 W zwrocie otrzymasz plik PDF z fakturą. {id} faktury znajdziesz w funkcji invoices.

Adres: https://arkanavoip.pl/api/fiance/history

200 W zwrocie otrzymasz json z historią operacji na swoim koncie.

Przykładowy kod odpowiedzi:

					

{
    "current_page": 1,
    "data": [
        {
            "id": 30054,
            "cost": 7,
            "balance": 54290,
            "desc": "Wysyłka SMS PL 1x1 części z test",
            "type": 0,
            "created_at": "2026-01-21T06:52:58.000000Z",
            "updated_at": "2026-01-21T06:52:58.000000Z"
        },
		{
            "id": 30054,
            "cost": 7,
            "balance": 54823,
            "desc": "Wysyłka SMS PL 1x1 części z test",
            "type": 0,
            "created_at": "2026-01-20T05:01:14.000000Z",
            "updated_at": "2026-01-20T05:01:14.000000Z"
        },
        {
            "url": "https://arkanavoip.pl/api/finance/history?page=2",
            "label": "Następna »",
            "active": false
        }
    ],
    "next_page_url": "https://arkanavoip.pl/api/finance/history?page=2",
    "path": "https://arkanavoip.pl/api/finance/history",
    "per_page": 100,
    "prev_page_url": null,
    "to": 100,
    "total": 1442
}+
					
				

Adres: https://arkanavoip.pl/api/billing/sip/{type}

Parametry do obsługi funkcji getBillings

200W odpowiedzi otrzymasz tablicę data z połączeniami billingowymi, liczbę wszystkich rekordówrecordsTotal, documentację paginacji zgodną z Datatables oraz dodatkowe pola: totalSec (sumaryczny czas rozmowy w sekundach), totalCost(sumaryczny koszt połączeń), sips z wprowadzonymi numerami kont SIP.

				
{
	"data": [
		{
			"id": 1277302,
			"src": "48223334455",
			"dst": "500600700",
			"start": "2026-03-22 22:32:06",
			"answer": "2026-03-22 22:32:21",
			"end": "2026-03-22 22:37:21",
			"duration": 314,
			"billsec": 299,
			"disposition": "ANSWERED",
			"typ": "out",
			"billcostCl": "49.8333333333333334"
		},
		// ...
	],
	"draw": null,
	"recordsTotal": 68,
	"recordsFiltered": 68,
	"sips": [100, 101],
	"totalSec": "13031",
	"totalCost": 1830.166666666666,
	"length": "10"
}
				
			

Adres: https://arkanavoip.pl/api/docallremote

Parametry formularza doCallRemote (POST)

Uwaga dot. stanu konta
Jeśli użytkownik poda większy czas ograniczenia połączenia niż jego saldo pozwala, system automatycznie zmniejszy czas do maksymalnej długości, którą można opłacić z bieżącego stanu konta.

Uwaga dot. bezpieczeństwa
System nie pozwoli na zaprezentowanie się numerem telefonu, który nie należy do użytkownika. Każda próba prezentacji połączenia A lub B; numerem, do którego użytkownik nie ma prawa (numer na koncie SIP użytkownika - nie może być to numer na karcie eSIM lub SIM nawet w naszej sieci) w systemie ArkanaVoIP.PL zostanie zarejestrowana. W razie potrzeby zgoszona wraz z danymi użytkownika do odpowiednich służb.
Jeśli prób tych jest więcej niż statystyki błędu użytkownika usługa zostanie zablokowana na koncie użytkownika dożywotnio. (przy integracji można testować wyłącznie pod swoje numery telefonu w naszej sieci (!); po poprawnej integracji max 2 pomyłki w ciągu roku).

201 W przypadku poprawnego utworzenia połączenia (odebrania telefonu/odrzucenia rozmowy przez numberA) API zwraca status HTTP 201 z pustym body JSON.

Do obsługi SMS nie jest wymagana usługa API. Należy wygenerować kod API służący wyłącznie do obsugi SMS w zakładce SMS. Można posługiwać sie również kluczem ogólnym do API.

Adres: https://arkanavoip.pl/api/sms/store

Parametry do obsługi funkcji smsStore

Przykład kodu w php:

				
$res = new \GuzzleHttp\Client( [
	'http_errors' => false,
	'headers' => [
		'Content-Type'	=> 'application/json',
		'Accept'	=> 'application/json',
		'Authorization' => 'Bearer klucz-api-np.1234567890abcdefghijklmnopi',
	]
] );

$res = $res->post('https://arkanavoip.pl/api/sms/store', [
	'form_params' => [
		'src' 	=> 'test',
		'dst[]' => '500600700',
		'dst[]' => '500700800',
		'msg' 	=> 'testowa wiadomosc'
	]
] );
				
			

201 | 202 W zwrocie otrzymasz kod odpowiedzi 201/202 jesli udało się zapisać i wysłać wiadomość. Każdy inny kod odpowiedzi oznacza niepowodzenie. Wiadomość dojdzie do odbiorców w ciągu kilku sekund. Otrzymasz także jsona z danymi:

				
{
    "status": "accepted",					// informacja, że wiadomość została przyjęta do wysyłki
    "batches": [						// tablica z informacjami o każdej partii wiadomości (partia to maksymalnie 99 numerów telefonu, jeśli wysyłasz SMSy do więcej niż 99 numerów, zostaną one podzielone na partie - każda partia ma swój oddzielny msgid)
        {
            "index": 0,						// 0 jako pierwsza partia, 1 jako druga partia itd.
            "msgid": "abcf9325-5e03-4a66-9218-8e805d150b55",	// unikalne msgid dla każdej partii
            "msisdns": [					// tablica z numerami telefonów z danej partii
                "500600700",
                "500700800"
            ]							// w przypadku użycia tylko jednego numeru telefonu to będzie msgid dla danej wiadomości.
        }
    ]
}
				
			

Uwagi: W przypadku, gdy prowadzisz masową wysyłke SMS - nie wysyłaj każdego numeru osobno, grupuj je w dst[]. Jeśli zauważymy spamowy ruch (te same treści wiadomości pod różne numery z tych samych dst), w krótkich odstępach czasu (np. co 3 na sekundy lub częściej) zablokujemy Twój adres IP na 30 minut. Blokada adresu IP obejmuje całościowe korzystanie z API (dla wszystkich możliwych metod) dla danego adresu IP i użytkownika (nie wystarczy zmienić adresu IP).

Adres: https://arkanavoip.pl/api/sms/{dir}

Parametry do obsługi funkcji smss

200 W zwrocie otrzymasz informacje w json z wszystkimi smsami z danego dir. Możesz stosować sortowanie zgodnie z dokumentacją datatables.

					
{
    "current_page": 1,
    "data": [
        {
            "id": 72027,
            "src": "test",
            "dst": "500600700",
            "msg": "test",
            "dir": "out",
            "status": null,
            "msgid": "fb92dcab-c5b0-4857-8725-a119d7132d76",
            "sip_id": null,
            "created_at": "2026-01-19T03:30:02.000000Z",
            "updated_at": "2026-01-19T03:30:02.000000Z"
        },
        {
            "id": 72026,
            "src": "test",
            "dst": "500600700",
            "msg": "test",
            "dir": "out",
            "status": null,
            "msgid": "3edf86e0-e963-40d5-a792-68c36eaadf00",
            "sip_id": null,
            "created_at": "2026-01-19T03:09:37.000000Z",
            "updated_at": "2026-01-19T03:09:37.000000Z"
        }
    ],
    "first_page_url": "https://arkanavoip.pl/api/sms/out?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://arkanavoip.pl/api/sms/out?page=1",
    "links": [
        {
            "url": null,
            "label": "« Poprzednia",
            "active": false
        },
        {
            "url": "https://arkanavoip.pl/api/sms/out?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "Następna »",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "https://arkanavoip.pl/api/sms/out",
    "per_page": 100,
    "prev_page_url": null,
    "to": 3,
    "total": 3
}
				
			

Adres: https://arkanavoip.pl/api/sms/{id}

200 W zwrocie otrzymasz informacje w json danego SMSa.

					
{
    "id": 72046,
    "src": "test",
    "dst": "500600700",
    "msg": "test123",
    "dir": "out",
    "status": "Doręczono do SIP 2026-01-17 18:56:44",			// tu pojawi się status doręczenia (DRL) wiadomości. (do SIP, Panelu - możesz ustawić doręczenie wiadomości SMS do konta SIP - wtedy przyjdzie jako SMS w koncie SIP (jeśli SIP to obsluguje))
    "msgid": "de9bb849-ab25-48c6-adc0-30e3414dff6a",
    "sip_id": 10698,
    "created_at": "2026-01-19T05:20:55.000000Z",
    "updated_at": "2026-01-19T05:20:55.000000Z"
}
				
			

401 Nie podano {id} (lub podano błędne).

403 {id} nie jest Twoim id SMS (dany sms nie nalezy do Ciebie).

404 {id} - zasób nie istnieje.

Do obsługi webhooków należy dodać w Panelu Abonenta w zakładce SMS własny adres URL. Pod ten adres URL - metodą POST będziemy wysyłali Ci dane w formacie json.

Co wysyłamy?

Przykład komunikatu jaki od nas otrzymasz:

				
{
  "src": "500600700",						// Z numeru
  "dst": "600700800",						// Pod numer
  "msg": "Cześć! Co u Ciebie słychać?",				// Treść wiadomości
  "dir": "in",							// in: przychodząca | out: wychodząca - w tym wypadku zawsze in
  "msgid": "8f71558e-e10d-48ba-b216-89cede4f966f",		// uuid wiadomości
  "updated_at": "2025-09-14 01:22:34",
  "created_at": "2025-09-14 01:22:34,
  "id": 1,							// id z naszego systemu (wiadomości, do późniejszego jej wyszukania w metodzie np. POST /api/sms)
  "sip_id": 2 							// konto SIP do jakiego przypisany jest numer
}
				
			

200 | 201 Powinieneś wysłac nam kod odpowiedzi 200 lub 201. Nie przewidujemy ponownej wysyłki jeśli otrzymamy bląd. Wiadomość zawsze dostępna jest w Panelu Abonenta (nawet w przypadku błędu wysyłki przez API, czy braku dostępności konta SIP).

Do obsługi webhooków należy dodać w Panelu Abonenta w zakładce SMS własny adres URL. Pod ten adres URL - metodą POST będziemy wysyłali Ci dane w formacie json.

Co wysyłamy?

Przykład komunikatu jaki od nas otrzymasz:

				
{
  "id": 1,							// id z naszego systemu (wiadomości, do późniejszego jej wyszukania w metodzie np. POST /api/sms)
  "src": "500600700",						// Z numerulub nadpisy np. FirmaABC
  "dst": "600700800",						// Pod numer
  "msg": "Cześć! Co u Ciebie słychać?",				// Treść wiadomości
  "dir": "in",							// in: przychodząca | out: wychodząca
  "msgid": "8f71558e-e10d-48ba-b216-89cede4f966f",		// uuid wiadomości
  "updated_at": "2025-09-14 01:22:34",
  "created_at": "2025-09-14 01:22:34,
  "sip_id": 2 							// konto SIP do jakiego przypisany jest numer
}
				
			

200 | 201 Powinieneś wysłac nam kod odpowiedzi 200 lub 201. Nie przewidujemy ponownej wysyłki raportu doręczenia jeśli otrzymamy błąd. Wiadomość zawsze dostępna jest w Panelu Abonenta (nawet w przypadku błędu wysyłki przez API, czy braku dostępności konta SIP).