Руководство по API Редакто

Получение API ключа

API ключ тестовой среды выдается через блок «Тестовая среда API для интеграторов» на Главной странице. Форма запрашивает email, подтверждение синтетических тестовых данных и подтверждение политики обработки персональных данных. После проверки кода из письма исходный API ключ показывается один раз.

Ключ используется только на домене тестовой среды API, а не на основном домене лендинга. Если ключ потерян, получите новый ключ через тот же сценарий выдачи.

Базовый URL

Все рабочие запросы тестовой среды отправляются на отдельный сервис:

export REDACTO_API_BASE='https://sandbox-api.redactoapp.ru'
export REDACTO_SANDBOX_API_KEY='rdx_sbx_<keyId>_<secret>'

REDACTO_API_BASE хранит адрес API, а REDACTO_SANDBOX_API_KEY хранит API ключ, который вы получили на Главной странице. Эти переменные действуют только в текущем окне терминала; в новом окне их нужно задать повторно.

Схемы и полный список endpoint-ов доступны в Swagger. JSON-источник спецификации: openapi/redacto-sandbox.v1.openapi.json.

Подготовка терминала

Перед выполнением примеров задайте переменные и проверьте утилиты для удобного вывода. jq форматирует JSON, а unzip показывает содержимое ZIP-ответа файлового endpoint-а.

export REDACTO_API_BASE='https://sandbox-api.redactoapp.ru'
export REDACTO_SANDBOX_API_KEY='rdx_sbx_<keyId>_<secret>'

jq --version
unzip -v | head -n 1

Если jq не установлен, API все равно работает, но JSON будет выводиться одной длинной строкой. В примерах ниже вариант с | jq нужен только для удобного просмотра ответа.

Авторизация

Рабочие endpoint-ы используют схему OpenAPI SandboxBearer. Передавайте API ключ как Bearer token в заголовке Authorization.

Authorization: Bearer rdx_sbx_<keyId>_<secret>

Лимиты тестовой среды

При превышении почасового или общего лимита API возвращает 429 {"error":"quota_exceeded"}. При превышении размера запроса возвращается 413 {"error":"body_too_large"}.

Быстрый старт

Минимальная проверка: сначала убедитесь, что задан базовый URL и API ключ, затем запросите готовность среды выполнения и отправьте синтетический текст на анонимизацию.

Команда для проверки готовности:

export REDACTO_API_BASE='https://sandbox-api.redactoapp.ru'
export REDACTO_SANDBOX_API_KEY='rdx_sbx_<keyId>_<secret>'

curl -fsS "$REDACTO_API_BASE/readyz" | jq

Ответ на команду готовности:

{
  "ok": true
}

Следующая команда отправляет синтетический текст на анонимизацию:

curl -fsS "$REDACTO_API_BASE/v1/anonymize/text" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq
{
  "text": "Почта synthetic-buyer@example.test",
  "enableNer": false
}
JSON

Ответ на команду анонимизации будет JSON с maskedText, dictionary и кратким report:

{
  "maskedText": "Почта [EMAIL_1]",
  "dictionary": {
    "encrypted": false,
    "mapping": {
      "[EMAIL_1]": "synthetic-buyer@example.test"
    }
  },
  "report": {
    "totalFindings": 1,
    "maskedCount": 1,
    "dictionaryEntries": 1
  }
}

Словарь восстановления содержит исходные значения и должен храниться как чувствительный артефакт.

Текстовая анонимизация и восстановление

Перед выполнением примеров задайте REDACTO_API_BASE и REDACTO_SANDBOX_API_KEY, как показано в разделе подготовки терминала. POST /v1/anonymize/text принимает JSON. Поле text обязательно. Поля enableNer, dictionaryPassword и policy опциональны.

