API REST

Todos los endpoints están bajo https://api.saremi.io/v1/verify/ y requieren el header X-API-Key (ver Autenticación).

Verificación automática (recomendada)

POST /v1/verify/document
Content-Type: multipart/form-data

Envías el archivo y SAREMI detecta el tipo de documento automáticamente (por texto extraído, y si no es suficiente, con clasificación visual). Es el endpoint recomendado para la mayoría de integraciones.

curl -X POST https://api.saremi.io/v1/verify/document \
  -H "X-API-Key: TU_API_KEY" \
  -F "file=@ine_frontal.jpg" \
  -F "client_reference_id=expediente-1234"

Endpoints por tipo de documento

Si ya sabes el tipo de documento, puedes llamar directamente al endpoint específico en vez de /document — evita el paso de auto-detección:

Todos aceptan multipart/form-data con un campo file, y responden el mismo modelo de respuesta que /document. Son síncronos: la conexión se mantiene abierta hasta que termina el análisis (OCR + verificadores + análisis de fraude con IA), lo cual puede tardar 10–60 segundos.

Verificación asíncrona (recomendada)

POST /v1/verify/submit
Content-Type: multipart/form-data

Responde de inmediato (HTTP 200) con un id y status: "processing" — el análisis corre en segundo plano. Es el equivalente REST de SubmitDocument + GetVerificationResult en la API SOAP, y es la forma recomendada de integrarte si tu plataforma tiene límite de tiempo por request, o si simplemente quieres mostrarle “documento en revisión” al usuario de inmediato en vez de bloquear tu UI 10–60 segundos.

curl -X POST https://api.saremi.io/v1/verify/submit \
  -H "X-API-Key: TU_API_KEY" \
  -F "file=@ine_frontal.jpg" \
  -F "document_type=ine" \
  -F "client_reference_id=expediente-1234"

Respuesta inmediata:

{
  "id": "a1b2c3d4-...",
  "status": "processing",
  "document_type": "ine",
  "message": "Documento recibido. Consulta el resultado con GET /v1/verify/result/{id}."
}

Consulta el resultado con el id recibido:

GET /v1/verify/result/{id}

Mientras el análisis no haya terminado, sigue respondiendo { "id", "status": "processing", ... }. Al terminar, responde el mismo modelo de respuesta que los endpoints síncronos, con el campo "id" agregado. Recomendado: reintentar cada 10–15 segundos hasta que status deje de ser "processing".

curl https://api.saremi.io/v1/verify/result/a1b2c3d4-... \
  -H "X-API-Key: TU_API_KEY"

Registrar antes de analizar (obsoleto)

POST /v1/verify/pending

Crea un registro en estado processing antes de llamar a un endpoint síncrono, y devuelve { "id": "..." } para pasarlo como pending_id. Sigue funcionando, pero no evita el timeout: la llamada síncrona posterior sigue bloqueando 10–60 segundos igual. Para eso usa POST /v1/verify/submit, que sí regresa de inmediato.

Modelo de respuesta

Todos los endpoints de verificación devuelven el mismo objeto:

{
  "document_type": "ine",
  "status": "verified",
  "confidence_score": 0.925,
  "extracted_data": {
    "full_name": "JUAN PÉREZ LÓPEZ",
    "curp": "PELJ800101HDFRPN09"
  },
  "checks": [
    { "name": "curp_format", "status": "passed", "detail": "El formato del CURP es válido" }
  ],
  "conclusion": "Documento verificado correctamente...",
  "warnings": [],
  "fraud_flags": [
    {
      "code": "AI_GENERATED",
      "severity": "critical",
      "description": "El documento presenta patrones consistentes con generación por IA",
      "source_check": "image_authenticity"
    }
  ],
  "processing_time_ms": 18432,
  "report_url": "https://api.saremi.io/v1/verify/report/a1b2c3d4-..."
}

Reporte PDF membretado

Cada verificación completada genera automáticamente un reporte PDF con el membrete de SAREMI: veredicto, conclusión, checks, datos extraídos y alertas de fraude — listo para archivo o para compartir con el usuario final. La URL queda en report_url de la respuesta (o de GET /v1/verify/result/{id} si usaste el flujo asíncrono).

GET /v1/verify/report/{id}

Descarga el PDF directamente. Requiere el header X-API-Key de la misma institución dueña de la verificación — a diferencia del resto de la URL de la respuesta, no es un link público: sin el header no se puede descargar, así que si necesitas compartirlo con tu usuario final tienes que hacer de proxy (bajarlo desde tu backend y reenviarlo tú).

curl https://api.saremi.io/v1/verify/report/a1b2c3d4-... \
  -H "X-API-Key: TU_API_KEY" \
  -o reporte.pdf