docvalidator-sdk

Cliente TypeScript/JavaScript para DocValidator v2 — plataforma horizontal de validación documental.

Instalación

npm install docvalidator-sdk

Requiere Node.js 18+ (la API usa fetch global).

Quickstart

import { DocValidatorClient, verifyWebhookSignature } from 'docvalidator-sdk';

const client = new DocValidatorClient({
  apiKey: process.env.DOCVALIDATOR_API_KEY!,
  baseUrl: 'https://api.docvalidator.com',  // o http://localhost:3000 en sandbox
});

// Crear job (modo async)
const job = await client.processDocument({
  document_type: 'cedula',
  document: 'https://example.com/cedula.pdf',
  webhook_url: 'https://miapi.com/webhooks/docvalidator',
  webhook_secret: 'min-16-chars-shared-secret',
  process_mode: 'full',
});

// Consultar estado
const status = await client.getStatus(job.job_id);

// Listar jobs
const list = await client.listJobs({ status: 'completed', limit: 50 });

Verificar firma del webhook

DocValidator firma cada webhook con HMAC-SHA256 sobre el body JSON. El SDK incluye un helper:

import { verifyWebhookSignature } from 'docvalidator-sdk';

// En tu endpoint receptor (Express, Fastify, etc.)
app.post('/webhooks/docvalidator', (req, res) => {
  const rawBody = req.rawBody.toString('utf8');                          // body crudo, sin re-stringify
  const signature = req.headers['x-webhook-signature'] as string;
  const secret = process.env.DOCVALIDATOR_WEBHOOK_SECRET!;
  if (!verifyWebhookSignature(rawBody, signature, secret)) {
    return res.status(401).send('invalid signature');
  }
  // body verificado; procesar el evento
  res.status(204).end();
});

API

| Método | Descripción | |--------|-------------| | client.processDocument(body, { responseMode }) | POST /process — async (default) o sync (timeout 60s) | | client.getStatus(jobId) | GET /status/:job_id | | client.listJobs({ limit, offset, status }) | GET /jobs | | verifyWebhookSignature(rawBody, signature, secret) | Valida HMAC-SHA256 timing-safe |

Tipos exportados

DocumentType, ProcessMode, ResponseMode, JobStatus, Decision, ProcessDocumentRequest, PipelineResult, Job, ListJobsResponse, WebhookPayload, DocValidatorApiError.

Cumplimiento Ley 1581 de 2012

DocValidator purga PII a las 72h de completado el job. Cuando llames getStatus(jobId) después de la purga:

• pii_purged: true
• extraction_result contiene "[PURGED]" en lugar de los valores PII.

License

UNLICENSED — Uso autorizado por DocValidator a sus integradores contratados.