Firma
Iniciar sesiónRegistrarse

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://firma.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.

Request body:

{
  "file": "(PDF binary)",
  "signer_name": "Juan Pérez",
  "signer_email": "juan@ejemplo.cl",
  "signer_phone": "+56912345678",
  "message": "Por favor firme este contrato"
}

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.

// Header: X-Firma-Signature: sha256=...
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(payload))
  .digest('hex');
const isValid = signature === receivedSignature;

Eventos disponibles:

signature.createdsignature.viewedsignature.acceptedsignature.completedsignature.failedsignature.cancelledsignature.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.