API для оплаты агентам

Введение

API для платежей агентов позволяет ИИ-агенту автономно управлять кредитами API и приобретать их от имени пользователя. Это обеспечивает работу в автоматическом режиме, позволяя агенту проверять оставшийся баланс кредитов, отслеживать лимиты расходов и пополнять кредиты через сохраненный пользователем способ оплаты Stripe — всё без участия человека.

Все три конечные точки размещены на payments.builtwith.com и пройдите аутентификацию с помощью своего API-ключа BuiltWith.

Прежде чем агент сможет использовать эти конечные точки, пользователь должен включить выставление счетов через API агента и настроить лимиты расходов. https://payments.builtwith.com/agent-payment-api-config.

Аутентификация

Передайте ключ API агента, используя один из описанных ниже способов. Параметр запроса KEY имеет приоритет, если указаны оба параметра.

Заголовок авторизации (рекомендуется)

Authorization: Bearer 00000000-0000-0000-0000-000000000000

Параметр запроса (резервный вариант)

?KEY=00000000-0000-0000-0000-000000000000

Запросы с отсутствующим, недействительным или отключенным ключом возвращают HTTP 401. Учетные записи с приостановленной оплатой возвращают HTTP 403.

🤖 Подсказка от ИИ-агента

Reference https://api.builtwith.com/llms.txt and
https://raw.githubusercontent.com/builtwith/builtwith-ai-sdk/refs/heads/main/README.md
Add BuiltWith Agent Payment API support to my app. Check the current API credit balance,
and if below 1000 credits, purchase 2000 more using the Agent Payment API.

GET /v1/billing/api-discovery — Кредитовый баланс

Возвращает текущий баланс средств API на счете.

Запрос

GET https://payments.builtwith.com/v1/billing/api-discovery?KEY=00000000-0000-0000-0000-000000000000

Поля ответа

Поле	Тип	Описание
`credits_total`	`number`	Общая сумма средств, когда-либо зачисленных на счет.
`credits_used`	`number`	Кредиты, израсходованные на вызовы API на данный момент.
`credits_available`	`number`	Остаток доступных кредитов (общая сумма минус использованные). Это то, что агент должен проверить перед выполнением вызовов API.

Пример ответа

{
  "credits_total": 10000,
  "credits_used": 1234,
  "credits_available": 8766
}

GET /v1/billing/api-configuration — Лимиты расходов

Возвращает установленные лимиты расходов и сумму уже использованного ежемесячного лимита. Агент должен проверить это перед попыткой покупки, чтобы избежать отклоненных запросов.

Запрос

GET https://payments.builtwith.com/v1/billing/api-configuration?KEY=00000000-0000-0000-0000-000000000000

Поля ответа

Поле	Тип	Описание
`max_per_purchase`	`number`	Максимальное количество кредитов, которое агент может приобрести за одну транзакцию.
`max_monthly`	`number`	Максимальное количество кредитов, которое агент может п��иобрести в течение текущего календарного месяца.
`monthly_purchased`	`number`	Кредиты, уже приобретенные агентом в этом календарном месяце.
`monthly_remaining`	`number`	Сколько ещё кредитов можно приобрести в этом месяце, прежде чем будет достигнут месячный лимит?
`cost_per_2000_credits_usd`	`number`	Стоимость покупки на сумму не менее 2000 кредитов в долларах США. Используйте эту информацию для оценки стоимости планируемой покупки.

Пример ответа

{
  "max_per_purchase": 5000,
  "max_monthly": 20000,
  "monthly_purchased": 5000,
  "monthly_remaining": 15000,
  "cost_per_2000_credits_usd": 99.00
}

POST /v1/billing/api-purchase — Купить кредиты

Списание средств с сохраненного пользователем способа оплаты Stripe и немедленное зачисление на счет. Покупка осуществляется в соответствии с лимитами на одну покупку и на месяц, установленными в настройках выставления счетов Agent API.

Запрос

POST https://payments.builtwith.com/v1/billing/api-purchase

Отправьте ключ API агента в качестве параметра. Authorization: Bearer заголовок или в качестве ?KEY= Параметр запроса. Тело запроса должно быть в формате JSON.

Текст запроса

Поле	Тип	Необходимый	Описание
`credits`	`number`	Да	Количество кредитов для покупки. Минимум 2000. Не должно превышать `max_per_purchase` или оставшуюся часть ежемесячного пособия.

Успешный ответ (HTTP 200)

Поле	Тип	Описание
`success`	`boolean`	`true`
`credits_purchased`	`number`	Кредиты зачислены на счет.
`cost_usd`	`number`	Сумма к оплате указана в долларах США.
`payment_id`	`string`	Идентификатор платежного намерения Stripe для сверки.
`credits_available`	`number`	Обновление доступного кредитного баланса после покупки.

Пример текста запроса

{ "credits": 2000 }

Пример успешного ответа

{
  "success": true,
  "credits_purchased": 2000,
  "cost_usd": 99.00,
  "payment_id": "pi_3abc123xyz",
  "credits_available": 10766
}

Ответы об ошибках

HTTP	Значение
400	Сбой проверки — количество кредитов меньше 2000, превышен лимит на одну покупку или превышен месячный лимит.
401	Отсутствует или недействителен ключ API агента.
402	Платеж через Stripe не удался или в системе не указан способ оплаты, за который можно произвести оплату.
403	Выставление счетов приостановлено.
405	Метод недопустим — конечная точка требует POST-запроса.

Специальные домены

Мы ведём два списка, которые пригодятся вам при поиске доменов: списки игнорирования и списки BuiltWith Suffix.

Список игнорирования
TЭто наш внутренний список доменов, которые мы не индексируем. Они либо заблокированы, либо содержат слишком много вводящих в заблуждение технологий, либо слишком много поддоменов с пользовательским контентом.

BuiltWith Список суффиксов
Это основано на Список публичных суффиксов но включает множество дополнительных записей для компаний с поддоменами, которые следует считать доменами верхнего уровня. Этот список обеспечивает лучшую видимость внутренних веб-сайтов, например, он выводит northernbeaches.nsw.gov.au на верхний уровень по сравнению с nsw.gov.au.

Игнорировать домены (XML, JSON or TXT)

https://api.builtwith.com/ignoresv1/api.json

Суффиксные домены (XML, JSON or TXT)

https://api.builtwith.com/suffixv1/api.json

Коды ошибок

Обратите внимание, что отправка сообщений об ошибках в этом формате не может быть гарантирована, ваша реализация должна также рассматривать коды ответа, отличные от 200, как ошибки. Свойство Lookup будет иметь значение null (json) или не будет предоставлено (xml), если ошибка связана с сервером. Просмотреть все возможные правильно сформированные коды ошибок.

Условия эксплуатации

Наш стандартные условия распространяется на использование всех наших API.

В целом, вы можете использовать API для улучшения своего продукта различными способами. Единственное ограничение — вы не можете перепродавать данные в их исходном виде или предоставлять дублирующий функционал builtwith.com и связанным с ним сервисам.