API para programas
Esta página explica cómo un programa puede subir un PDF, enviarlo a firmar, seguir su estado y descargar el resultado y sus evidencias. Todo lo que aparece aquí existe hoy en el servicio; lo que no existe está en el apartado No disponible hoy.
Autenticación
Cada llamada lleva la cabecera Authorization con la palabra Bearer y tu clave de API. Sin cabecera, o con una clave que no existe, la respuesta es 401.
Authorization: Bearer $FIRMA_API_KEY
En los ejemplos, la clave está guardada en la variable de entorno FIRMA_API_KEY. No la pegues en el código ni la compartas.
Las claves de tu cuenta se crean, revocan y rotan en la página de claves de API. Ir a mis claves de API
Si el plan de la cuenta no incluye acceso por API, la respuesta es 403.
Los permisos de gestión MCP se eligen al crear una clave nueva. No limitan la API REST: una clave de API sigue pudiendo usar sus rutas. No compartas una clave con un asistente si solo quieres lectura en todos los canales.
Operaciones
Cada operación aparece con su método HTTP y su ruta. Las partes entre llaves son identificadores que devuelve el propio servicio.
- Subir un PDF:
POST /firma/documentos - Enviar a firmar:
POST /firma/solicitudes - Consultar el estado de una solicitud:
GET /firma/solicitudes/{request_id}/estado - Ver las solicitudes de un documento:
GET /firma/documentos/{document_id}/solicitudes - Descargar el PDF firmado:
GET /firma/documentos/{document_id}/signed-pdf - Leer el resumen de evidencias:
GET /firma/documentos/{document_id}/resumen-evidencias - Descargar el paquete de evidencias (ZIP):
GET /firma/documentos/{document_id}/paquete-evidencias - Borrar un documento:
DELETE /firma/documentos/{document_id} - Dar de alta un aviso automático (webhook):
POST /firma/webhooks - Ver los avisos automáticos:
GET /firma/webhooks - Dar de baja un aviso automático:
DELETE /firma/webhooks/{webhook_id} - Enviar un aviso de prueba:
POST /firma/webhooks/{webhook_id}/test - Ver el registro de entregas de avisos:
GET /firma/webhooks/deliveries
Ejemplos con curl
Las palabras en mayúsculas, como DOCUMENT_ID o REQUEST_ID, se sustituyen por los valores reales que devuelve el servicio.
Subir un PDF
curl -X POST "https://ambarmark.com/firma/documentos" -H "Authorization: Bearer $FIRMA_API_KEY" \
-F "file=@contrato.pdf;type=application/pdf" -F "tenant=TENANT" -F "uploaded_by=ana@example.org" -F "lang=es"
En la subida, tenant es el identificador del espacio al que pertenece tu clave y uploaded_by es el correo de quien sube el documento. Si tenant no coincide con el de la clave, la respuesta es 403.
Enviar a firmar
curl -X POST "https://ambarmark.com/firma/solicitudes" -H "Authorization: Bearer $FIRMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"document_id": "DOCUMENT_ID", "signee_email": "ana@example.org", "signee_name": "Ana Ejemplo", "lang": "es"}'
Importante: al crear una solicitud, el correo de invitación sale en ese mismo momento y la solicitud cuenta en el uso de tu plan. No hay paso intermedio de revisión.
La respuesta incluye request_id, signing_url, status y email_sent. Si email_sent es false, el correo no se pudo enviar y puedes reenviar el enlace por otra vía.
Consultar el estado de una solicitud
curl "https://ambarmark.com/firma/solicitudes/REQUEST_ID/estado" -H "Authorization: Bearer $FIRMA_API_KEY"
Ver las solicitudes de un documento
curl "https://ambarmark.com/firma/documentos/DOCUMENT_ID/solicitudes" -H "Authorization: Bearer $FIRMA_API_KEY"
Descargar el PDF firmado
curl -o firmado.pdf "https://ambarmark.com/firma/documentos/DOCUMENT_ID/signed-pdf" -H "Authorization: Bearer $FIRMA_API_KEY"
Leer el resumen de evidencias
curl "https://ambarmark.com/firma/documentos/DOCUMENT_ID/resumen-evidencias?formato=texto" -H "Authorization: Bearer $FIRMA_API_KEY"
Dar de alta un aviso automático (webhook)
curl -X POST "https://ambarmark.com/firma/webhooks" -H "Authorization: Bearer $FIRMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.org/avisos", "secret": "WEBHOOK_SECRET", "events": ["all_signed"]}'
Enviar un aviso de prueba
curl -X POST "https://ambarmark.com/firma/webhooks/WEBHOOK_ID/test" -H "Authorization: Bearer $FIRMA_API_KEY"
Estados de una solicitud
El campo status de la consulta de estado toma uno de estos valores:
- pending: creada, sin invitación enviada todavía.
- email_sent: la invitación se ha enviado por correo.
- otp_sent: se ha enviado a la persona su código de un solo uso.
- signed: firmada.
- cancelled: cancelada; ya no se puede firmar.
- rejected: la persona ha rechazado firmar.
- expired: el enlace ha caducado. Hoy un enlace dura 7 días.
Resumen de evidencias
Cuando todas las personas han firmado, el resumen de evidencias se lee con la misma clave que el PDF firmado. Sin más parámetros devuelve una página HTML; con formato=texto devuelve texto plano. Si el documento no está firmado del todo, la respuesta es 409.
El paquete de evidencias es un ZIP con el PDF firmado, el informe, el historial y sus huellas SHA-256.
Avisos automáticos (webhooks)
Un webhook es un aviso que AmbarMark envía a un servidor tuyo cuando pasa algo. Lo da de alta una clave de cuenta; en un espacio de equipo, solo quien lo administra.
Al darlo de alta envías la dirección, que tiene que empezar por https y apuntar a una dirección pública, un secreto de al menos 16 caracteres y la lista de eventos.
Eventos que se envían
- all_signed: han firmado todas las personas del documento.
- document_signed: una persona ha firmado.
- signing_expired: el enlace de firma ha caducado.
- signing_rejected: una persona ha rechazado firmar.
Cada aviso es un POST con un cuerpo JSON con estos campos: event, tenant, timestamp, document (id, filename, sha256) y signing_request (id, signee_email, signee_name, signed_at, status). En los eventos de firma, si la solicitud llevaba presupuesto o confirmación, se añaden sus datos.
El campo document.sha256 es la huella del PDF original que se subió, no la del PDF firmado.
Cabeceras de cada aviso: X-Firma-Signature lleva la firma HMAC-SHA256 en hexadecimal del cuerpo exacto, calculada con tu secreto; X-Firma-Event lleva el nombre del evento; X-Firma-Delivery lleva un identificador único de la entrega.
Si tu servidor no responde, falla la conexión o responde con un error 5xx, se reintenta hasta 3 intentos en total, esperando 4 elevado al número de reintento menos uno, en segundos. Una respuesta 4xx no se reintenta. Las redirecciones no se siguen y cuentan como no entregado. Cada intento espera como mucho 5.0 segundos.
Puertos de destino permitidos: 443 (HTTPS).
El aviso de prueba hace un solo intento con un evento de ejemplo que lleva "test": true. Se permiten 5 pruebas cada 60 segundos; si pasas de ahí, la respuesta es 429 con la cabecera Retry-After.
El registro de entregas se puede filtrar por estado y por webhook, devuelve 50 entregas por página y guarda las de los últimos 30 días.
Comprobar que el aviso viene de AmbarMark
Calcula la firma sobre los bytes recibidos, sin volver a formatear el JSON, y compárala con la cabecera X-Firma-Signature. Un ejemplo en Python:
import hashlib, hmac
def signature_ok(body: bytes, header_value: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header_value)
Errores
Los errores llegan en JSON con un campo detail que explica el motivo. Algunos textos de detail solo están en castellano.
- 400: el archivo no es un PDF válido, pasa del tamaño máximo de subida, o falta un dato obligatorio.
- 401: falta la cabecera Authorization o la clave no es válida.
- 403: el plan no incluye API, la clave no puede usar ese espacio, o en un equipo no administras ese recurso.
- 404: el documento, la solicitud o el webhook no existe o no es de tu cuenta.
- 409: pides las evidencias de un documento que aún no está firmado del todo.
- 413: el cuerpo de la petición pasa del máximo permitido.
- 422: los datos enviados no tienen el formato esperado, o la dirección del webhook no es segura.
- 429: has llegado al máximo diario de invitaciones o al de avisos de prueba.
- 503: el servicio no puede comprobar las claves en ese momento, o las herramientas PDF están ocupadas; en ese caso llega la cabecera Retry-After.
Límites
Estos son los valores con los que funciona hoy este servicio.
- PDF para firmar: hasta 10 MB.
- Cuerpo de una petición: hasta 64 MB.
- Invitaciones de firma por cuenta y día: 50. Cuentas sin plan de pago: 5.
- Validez de un enlace de firma: 7 días.
- Herramientas PDF: archivos de hasta 50 MB y 2 trabajos a la vez.
Herramientas PDF por API
Además de la firma, hay operaciones para trabajar con PDF. Todas son POST con la misma clave:
POST /firma/tools/compressPOST /firma/tools/extract-pagesPOST /firma/tools/flattenPOST /firma/tools/images-to-pdfPOST /firma/tools/infoPOST /firma/tools/mergePOST /firma/tools/metadataPOST /firma/tools/ocrPOST /firma/tools/office-to-pdfPOST /firma/tools/page-numbersPOST /firma/tools/pdf-to-imagesPOST /firma/tools/protectPOST /firma/tools/redactPOST /firma/tools/rotatePOST /firma/tools/splitPOST /firma/tools/to-pdfaPOST /firma/tools/unprotectPOST /firma/tools/watermark
Servidor MCP (asistentes de IA)
Un asistente de IA puede conectarse por MCP a /firma/mcp (método POST) con la misma clave de API en la cabecera Authorization: Bearer. Las respuestas siempre se limitan al espacio de la cuenta de la clave. Hay un límite de 120 llamadas por minuto y espacio.
Herramientas disponibles:
listar_modelos_documento: modelos disponibles con sus campos para crear un documento, siempre revisados por el cliente.resumen_cuenta: visión general: documentos completados, pendientes, rechazados o caducados, firmantes habituales y plantillas.listar_documentos: lista los documentos del espacio, con filtro por estado (incluye rechazados y caducados), búsqueda por nombre o referencia, por firmante y paginación.estado_documento: detalle de un documento y del estado de cada firmante, con el resumen en lenguaje llano que vio.listar_firmantes_habituales: libreta de firmantes habituales, con búsqueda por nombre o correo.listar_plantillas_firma: plantillas de firma guardadas, con sus firmantes, mensaje y resumen.subir_documento: prepara un PDF en base64 con título y referencia.crear_desde_modelo: prepara un modelo con sus datos; requiere modelo_revisado=true.enviar_documento: prepara firmantes (nombre/correo), mensaje, resumen, idioma y orden; admite plantilla_id guardada.enviar_masivo: prepara un CSV nombre,correo con una copia por persona, sujeto a los topes y cupo del plan.recordar_firma: prepara un recordatorio sujeto al intervalo, estado y límite diario del producto.reenviar_invitacion: prepara reenvío a la misma dirección, con los mismos controles que un recordatorio.cancelar_documento: prepara cancelar las solicitudes abiertas; no borra el documento ni las firmas hechas.duplicar_documento: prepara una copia del original como borrador, sin firmas ni enlaces anteriores.actualizar_referencia: prepara el cambio de la referencia del cliente.editar_firmante: prepara el cambio de nombre o correo de un contacto; no cambia solicitudes ya enviadas.guardar_firmante: prepara añadir un contacto a la libreta.guardar_plantilla_firma: prepara una plantilla de firma con firmantes y contenido, con límite del plan.estado_operacion: consulta el resultado sin ejecutar cambios; no reintentes automáticamente los envíos parciales.
Las claves actuales mantienen MCP de solo lectura. Para gestionar, crea una clave nueva marcando gestión MCP. Cada herramienta prepara una propuesta privada durante 10 minutos. Abre revision_url en tu cuenta, revisa el PDF, destinatarios, contenido y consumo del plan y confirma con tu sesión (y contraseña si hace falta). Solo esa página ejecuta el cambio una vez. Consulta estado_operacion. No hay borrado de documentos ni firma por otras personas. Las propuestas se pierden si reinicia el servicio; los resultados solo se consultan durante esos 10 minutos.
No disponible hoy
- Entorno de pruebas: no hay. Cualquier clave trabaja con datos reales, envía correos reales y cuenta en el uso del plan. Para probar, usa direcciones de correo tuyas.
- MCP requiere revisión humana en la web para cada cambio. La API REST sigue enviando directamente sin esa revisión.
- Avisos de documento enviado, documento abierto o borrado próximo: no existen.