Inicio rápido

Esta guía lleva su integración desde una credencial nueva hasta un 201 de POST /api/v1/envelopes: un sobre creado en su organización.

Requisitos: una cuenta de bb-sign con el rol de administrador de la organización (o el apoyo de alguien que lo tenga), y Java 17 o superior, o Node 20 o superior.

1. Obtener una credencial

Una credencial de API permite que un sistema llame a bb-sign en nombre de su organización, con acceso limitado a esa organización.

1. Inicie sesión en bb-sign y abra Configuración, pestaña Credenciales de API.
2. Seleccione Nueva credencial. Asígnele una etiqueta que identifique el sistema que la usará, por ejemplo «Sistema de facturación».
3. En Acceso, conserve el espacio de trabajo y el rol predeterminados, salvo que necesite otros: «General con Gestor es la opción predeterminada».
4. Copie el ID de cliente y el Secreto de cliente.

El secreto se muestra una sola vez

Se almacena únicamente en Keycloak y bb-sign no conserva copia. Si lo pierde, use Rotar; la rotación no tiene periodo de gracia: «El secreto actual deja de funcionar de inmediato. Cualquier integración que lo use fallará hasta que la vuelvas a desplegar con el nuevo secreto».

Configuración aparece en la barra lateral para los administradores de la organización. Si no tiene ese rol, pida al administrador de su organización en bb-sign que cree la credencial y le envíe los dos valores.

Además, necesita dos URL. En producción son:

	Valor
URL base de la API	https://sign-api.binarybridges.co
URL del token	https://auth.binarybridges.co/realms/bbsign/protocol/openid-connect/token

Defínalas como variables de entorno, fuera del código fuente:

export BBSIGN_BASE_URL="https://sign-api.binarybridges.co"
export BBSIGN_TOKEN_URL="https://auth.binarybridges.co/realms/bbsign/protocol/openid-connect/token"
export BBSIGN_CLIENT_ID="..."
export BBSIGN_CLIENT_SECRET="..."

2. Verificar la credencial

Antes de escribir código, confirme que la credencial obtiene un token:

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

La respuesta es un JSON con access_token. Si recibe invalid_client, el id o el secreto son incorrectos: cópielos de nuevo, o rote el secreto y vuelva a intentarlo.

Con la credencial verificada, cualquier fallo posterior es más fácil de diagnosticar.

3. Instalar un SDK

La API es HTTP estándar y la referencia la documenta por completo, de modo que el SDK es opcional. Los SDKs se encargan de renovar el token, de los reintentos y de verificar la firma de los webhooks.

curl

No requiere instalación. Los ejemplos usan curl y jq.

JavaScript

El SDK se entrega como un tarball:

npm install ./binarybridges-bb-sign-sdk-0.1.0.tgz

Requiere Node 20 o superior, y el paquete es solo ESM: use import en lugar de require. Más detalles en SDK de JavaScript.

Java

El SDK se entrega en cuatro archivos. Instale el jar en su repositorio local de Maven:

shasum -a 256 -c bb-sign-sdk-java-0.1.0-SNAPSHOT.jar.sha256

mvn install:install-file \
  -Dfile=bb-sign-sdk-java-0.1.0-SNAPSHOT.jar \
  -DpomFile=bb-sign-sdk-java-0.1.0-SNAPSHOT.pom

-DpomFile es obligatorio. Sin él, Maven genera un pom sin dependencias: la instalación y la compilación terminan sin errores, pero la primera llamada a la API falla en tiempo de ejecución con NoClassDefFoundError.

<dependency>
  <groupId>co.binarybridges.sign</groupId>
  <artifactId>bb-sign-sdk-java</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

Más detalles en SDK de Java.

4. Crear un sobre

curl

TOKEN=$(curl -s -X POST "$BBSIGN_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$BBSIGN_CLIENT_ID" \
  -d client_secret="$BBSIGN_CLIENT_SECRET" | jq -r .access_token)

curl -s -X POST "$BBSIGN_BASE_URL/api/v1/envelopes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first envelope",
    "otpRequired": false,
    "expiresAt": "2026-12-01T00:00:00Z",
    "signers": [{"email": "someone@example.com", "name": "Someone", "signOrder": 1}]
  }'

JavaScript

import { createClient } from '@binarybridges/bb-sign-sdk'

const client = createClient({
  baseUrl: process.env.BBSIGN_BASE_URL,
  tokenUrl: process.env.BBSIGN_TOKEN_URL,
  clientId: process.env.BBSIGN_CLIENT_ID,
  clientSecret: process.env.BBSIGN_CLIENT_SECRET,
})

