Use o solvethree em uma view do Django

1. 1.

   Instale no ambiente Django

   O SDK oficial exige Python 3.10+. No ambiente que executa o Django, use python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl.

2. 2.

   Defina as variáveis de ambiente do servidor

   Defina SOLVETHREE_API_KEY como a chave de API do seu workspace, CAPTCHA_SITE como o nome de host do destino — não uma URL completa — e SOLVETHREE_PROXY como o proxy usado para a resolução e o envio subsequente ao destino. Mantenha a chave de API e as credenciais do proxy no servidor.

3. 3.

   Ative o perfil do site

   Configure no console um perfil ativo para esse nome de host, disponível para o seu workspace. Enviar um nome de host e uma ação não cria um perfil. Consulte a configuração do perfil do site.

O exemplo fixa a ação em login e não recebe configurações do destino de quem faz a chamada. Altere essa ação se o destino configurado exigir outra. A requisição usa o modo padrão enterprise-v3; ela precisa de site, action e exatamente um entre proxy e proxyCandidates, não de type ou url.

# views.py in an existing Django project with authentication/CSRF configured.
import os
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.views.decorators.http import require_GET, require_POST
from solvethree import Solvethree, SolvethreeError

def client():
    return Solvethree(os.environ["SOLVETHREE_API_KEY"])

@login_required
@require_POST
def create_captcha(request):
    task = {"site": os.environ["CAPTCHA_SITE"], "action": "login", "proxy": os.environ["SOLVETHREE_PROXY"]}
    if request.headers.get("X-Request-ID"):
        task["requestId"] = request.headers["X-Request-ID"]
    try:
        return JsonResponse(client().create_task(task, wait_ms=0, timeout=20))
    except ValueError:
        return JsonResponse({"error": "Invalid task input"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

@login_required
@require_GET
def get_captcha(request, task_id):
    try:
        return JsonResponse(client().get_task(task_id, wait_ms=15000, timeout=25))
    except ValueError:
        return JsonResponse({"error": "Invalid task ID"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

# urls.py: import these views and add to urlpatterns:
# path("captcha/tasks", create_captcha),
# path("captcha/tasks/<str:task_id>", get_captcha),

create_task usa wait_ms=0, portanto retorna a tarefa sem aguardar toda a resolução. Sua chamada HTTP tem um tempo limite de 20 segundos. A view de consulta pode aguardar até 15 segundos por uma atualização da tarefa, com um tempo limite HTTP de 25 segundos. Essas chamadas do SDK são síncronas: a requisição de consulta continua ocupando seu worker do Django enquanto aguarda.

login_required restringe o acesso a usuários autenticados; os decoradores de método permitem POST para criação e GET para consulta. Mantenha a proteção CSRF normal do Django e inclua o token CSRF ao fazer o POST. Não adicione csrf_exempt.

1. 1.

   Atualize o URLconf existente

   Importe path de django.urls e importe create_captcha e get_captcha do módulo de views da sua aplicação. Adicione as duas entradas de rota mostradas no final do exemplo ao urlpatterns existente. Se você usa um URLconf da aplicação, certifique-se de que o URLconf do projeto o inclua.

2. 2.

   Inicie o servidor de desenvolvimento

   Com as variáveis de ambiente disponíveis para o processo, execute python manage.py runserver no diretório que contém manage.py. Use o fluxo de login existente do seu projeto antes de chamar os endpoints.

3. 3.

   Use os caminhos registrados

   Sem um prefixo de URL externo, a criação é feita com POST em /captcha/tasks e a consulta com GET em /captcha/tasks/<task_id>. As rotas fornecidas não têm barra no final. Inclua qualquer prefixo introduzido pelo URLconf do seu projeto.

1. 1.

   Salve um ID antes de enviar o POST

   Escolha um novo X-Request-ID para cada tarefa lógica e guarde-o até que o resultado da criação seja confirmado. Use de 1–64 letras ASCII, números, sublinhados ou hífens. A view encaminha esse cabeçalho como o requestId da tarefa.

2. 2.

   Verifique o sucesso HTTP antes do status da tarefa

   O exemplo retorna HTTP 400 para erros capturados de validação de entrada e 502 para erros capturados do SDK. Uma resposta bem-sucedida contém o payload da tarefa; leia seu id e status. O sucesso HTTP significa que a requisição foi bem-sucedida, não que um token está pronto.

3. 3.

   Consulte até a tarefa terminar

   Chame o endpoint GET com o ID retornado da tarefa. Continue para pending ou solving. Em ready, use a solução. Em failed, pare as consultas periódicas e verifique errorCode e error; resoluções que falham são reembolsadas. Corrija os dados de entrada inválidos em vez de tentar novamente sem alterá-los.

4. 4.

   Recupere uma criação incerta

   Se o POST atingir o tempo limite ou retornar um erro do SDK, não crie imediatamente outra tarefa com um novo ID. Consulte a tarefa existente se o ID dela for conhecido. Caso contrário, repita o POST com o X-Request-ID original e os mesmos dados de entrada da tarefa para recuperá-la. Reutilizar esse ID com dados de entrada diferentes gera um conflito — incluindo alterações no nome de host, na ação ou no proxy configurados.

A resposta de erro do SDK inclui requestId e taskId da exceção para diagnóstico. Guarde separadamente o X-Request-ID original de quem fez a chamada para que a recuperação não dependa do recebimento dessa resposta. Consulte erros da API de CAPTCHA para saber como tratar falhas.

Somente uma tarefa ready contém uma solução utilizável. O valor a enviar ao destino pretendido é solution.token, não o ID da tarefa. Use a identidade de navegador retornada em solution.userAgent e solution.secChUa, junto com o proxy original configurado em SOLVETHREE_PROXY.

Essas views não enviam nada ao destino. Seu código de envio deve manter esse proxy e aplicar a identidade retornada; retornar o token a uma sessão de navegador não relacionada não faz isso automaticamente. Mantenha as credenciais do proxy no servidor e não combine a solução com outra URL de destino ou identidade de navegador.