curl -fsS "$REDACTO_API_BASE/v1/anonymize/text" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq
{
  "text": "Почта synthetic-buyer@example.test\nТелефон +7 (111) 111-11-11",
  "enableNer": false,
  "dictionaryPassword": "",
  "policy": {
    "entityTypes": ["EMAIL", "PHONE"]
  }
}
JSON

Если нужно сохранить полный ответ и отдельно посмотреть замаскированный текст:

curl -fsS "$REDACTO_API_BASE/v1/anonymize/text" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' > /tmp/redacto-text-response.json
{
  "text": "Почта synthetic-buyer@example.test\nТелефон +7 (111) 111-11-11",
  "enableNer": false,
  "dictionaryPassword": "",
  "policy": {
    "entityTypes": ["EMAIL", "PHONE"]
  }
}
JSON

Команды для просмотра сохраненного ответа:

jq -r '.maskedText' /tmp/redacto-text-response.json
jq '.report' /tmp/redacto-text-response.json

Вывод будет выглядеть так:

Почта [EMAIL_1]
Телефон [PHONE_1]

Краткий отчет из report:

{
  "totalFindings": 2,
  "maskedCount": 2,
  "dictionaryEntries": 2
}

Пример полного успешного JSON-ответа:

{
  "maskedText": "Почта [EMAIL_1]\nТелефон [PHONE_1]",
  "dictionary": {
    "version": 1,
    "generator": "Redacto",
    "sourceFilename": "text.txt",
    "maskedFilename": "text.sanitized.txt",
    "encrypted": false,
    "mapping": {
      "[EMAIL_1]": "synthetic-buyer@example.test",
      "[PHONE_1]": "+7 (111) 111-11-11"
    }
  },
  "report": {
    "totalFindings": 2,
    "maskedCount": 2,
    "dictionaryEntries": 2
  }
}

POST /v1/restore/text восстанавливает текст по словарю из предыдущего ответа.

curl -fsS "$REDACTO_API_BASE/v1/restore/text" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq -r '.text'
{
  "text": "Почта [EMAIL_1]\nТелефон [PHONE_1]",
  "dictionary": {
    "version": 1,
    "generator": "Redacto",
    "encrypted": false,
    "mapping": {
      "[EMAIL_1]": "synthetic-buyer@example.test",
      "[PHONE_1]": "+7 (111) 111-11-11"
    }
  },
  "dictionaryPassword": ""
}
JSON

Ожидаемый вывод:

Почта synthetic-buyer@example.test
Телефон +7 (111) 111-11-11

Файловый ZIP-сценарий

Перед файловыми примерами задайте REDACTO_API_BASE и REDACTO_SANDBOX_API_KEY. Для просмотра результата нужен unzip. POST /v1/anonymize/file принимает multipart/form-data и возвращает бинарный ZIP. ZIP содержит анонимизированный файл и связанный *.dict.json.

printf 'Почта synthetic-buyer@example.test\nТелефон +7 (111) 111-11-11\n' > /tmp/redacto-synthetic.txt

curl -fsS "$REDACTO_API_BASE/v1/anonymize/file" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -F 'file=@/tmp/redacto-synthetic.txt;type=text/plain' \
  -F 'policy={"entityTypes":["EMAIL","PHONE"]}' \
  -F 'dictionaryPassword=' \
  -o /tmp/redacto-synthetic.sanitized.zip

unzip -l /tmp/redacto-synthetic.sanitized.zip

Вывод unzip -l должен показать два файла:

redacto-synthetic.sanitized.txt
redacto-synthetic.sanitized.dict.json

Чтобы быстро проверить содержимое словаря без вывода всего файла:

unzip -p /tmp/redacto-synthetic.sanitized.zip redacto-synthetic.sanitized.dict.json \
  | jq '.report? // {mappingSize: (.mapping | length)}'

POST /v1/restore/file принимает анонимизированный файл и словарь восстановления. Ответом будет восстановленный бинарный файл с подходящим Content-Type.

unzip -o /tmp/redacto-synthetic.sanitized.zip -d /tmp/redacto-synthetic-result

