Bseal · Contrato de integración

Bseal es el sello (seal) que cierra cada documento. Este contrato describe cómo crear plantillas PDF, disparar firmas criptográficas y verificar el resultado. La llave privada vive siempre en AWS KMS — solo el documento sellado abandona la infraestructura.

Cuidado

Cada PDF sellado consume 40 Açaí. Verifica que el merge de variables sea correcto antes de firmar — un PDF firmado no se puede modificar (esa es la idea).

Operaciones disponibles

Operación	Endpoint	Plano	Costo
Subir plantilla PDF	POST /v1/templates	Control	0 Açaí
Crear solicitud de firma	POST /v1/signatures	Data	40 Açaí
Verificar firma de documento existente	POST /v1/signatures/verify	Data	2 Açaí
Descargar PDF sellado	GET /v1/signatures/{id}/download	Data	1 Açaí
Listar firmas	GET /v1/signatures	Data	1 Açaí

Flujo end-to-end

1. Subir plantilla PDF (con placeholders tipo {{cliente.nombre}}) y mapear las variables desde el Template Builder.
2. Tu app llama POST /v1/signatures con template_code + merge_data + subject_ref.
3. Bseal responde 202 con signature_id y status: pending.
4. Worker procesa: merge → hash SHA-256 → KMS sign → upload S3 → publish event.
5. Recibes webhook bseal.signature.completed con la URL firmada del PDF sellado.
6. Descargas o reenvías el PDF al cliente final.

1. Crear solicitud de firma

Request

POST /v1/signatures HTTP/1.1
Host: api.digital-jungle.bjungle.com
X-API-Key: <api_key>
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "template_code": "pagare-microcredito-v3",
  "subject_ref":   "0c4b5b32-3a89-4a45-9c2c-1a8c47e91234",
  "merge_data": {
    "cliente": {
      "nombre":   "Camila Rodríguez",
      "documento": "1023456789",
      "ciudad":    "Bogotá"
    },
    "credito": {
      "monto":   5000000,
      "moneda":  "COP",
      "tasa_ea": 28.5,
      "plazo_meses": 12
    },
    "fecha_desembolso": "2026-05-25"
  },
  "expires_at": "2026-06-25T23:59:59Z"
}

Response — 202 Accepted

{
  "signature_id": "01J8G15K6N7P8Q9R0S1T2V3W4X",
  "status":       "pending",
  "acai_debited": 40
}

Webhook resultado — bseal.signature.completed

{
  "event_id":   "5f8d1c3e-5d02-4d6e-8a9d-5e8c8b5f9abc",
  "tenant_id":  "8a7b6c5d-1234-5678-9abc-def012345678",
  "module":     "bseal",
  "event_type": "bseal.signature.completed",
  "occurred_at":"2026-05-25T14:00:05Z",
  "payload": {
    "signature_id":  "01J8G15K6N7P8Q9R0S1T2V3W4X",
    "subject_ref":   "0c4b5b32-3a89-4a45-9c2c-1a8c47e91234",
    "template_code": "pagare-microcredito-v3",
    "document": {
      "download_url": "https://s3.amazonaws.com/bjungle-bseal/.../pagare.pdf?X-Amz-...",
      "sha256":       "9b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c",
      "size_bytes":   124583,
      "expires_at":   "2026-05-26T14:00:05Z"
    },
    "signature": {
      "algorithm":   "RSASSA-PKCS1-v1_5-SHA256",
      "kms_key_arn": "arn:aws:kms:us-east-1:000000000000:key/abcd-1234",
      "signed_at":   "2026-05-25T14:00:05Z"
    }
  }
}

Dica

El download_url expira en 24 h por defecto. Para acceso permanente, descárgalo y archívalo en tu propio storage — el hash SHA-256 permite re-validar la integridad contra el KMS cuando quieras.

Snippets

cURL

curl -X POST https://api.digital-jungle.bjungle.com/v1/signatures \
  -H "X-API-Key: $BSEAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @signature.json

TypeScript

import { BsealClient } from '@bjungle/bseal-client';
import { randomUUID } from 'node:crypto';

const bseal = new BsealClient({ apiKey: process.env.BSEAL_KEY! });

const res = await bseal.signatures.create(
  {
    template_code: 'pagare-microcredito-v3',
    subject_ref:   subjectId,
    merge_data:    pagareData,
    expires_at:    in30Days,
  },
  { headers: { 'Idempotency-Key': randomUUID() } },
);

console.log(res.signature_id);

Go

client := bseal.NewClient(os.Getenv("BSEAL_KEY"))
res, err := client.Signatures.Create(ctx, &bseal.SignatureInput{
    TemplateCode: "pagare-microcredito-v3",
    SubjectRef:   subjectID,
    MergeData:    pagareData,
    ExpiresAt:    in30Days,
}, bseal.WithIdempotencyKey(uuid.NewString()))

2. Verificar la firma de un PDF que ya recibiste

Útil cuando un tercero (notaría, contraparte) te envía de vuelta el documento y quieres revalidar que no se modificó.

POST /v1/signatures/verify HTTP/1.1
Host: api.digital-jungle.bjungle.com
X-API-Key: <api_key>
Content-Type: application/json

{
  "signature_id": "01J8G15K6N7P8Q9R0S1T2V3W4X",
  "sha256":       "9b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c"
}

Response 200:

{
  "valid": true,
  "signed_at": "2026-05-25T14:00:05Z",
  "kms_key_arn": "arn:aws:kms:us-east-1:000000000000:key/abcd-1234"
}

Eventos emitidos

Evento	Cuándo
bseal.signature.requested	Solicitud aceptada, antes de procesar
bseal.signature.completed	PDF sellado y disponible en S3
bseal.signature.failed	Falla irrecuperable (template inválido, KMS down, merge incompleto)
bseal.signature.expired	El expires_at venció sin que se completara

Errores típicos

Status	Caso
400	merge_data no cubre todos los placeholders del template
404	template_code o signature_id inexistente
402	Sin Açaí disponibles
409	Idempotency-Key repetida con payload distinto
422	Plantilla deshabilitada o KMS key no disponible para este tenant
503	KMS o S3 temporalmente no disponible — la petición se reintenta automáticamente