Dla deweloperów

Buduj na TraXmark: jeden interfejs REST, klucze API z jawnymi zakresami, błędy RFC 7807 i paginacja kursorem.

Referencja OpenAPI 3.1.0

TraXmark API v1

Analityka reakcji na e-maile w jednym interfejsie REST. Odczyt i zapis kontaktów, wiadomości, zdarzeń, dokumentów, kopert i propozycji — ten sam format klucza, kształt błędu i kontrakt paginacji.

Uwierzytelnianie: klucz API trax_…. W bazie przechowywany jest wyłącznie jego hash Argon2id.
Błędy zgodne z RFC 7807, z kluczem i18n oraz nagłówkiem x-correlation-id.
Paginacja kursorowa na każdej liście, limit 100 pozycji na stronę.
Ochrona przed enumeracją: zasób nieistniejący i zasób bez dostępu odpowiadają identycznie — 404.

Zasoby

Sześć zasobów, każdy z odczytem i zapisem przez pasujące zakresy.

/api/v1/contactsOdczyt z zakresem contacts:read, zapis z zakresem contacts:write.

/api/v1/messagesOdczyt z zakresem messages:read, zapis z zakresem messages:write.

/api/v1/eventsOdczyt z zakresem events:read, zapis z zakresem events:write.

/api/v1/documentsOdczyt z zakresem documents:read, zapis z zakresem documents:write.

/api/v1/envelopesOdczyt z zakresem envelopes:read, zapis z zakresem envelopes:write.

/api/v1/proposalsOdczyt z zakresem proposals:read, zapis z zakresem proposals:write.

Zakresy

Każdy klucz API jest wydawany z jawnym zestawem 16 zakresów.

campaigns:read

campaigns:write

contacts:read

contacts:write

messages:read

messages:write

events:read

events:write

documents:read

documents:write

envelopes:read

envelopes:write

proposals:read

proposals:write

devices:read

devices:write

Żądanie bez wymaganego zakresu jest odrzucane kodem 403.

Endpointy (19)

Wszystkie trasy działają pod jednym bazowym adresem URL i zwracają ten sam kształt błędu.

Metoda	Ścieżka	Zakres	Opis
`GET`	`/api/v1/contacts`	`contacts:read`	Zwraca stronę zasobu `contacts` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/contacts`	`contacts:write`	Tworzy nowy wpis zasobu `contacts`.
`GET`	`/api/v1/contacts/{id}`	`contacts:read`	Pobiera pojedynczy element `contacts` po ID. Brak zasobu lub brak dostępu = 404.
`GET`	`/api/v1/messages`	`messages:read`	Zwraca stronę zasobu `messages` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/messages`	`messages:write`	Tworzy nowy wpis zasobu `messages`.
`GET`	`/api/v1/messages/{id}`	`messages:read`	Pobiera pojedynczy element `messages` po ID. Brak zasobu lub brak dostępu = 404.
`GET`	`/api/v1/events`	`events:read`	Zwraca stronę zasobu `events` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/events`	`events:write`	Tworzy nowy wpis zasobu `events`.
`GET`	`/api/v1/events/{id}`	`events:read`	Pobiera pojedynczy element `events` po ID. Brak zasobu lub brak dostępu = 404.
`GET`	`/api/v1/documents`	`documents:read`	Zwraca stronę zasobu `documents` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/documents`	`documents:write`	Tworzy nowy wpis zasobu `documents`.
`GET`	`/api/v1/documents/{id}`	`documents:read`	Pobiera pojedynczy element `documents` po ID. Brak zasobu lub brak dostępu = 404.
`GET`	`/api/v1/envelopes`	`envelopes:read`	Zwraca stronę zasobu `envelopes` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/envelopes`	`envelopes:write`	Tworzy nowy wpis zasobu `envelopes`.
`GET`	`/api/v1/envelopes/{id}`	`envelopes:read`	Pobiera pojedynczy element `envelopes` po ID. Brak zasobu lub brak dostępu = 404.
`GET`	`/api/v1/proposals`	`proposals:read`	Zwraca stronę zasobu `proposals` (paginacja kursorowa, limit 100).
`POST`	`/api/v1/proposals`	`proposals:write`	Tworzy nowy wpis zasobu `proposals`.
`GET`	`/api/v1/proposals/{id}`	`proposals:read`	Pobiera pojedynczy element `proposals` po ID. Brak zasobu lub brak dostępu = 404.
`POST`	`/api/v1/campaigns/send`	`campaigns:write`	Uruchamia kampanię. Konsumuje jedną jednostkę `campaigns_per_month` oraz `messages_per_month` równe liczbie odbiorców. Ponad limit wiadomości API odpowiada 403 — chyba że tenant ma overage (`platform_config` → `overage.enabled`) i klienta Stripe; wtedy faktura za blok 1000 wiadomości, limit rośnie i wysyłka przechodzi.

Przykłady SDK

Punkty startowe do skopiowania (publiczny bazowy adres URL).

Node.js

Natywny fetch, ciało RFC 7807 przy błędzie, kursor z nextCursor.

const res = await fetch('https://api.traxmark.com/api/v1/contacts?limit=50', {
  headers: { Authorization: `Bearer ${process.env.TRAXMARK_API_KEY}` },
});
if (!res.ok) throw new Error(await res.text()); // RFC7807 JSON
const { items, nextCursor } = await res.json();

Python

requests z raise_for_status i dekodowaniem JSON.

import requests
r = requests.get('https://api.traxmark.com/api/v1/contacts',
                 headers={'Authorization': f'Bearer {API_KEY}'}, params={'limit': 50})
r.raise_for_status(); data = r.json()

Podmień zmienną środowiskową na klucz wydany w Ustawienia → Klucze API; zaczyna się od trax_.