Към съдържанието
Sursa Developers

POST/v1/cards/{card_id}/verify

Потвърждаване, че картата е актуална

verify_card

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

Изпратете API ключ в заглавката Authorization: Authorization: Bearer <ключ>.

Параметри на пътя

  • card_idstringзадължително

Параметри в заглавката

  • Idempotency-Keystring

    Ключ за безопасен повторен опит при запис: от 1 до 255 печатаеми ASCII знака; препоръчва се UUID v4 за всяка логическа операция. Повторен опит със същия ключ в рамките на 24 часа не изпълнява операцията отново: връща записания отговор (статус, заглавки и тяло) със заглавката Idempotency-Replayed: true. Същият ключ с друг метод, път, Content-Type или тяло връща 409 api.idempotency_mismatch, а докато първата заявка още се изпълнява – 409 api.idempotency_in_progress с Retry-After: 1. След отговор 5xx или 429 ключът се освобождава и повторният опит изпълнява операцията отново. Ключът важи в рамките на организацията и извикващия (API ключ, потребител или ключ на собствен източник).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Само за API ключове с ролята admin. Изпълнява заявката от името на профила за достъп <profile>[:viewer|verifier|editor], например employee:viewer. Ключът на инсталацията не може да използва тази заглавка (403).

Параметри в бисквитка

  • kb_view_asstring

    Бисквитка на режима „View as“ за сесия. POST /auth/view-as я задава, а DELETE /auth/view-as я изчиства.

Тяло на заявката

application/json

Обект: VerifyRequest

  • notestring | null

Отговори

200Успешен отговор

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

  • Idempotency-Replayed

    true означава, че отговорът е възпроизведен от записания за този Idempotency-Key: операцията не е изпълнена отново.

application/json

Обект: Card

  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Допустими стойности: wholepartial

  • access_contactstring

    С кого да се свържете за достъп (само при access=partial).

  • aclobject
    Полета
    • verifybooleanзадължително
    • writebooleanзадължително
  • categorystringзадължително
  • category_confidencenumber | nullзадължително
  • category_lockedbooleanзадължително
  • category_reviewbooleanзадължително
  • category_sourceCategorySource | nullзадължително
  • collectionstringзадължително
  • collection_idintegerзадължително
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Съдържанието за редактора на последната публикувана версия. Полето може да липсва; в такъв случай вземете съдържанието за редактора от чернова (POST /v1/drafts с card_id).

  • editing_lockEditingLock | null

    Активно заключване за редактиране. Полето може да липсва; в такъв случай редакторът научава кой държи заключването от 409 cards.locked при POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)задължително
  • days_since_verifiedintegerзадължително
  • errorstring | nullзадължително
  • eventsarray of CardEvent
  • feedback_negintegerзадължително
  • feedback_posintegerзадължително
  • foldersarray of CardFolderRef

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

  • has_tablesboolean

    Само в списъка с карти.

  • hidden_partsboolean
  • idstringзадължително
  • jobJob | null
  • kindCardKindзадължително
  • org_idintegerзадължително
  • owner_activeboolean | null
  • owner_idinteger | nullзадължително
  • owner_namestring | nullзадължително
  • pagesinteger | nullзадължително
  • parserstring | nullзадължително

    Начин на разбор на документа като неутрален код: document (пълна структура: страници, заглавия, таблици, сканирани страници), pdf (текстовият слой на PDF), docx, xlsx, csv, markdown, html, text. Списъкът може да се разширява.

  • partsarray of CardPartзадължително
  • sensitivebooleanзадължително
  • sha256string | nullзадължително
  • sizeintegerзадължително
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanзадължително
  • source_pathstring | nullзадължително
  • source_urlstring | nullзадължително
  • statusstringзадължително

    Допустими стойности: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringзадължително
  • titlestringзадължително
  • trustnumberзадължително
  • trust_if_verifiednumber
  • trust_partsTrustPartsзадължително
  • updated_atstring (date-time)задължително
  • verificationVerificationзадължително
  • verified_atstring (date-time) | nullзадължително
  • verified_byinteger | nullзадължително
  • verified_by_namestring | null
  • verifier_idsarray of integerзадължително
  • verifiersarray of object
    Полета
    • activebooleanзадължително
    • idintegerзадължително
    • namestringзадължително
  • verify_interval_daysintegerзадължително
  • versionintegerзадължително
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Ръчни настройки на разбора (преглед на разбора).

  • doc_kindDocKind | null

    Тип на документа. null, ако типът не е определен (например за карти, индексирани преди въвеждането на типовете документи).

  • doc_kind_confidencenumber | null

    Степен на увереност в типа на документа, от 0 до 1.

  • doc_kind_sourcestring | null

    Какво е определило типа: правила (rules), потребител (manual) или автоматична класификация. Списъкът може да се разширява: третирайте непозната стойност като автоматична класификация.

    Допустими стойности: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Полета на фактура, кредитно известие или касова бележка (само за тези типове и само в картата, не в списъка). null, ако нямате достъп до целия документ, защото полетата се извличат от целия документ.

  • warningsarray of ReviewWarning

    Предупреждения при разбора на документа (ReviewWarning; само в картата, не в списъка).

  • enrichmentCardEnrichmentStatus | null

    Статус на обогатяването (само в картата, не в списъка). Типът на документа, полетата на фактурата и финансовите записи се добавят във фонов режим след индексирането и може да бъдат преизчислени по-късно; те се появяват в картата, когато са готови. null означава, че няма наличен статус (картата е индексирана без фоново обогатяване).

  • external_idstring | null

    ID на картата в системата на интегратора. Уникален е в организацията сред картите, които не идват от източници; null означава, че не е зададен. /v1/cards-by-external-id/{external_id} чете и заменя картата по него.

    length ≤ 512

  • metadataMetadata
