Documentación API

API REST para integrar firma electrónica simple en tus aplicaciones.

Autenticación

Todas las solicitudes requieren un API key en el header Authorization:

curl -X POST https://www.firmaelectronicasimple.cl/api/v1/signatures \
  -H "Authorization: Bearer frm_live_tu_api_key" \
  -F "file=@contrato.pdf" \
  -F "signer_name=Juan Pérez" \
  -F "signer_email=juan@ejemplo.cl" \
  -F "signer_phone=+56912345678"

Las API keys se generan desde el dashboard en la sección API Objects.

Flujo de firma

POST /signatures→ Email al firmante→ Firmante acepta→ SMS OTP→ Firma completada→ Webhook

Endpoints

POST/api/v1/signaturesCrear solicitud de firma

Envía un documento PDF para ser firmado electrónicamente. Requiere multipart/form-data con el archivo y datos del firmante. Parámetro opcional send_confirmation_email (default: true): si se envía como false, la plataforma omite el email de confirmación al firmante tras firmar — útil cuando el cliente maneja la comunicación vía el webhook signature.completed.

Request body:

{
  "file": "(PDF binary)",
  "signer_name": "Juan Pérez",
  "signer_email": "juan@ejemplo.cl",
  "signer_phone": "+56912345678",
  "send_confirmation_email": false
}

Response:

{
  "id": "uuid",
  "status": "pending",
  "signer_name": "Juan Pérez",
  "signer_email": "juan@ejemplo.cl",
  "original_filename": "contrato.pdf",
  "created_at": "2026-03-12T..."
}

GET/api/v1/signaturesListar firmas

Retorna las solicitudes de firma paginadas. Soporta filtros por status y fecha.

Response:

{
  "data": [...],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 20
  }
}

GET/api/v1/signatures/:idDetalle de firma

Retorna el detalle completo de una solicitud incluyendo audit trail.

Response:

{
  "id": "uuid",
  "status": "signed",
  "signer_name": "...",
  "audit_trail": [...]
}

GET/api/v1/signatures/:id/downloadDescargar PDF firmado

Retorna una URL pre-firmada temporal para descargar el documento firmado.

Response:

{
  "download_url": "https://...",
  "expires_in": 3600
}

POST/api/v1/signatures/:id/cancelCancelar solicitud

Cancela una solicitud de firma pendiente.

Response:

{
  "id": "uuid",
  "status": "cancelled"
}

POST/api/v1/webhooksRegistrar webhook

Crea un endpoint webhook para recibir notificaciones de eventos.

Request body:

{
  "url": "https://tu-servidor.com/webhook",
  "events": ["signature.completed", "signature.viewed"]
}

Response:

{
  "id": "uuid",
  "url": "https://...",
  "secret": "whsec_...",
  "events": [...]
}

GET/api/v1/usageConsultar uso

Retorna el uso del período de facturación actual desglosado por API Object.

Response:

{
  "billing_period": "2026-03",
  "total_tokens": 150,
  "by_api_object": [...]
}

Webhooks

Firma envía webhooks firmados con HMAC-SHA256. Verifica la firma usando el secret proporcionado al crear el webhook.

// Headers recibidos:
// X-Firma-Signature: sha256=<hex>
// X-Firma-Timestamp: <unix_seconds>
// X-Firma-Event: signature.completed

const crypto = require('crypto');

// La firma cubre: "<timestamp>.<raw_body>"
function verifyWebhook(rawBody, secret, headers) {
  const timestamp = headers['x-firma-timestamp'];
  const received  = headers['x-firma-signature'].replace('sha256=', '');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

Eventos disponibles:

signature.viewedsignature.completedsignature.failedsignature.expired

Rate Limiting

Por defecto, 60 requests por minuto por API Object. Configurable desde el dashboard. Cuando se excede el límite, la API retorna 429 Too Many Requests.