POST /v1/verify/w8ben-giin bezpłatny Bez klucza Weryfikacja

Weryfikacja danych statusu podatkowego podmiotu zagranicznego w…

Weryfikacja danych statusu podatkowego podmiotu zagranicznego w formularzach US IRS W-8BEN / W-8BEN-E, walidacja 19-znakowych sum kontrolnych FATCA GIIN Modulo 31 oraz ocena stawek podatku u źródła (withholding) na podstawie US Bilateral Income Tax Treaty

POST Adres żądania

Żądanie

x-api-key: <your-api-key>
Content-Type: application/json

Treść żądania

Odpowiedź

{
  "formAudit": {
    "formType": "standard",
    "isFormValid": true,
    "issues": [
      "<issue>"
    ],
    "warnings": []
  },
  "giinDetails": {
    "categoryCode": "ABC-123",
    "categoryName": "Ada Lovelace",
    "countryName": "Poland",
    "countryNumericCode": "ABC-123",
    "fatcaId": "fat_684777",
    "fiType": "standard",
    "isValid": true,
    "normalized": "PL61109010140000071219812874",
    "reason": "checksum ok"
  },
  "isValid": true,
  "status": "success",
  "tokensDeducted": 2,
  "treatyEligibility": {
    "countryOfTaxResidence": "PL",
    "isTreatyEligible": true,
    "treatyCountryName": "Poland",
    "withholdingRates": {
      "standardStatutoryRate": 4,
      "treatyDividendRate": 4,
      "treatyInterestRate": 4,
      "treatyRoyaltyRate": 4
    }
  }
}

Odpowiedź poniżej to makieta zbudowana ze schematu endpointu — żadne żądanie nie opuszcza tej strony. Zmień treść, naciśnij Wyślij, zobacz kształt odpowiedzi. Uruchom naprawdę w panelu →

Co robi

Żądanie

Treść

Pole	Typ	Wymagane	Opis
`chapter3Status`	string	nie	Entity classification (e.g., "Corporation", "Partnership", "Disregarded Entity")
`chapter4Status`	string	nie	FATCA classification (e.g., "REPORTING_MODEL_1_FFI", "ACTIVE_NFFE", "PASSIVE_NFFE")
`countryOfCitizenship`	string	nie	ISO 2-letter or 3-letter country code of tax residence
`dateOfBirth`	string	nie	Date of birth YYYY-MM-DD (W-8BEN individual)
`formType`	enum	tak	Target tax form or standalone GIIN verification One of: W-8BEN, W-8BEN-E, GIIN_ONLY.
`fullName`	string	nie	Beneficial owner name (W-8BEN individual)
`giin`	string	nie	19-character FATCA GIIN identifier (e.g., "980000.00000.ME.250")
`organizationName`	string	nie	Organization name (W-8BEN-E entity)

Przykładowe żądanie

{
  "chapter3Status": "success",
  "chapter4Status": "success",
  "countryOfCitizenship": "PL",
  "dateOfBirth": "2026-09-08",
  "formType": "W-8BEN",
  "fullName": "Ada Lovelace",
  "giin": "<giin>",
  "organizationName": "Ada Lovelace"
}

Odpowiedź

Pole	Typ	Opis
`formAudit`	object
`↳ formType`	string
`↳ isFormValid`	boolean
`↳ issues`	array<string>
`↳ warnings`	array<string>
`giinDetails`	object
`↳ categoryCode`	string
`↳ categoryName`	string
`↳ countryName`	string
`↳ countryNumericCode`	string
`↳ fatcaId`	string
`↳ fiType`	string
`↳ isValid`	boolean
`↳ normalized`	string
`↳ reason`	string
`isValid`	boolean
`status`	string
`tokensDeducted`	integer
`treatyEligibility`	object
`↳ countryOfTaxResidence`	string
`↳ isTreatyEligible`	boolean
`↳ treatyCountryName`	string
`↳ withholdingRates`	object

Przykładowa odpowiedź

{
  "formAudit": {
    "formType": "standard",
    "isFormValid": true,
    "issues": [
      "<issue>"
    ],
    "warnings": []
  },
  "giinDetails": {
    "categoryCode": "ABC-123",
    "categoryName": "Ada Lovelace",
    "countryName": "Poland",
    "countryNumericCode": "ABC-123",
    "fatcaId": "fat_684777",
    "fiType": "standard",
    "isValid": true,
    "normalized": "PL61109010140000071219812874",
    "reason": "checksum ok"
  },
  "isValid": true,
  "status": "success",
  "tokensDeducted": 2,
  "treatyEligibility": {
    "countryOfTaxResidence": "PL",
    "isTreatyEligible": true,
    "treatyCountryName": "Poland",
    "withholdingRates": {
      "standardStatutoryRate": 4,
      "treatyDividendRate": 4,
      "treatyInterestRate": 4,
      "treatyRoyaltyRate": 4
    }
  }
}