curl -fsS "$REDACTO_API_BASE/v1/restore/file" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -F 'file=@/tmp/redacto-synthetic-result/redacto-synthetic.sanitized.txt;type=text/plain' \
  -F 'dictionary=@/tmp/redacto-synthetic-result/redacto-synthetic.sanitized.dict.json;type=application/json' \
  -F 'dictionaryPassword=' \
  -o /tmp/redacto-synthetic.restored.txt

Проверка восстановленного текстового файла:

cat /tmp/redacto-synthetic.restored.txt

Ожидаемый вывод:

Почта synthetic-buyer@example.test
Телефон +7 (111) 111-11-11

JSON-режим для сервисных клиентов

Файловые endpoint-ы также принимают JSON с contentBase64. Этот режим удобен для сервисных интеграций и автотестов, но ответ /v1/anonymize/file все равно остается ZIP.

curl -fsS "$REDACTO_API_BASE/v1/anonymize/file" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- \
  -o /tmp/redacto-synthetic.sanitized.zip <<'JSON'
{
  "filename": "redacto-synthetic.txt",
  "contentBase64": "0J/QvtGH0YLQsCBzeW50aGV0aWMtYnV5ZXJAZXhhbXBsZS50ZXN0",
  "dictionaryPassword": "",
  "policy": {
    "entityTypes": ["EMAIL"]
  }
}
JSON

После JSON-запроса проверка такая же, как для multipart: unzip -l /tmp/redacto-synthetic.sanitized.zip.

policy.entityTypes

policy.entityTypes работает как список разрешенных типов для конкретного запроса: API обрабатывает только указанные типы, а остальные типы не ищет. Серверные обязательные типы могут быть добавлены обратно настройкой сервера и не отключаются политикой запроса.

Минимальный фрагмент JSON-политики:

{
  "policy": {
    "entityTypes": ["EMAIL", "PHONE"]
  }
}

Проверить такую политику на синтетическом тексте можно отдельным запросом. В ответе удобно смотреть только maskedText и report.

curl -fsS "$REDACTO_API_BASE/v1/anonymize/text" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq '{maskedText, report}'
{
  "text": "Почта synthetic-buyer@example.test, телефон +7 (111) 111-11-11, договор № SYN-42",
  "enableNer": false,
  "policy": {
    "entityTypes": ["EMAIL", "PHONE"]
  }
}
JSON

Ожидаемый вывод показывает, что маскируются только email и телефон; номер договора остается открытым, потому что CONTRACTNO не указан в списке разрешенных типов.

{
  "maskedText": "Почта [EMAIL_1], телефон [PHONE_1], договор № SYN-42",
  "report": {
    "totalFindings": 2,
    "maskedCount": 2,
    "dictionaryEntries": 2
  }
}

Чтобы отключить один тип из набора по умолчанию, передайте полный список типов, которые должны остаться включенными. Актуальный enum смотрите в Swagger или получайте через GET /v1/entity-types.

Каталог сущностей

GET /v1/entity-types возвращает каталог допустимых значений для policy.entityTypes, русские и английские названия, группы интерфейса, набор по умолчанию и обязательные серверные типы.

Чтобы запросить каталог из терминала, сначала задайте базовый URL. Без форматирования API вернет JSON одной строкой; для удобного просмотра используйте jq.

export REDACTO_API_BASE='https://sandbox-api.redactoapp.ru'

curl -fsS "$REDACTO_API_BASE/v1/entity-types" | jq

Если нужен только список кодов и русских названий:

curl -fsS "$REDACTO_API_BASE/v1/entity-types" \
  | jq -r '.entityTypes[] | "\(.type)\t\(.title.ru)"'

Пример сокращенного JSON-ответа каталога:

