API y MCP · CheckThisFile

Descargar SDK · 0.2.0 Guía completa · English Skill de integración Índice para agentes

SDK de servidor · JavaScript y TypeScript

Descarga e instala el archivo con npm install ./checkthisfile-0.2.0.tgz. Node.js 22+, ESM y sin dependencias. Distribución local, todavía no publicado en npm.

import { readFile } from 'node:fs/promises';
import { CheckThisFile } from 'checkthisfile';

const ctf = new CheckThisFile({
  baseUrl: process.env.CHECKTHISFILE_BASE_URL, // origen, sin /api/v1
  apiKey: process.env.CHECKTHISFILE_API_KEY,
});
const result = await ctf.verifyBytes({
  publicId: process.env.CHECKTHISFILE_CERTIFICATE_ID,
  bytes: await readFile('./documento.pdf'),
});
// Aceptar solo result.verified === true.

El SDK no reintenta escrituras ni aprueba de forma implícita. Una excepción de red o permisos no es prueba de manipulación. También tienes un ejemplo Python sin dependencias.

Primera integración

Crea un espacio: Gratis incluye 3.000 peticiones API + MCP y 100 registros por mes natural UTC, sin tarjeta. Amplía el plan o compra una recarga desde Facturación cuando lo necesites.
Entra en API y MCP y crea una clave con verify:read.
Calcula SHA-256 sobre los bytes exactos del archivo en tu sistema. No normalices texto ni conviertas el formato.
Envía el ID del certificado y la huella. Usa data.verified === true como condición de coincidencia con un certificado válido y vigente.

curl 'https://checkthisfile.com/api/v1/verify' \
  -H "Authorization: Bearer $CHECKTHISFILE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"publicId":"ew_ID_REAL_DEL_CERTIFICADO","sha256":"HUELLA_HEXADECIMAL_DE_64_CARACTERES"}'

Sustituye los valores de ejemplo por un certificado emitido y una huella real. La clave vive en el servidor de tu aplicación, nunca en el frontend.

{
  "data": {
    "verified": true,
    "hashMatches": true,
    "signatureValid": true,
    "certificateCurrent": true,
    "certificateStatus": "valid",
    "reason": "MATCH",
    "documentUploaded": false
  },
  "error": null,
  "meta": {}
}

Un archivo modificado devuelve HASH_MISMATCH. Una huella que coincide con un certificado revocado o sustituido devuelve verified: false. El servicio compara lo que le envías; no prueba autoría ni veracidad.

GET /api/v1/usage muestra cuota, saldo y próximo reinicio sin gastar peticiones mensuales, incluso con cuota agotada (máximo 10/minuto). Los avisos al 80/95/100 % no autorizan compras ni cambios de plan automáticos.

Operaciones disponibles

OpenAPI 3.1 · descargar

Endpoints REST de CheckThisFile y permisos necesarios
Operación	Qué resuelve	Permiso
`GET /api/v1/usage`	Consumo y saldo incluso con cuota agotada	`Clave activa · cualquier scope`
`GET /api/v1/me`	Identidad, permisos y cuota	`Cualquier clave activa`
`POST /api/v1/verify`	Comparar huella, firma y vigencia sin subir el archivo	`verify:read`
`GET /api/v1/artifacts`	Documentos propios · limit y offset	`artifacts:read`
`GET /api/v1/artifacts/{id}`	Versiones, revisiones, aprobación y certificado del documento	`artifacts:read`
`POST /api/v1/artifacts` · Idempotency-Key	Registrar archivo o texto y ejecutar análisis local	`artifacts:write`
`POST /api/v1/artifacts/{id}/versions` · Idempotency-Key	Registrar y analizar una versión posterior	`artifacts:write`
`GET /api/v1/analyses/{id}`	Resultados y limitaciones del análisis	`analyses:read`
`POST /api/v1/artifacts/{id}/reviews` · Idempotency-Key	Declarar revisión y aportar el archivo exacto	`reviews:write`
`POST /api/v1/versions/{id}/approve` · Idempotency-Key	Aprobar con responsabilidad expresa	`approvals:write`
`POST /api/v1/versions/{id}/certificates` · Idempotency-Key	Emitir certificado con autorización de publicación	`certificates:write`
`GET /api/v1/certificates/{id}/download`	Descargar sobre JSON firmado de la organización	`certificates:read`
`POST /api/v1/certificates/{id}/revoke` · Idempotency-Key	Revocar con motivo documentado	`certificates:write`
`GET /api/v1/audit-events`	Historial de la organización · limit y offset	`audit:read`
`GET /api/v1/metrics/detectors`	Métricas agregadas de detectores	`metrics:read`
`GET /api/v1/certificates/{id}/verify`	Comprobación pública del certificado	`Público · sin clave`

Los permisos de la clave no elevan el rol del usuario. Registrar exige analyst/admin/owner; revisar, reviewer/admin/owner; aprobar, emitir y revocar, admin/owner. Análisis síncrono: local en desarrollo, parser separado por socket Unix obligatorio en producción.

MCP para agentes

Dirección: https://checkthisfile.com/api/v1/mcp. Transporte Streamable HTTP, sin sesión ni SSE; mensajes JSON-RPC y respuesta JSON. Versiones admitidas: 2025-11-25, 2025-06-18 y 2025-03-26.

{
  "mcpServers": {
    "checkthisfile": {
      "url": "https://checkthisfile.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${CHECKTHISFILE_API_KEY}"
      }
    }
  }
}

Ejemplo conceptual: el formato y la expansión de variables dependen de tu cliente. Puedes usar claves Bearer; OAuth opcional exige proveedor externo configurado, identidad vinculada y consentimiento. No se garantiza compatibilidad con todos los conectores web.

verificar_documento: huella, firma y vigencia.
verificar_certificado: datos autorizados para publicación.
listar_documentos: documentos de tu organización, si la clave lo permite.
consultar_consumo: plan y cuota.

No se ofrecen herramientas para declarar revisión, aprobar o emitir. Las herramientas disponibles se filtran por los permisos de la clave.

Contrato de integración

Sin archivo: /verify solo recibe el ID y la huella. El registro y la revisión sí envían los bytes al servidor; se aplica la política de retención de la organización.

Reintentos: conserva la misma Idempotency-Key y el mismo contenido en las escrituras. No hay garantía exactly-once ante un fallo entre el commit y la respuesta almacenada.

Cuotas: cada petición Bearer admitida consume una solicitud, incluso si después falla la validación, reproduce una respuesta o inicializa MCP. Las peticiones rechazadas por clave, scope, plan o cuota no consumen. Un 429 incluye Retry-After.

Errores: 401 clave inválida; 403 permisos o plan; 409 conflicto o solicitud en curso; 413 tamaño; 422 datos inválidos. En MCP, distingue errores HTTP de errores JSON-RPC.

Stripe, invitaciones Resend, webhooks con outbox cifrado y OAuth externo están implementados. Falta validar proveedores reales, el sandbox Docker y carga/TLS antes de la ingesta pública. Análisis sigue síncrono; la cola operacional no conserva documentos.