Referencia de la API REST de ABSign: Guía de integración, autenticación y puntos finales v2

Introducción a la API ABSign v2

ABSign REST API v2 es la interfaz programática oficial para integrar capacidades de firma electrónica de nivel empresarial en sus sistemas comerciales, plataformas comerciales y flujos de trabajo de gestión de documentos. Construida sobre principios REST con cargas útiles de solicitud y respuesta JSON, la API se conecta perfectamente con cualquier pila de tecnología capaz de realizar llamadas HTTPS, desde aplicaciones Python y Node.js hasta servicios Java Spring Boot, sistemas PHP Laravel y aplicaciones .NET Core. El punto final base para todas las llamadas API v2 es https://www.abroadsign.com/api/v2/, que reemplaza el endpoint v1 heredado e introduce seguridad mejorada, cobertura ampliada de eventos de webhook y limitación de velocidad mejorada para integraciones empresariales de gran volumen.

Organizaciones de más de 180 países confían en la API ABSign para automatizar los flujos de trabajo de firma de documentos que abarcan contratos de transporte de carga, cartas de crédito de financiación comercial, declaraciones de aduanas, acuerdos de cadena de suministro entre múltiples partes y documentos de adquisiciones empresariales. La versión v2 presenta soporte nativo para operaciones masivas de documentos, combinación avanzada de plantillas, anclaje de marcas de tiempo de blockchain y funciones de colaboración en tiempo real que permiten ceremonias simultáneas de múltiples firmantes desde cualquier navegador o dispositivo móvil sin necesidad de que los participantes instalen software especializado o creen cuentas ABSign. Ya sea que sea una startup que crea su primer flujo de incorporación de clientes o una empresa que reemplaza toda una infraestructura de contratación basada en papel, la API ABSign proporciona los componentes básicos para una firma digital totalmente automatizada y que cumple con la ley a escala global.

Configuración de autenticación y seguridad

Asegurar el acceso a la API es primordial cuando se manejan firmas digitales legalmente vinculantes. ABSign API v2 emplea autenticación basada en claves API combinada con cifrado de transporte TLS 1.3, lo que garantiza que cada solicitud y respuesta esté cifrada en tránsito y sea inmune a intercepciones o ataques de intermediario. Todas las claves API se generan desde el panel de ABSign en Configuración, con alcances de permisos granulares que siguen el principio de privilegio mínimo: cada integración recibe exactamente los permisos que necesita, nada más. Las claves nunca se transmiten en URL, solo en encabezados HTTP, y sus sistemas deben almacenarlas en variables de entorno o plataformas de administración de secretos dedicadas, como AWS Secrets Manager, HashiCorp Vault o Azure Key Vault, en lugar de incrustarlas en repositorios de código fuente o archivos de configuración comprometidos con sistemas de control de versiones.

• Encabezado del token al portador: Cada solicitud de API debe incluir la Authorization: Bearer YOUR_API_KEY encabezamiento. Nunca codifique claves API en el código fuente de la aplicación; utilice variables de entorno o sistemas de gestión de secretos para inyectar credenciales en tiempo de ejecución.
• Aplicación de TLS 1.3: Todas las conexiones API deben utilizar TLS 1.3. Las conexiones que intenten utilizar versiones TLS anteriores serán rechazadas con una respuesta 400 Solicitud incorrecta. Esto garantiza que el contenido del documento y los datos de la firma nunca queden expuestos a través de canales no cifrados.
• Alcances de permiso: Las claves API tienen como alcance operaciones específicas: documentos.leer, documentos.escribir, plantillas.leer, plantillas.escribir, firmantes.manage, webhooks.admin y organización.leer. Asigne solo los alcances necesarios para cada caso de uso de integración para limitar el radio de explosión si una clave se ve comprometida.
• Política de rotación de claves: Implemente la rotación de claves automatizada en un cronograma de 90 días. El panel de ABSign admite la rotación de claves sin tiempo de inactividad a través del concepto de claves primarias y secundarias, lo que le permite transferir credenciales sin interrumpir los flujos de trabajo de firma en curso.
• Lista de direcciones IP permitidas: Las cuentas empresariales pueden restringir el acceso a la API a direcciones IP específicas o rangos de CIDR. Habilite la lista de IP permitidas desde la página Configuración de seguridad para integraciones de servidor a servidor donde las IP de llamada son conocidas y estables.

“La implementación de TLS 1.3 y el alcance de la clave API redujo nuestros hallazgos de auditoría de seguridad a cero. La API ABSign fue diseñada teniendo en cuenta los requisitos de seguridad empresarial; se mostró en cada detalle del proceso de integración”.

— Jefe de Seguridad de la Información, empresa comercializadora global de productos básicos

Referencia de punto final de API principal