{
  "schemaVersion": 24,
  "entityTypes": [
    {
      "type": "EMAIL",
      "title": {
        "ru": "Email",
        "en": "Email"
      },
      "defaultEnabled": true,
      "required": false,
      "groups": ["common.contacts"]
    }
  ],
  "defaultEntityTypes": ["PERSON", "ORG", "BANK", "ADDRESS", "EMAIL"],
  "defaultDisabledEntityTypes": ["CONTRACTNO"],
  "requiredEntityTypes": []
}

Словарь восстановления

dictionary и файл *.dict.json содержат карту маркер -> исходное значение. Это чувствительный артефакт того же класса, что исходный текст или файл.

Для реальных корпоративных процессов используйте защищенное хранилище словарей, не пишите словари в логи и не передавайте их в системы, которым не нужен restore-сценарий.

Если вы сохранили ответ текстовой анонимизации в /tmp/redacto-text-response.json, структуру словаря можно проверить без вывода исходных значений:

jq '.dictionary | {encrypted, sourceFilename, maskedFilename, mappingSize: (.mapping | length)}' \
  /tmp/redacto-text-response.json

Ожидаемый вывод:

{
  "encrypted": false,
  "sourceFilename": "text.txt",
  "maskedFilename": "text.sanitized.txt",
  "mappingSize": 2
}

Коды ошибок

Ошибки возвращаются как JSON с полем error. Для бинарных endpoint-ов это правило применяется к ошибочным ответам. Для диагностических примеров ниже используется curl -sS без -f, чтобы curl не скрыл тело ожидаемой ошибки.

Пример запроса без Bearer token:

curl -sS "$REDACTO_API_BASE/v1/anonymize/text" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq
{
  "text": "Почта synthetic-buyer@example.test"
}
JSON

Ожидаемый ответ:

{
  "error": "auth_required"
}

Пример неподдерживаемого расширения файла:

curl -sS "$REDACTO_API_BASE/v1/anonymize/file" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq
{
  "filename": "synthetic.pdf",
  "contentBase64": "U1lOVEhFVElD"
}
JSON

Ожидаемый ответ:

{
  "error": "unsupported_format"
}

Фоновые задачи

Маршруты /v1/jobs/* описаны в Swagger для корпоративных сценариев с крупными Office-файлами и коротким временем ожидания HTTP-запроса. В публичной тестовой среде они выключены по умолчанию.

Команда использует те же REDACTO_API_BASE и REDACTO_SANDBOX_API_KEY. Здесь тоже используется curl -sS без -f, потому что ожидаемый результат публичной тестовой среды: ошибка 403 feature_disabled.

curl -sS "$REDACTO_API_BASE/v1/jobs/anonymize-file" \
  -H "authorization: Bearer $REDACTO_SANDBOX_API_KEY" \
  -H 'content-type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON' | jq
{
  "filename": "redacto-synthetic.txt",
  "contentBase64": "0J/QvtGH0YLQsA=="
}
JSON

Ожидаемый ответ публичной тестовой среды:

{
  "error": "feature_disabled"
}

Безопасность интеграции

• Не логируйте исходный текст, файлы, словари, ZIP-ответы, maskedText, API ключи и Bearer-заголовки.
• Храните *.dict.json как секрет: словарь содержит исходные значения и позволяет выполнить восстановление.
• Передавайте запросы только по HTTPS и задавайте время ожидания на стороне клиента для файловых операций.
• Перед дальнейшей передачей ZIP проверяйте, что словарь сохранен в защищенном хранилище.
• В тестовую среду отправляйте только синтетические данные и синтетические файлы.

Разбор неполадок

Все команды в руководстве предполагают предварительную настройку переменных из раздела «Подготовка терминала». Если команда возвращает пустой ответ или ошибку терминала, сначала проверьте echo "$REDACTO_API_BASE", echo "$REDACTO_SANDBOX_API_KEY", наличие jq и наличие unzip.

Если нужна точная форма поля или ответа, сверяйтесь со Swagger: он использует тот же OpenAPI JSON, который хранится рядом со страницей.