Разработчици

API за митническа проверка

Същата проверка като на този сайт, извиквана от вашия софтуер. Изпращате досие в JSON и получавате оценка от 100, блокиращите точки, предупрежденията и препоръчаните действия — със стабилни кодове на несъответствия и съобщения на 24-те официални езика на Европейския съюз.

Създаване на ключ Спецификация OpenAPI

Това е API между сървъри. Ключът за API е тайна. Извикванията от браузър не се поддържат и по удостоверените маршрути не се изпращат заглавки CORS: ключ, който попадне в браузър, е разкрит ключ.

Общ преглед

API предоставя контролния механизъм на валидатора: четиринадесет общи правила, пет правила по TARIC, четири правила за пълнота на документите и валидаторите на всяка декларационна система. Не изпраща нищо: проверява формата и съгласуваността на преписката, наличието на кодовете в номенклатурата и, при внос в ЕС, мерките по TARIC, приложими за произхода (антидъмпинг, контрол, преференции, ставка на митото), преди да подготвите декларацията.

Всеки маршрут носи префикс на своята версия. Маршрутите за откриване и спецификацията са публични: интегратор или агент може да прочете схемата още преди да разполага с ключ.

Маршрут	Роля	Удостоверяване
POST/v1/checks	Проверява досие и връща пълния доклад	Изисква ключ
POST/v1/checks/batch	Проверява до 25 досиета с едно извикване	Изисква ключ
GET/v1/me	Връща текущия ключ и квотата му, без да я изразходва	Изисква ключ
GET/v1/declaration-types	Изброява разпознаваните видове декларации	Публичен
GET/v1/declaration-types/{type}	Описва полетата, очаквани за даден вид	Публичен
GET/v1/openapi.json	Спецификацията OpenAPI 3.1 на това API	Публичен

Удостоверяване

API-то се удостоверява с токен носител. Токенът се показва само веднъж, при създаването: запазва се само неговият отпечатък, така че изгубен ключ се заменя, но никога не се възстановява.

Можете да държите три активни ключа едновременно, което позволява да завъртите ключ, без да прекъсвате интеграцията си: създайте новия, внедрете го и после отнемете стария.

01Създайте ключ от профила си, в раздел „API ключове“.
02Изпращайте го в заглавката Authorization на всяка заявка.
03Отнемете го при изтичане: прекъсването е незабавно, а съдържанието на досиетата, подадени с този ключ, се изтрива веднага.

Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Първа проверка

Едно досие се състои от вид, заглавна част и стокови редове. Всички стойности са низове: машината се грижи за тълкуването им. Имената на полетата се откриват по време на изпълнение, вид по вид.

Отговорът идва незабавно; след това няма какво да се запитва.

Заявка

curl https://www.customs-check.com/api/v1/checks \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "import-export",
    "reference": "PO-2026-114",
    "header": {
      "flow": "IM",
      "shipmentCountry": "CN",
      "destinationCountry": "FR",
      "incoterm": "FOB",
      "companyName": "Acme SAS",
      "companyCountry": "FR",
      "eori": "FR12345678900012",
      "transportMode": "sea",
      "currency": "USD",
      "invoiceTotal": "12500"
    },
    "items": [
      {
        "description": "Leather sport shoes",
        "hsCode": "6403990000",
        "quantity": "500",
        "value": "12500",
        "origin": "VN",
        "grossMass": "850",
        "netMass": "800"
      }
    ],
    "documents": { "commercialInvoice": "available", "packingList": "missing" }
  }'

Четене на отговора

Всяко несъответствие носи едновременно машинна самоличност и четимо изречение. Изградете логиката си върху машинната самоличност: тя не се променя без смяна на версията.

severity · code · path · rule: Стабилен договорСтабилни. Може да се появят нови кодове; съществуващите не се преименуват без смяна на версията.
field · message · text: Само за показванеПреведени за показване. Могат да бъдат преформулирани по всяко време — никога не ги сравнявайте в кода си.
engine.version: Променя се, щом промяна в правилата измести оценката на непроменено досие. Архивирайте я заедно с докладите си.

Полето „path“ отразява формата на вашата заявка, така че можете да свържете несъответствие направо със съответното поле във вашия интерфейс.

header.<поле> · items.<n>.<поле> · documents.<category> · global

Отговор