La API v2 organiza la funcionalidad en torno a puntos finales orientados a recursos que se asignan naturalmente a las entidades en un flujo de trabajo de firma digital: documentos, plantillas, firmantes, firmas, webhooks y organizaciones. Cada recurso admite operaciones CRUD estándar además de acciones específicas de recursos, como enviar documentos para firmar, recordar a los firmantes pendientes o descargar paquetes de documentos completos con firmas integradas y certificados de integridad criptográfica. La siguiente tabla proporciona la referencia completa del grupo de puntos finales para un rápido desarrollo de la integración.

Grupo de terminales	Ruta básica	Operaciones clave	Caso de uso común
Documentos	/documents	Crear, leer, listar, actualizar, descargar, archivar, eliminar	Iniciar la firma, recuperar documentos completos
Plantillas	/templates	Crear, leer, actualizar, eliminar, clonar, enumerar	Flujos de trabajo de documentos estandarizados
Firmantes	/signers	Invitar, reenviar invitación, cancelar, verificar identidad	Gestión de firmas
Firmas	/signatures	Aplicar, verificar, verificar el estado, recuperar el seguimiento de auditoría	Completar y validar firmas
Ganchos web	/webhooks	Crear, enumerar, eliminar, probar, habilitar/deshabilitar	Notificaciones de eventos en tiempo real
Organizaciones	/organizations	Leer, actualizar, configuración, miembros del equipo	Configuración de administración y cumplimiento
Registros de auditoría	/audit-logs	Listar, filtrar, exportar, descargar PDF	Informes de cumplimiento y análisis forense
Operaciones masivas	/bulk	Crear lote, estado, cancelar lote	Procesamiento de documentos de gran volumen

Patrón de integración del ciclo de vida del documento

El patrón de integración de API más común sigue el ciclo de vida del documento desde su creación, pasando por la recopilación de firmas hasta el archivo. Este flujo de trabajo de un extremo a otro demuestra cómo sus sistemas interactúan con la API ABSign en cada etapa, lo que permite procesos de firma totalmente automatizados sin intervención manual ni gastos administrativos. Comprender este ciclo de vida es esencial para crear integraciones confiables que manejen escenarios de falla de manera elegante y mantengan la coherencia de los datos en todos los sistemas distribuidos.

Paso 1: Creación de documentos y llenado de plantillas

Comience creando un documento a partir de una plantilla preconfigurada o de contenido HTML o PDF sin formato enviado directamente a la API. Para la creación basada en plantillas, pase valores de variables de plantilla en el cuerpo de la solicitud para personalizar el contenido del documento para cada ocasión de firma específica, manteniendo al mismo tiempo la coherencia de la marca y la estandarización de las cláusulas legales. La API responde inmediatamente con un ID de documento que su sistema almacena para todas las operaciones posteriores en este documento. La creación de documentos admite el modo por lotes, donde puede enviar hasta 500 documentos en una única llamada API para colas de procesamiento que necesitan iniciar docenas o cientos de flujos de trabajo de firma simultáneamente durante los períodos de mayor actividad comercial.

• Uso POST /documents con template_id y template_data para crear a partir de una plantilla o enviar content_html o content_pdf_base64 para contenido crudo.
• Establecer el signing_sequence a sequential para la firma ordenada por varias partes o parallel cuando todas las partes puedan firmar simultáneamente para minimizar el tiempo de espera.
• Especificar expiry_days para controlar cuánto tiempo permanece activa la invitación a firmar antes de que el documento caduque automáticamente y requiera renovación.
• Permitir block_download_until_completed para evitar el acceso prematuro al documento mientras aún esté pendiente la firma requerida.

Paso 2: Configuración del firmante y envío del flujo de trabajo

Después de crear un documento, agregue los firmantes requeridos especificando sus direcciones de correo electrónico, nombres para mostrar y su posición en la secuencia de firma. Para integraciones que requieren una mayor garantía de identidad, como transacciones de financiación comercial de alto valor o documentación de importación y exportación regulada, habilite la identity_verification_required bandera para exigir la verificación biométrica o de identificación gubernamental antes de que se acepte la firma. Envíe el documento a todos los firmantes con una única llamada API y la plataforma ABSign generará automáticamente invitaciones por correo electrónico con formato profesional con enlaces de documentos personalizados, avisos de caducidad e instrucciones de firma claras en el idioma preferido del destinatario.

• Agregar firmantes mediante POST /documents/{document_id}/signers con correo electrónico, nombre y rol (signer, witness, o 抄送 para cc).
• Configurar reminder_schedule para enviar automáticamente correos electrónicos de recordatorio en intervalos de 24 y 72 horas a los firmantes que aún no han actuado.
• Colocar redirect_url_after_signed para guiar a los firmantes a una página de finalización personalizada en su sistema después de que terminen de firmar.
• Permitir signer_authentication requiriendo verificación OTP por correo electrónico o SMS como capa adicional de confirmación de identidad del firmante.

