Migrar desde Adobe Acrobat Sign

Si su equipo ya tiene una integración con Acrobat Sign, esta guía le permite trasladarla a bb-sign con un mapa claro de conceptos, autenticación, webhooks y endpoints. Toma como referencia la API v6 de Acrobat Sign.

Equivalencia de conceptos

Acrobat Sign	bb-sign	Cómo se traslada
Agreement	Sobre	Equivalencia directa
Participant set / destinatario	Firmante	Cada firmante es una persona con un signOrder. Para varias personas, agregue un firmante por cada una
Transient document	Subida a POST /api/v1/documents y referencia por id	Una vez adjunto, el documento se conserva con el sobre y cuenta para su cuota de almacenamiento. Las subidas sin adjuntar se eliminan tras 24 horas
Library document / template	Documentos propios de cada sobre	Conserve el contrato base en su sistema y súbalo al crear cada sobre
Agreement state OUT_FOR_SIGNATURE	SENT, y luego IN_PROGRESS cuando firma el primer firmante
Agreement state SIGNED	COMPLETED	Indica que firmaron todos los firmantes. La firma de un firmante individual se notifica con el evento signer.signed
Integration key	Credencial de cliente	Ver Autenticación
Webhook con verificación por eco	Webhook con firma HMAC	Ver Webhooks; es el cambio principal
Megasign / bulk send	Un sobre por destinatario	Cree los sobres en un ciclo con POST /api/v1/envelopes
Custom workflow	Firma secuencial o en paralelo	Se define con el booleano sequentialSigning del sobre y el signOrder de cada firmante
Form fields / anchors	Un marcador de texto en el PDF	El sello se ubica donde el PDF contiene {{signerN}} (N es el orden del firmante); sin marcador, los sellos se ubican en la última página. Consulte Documentos

Autenticación: de la clave de integración a client credentials

La clave de integración de Acrobat Sign es un bearer token de larga duración que se envía en un encabezado. En bb-sign, un par de client credentials de OAuth2 se intercambia por un token de corta duración.

	Acrobat Sign	bb-sign
Credencial	Una clave de integración	Un id y un secreto de cliente
Valor enviado	La clave	Un bearer token obtenido con ellos
Vigencia	Hasta que se revoca	El token expira a los 300 s; la credencial dura hasta que se revoca
Origen	La consola de administración de Adobe	Configuración, pestaña Credenciales de API, en autoservicio para un administrador de la organización

curl -X POST "$BBSIGN_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$BBSIGN_CLIENT_ID" \
  -d client_secret="$BBSIGN_CLIENT_SECRET"

Ambos SDKs obtienen el token, lo guardan en caché y lo renuevan antes de que expire. Si escribe su propio cliente, guarde el token en caché en lugar de solicitar uno por cada llamada.

Revocación. Revocar detiene de inmediato la emisión de tokens nuevos; un token ya emitido sigue siendo válido hasta que expira, como máximo 300 s. El panel de configuración indica la ventana exacta antes de confirmar y muestra la credencial como Revocada — en expiración hasta que transcurre. Ante una filtración, considere la credencial activa hasta que haya pasado ese tiempo.

Webhooks: de la verificación por eco a la firma HMAC

Este es el cambio de comportamiento más importante de la migración.

Acrobat Sign verifica su endpoint enviando un clientId en la solicitud y exigiendo que se devuelva en la respuesta. El registro y la verificación usan el mismo mecanismo.

bb-sign firma cada entrega con un HMAC-SHA256 sobre el cuerpo original, en el encabezado X-BBSign-Signature. Su endpoint verifica la firma y responde 2xx, sin devolver ningún valor.

	Acrobat Sign	bb-sign
Cómo se comprueba que una solicitud es auténtica	Devolver el clientId	Verificar la firma HMAC
Respuesta del endpoint	Un cuerpo JSON con el id	Un 2xx sin cuerpo
Valor por solicitud	El mismo en cada solicitud	Distinto en cada solicitud
Responsabilidad del receptor	Responder con el eco	Verificar la firma en cada entrega

La última fila es la clave: la seguridad de la integración depende de que su endpoint verifique la firma antes de procesar el evento. Ambos SDKs incluyen la verificación, y los vectores de prueba permiten validar una implementación propia. La guía de webhooks detalla los tres requisitos que debe cumplir un verificador.

Contenido del evento. bb-sign entrega un evento compacto y tipado: id del sobre, título, estado y, en los eventos signer.*, el firmante. Para obtener más datos, consulte la API. Así los payloads se mantienen pequeños y el contrato del webhook permanece estable.

Equivalencia de endpoints

Acrobat Sign	bb-sign
POST /transientDocuments	POST /api/v1/documents
POST /agreements	POST /api/v1/envelopes y luego POST /api/v1/envelopes/{id}/send
GET /agreements	GET /api/v1/envelopes
GET /agreements/{id}	GET /api/v1/envelopes/{id}
GET /agreements/{id}/documents	GET /api/v1/envelopes/{id}/documents
PUT /agreements/{id}/state a CANCELLED	POST /api/v1/envelopes/{id}/cancel
POST /webhooks	Configuración, pestaña Webhooks (los webhooks se administran en la interfaz)

Crear y enviar son dos llamadas. El sobre se crea en DRAFT, se le adjuntan los documentos y luego se envía. De este modo, un acuerdo que queda a medio construir permanece como borrador y no llega a ningún firmante.

La referencia de la API describe la superficie completa.

Antes de migrar

• Contratos base. Guárdelos en su sistema y súbalos con cada sobre.
• Envíos a muchos destinatarios. Cree un sobre por destinatario con POST /api/v1/envelopes; las cuotas se aplican por organización.
• Ubicación de la firma. Agregue el marcador de texto al PDF en el lugar donde debe ir cada sello.
• Orden de firma. Use signOrder y el booleano sequentialSigning.
• Espacios de trabajo. Cada sobre pertenece a un espacio de trabajo, y una credencial accede a los espacios que se le asignaron; consulte Autenticación de máquinas.