{
  "id": "4c749e25-3408-48f9-b3ca-b18a7ad84681",
  "createdAt": "2026-09-16T12:46:13.186Z",
  "type": "import-export",
  "locale": "en",
  "reference": "PO-2026-114",
  "score": 90,
  "level": "good",
  "counts": { "errors": 0, "warnings": 2, "infos": 1 },
  "documents": { "commercialInvoice": "available", "packingList": "missing" },
  "issues": [
    {
      "severity": "warning",
      "code": "docPackingListMissing",
      "path": "documents.packingList",
      "rule": "DOC-002",
      "params": null,
      "field": "Packing list",
      "message": "Packing list not provided",
      "text": "Packing list not provided"
    },
    {
      "severity": "warning",
      "code": "docTransportMissing",
      "path": "documents.transportDocument",
      "rule": "DOC-003",
      "params": null,
      "field": "Transport document (B/L, AWB, CMR)",
      "message": "Transport document not provided",
      "text": "Transport document not provided"
    }
  ],
  "actions": [
    { "severity": "warning", "code": "docPackingListMissing",
      "path": "documents.packingList", "text": "Add: Packing list" }
  ],
  "tips": [
    {
      "severity": "info",
      "code": "taricControlsPossible",
      "path": "items.0.hsCode",
      "rule": "RULE-017",
      "params": { "measures": "Import control - CITES ; Import control on seal products" },
      "field": "Product 1 — HS / commodity code (if known)",
      "message": "Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply.",
      "text": "Product 1 — HS / commodity code (if known): Possible import controls depending on the goods (Import control - CITES ; Import control on seal products): check whether they apply."
    }
  ],
  "engine": { "version": "1.6.0", "rules": 25, "taric": "2026-10-01" }
}

Откриване на полетата

Видовете декларации и техните полета са публични, не е нужен ключ. Това е маршрутът за изграждане на формуляр, за захранване на съответствие от вашия ERP или за предаване на схемата на агент, който трябва да я попълни.

Върнатите тук имена са точно ключовете за използване в заглавната част и във всеки стоков ред. Списъците с възможности се връщат разрешени и преведени; добавете параметъра, за да ги пропуснете, ако отговорът ви се струва тежък.

# The 8 declaration types
curl "https://www.customs-check.com/api/v1/declaration-types?locale=en"

# The fields of one type
curl "https://www.customs-check.com/api/v1/declaration-types/h7?locale=en"

# Same, without the resolved option lists
curl "https://www.customs-check.com/api/v1/declaration-types/h7?options=false"

Пакетна обработка

До 25 досиета на извикване. Отговорът винаги е успешен, щом пакетът бъде приет, а всеки запис носи собствен статус: едно неправилно оформено досие никога не проваля останалите.

Ако оставащата квота не покрива всички валидни записи, целият пакет се отхвърля, вместо да се обработи частично — никога не се налага да гадаете къде е спряла обработката.

curl https://www.customs-check.com/api/v1/checks/batch \
  -H "Authorization: Bearer $CUSTOM_CHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": [ { "type": "h7", "header": {}, "items": [] } ] }'

Агенти и инструменти

Освен REST маршрутите, същият механизъм и същите данни са достъпни от ИИ асистент чрез сървър за Model Context Protocol (MCP) и от API клиент чрез готова колекция за Postman. И двата използват API ключа и дневната квота, описани по-горе.

MCP сървър

MCP сървърът позволява на асистент да търси митнически кодове, да чете вносното мито за даден код, да проверява номер EORI, ДДС или AEO в официалните регистри и да проверява чернова на декларация, без да пишете нито ред свързващ код. Отговаря на POST /api/mcp, с JSON отговори.

Той е без състояние и поддържа и двете поколения на протокола: ревизията 2026-07-28, при която всяка заявка носи своята версия, и по-ранните ревизии, които започват с извикване initialize. Връзката, откриването и списъкът с инструменти са безплатни; всяко извикване на инструмент използва една единица от дневната квота на ключа.

Удостоверяването е със същия bearer токен като REST API. Клиент, който поддържа само вход чрез OAuth, като уеб конекторите на claude.ai, засега не може да се свърже: използвайте клиент, който позволява задаване на хедър.

POST https://www.customs-check.com/api/mcp

claude mcp add --transport http customs-check https://www.customs-check.com/api/mcp \
  --header "Authorization: Bearer $CUSTOM_CHECK_KEY"