Paso 3: Finalización impulsada por Webhook y procesamiento posterior

El sistema de webhook ABSign ofrece notificaciones de eventos en tiempo real a su punto final HTTPS configurado cada vez que un firmante realiza una acción o cambia el estado del ciclo de vida del documento. En lugar de sondear la API repetidamente para verificar el estado del documento, lo que consume su cuota de límite de velocidad y agrega latencia, configure webhooks para recibir notificaciones automáticas que activen procesos posteriores automáticamente. Al recibir el document.completed En cualquier caso, su sistema recupera el paquete de documentos completo, incluido el PDF firmado, el certificado hash criptográfico, el ancla de marca de tiempo de blockchain y el documento completo de seguimiento de auditoría que sirve como evidencia principal en disputas legales o auditorías de cumplimiento.

---

Referencia de notificaciones en tiempo real y eventos de webhook

Los webhooks son la columna vertebral de las arquitecturas de integración automatizada. ABSign API v2 admite una cobertura integral de eventos durante todo el ciclo de vida del documento, lo que permite que sus sistemas respondan inmediatamente cuando ocurren cambios de estado en lugar de depender de intervalos de sondeo que desperdician la cuota de API e introducen latencia innecesaria en sus flujos de trabajo. Cada entrega de webhook incluye una carga útil JSON con datos específicos del evento y un encabezado de firma HMAC-SHA256 que su punto final debe verificar antes de procesar la notificación para evitar que eventos falsificados desencadenen acciones no autorizadas en sus sistemas.

Tipo de evento	Condición de activación	Campos clave de carga útil	Respuesta de integración
document.created	Nuevo documento agregado a la plataforma.	document_id, título, creado_en, creado_por	Regístrate en el sistema de seguimiento interno.
document.sent	Documento enviado a los firmantes.	document_id, firmantes[], expires_at, asunto	Actualizar el estado del panel de flujo de trabajo
signer.viewed	El firmante abre el enlace del documento	ID_documento, ID_firmante, visto_en, dirección_ip	Registrar participación y activar temporizador
signer.completed	El firmante envía su firma	id_documento, id_firmante, firma_at, firma_hash	Verificar la finalización, notificar aguas abajo
document.completed	Todas las firmas requeridas obtenidas	document_id, complete_at, download_url, audit_trail_url	Activar el siguiente paso del flujo de trabajo
document.expired	Se superó el plazo de firma	document_id, expired_at, signers_pending[]	Iniciar renovación o alertar al equipo de operaciones.
document.declined	El firmante se niega explícitamente a firmar	document_id, signer_id, declinado_at, motivo	Alertar operaciones y escalar
document Voided	Documento cancelado por el creador	document_id, voided_by, voided_at, motivo	Cerrar registros internos y notificar

Límites de tarifas, cuotas y optimización del rendimiento

ABSign API v2 impone límites de velocidad para garantizar la estabilidad de la plataforma y la asignación justa de recursos entre todos los consumidores de API. Las cuentas de nivel estándar están limitadas a 1000 solicitudes por minuto por clave API, mientras que las cuentas Enterprise reciben límites elevados negociados en función de los requisitos de integración documentados y los volúmenes de transacciones esperados. El estado del límite de velocidad se comunica en cada respuesta de API a través del X-RateLimit-Remaining y X-RateLimit-Reset encabezados de respuesta, lo que permite que su integración implemente una limitación proactiva en lugar de esperar a que las respuestas 429 desencadenen un comportamiento de retroceso. Para operaciones por lotes de gran volumen que procesan miles de documentos, utilice el módulo dedicado /bulk puntos finales que están diseñados específicamente para un rendimiento masivo con cuotas por minuto más altas y una sobrecarga reducida por documento.

• Monitor X-RateLimit-Remaining encabezado en cada respuesta y pausar las solicitudes cuando se acerque a cero para evitar recibir respuestas 429 Demasiadas solicitudes que detengan el procesamiento de la ventana de reinicio.
• Utilice el Retry-After valor del encabezado para esperar la duración exacta antes de reanudar las solicitudes en lugar de implementar intervalos de suspensión arbitrarios que pueden ser demasiado cortos o innecesariamente largos.
• Para el procesamiento masivo de documentos, prefiera POST /bulk puntos finales sobre individuos POST /documents Llamadas: las operaciones masivas ofrecen una mejora del rendimiento de hasta 10 veces para flujos de trabajo de gran volumen.
• Implemente un retroceso exponencial con fluctuación para toda la lógica de reintento para manejar errores transitorios del lado del servidor sin sobrecargar la plataforma durante los períodos de recuperación.
• Uso Conditional Requests con If-Modified-Since o ETag encabezados al recuperar el estado del documento para evitar transferencias de datos innecesarias y reducir la latencia para las verificaciones de estado.

