Pierwsze kroki z castomAPI

1. Odbierz klucz

Zaloguj się pod https://dashboard.castomapi.com/ kontem castomo — tym, którego używasz do dash-b, castomo albo dowolnego produktu rodziny. Panel wydaje klucze API; surowy klucz jest pokazywany raz. Klucze można cofnąć z tego samego ekranu.

2. Wykonaj wywołanie

Każdy rozliczany endpoint przyjmuje klucz w nagłówku x-api-key. Treści są w JSON. To cała ceremonia:

curl -X POST https://app.castomapi.com/v1/verify/iban \
  -H 'x-api-key: <twoj-klucz-api>' \
  -H 'Content-Type: application/json' \
  -d '{"iban": "PL61109010140000071219812874"}'

Ten nagłówek to jedyny schemat, jaki przyjmuje rozliczany endpoint; token Authorization: Bearer go nie uwierzytelni. Bearer należy do strony konta: panel i API konta przyjmują sesję JWT, a castomapi-auth wydaje je standardowym uzgodnieniem OAuth2 — grantami authorization code, client credentials i refresh, przez /oauth/authorize, /oauth/token i /oauth/userinfo. Podłączenie konta Shopify albo Google klienta to trzecia sprawa, którą opisuje krok 7.

3. Przeczytaj kopertę

Każdy sukces odpowiada status: "success", danymi i tokensDeducted — kosztem wywołania, które właśnie wykonałeś. Każdy błąd odpowiada status: "error", maszynowym code, message napisanym dla człowieka i statusem HTTP. Błędy walidacji dodają tablicę details wskazującą pole.

{ "status": "success", "valid": true, "country": "PL", "tokensDeducted": 1 }

{ "status": "error", "code": "VALIDATION", "message": "body/iban must be a string", "statusCode": 400,
  "details": [{ "field": "iban", "reason": "must be string" }] }

4. Zrozum portfel

Koszt każdego endpointu jest w jego opisie i na jego stronie tutaj. Większość kosztuje jeden token.
Obciążenie następuje po odpowiedzi i tylko dla statusu poniżej 400. Niepowodzenia są bezpłatne.
Każde konto jest uzupełniane do 1000 tokenów przy pierwszym użyciu po upływie miesiąca — nie w stałym terminie. Opłacone saldo nigdy nie wygasa.
69 tras nie wymaga ani klucza, ani portfela: wywołane bez klucza odpowiadają 200, nic nie pobierają i mają limit 10 żądań na minutę z jednego IP.
Portfel może wejść w mały debet zamiast odmówić w połowie żądania; wyrównuje się przy następnym doładowaniu.
GET /wallet/balance i GET /wallet/ledger są bezpłatne i pokazują każdy ruch.

5. Obsłuż błędy

`400`	Treść albo parametr nie przeszły walidacji. Tablica details wskazuje pole.
`401`	Brak klucza, klucz cofnięty albo zły nagłówek. Wyślij x-api-key.
`402`	Portfel nie pokrywa tego wywołania. Doładuj albo poczekaj na miesięczny przydział.
`404`	Zasób nie istnieje albo nie jest Twój. Obie sytuacje odpowiadają identycznie i nic nie kosztują.
`409`	Kilka podłączonych kont na platformie i żadne nie wskazane; treść je wymienia. Albo slug już zajęty.
`429`	Przekroczony limit na minutę dla Twojego planu. Odczekaj i ponów. Nagłówek `retry-after` mówi, jak długo.
`502` / `504`	Usługa nadrzędna odmówiła albo przekroczyła czas. Wywołanie nie jest rozliczane.

6. Poznaj limity

Plan	Żądań / minutę
Bez klucza	10
Free	60
Pro	300
Enterprise	1200

Limity są na konto, łącznie dla wszystkich endpointów. Żądania bez uwierzytelnienia są ograniczane na adres IP do 10 na minutę.

7. Podłącz platformę

Integracje podłączają własne konto użytkownika końcowego. Z sesji panelu wywołaj auth/url platformy, wyślij tam użytkownika, a po zgodzie każde wywołanie tej grupy działa Twoim kluczem. Kilka kont na jednej platformie rozróżnia accountId. Szczegóły na stronie integracji.

8. Zabierz to do n8n, Make, Zapiera albo agenta

POST /v1/ecosystem/export generuje natywne pakiety węzłów dla n8n i Make z dowolnego zestawu endpointów. Grupa Zapier ma hooki, wsady i zadania asynchroniczne. Serwer MCP wystawia katalog każdemu klientowi Model Context Protocol jako narzędzia.

9. Przeczytaj specyfikację maszynową

Dokument OpenAPI 3 stojący za dokumentacją na żywo i za tą witryną: https://app.castomapi.com/docs/json. Wygeneruj z niego klienta, porównaj między wydaniami, podaj agentowi. llms.txt i llms-full.txt tej witryny to ten sam katalog skondensowany dla modeli językowych.