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

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

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

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

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

Общ преглед

API-то предоставя машината за проверка на валидатора: тринадесет правила през полетата, четири правила за пълнота на документите и валидаторите, присъщи на всяка декларационна система. То не подава нищо и не запитва никаква тарифна база — проверява вътрешната съгласуваност и формата на вашето досие, преди да подготвите декларацията.

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

Маршрут	Роля	Удостоверяване
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-то се удостоверява с токен носител. Токенът се показва само веднъж, при създаването: запазва се само неговият отпечатък, така че изгубен ключ се заменя, но никога не се възстановява.

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

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

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": 0 },
  "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": [],
  "engine": { "version": "1.0.0", "rules": 13 }
}

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

Видовете декларации и техните полета са публични, не е нужен ключ. Това е маршрутът за изграждане на формуляр, за захранване на съответствие от вашия 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": [] } ] }'

Квота

Всеки ключ разполага с 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

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

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