“Procesamos más de 50.000 documentos de carga por mes a través de la API ABSign. El punto final de operaciones masivas combinado con el manejo adecuado del webhook significa que todo nuestro flujo de trabajo de firma se ejecuta con una latencia inferior a un minuto, completamente sin intervención después de la llamada API inicial”.

— Ingeniero líder de plataforma, red global de transporte de carga

Paquetes SDK oficiales e inicio rápido

ABSign mantiene paquetes SDK oficiales para los lenguajes y marcos de programación más ampliamente adoptados, cada uno de los cuales proporciona estructuras de datos en el lenguaje nativo, lógica de reintento automático con retroceso exponencial para fallas transitorias, definiciones de tipos integrales para seguridad en tiempo de compilación y configuraciones de cliente HTTP preconfiguradas que cumplen con los requisitos de seguridad de API. Los paquetes SDK son de código abierto y están disponibles en GitHub, donde las contribuciones de la comunidad para idiomas adicionales son bienvenidas y revisadas por el equipo de ingeniería de ABSign. Todos los SDK oficiales tienen versiones en paralelo con la API para garantizar que las firmas y el comportamiento de los métodos del SDK sigan siendo coherentes con los puntos finales REST subyacentes.

• SDK de Python: Instalar a través de pip install abroadsign-api. Soporte completo asíncrono/en espera para aplicaciones Python modernas, con ayudas de integración automática para sistemas de tareas en segundo plano basados ​​en Django, FastAPI y Celery. Se incluyen sugerencias de tipo completo y soporte de autocompletar IDE.
• SDK de Node.js/TypeScript: Instalar a través de npm install abroadsign-api. Paquete TypeScript completamente tipificado con definiciones de tipos completas para todos los objetos de solicitud y respuesta. Incluye soporte de middleware nativo para Express.js, rutas API de Next.js y funciones sin servidor en AWS Lambda y Vercel.
• SDK de arranque de Java/Spring: Coordenadas de Maven disponibles en Maven Central. Compatible con Spring Boot 2.x y 3.x, con soporte de configuración automática y documentación Javadoc completa para equipos de desarrollo de Java empresariales.
• SDK de PHP: Paquete compatible con PSR compatible con Laravel, Symfony y aplicaciones PHP 8.1+ independientes. Incluye el proveedor de servicios Laravel para una configuración perfecta de inyección de dependencias a través del contenedor de servicios Laravel.
• SDK de .NET/C#: Compatibilidad con .NET Standard 2.0 que admite .NET Framework, .NET Core y .NET 5+ en Windows, Linux y macOS. Incluye integración de inyección de dependencia de ASP.NET Core con el patrón HttpClientFactory.

---

Primeros pasos: su primera integración API

Comience su integración accediendo al entorno sandbox de API de ABSign, que proporciona un espejo de API completamente funcional con datos de prueba aislados que no afectan las bóvedas de documentos de producción ni cuentan para las cuotas de producción. Genere sus credenciales de API de zona de pruebas desde el panel en Configuración y comience a realizar llamadas API de inmediato para explorar la creación de documentos, la configuración del firmante y la entrega de webhooks en un entorno seguro. El entorno de pruebas simula automáticamente las ceremonias de firma, por lo que puede probar flujos de trabajo completos de un extremo a otro sin esperar a que firmantes humanos reales actúen durante los ciclos de desarrollo y control de calidad. Nuestro portal interactivo de documentación API proporciona un explorador de API en vivo donde puede ejecutar solicitudes directamente en el navegador, inspeccionar las cargas útiles de solicitudes y respuestas y generar fragmentos de código listos para usar para cualquier punto final en cualquiera de los idiomas del SDK admitidos.

Para patrones de integración avanzados que incluyen procesamiento por lotes de gran volumen, implementaciones de marca blanca multiinquilino y arquitecturas de confiabilidad de webhook personalizadas, explore nuestra Guía de automatización del flujo de trabajo de documentos que cubre el ajuste del rendimiento, las estrategias de manejo de errores y las mejores prácticas de implementación empresarial. Nuestro equipo de ingeniería de integración también ofrece sesiones de revisión de arquitectura técnica de cortesía para que los clientes empresariales validen su diseño de integración antes de comprometerse con los volúmenes de tráfico de producción.

¿Listo para construir su integración? Visite el portal de documentación de API para obtener referencias completas de puntos finales, descargas de SDK y ejemplos de códigos de trabajo. Si tiene preguntas sobre los requisitos de API empresarial, la arquitectura de integración personalizada o el escalado de producción, contacta con nuestro equipo técnico de integración para programar una sesión de revisión de arquitectura gratuita con uno de nuestros ingenieros senior de API.