Błędy

Każdy błąd ma tę samą kopertę: status HTTP, kod maszynowy i jedno zdanie.

`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ą.
`429`	Przekroczony limit na minutę dla Twojego planu. Odczekaj i ponów.
`5xx`	Usługa nadrzędna odmówiła albo przekroczyła czas. Wywołanie nie jest rozliczane.

Kod

curl -X POST 'https://app.castomapi.com/v1/verify/w8ben-giin' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"chapter3Status": "success", "chapter4Status": "success", "countryOfCitizenship": "PL", "dateOfBirth": "2026-09-08", "formType": "W-8BEN", "fullName": "Ada Lovelace", "giin": "<giin>", "organizationName": "Ada Lovelace"}'

const res = await fetch('https://app.castomapi.com/v1/verify/w8ben-giin', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"chapter3Status": "success", "chapter4Status": "success", "countryOfCitizenship": "PL", "dateOfBirth": "2026-09-08", "formType": "W-8BEN", "fullName": "Ada Lovelace", "giin": "<giin>", "organizationName": "Ada Lovelace"})
});
const data = await res.json();
console.log(data);

import { request } from 'node:https';

// Node 18+ has fetch built in
const res = await fetch('https://app.castomapi.com/v1/verify/w8ben-giin', {
  method: 'POST',
  headers: { 'x-api-key': '<your-api-key>', 'Content-Type': 'application/json' },
  body: JSON.stringify({"chapter3Status": "success", "chapter4Status": "success", "countryOfCitizenship": "PL", "dateOfBirth": "2026-09-08", "formType": "W-8BEN", "fullName": "Ada Lovelace", "giin": "<giin>", "organizationName": "Ada Lovelace"})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    'https://app.castomapi.com/v1/verify/w8ben-giin',
    headers={'x-api-key': '<your-api-key>'},
    json={"chapter3Status": "success", "chapter4Status": "success", "countryOfCitizenship": "PL", "dateOfBirth": "2026-09-08", "formType": "W-8BEN", "fullName": "Ada Lovelace", "giin": "<giin>", "organizationName": "Ada Lovelace"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://app.castomapi.com/v1/verify/w8ben-giin');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['x-api-key: <your-api-key>', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['chapter3Status' => 'success', 'chapter4Status' => 'success', 'countryOfCitizenship' => 'PL', 'dateOfBirth' => '2026-09-08', 'formType' => 'W-8BEN', 'fullName' => 'Ada Lovelace', 'giin' => '<giin>', 'organizationName' => 'Ada Lovelace']),
]);
$data = json_decode(curl_exec($ch), true);
print_r($data);

Koszt i limity

Ta operacja nie wymaga klucza API i nic nie kosztuje: wywołana bez klucza odpowiada 200 i pobiera zero tokenów, do 10 żądań na minutę z jednego adresu IP.

Limity żądań na minutę

Bez klucza	10
Free	60
Pro	300
Enterprise	1200

Dokumentacja → Cennik

Pytania

Ile kosztuje Weryfikacja danych statusu podatkowego podmiotu zagranicznego w…?

Ta operacja nie wymaga klucza API i nic nie kosztuje: wywołana bez klucza odpowiada 200 i pobiera zero tokenów, do 10 żądań na minutę z jednego adresu IP.

Jak się uwierzytelnić?

Wyślij klucz w nagłówku x-api-key. Jeden klucz obejmuje każdy rozliczany endpoint; niczego nie trzeba włączać osobno.

Czy mogę wysłać nagłówek Authorization: Bearer zamiast klucza?

Nie dla rozliczanego endpointu — te przyjmują wyłącznie nagłówek x-api-key. Tokeny Bearer należą do strony konta: panel i API konta przyjmują sesję JWT, a castomapi-auth wydaje je standardowym uzgodnieniem OAuth2, z grantami authorization code, client credentials i refresh. Opisuje to strona usługi auth.

Jakie są limity?

10 żądań na minutę z jednego IP zupełnie bez klucza, 60 na minutę w planie Free, 300 w Pro, 1200 w Enterprise. Powyżej poziomu bez klucza limit jest na konto, łącznie dla wszystkich endpointów.

OpenAPI: https://app.castomapi.com/docs/json

Żądanie

Odpowiedź

Co robi

Żądanie

Treść

Przykładowe żądanie

Odpowiedź

Przykładowa odpowiedź

Błędy

Kod

Koszt i limity

Limity żądań na minutę

Pytania

Więcej w grupie Weryfikacja

Gdzie pasuje