# Usar SAT Captcha Solver

Envía una imagen del captcha SAT a `POST https://sat.ai.prevalentware.com/` con la clave existente en `x-api-key`. La respuesta contiene `data.result.codigo`, un texto de seis caracteres. El cliente mantiene la sesión SAT y envía ese texto al captcha que capturó.

## Referencias públicas

- Swagger: https://sat.ai.prevalentware.com/
- Contrato OpenAPI JSON: https://sat.ai.prevalentware.com/openapi.json
- Esta guía Markdown: https://sat.ai.prevalentware.com/docs

Estas rutas GET no requieren clave, no invocan el modelo ni generan registros o cobros de reconocimiento. El POST sí requiere clave y registra la ejecución en el IDP.

## Ejemplo Python

Obtener `IDP_API_KEY` mediante el mecanismo de secretos existente. No incluir su valor en prompts, logs o archivos públicos.

```python
import base64
import os
from pathlib import Path
import requests

image = base64.b64encode(Path("captcha.png").read_bytes()).decode("ascii")
response = requests.post(
    "https://sat.ai.prevalentware.com/",
    headers={"x-api-key": os.environ["IDP_API_KEY"]},
    json={
        "prompt": "Reconocer el captcha",
        "images": ["data:image/png;base64," + image],
        "response_type": "json",
    },
    timeout=60,
)
response.raise_for_status()
payload = response.json()
assert payload["status"] == "success"
codigo = payload["data"]["result"]["codigo"]
request_id = payload["data"]["provider_request_id"]
```

## Payload y límites

| Campo | Uso |
| --- | --- |
| `prompt` | String obligatorio, hasta 32 000 bytes UTF-8. Se conserva por compatibilidad; no dirige la inferencia. |
| `images` | Lista obligatoria de una o dos imágenes, en base64 puro o data URI `data:image/png;base64,...`. |
| `response_type` | `json` recomendado: `data.result` es objeto. Con `text`, el valor por defecto, es un string que contiene JSON. |
| `provider`, `model` | Campos heredados opcionales, aceptados para conservar el cliente. La inferencia siempre usa ONNX local. |
| `zdr` | Booleano opcional, por defecto `false`. Con `true`, el registro contable omite contenido y conserva medición. |

Máximo 1 MiB decodificado y 4 000 000 píxeles por imagen; cuerpo JSON máximo 3 MiB. Formatos PNG, JPEG, GIF o WebP; el tipo declarado en el data URI debe coincidir con los bytes. Preferir PNG. La primera imagen determina el resultado; la segunda se valida y cuenta para facturación. Enviar dos versiones de la misma imagen no produce dos predicciones. PDF y peticiones `file`/`s3_key` no están soportados.

Para el cliente Modinsa existente, conservar su payload color+gris, `provider: anthropic`, `model: sonnet-4.6` y parser. Cambiar `IDP_URL` a `https://sat.ai.prevalentware.com/`, conservar `IDP_API_KEY` y reiniciar el proceso. La URL del dominio no lleva `/prod`. El servidor normaliza el borde y escalado del pipeline heredado.

## Leer la respuesta

```json
{
  "status": "success",
  "data": {
    "result": {"codigo": "SCH57K", "confianza": 0.999814},
    "format": "json",
    "page_count": 1,
    "provider": "onnx",
    "model": "sat-captcha-boxfactura",
    "total_cost": 0,
    "provider_request_id": "00000000-0000-4000-8000-000000000000"
  }
}
```

El ejemplo muestra parte de los campos; OpenAPI enumera el contrato completo. `codigo` tiene seis caracteres. `confianza` está entre 0 y 1 y representa un score CTC sin calibración: no garantiza que SAT acepte el captcha. El modelo está orientado al login de Cancela y Recupera Tus Facturas; no se ha probado para todos los captchas del SAT.

`provider_request_id` permite correlacionar la respuesta con su registro contable. Los tokens y `total_cost` del modelo son cero. El precio al cliente lo resuelve el IDP desde la tarifa vigente de BD: una imagen cuenta como una página; color+gris cuentan como dos. La publicación contable precede al HTTP 200 y la persistencia en BD es asíncrona.

## Errores y reintentos

| HTTP | Acción |
| --- | --- |
| 400 | Corregir JSON, imágenes o límites. El handler devuelve `status: error` y `error`. |
| 403 | Revisar la clave y su autorización. Gateway puede devolver `message`; el handler puede devolver `status/error`. |
| 429 | Cuota o límite de solicitudes; reintentar con espera exponencial y jitter. |
| 500 | Fallo de inferencia; conservar el identificador de la respuesta/solicitud disponible y no asumir un código válido. |
| 503 | Publicación contable no disponible; no se devuelve resultado exitoso. |
| 504 | Timeout de Gateway; el resultado de la ejecución puede ser incierto. |

No hay clave de idempotencia de cliente: repetir un POST puede crear otra ejecución y otro cobro. No reintentar automáticamente un timeout como si fuera una lectura. Limitar reintentos y capturar el captcha vigente de la misma sesión antes de enviarlo al SAT. La API no realiza login, no administra credenciales SAT y no descarga facturas.