check_declaration	Проверка на чернова на декларация: оценка от 100, ниво и всеки проблем с полето и действието. Не запазва съдържанието на файла, освен ако не е поискано.
list_declaration_types	Поддържаните декларационни системи, с орган, регион и очаквани документи.
describe_declaration_type	Полетата на заглавната част и на позициите на даден тип, за да се състави входът на check_declaration.
search_hs_codes	Кандидатни кодове от Комбинираната номенклатура по описание на продукта, на всеки от 24-те езика на ЕС.
describe_hs_code	Дали код от 4 до 10 цифри съществува в действащата номенклатура, с официалния му път и текст.
lookup_import_duty	Вносно мито на ЕС за даден код по данните TARIC на Комисията: мито за трети държави, преференции за произход, квоти, антидъмпингови мерки и контрол.
search_chemical	Химично вещество по CAS номер, CUS номер или име в описа ECICS на Комисията: кодът от Комбинираната номенклатура за всеки запис, за проверка.
get_quota_balance	Оставащ остатък от тарифна квота на ЕС в базата QUOTA на Комисията, по пореден номер или по код и произход: остатък, състояние (отворена, критична, блокирана, изчерпана), период и час на прочитане.
validate_eori	Формат на номер EORI и състоянието му в официалния регистър (Европейска комисия, HMRC).
validate_vat	Формат на номер по ДДС в ЕС и валидността му във VIES, с вписаното наименование, когато е публикувано.
check_rex	Формат на REX номер на регистриран износител и статусът му в базата данни REX на Комисията (валиден, отменен или неизвестен), с датите.
screen_sanctions	Дружество, лице или кораб спрямо санкционните списъци на ЕС, ООН, Обединеното кралство и САЩ, актуализирани всеки ден: всяко съвпадение с оценка, силно или частично.
search_aeo	Търсене в базата данни на Комисията за одобрени икономически оператори по име на фирма.

Митническите кодове са предложения, взети от текста на номенклатурата. Класирането може да потвърди само декларантът или обвързваща тарифна информация от митницата.
Митата са ориентировъчни: условията, изключенията по държави и изчерпаните квоти не се оценяват. Всеки отговор носи референтната дата на извадката от TARIC, обновявана ежемесечно.
Регистър, който не отговаря, се отчита като недостъпен, никога като невалиден номер. Нищо никога не се изпраща на митницата.

Колекция за Postman

Колекцията се генерира от спецификацията OpenAPI, така че винаги съвпада с нея: една заявка на маршрут, групирани по етикет, със скелет на тялото за всеки POST. Импортирайте я в Postman, попълнете променливата apiKey (пази се като тайна) и заявките са готови за изпращане.

Изтегляне на колекцията

Квота

Всеки ключ разполага с 500 проверки на календарен ден по UTC. Текущото състояние пътува с всеки удостоверен отговор, така че никога не ви трябва допълнително извикване, за да го узнаете.

Отхвърлените извиквания също се броят: клиент, който зацикля върху невалидни заявки, сам се ограничава. Квотата се определя за всеки ключ — пишете ни, ако ви трябва повече.

Отговор

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 437
X-RateLimit-Reset: 1789603200
X-RateLimit-Policy: 500;w=86400

Грешки

Съобщенията за грешка са само на английски: това са протоколни съобщения, предназначени за разработчици. Превежда се само съдържанието по същество.

Всеки отговор носи идентификатор на заявката, повторен в тялото. Посочете го, когато се свържете с нас — води ни право до извикването.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body failed validation.",
    "details": [
      { "path": "items.0.quantity", "message": "expected a string" }
    ],
    "requestId": "2bbb0946-6178-4b54-921c-b28f794c44bd"
  }
}

Статус	code	Значение
400	invalid_json	Тялото не е валиден JSON.
422	invalid_request	JSON е валиден, но съдържанието му не е. Подробностите посочват грешното поле.
401	missing_credentials	Липсваща или неправилна заглавка Authorization.
401	invalid_key	Непознат ключ.
401	key_revoked	Отнет ключ.
403	account_suspended	Профилът, притежаващ ключа, е спрян.
415	unsupported_media_type	Типът съдържание не е JSON.
413	payload_too_large	Тялото на заявката е твърде голямо.
429	rate_limit_exceeded	Достигната дневна квота. Вижте заглавката Retry-After.
500	internal_error	Грешка от наша страна. Опитайте отново и ни я съобщете с идентификатора на заявката.

Данни и съхранение

Досиетата, изпратени през API, са данни на вашите клиенти: пазим възможно най-малко, а вие разполагате с ключ, за да не се пази нищо.

Изпратете „store“ като false и никакво съдържание на досието няма да бъде записано: остават само оценката и кодовете на несъответствия.
В противен случай съдържанието на досиетата се изтрива след 30 дни.
Отнемането на ключ незабавно изтрива съдържанието на досиетата, подадени с него.
Обработката се извършва във Франкфурт, а базата данни се хоства в Европейския съюз.
През API не се качват файлове: вие само посочвате какви документи притежавате.

200 items · 256 KB · 25 / batch · reference ≤ 64

Какво не е това API

Проверката помага при подготовката. Тя не представлява одобрение от митническата администрация, не подава нищо и не замества нормативните задължения, приложими към вашата операция.

Митническите кодове се проверяват за формат, наличие в номенклатурата и, при внос в ЕС, спрямо мерките по TARIC за техния произход, но никога за класирането на стоката: съществуващият код остава код за проверка. Мерките по TARIC са ориентировъчни (месечно извлечение на Европейската комисия): изключенията на държави, изчерпаните квоти и условните мита не се оценяват.