const envelope = await client.envelopes.createEnvelope({
  createEnvelopeRequest: {
    title: 'My first envelope',
    otpRequired: false,
    expiresAt: new Date(Date.now() + 72 * 3600 * 1000),
    signers: [{ email: 'someone@example.com', name: 'Someone', signOrder: 1 }],
  },
})

console.log('Created', envelope.id)

Java

import co.binarybridges.sign.sdk.BbSignClient;
import co.binarybridges.sign.sdk.generated.model.*;
import java.time.OffsetDateTime;
import java.util.List;

try (BbSignClient client = BbSignClient.builder()
        .baseUrl(System.getenv("BBSIGN_BASE_URL"))
        .tokenUrl(System.getenv("BBSIGN_TOKEN_URL"))
        .clientCredentials(System.getenv("BBSIGN_CLIENT_ID"), System.getenv("BBSIGN_CLIENT_SECRET"))
        .build()) {

    EnvelopeResponse envelope = client.execute(client.envelopes().createEnvelope(
            new CreateEnvelopeRequest()
                    .title("My first envelope")
                    .otpRequired(false)
                    .expiresAt(OffsetDateTime.now().plusHours(72))
                    .signers(List.of(new CreateSignerSpec()
                            .email("someone@example.com")
                            .name("Someone")
                            .signOrder(1)))));

    System.out.println("Created " + envelope.getId());
}

La respuesta 201 confirma que el sobre existe, en estado DRAFT.

Elegir un espacio de trabajo

Cada sobre pertenece a un espacio de trabajo, y una credencial accede a los espacios que se le asignaron. Una credencial nueva es Gestor en el espacio General de su organización, salvo que el administrador haya elegido otro. Sin workspaceId, el sobre se archiva en General. Para archivarlo en otro espacio, liste los espacios disponibles para la credencial y envíe el id de uno:

curl -s "$BBSIGN_BASE_URL/api/v1/workspaces" -H "Authorization: Bearer $TOKEN"
# [{"id":"6f1c...","name":"General","isGeneral":true}, {"id":"a2d9...","name":"HR","isGeneral":false}]

curl -s -X POST "$BBSIGN_BASE_URL/api/v1/envelopes" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Offer letter", "workspaceId": "a2d9...", "signers": [{"email": "someone@example.com", "name": "Someone"}]}'

Un espacio de trabajo en el que la credencial no puede crear responde 404 WORKSPACE_NOT_FOUND, igual que uno que no existe. Los sobres de espacios sin acceso responden 404 NOT_FOUND y no aparecen en las listas.

5. Enviar el sobre a firma

Un sobre en DRAFT todavía no se ha enviado. Para que los firmantes lo reciban:

1. Adjunte un documento: POST /api/v1/envelopes/{id}/documents (multipart), o súbalo antes con POST /api/v1/documents y envíe los ids como documentIds al crear el sobre.
2. Envíelo: POST /api/v1/envelopes/{id}/send. bb-sign envía por correo un enlace a cada firmante y devuelve sus tokens de firma. A partir de este momento, los documentos y los firmantes quedan fijos.
3. Reciba los cambios de estado: configure un webhook en lugar de consultar periódicamente.

De la credencial al documento firmado muestra cada una de estas llamadas en los tres lenguajes.

Solución de problemas

Síntoma	Significado	Acción
invalid_client desde la URL del token	El id o el secreto de cliente son incorrectos	Cópielos de nuevo o rote el secreto
401 desde la API	El token fue rechazado o expiró (un token es válido durante 300 s)	Si construyó la solicitud manualmente, revise el prefijo Bearer ; solicite un token nuevo
403	La credencial es válida, pero la operación no está disponible para credenciales	Confirme que la operación figura en la referencia de la API; la administración se realiza en la interfaz
404 WORKSPACE_NOT_FOUND	La credencial no tiene un rol que le permita crear en ese espacio de trabajo, o el espacio no existe	Omita workspaceId, o pida al administrador que asigne a la credencial un rol en ese espacio desde Configuración, pestaña Espacios de trabajo
400 sin detalle	Por lo general, un cuerpo mal formado	Compárelo campo por campo con el ejemplo; expiresAt debe estar en ISO-8601
NoClassDefFoundError en tiempo de ejecución (Java)	Se omitió -DpomFile en la instalación	Reinstale con ese parámetro
ERR_REQUIRE_ESM (JavaScript)	El paquete es solo ESM	Use import

Si su caso no aparece en la tabla, escríbanos con una descripción de lo que estaba haciendo.

Referencia

• Referencia de la API: cada endpoint, generado a partir del contrato.
• Webhooks: recibir eventos y verificar su origen.
• Migrar desde Adobe Acrobat Sign: equivalencia de conceptos.
• openapi.json: el contrato legible por máquinas, para generar su propio cliente.