API y MCP - CheckThisFile

Registrar solo la huella, sin subir el documento

Modalidad específica sin revisión ni aprobación: reserva del enlace, registro por SHA-256, empresas autorizadas, versiones, evidencia portable y reconciliación. Una unidad por versión nueva, repeticiones sin consumo adicional.

API de integridad - Python httpx y MCP

Los ejemplos de certificados de revisión de esta página corresponden al flujo anterior, no son necesarios para el registro por huella.

Descargar SDK - 0.2.0 Guía de certificados - 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
`POST /api/v1/integrity/records`	Register SHA-256 only - permanently deduplicated version, no review	`integrity:write`
`POST /api/v1/integrity/reservations`	Reserve a link before finalizing the PDF - no usage charge	`integrity:write`
`GET /api/v1/integrity/lookup`	Look up by company, source, document and version	`integrity:read`
`GET /api/v1/integrity/records/{publicId}`	Retrieve a record for an authorized company	`integrity:read`
`GET /api/v1/integrity/records/{publicId}/evidence`	Export portable evidence and a signed status observation	`integrity:read`
`POST /api/v1/integrity/records/{publicId}/revoke`	Revoke while retaining historical evidence	`integrity:revoke`
`GET /api/v1/integrity/changes`	Reconcile company changes with a stable cursor	`integrity:read`
`GET /api/v1/integrity/usage`	Integrity allowance and company contribution	`integrity:read`
`GET /api/v1/integrity/companies`	Companies authorized for this key	`integrity:read`
`POST /api/v1/integrity/companies`	Create an opaque company - owner/admin	`integrity:admin`
`POST /api/v1/integrity/companies/{companyId}/access`	Grant or revoke key access by company	`integrity:admin`
`POST /api/v1/integrity/companies/{companyId}/webhooks`	Authorize destinations by company	`integrity:admin`
`GET /api/v1/usage`	Usage and balance, including when the allowance is exhausted	`Clave activa - cualquier scope`
`GET /api/v1/me`	Identidad, permisos y cuota	`Cualquier clave activa`
`POST /api/v1/verify`	Compare hash, signature and current status without uploading the file	`verify:read`
`GET /api/v1/artifacts`	Documentos propios - limit y offset	`artifacts:read`
`GET /api/v1/artifacts/{id}`	Document versions, reviews, approval and certificate	`artifacts:read`
`POST /api/v1/artifacts` - Idempotency-Key	Register a file or text and run local analysis	`artifacts:write`
`POST /api/v1/artifacts/{id}/versions` - Idempotency-Key	Register and analyze a later version	`artifacts:write`
`GET /api/v1/analyses/{id}`	Analysis results and limitations	`analyses:read`
`POST /api/v1/artifacts/{id}/reviews` - Idempotency-Key	Declare a review and provide the exact file	`reviews:write`
`POST /api/v1/versions/{id}/approve` - Idempotency-Key	Approve with explicit responsibility	`approvals:write`
`POST /api/v1/versions/{id}/certificates` - Idempotency-Key	Issue a certificate with publication authorization	`certificates:write`
`GET /api/v1/certificates/{id}/download`	Download the organization's signed JSON envelope	`certificates:read`
`POST /api/v1/certificates/{id}/revoke` - Idempotency-Key	Revoke with a documented reason	`certificates:write`
`GET /api/v1/audit-events`	Organization history - limit and offset	`audit:read`
`GET /api/v1/metrics/detectors`	Aggregate detector metrics	`metrics:read`
`GET /api/v1/certificates/{id}/verify`	Public certificate verification	`Public - no key`

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.