API para programas
Con la API, otro programa (tu CRM, tu ERP, Zapier o Make) puede preparar y mandar documentos a firmar, consultar cómo van y descargar el PDF firmado. Y Rubrikea puede avisar a ese programa cuando alguien firma. Todo va por HTTPS, con JSON.
1. La clave de acceso
- Créala en Integraciones (hay que entrar con tu cuenta). Se enseña una sola vez: guárdala en el programa que la vaya a usar.
- Va en cada petición, en la cabecera
Authorization: Bearer rbk_…. - La clave actúa como la persona que la creó: ve y hace lo mismo que ella. Si esa persona sale del equipo, la clave deja de valer.
- Solo sirve para envíos y plantillas; nunca para la cuenta, el equipo o el plan.
- Límite: 120 peticiones por minuto y clave. Si lo pasas, la respuesta es 429: espera un poco y repite.
curl https://rubrikea.es/api/templates \
-H "Authorization: Bearer rbk_TU_CLAVE"2. Mandar a firmar desde una plantilla (lo más sencillo)
Prepara la plantilla una vez en la aplicación (documento, campos y papeles, por ejemplo «Vendedor» y «Comprador»). Después, por cada contrato:
GET /api/templates: tus plantillas, con suid.GET /api/templates/{id}: sus papeles (roleList), cada uno con suid.POST /api/templates/{id}/use: crea un borrador con las personas de cada papel. Responde{ envelopeId }.POST /api/envelopes/{envelopeId}/send: lo envía. Cada firmante recibe su correo.
curl -X POST https://rubrikea.es/api/templates/ID_PLANTILLA/use \
-H "Authorization: Bearer rbk_TU_CLAVE" -H "Content-Type: application/json" \
-d '{
"subject": "Contrato de arras · Calle Mayor 3",
"people": [
{ "roleId": "ID_PAPEL_VENDEDOR", "name": "Lucía Pérez", "email": "lucia@ejemplo.es" },
{ "roleId": "ID_PAPEL_COMPRADOR", "name": "Mario Gil", "email": "mario@ejemplo.es", "idNumber": "12345678Z" }
]
}'
curl -X POST https://rubrikea.es/api/envelopes/ID_ENVIO/send -H "Authorization: Bearer rbk_TU_CLAVE"idNumber es opcional: si lo pones, el firmante tendrá que escribir ese DNI o NIE antes de firmar.
3. Mandar a firmar un documento nuevo
POST /api/envelopes: crea un borrador vacío. Responde{ id }.POST /api/envelopes/{id}/documents: sube el PDF como formulario (multipart/form-data, campofile). Responde el documento con suidy el tamaño de cada página en puntos.PUT /api/envelopes/{id}/setup: asunto, mensaje y destinatarios.typeessigner(firma) occ(recibe copia). Con"ordered": truefirman uno detrás de otro.GET /api/envelopes/{id}: devuelve los destinatarios con suid, que hace falta para colocar los campos.PUT /api/envelopes/{id}/tabs: los campos. Las medidas van en puntos desde la esquina superior izquierda de la página.type:signature,initials,date_signed,full_name,email,textocheckbox.rotation(opcional) inclina el campo en grados.POST /api/envelopes/{id}/send: lo envía.
curl -X PUT https://rubrikea.es/api/envelopes/ID_ENVIO/setup \
-H "Authorization: Bearer rbk_TU_CLAVE" -H "Content-Type: application/json" \
-d '{ "subject": "Contrato de servicios", "message": "Hola, te lo envío para firmar.",
"recipients": [ { "name": "Lucía Pérez", "email": "lucia@ejemplo.es", "type": "signer" } ] }'
curl -X PUT https://rubrikea.es/api/envelopes/ID_ENVIO/tabs \
-H "Authorization: Bearer rbk_TU_CLAVE" -H "Content-Type: application/json" \
-d '{ "tabs": [ { "documentId": "ID_DOCUMENTO", "recipientId": "ID_DESTINATARIO", "type": "signature",
"page": 1, "x": 380, "y": 700, "width": 120, "height": 44, "required": true } ] }'4. Saber cómo va y descargar el firmado
GET /api/envelopes/{id}: estado del envío (draft,sent,completed,declined,voided,expired) y de cada persona.GET /api/envelopes/{id}/download: el PDF firmado y sellado, cuando el estado escompleted. Con?que=certificado, el certificado de la firma; con?que=sello, el sello de tiempo (fichero .tsr).POST /api/envelopes/{id}/voidcon{ "reason": "…" }: anula un envío que aún no está firmado.
5. Avisos automáticos (webhooks)
En Integraciones pon la dirección de tu programa y elige los avisos. Rubrikea le enviará un POST con JSON cada vez que pase algo:
envelope.sent,recipient.signed,envelope.completed,envelope.declined,envelope.voidedyenvelope.expired.- Si tu programa no responde con un 2xx, se reintenta más tarde varias veces.
- Cada aviso lleva la cabecera
Rubrikea-Signature: t=…,v1=…. Compruébala con el secreto que te damos al crear el aviso: así sabes que viene de Rubrikea y que nadie lo ha cambiado.
{ "id": "…", "type": "envelope.completed", "created": "2026-11-18T10:00:00.000Z",
"data": { "envelopeId": "…", "subject": "Contrato de arras", "status": "completed" } }// Node.js: comprobar la firma de un aviso
import { createHmac, timingSafeEqual } from "node:crypto";
function avisoValido(cuerpoEnTexto, cabecera, secreto) {
const partes = Object.fromEntries(cabecera.split(",").map((p) => p.split("=")));
const esperada = createHmac("sha256", secreto).update(`${partes.t}.${cuerpoEnTexto}`).digest("hex");
const reciente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300;
return reciente && timingSafeEqual(Buffer.from(esperada), Buffer.from(partes.v1 ?? ""));
}6. Con Zapier o Make, sin programar
- Recibir avisos. En Zapier, usa el disparador «Webhooks by Zapier → Catch Hook»; en Make, el módulo «Webhooks → Custom webhook». Copia la dirección que te dan y pégala en Integraciones. Desde ahí puedes, por ejemplo, guardar el PDF en Drive o marcar la operación como firmada en tu CRM.
- Mandar a firmar. En Zapier, «Webhooks by Zapier → Custom Request»; en Make, «HTTP → Make a request». Método
POST, direcciónhttps://rubrikea.es/api/templates/ID_PLANTILLA/use, cabeceraAuthorization: Bearer rbk_…y el cuerpo del punto 2. Después, otro paso igual a/api/envelopes/{envelopeId}/send. - Descargar el firmado. Cuando llegue el aviso
envelope.completed, un paso «GET» a/api/envelopes/{envelopeId}/downloadcon la misma cabecera.
Errores
Las respuestas de error llevan { "error": "…" } con el motivo en castellano: 400 (datos no válidos), 401 (falta la clave o no vale), 403 (sin permiso), 404 (no existe o no es tuyo), 409 (no se puede en el estado actual), 429 (demasiadas peticiones).
¿Dudas? Escribe a hola@rubrikea.es.