400Заявката е невалидна: стойност на параметър или състоянието на обекта не позволява действието (`detail` е съобщение).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

401Не са изпратени идентификационни данни (нито бисквитка на сесията, нито API ключ) или ключът не е намерен.

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

403Действието не е разрешено: ролята е недостатъчна, няма достъп до колекцията или картата, заявката се изпълнява в режим „View as“ или организацията е спряна или изтрита (`detail` е обект с `code: org_suspended | org_deleted`).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

404Обектът не съществува или не е достъпен за вас. API не потвърждава, че съществува обект с ограничен достъп.

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

422Грешка при валидиране: тялото или параметрите не съответстват на схемата (`detail` е списък с грешки при валидиране) или стойност на параметър е извън допустимия диапазон (`detail` е съобщение).

Заглавки на отговора

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

429Твърде много заявки (`api.rate_limited`), квотата на организацията за минутата, деня или месеца е изчерпана (`api.quota_exceeded`; `error.details` съдържа `quota`, `limit` и `reset_at`), достигнат е лимит на организацията или услугата за отговори е заета (`answers.engine_busy`). Изчакайте времето от заглавката `Retry-After`.

Заглавки на отговора

  • Retry-After

    Брой секунди, които да изчакате, преди да повторите заявката.

  • RateLimit-Policy

    Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.

  • RateLimit

    Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).

  • X-RateLimit-Remaining

    Оставащи заявки по най-строгия лимит.

  • X-RateLimit-Reset

    Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

Кодове на грешки

Кодове, които тази операция може да върне в error.code, освен общите кодове на всяка заявка.

Безопасни повторни опити

Изпращайте заглавката Idempotency-Key (например UUID) с всяка заявка POST и PATCH. Повторен опит със същия ключ в рамките на 24 часа връща запазения отговор, вместо да изпълни заявката отново.

Лимити на честотата

Отговорите съдържат заглавките RateLimit и RateLimit-Policy, както и по-ранните X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Отговорът 429 съдържа Retry-After в секунди: изчакайте и опитайте отново.

← cards · Справочник на API