API i deweloperzy · Commingle

Commingle udostępnia API, które pozwala bezpiecznie dodawać transakcje do Twojego konta spoza aplikacji. Możesz wykorzystać je we własnych skryptach i automatyzacjach, połączyć Commingle z innymi usługami lub umożliwić agentowi AI dodawanie transakcji w Twoim imieniu. Twoje dane finansowe pozostają chronione szyfrowaniem end-to-end – transakcje są szyfrowane przed wysłaniem do Commingle, dzięki czemu API nie potrzebuje dostępu do ich niezaszyfrowanej zawartości. W tym przewodniku dowiesz się, jak uzyskać klucz API, przygotować i zaszyfrować dane transakcji oraz prawidłowo przesłać je do Commingle.

Już wkrótce

Uzyskaj klucz API

W Commingle przejdź do Menu główne → Ustawienia → Dostęp do API. W tym miejscu możesz wygenerować klucz API, który pozwoli zewnętrznym aplikacjom i automatyzacjom dodawać transakcje do Twojego konta. Na tym ekranie znajdziesz również swój klucz publiczny, potrzebny do zaszyfrowania danych transakcji przed wysłaniem ich do Commingle.

Twój klucz API wygląda następująco:

00000000-0000-0000-0000-000000000000_UserId

Chroń swój klucz API. Jeśli podejrzewasz, że mógł trafić w niepowołane ręce, wygeneruj nowy na tym samym ekranie. Poprzedni klucz zostanie natychmiast unieważniony.

Już wkrótce

Endpoint dodawania transakcji

POSThttps://api.commingle.app/v1/transactions

Żądanie

# Zaszyfruj dane lokalnie
envelope = encrypt(publicKey, {
  "type": "expense",
  "title": "Coffee",
  "amount": "8.99 USD",
  ...
})

# Do Commingle wysyłaj wyłącznie zaszyfrowane dane
[
  {
    "idempotency": "txn_20260928_001",
    "encryptedData": envelope.encryptedData,
    "encryptedKey": {
      "ephemeralPublicKey": envelope.encryptedKey.ephemeralPublicKey,
      "wrappedContentKey": envelope.encryptedKey.wrappedContentKey
    },
    "nonce": envelope.nonce
  },
  ...
]

Odpowiedź

[
  {
    "id": "transaction_123",
    "idempotency": "txn_20260928_001"
  }
]

Zapoznaj się z przykładem w Pythonie, który zawiera w pełni działającą implementację wraz z szyfrowaniem. Wystarczy podać swój klucz API oraz klucz publiczny. Dla czytelności w powyższym przykładzie używamy pełnych, opisowych nazw pól. Właściwe API korzysta z krótszych nazw i skrótów – dokładny format znajdziesz w przykładzie w Pythonie. Wartość idempotency jest opcjonalna, ale zalecana, aby zapobiec przypadkowemu przesłaniu tej samej transakcji więcej niż raz.

Koszt korzystania z API

Korzystanie z API zużywa kredyty Commingle. Każde żądanie kosztuje 1 kredyt + 1 kredyt za każdą pomyślnie dodaną transakcję. Na przykład żądanie, które doda tylko 1 transakcję, kosztuje 2 kredyty, a żądanie, które doda 10 transakcji, kosztuje 11 kredytów.

Wskazówki

Testuj bezpiecznie. Ponieważ właściwa struktura transakcji jest szyfrowana end-to-end, Commingle nie może dokładnie zweryfikować jej zawartości. Rozważ utworzenie tymczasowego konta Commingle na czas testowania integracji. Sprawdź w aplikacji, czy transakcje wyświetlają się prawidłowo, a następnie zastąp dane dostępowe danymi z głównego konta.
Unikaj duplikatów. Dla każdej transakcji podaj stałą wartość idempotency. Commingle wykorzystuje ją, aby zapobiec ponownemu dodaniu tej samej transakcji.
Znajdź identyfikatory. Identyfikatory kategorii, portfeli, wydarzeń i innych elementów możesz znaleźć i skopiować bezpośrednio z formularza ich edycji w Commingle.
Tylko transakcje osobiste. Obecnie przez API nie można dodawać transakcji współdzielonych ze znajomymi.
Jeden endpoint. Obecnie API Commingle udostępnia tylko endpoint służący do dodawania transakcji.

Open source

Otwarte części Commingle i to, jak je udostępniamy.

Znajomi

Jak działają salda między Tobą a znajomymi.