La firma de Probática, desde tus sistemas

1. Creá tu clave en Configuración → API de tu empresa (rol de administrador y módulo de API habilitado). Elegí solo los alcances que tu integración necesita.
2. Probá la conexión listando tus plantillas — trae los role_id y las claves de variables que vas a necesitar:

curl https://probatica.com.ar/api/v1/plantillas \
  -H "Authorization: Bearer prbt_TU_CLAVE"

3. Creá tu primer envío con "enviar": false y revisalo en la pantalla: el sobre queda en borrador, no sale ningún aviso, y ves exactamente qué produjo tu pedido antes de que lo reciba un firmante real.
4. Cuando el borrador se vea bien, repetí con "enviar": true — el firmante recibe su enlace al instante.

Cada request lleva la clave en el encabezado. No hay sesiones, cookies ni login:

Authorization: Bearer prbt_TU_CLAVE

La clave tiene el prefijo prbt_ seguido de 30 a 80 caracteres. (Las claves de la marca anterior, con prefijo sgnv_, siguen aceptándose en la forma para que una revocada responda «revocada» y no «forma inválida».)

La API es servidor a servidor: no responde CORS, así que un navegador no puede llamarla, y la clave jamás va en una app móvil ni en un repositorio. En la base solo se guarda su huella SHA-256 — si la perdés, se genera otra; recuperarla es imposible a propósito.

El ciclo de vida: se crea con un nombre, sus alcances y, opcionalmente, un vencimiento a 30 días, 90 días o un año; se muestra una sola vez; no se edita ni se renueva —una clave con otros alcances o más plazo es otra clave—; y se revoca en el acto. Una clave revocada o vencida responde 401 desde el siguiente request.

Qué se revalida en cada request, y qué no. Siempre: que la clave exista y esté viva, que la empresa esté operativa y tenga el módulo, y el alcance. La membresía y el rol de la persona que creó la clave se vuelven a comprobar solo al crear y despachar —por eso creacion_rechazada puede decir «membresía inactiva»—; los extremos de lectura resuelven la pertenencia por empresa, no por la persona. En la práctica: lo único que corta el acceso de una clave es revocarla.

Quién queda como autor. Toda acción se atribuye a la persona que creó la clave, no a la clave: una clave no firma expedientes, una persona sí. Si esa persona deja la empresa, revocá sus claves y generá las nuevas a nombre de quien corresponda — generar otra no desactiva la primera.

El alcance decide qué puede hacer la clave. Pedir un extremo fuera de alcance responde 403 alcance_insuficiente con el alcance que falta. Dale a cada integración solo los que necesita: una que únicamente consulta estados no tiene por qué poder crear envíos.

Los requests rechazados en la autenticación (401, 403, 429) no cuentan contra el ritmo ni aparecen en el registro de uso de la pantalla: ese registro es de lo que la API efectivamente atendió.

Todos los errores que la API produce tienen la misma forma, así que tu código lee siempre los mismos dos campos:

{
  "error": {
    "code": "alcance_insuficiente",
    "message": "Este extremo requiere el alcance «envios:write» y la clave no lo tiene."
  }
}

El code es estable y está pensado para que tu programa decida qué hacer; el message está escrito para que una persona entienda qué corregir, y puede cambiar de redacción. No condiciones tu lógica al texto del mensaje. Un fallo no previsto del servidor responde 500 sin ese sobre: tratá cualquier respuesta sin error.code como transitoria y reintentá más tarde.

Estos ocho pueden volver de cualquier extremo:

El orden de validación importa y es este: la clave existe y está viva → la empresa está operativa y tiene el módulo → el alcance alcanza → el ritmo. El ritmo se comprueba último a propósito: una clave revocada recibe su 401 y no un 429 que sugeriría que sigue sirviendo.

Los códigos propios de cada extremo están en su sección: los quince de POST /envios en una tabla, estado_desconocido y consulta_invalida junto a los parámetros de GET /envios, envio_inexistente, documento_no_sellado y evidencia_no_disponible en el detalle y las descargas. En total son 28. Todos los 404 son el mismo para «no existe» y para «es de otra empresa»: distinguirlos le confirmaría a un tercero que el recurso existe en algún lado.

GET/api/v1/plantillasrequiere plantillas:read

El punto de partida: tus plantillas con todo lo que la creación de un envío va a pedir — los role_id de cada papel y las variables con sus claves. Devuelve hasta 100, sin las archivadas, de la editada más recientemente a la más vieja. No toma parámetros.

{
  "plantillas": [
    {
      "id": "9be0…",
      "nombre": "Convenio de refinanciación",
      "descripcion": "Para los acuerdos de pago con clientes en mora.",
      "origen": "composed",
      "estado": "active",
      "nivel": "biometrica",
      "modalidad": "parallel",
      "vence_en_dias": 30,
      "papeles": [
        { "role_id": "d1a2…", "etiqueta": "Cliente",  "participacion": "signer",   "fijo": false },
        { "role_id": "b7c3…", "etiqueta": "Gerencia", "participacion": "approver", "fijo": true  }
      ],
      "variables": [
        { "clave": "monto_de_la_deuda", "etiqueta": "Monto de la deuda", "requerida": true }
      ]
    }
  ]
}

Las plantillas no necesitan campos de firma: si no definiste dónde firma cada uno, Probática estampa las firmas al pie de la primera hoja, con nombre, CUIT o DNI, fecha certificada y el código de verificación.

POST/api/v1/enviosrequiere envios:write

El extremo principal. Crea un sobre desde una plantilla y, con "enviar": true, lo despacha en el mismo request; sin él queda en borrador. En una plantilla redactada, las variables completan el contrato y el PDF se genera ahí mismo.

curl -X POST https://probatica.com.ar/api/v1/envios \
  -H "Authorization: Bearer prbt_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "plantilla_id": "9be0…",
    "titulo": "Refinanciación 4471 — GOMEZ CARLOS",
    "mensaje": "Le acercamos el convenio para su firma.",
    "nivel": "biometrica",
    "variables": { "monto_de_la_deuda": "$ 120.500,00" },
    "destinatarios": [
      {
        "role_id": "d1a2…",
        "nombre": "GOMEZ CARLOS",
        "email": "gomez@ejemplo.com",
        "cuit": "20-12345678-9",
        "telefono": "+5491123456789"
      },
      {
        "nombre": "PEREZ ANA",
        "email": "perez@ejemplo.com"
      }
    ],
    "enviar": true
  }'

El cuerpo, campo por campo

Cada destinatario

La respuesta

{
  "envio": {
    "id": "77aa…",
    "estado": "sent",
    "nivel": "biometrica",
    "firmantes": [
      {
        "nombre": "GOMEZ CARLOS",
        "email": "gomez@ejemplo.com",
        "canal": "whatsapp",
        "entregado": true,
        "enlace_firma": "https://probatica.com.ar/firmar/a1b2…"
      },
      {
        "nombre": "PEREZ ANA",
        "email": "perez@ejemplo.com",
        "canal": "correo",
        "entregado": true,
        "enlace_firma": "https://probatica.com.ar/firmar/c3d4…"
      }
    ]
  }
}

Estado 201. Los campos canal, entregado y enlace_firma aparecen solo con "enviar": true, y en ese caso la lista trae a quienes firman o aprueban, en su orden de firma. Con false, estado es draft, cada firmante trae únicamente nombre y correo, y la lista incluye también a los viewer y cc de la plantilla.

nivel es el nivel efectivo del sobre, que puede diferir del pedido en las dos direcciones: si la plantilla exige biometría va a decir biometrica aunque no la hayas pedido, y si la plantilla es biométrica pero tu empresa no tiene el módulo va a decir avanzada. Leelo de la respuesta.

"entregado": false no invalida el envío: el sobre está creado y despachado, pero ese aviso no salió —una casilla inexistente, por ejemplo—. El enlace sigue sirviendo, y se reenvía desde la pantalla del envío.

El enlace de firma es la llave del documento. Cualquiera que lo tenga puede abrir el sobre y llegar al paso de verificación. Viene en la respuesta para que puedas entregarlo por tu propio canal, pero tratalo como una credencial: no lo registres en logs ni lo muestres a nadie que no sea el firmante.

Errores propios de este extremo

GET/api/v1/enviosrequiere envios:read

Los envíos de la empresa, del más nuevo al más viejo. Tres parámetros de consulta:

# Los envíos completados, de a 50
curl "https://probatica.com.ar/api/v1/envios?estado=completed&limite=50" \
  -H "Authorization: Bearer prbt_TU_CLAVE"

# La página siguiente
curl "https://probatica.com.ar/api/v1/envios?estado=completed&limite=50&antes_de=2026-09-01T14:22:10.343361%2B00:00" \
  -H "Authorization: Bearer prbt_TU_CLAVE"

{
  "envios": [
    {
      "id": "77aa…",
      "titulo": "Refinanciación 4471 — GOMEZ CARLOS",
      "estado": "completed",
      "nivel": "biometrica",
      "origen": "api",
      "creado":     "2026-09-01T14:22:10.343361+00:00",
      "enviado":    "2026-09-01T14:22:14.918204+00:00",
      "completado": "2026-09-02T09:41:03.115577+00:00",
      "sha256": "e3b0c442…"
    }
  ],
  "siguiente": "2026-09-01T14:22:10.343361+00:00"
}

siguiente en null significa que no hay más páginas. origen es app o api: sirve para no volver a procesar lo que tu propio sistema creó. sha256 viene en null hasta que el sobre se sella.

GET/api/v1/envios/:idrequiere envios:read

El detalle completo, con el estado de cada firmante. Es el request que responde «¿en qué quedó?».

{
  "envio": {
    "id": "77aa…",
    "titulo": "Refinanciación 4471 — GOMEZ CARLOS",
    "estado": "completed",
    "nivel": "biometrica",
    "origen": "api",
    "marco_legal": "AR_25506_SIMPLE",
    "creado":     "2026-09-01T14:22:10.343361+00:00",
    "enviado":    "2026-09-01T14:22:14.918204+00:00",
    "completado": "2026-09-02T09:41:03.115577+00:00",
    "sellado":    "2026-09-02T09:41:12.604419+00:00",
    "vence":      "2026-10-01T14:22:10.343361+00:00",
    "sha256": "e3b0c442…",
    "firmantes": [
      {
        "nombre": "GOMEZ CARLOS",
        "email": "gomez@ejemplo.com",
        "telefono": "+5491123456789",
        "participacion": "signer",
        "estado": "signed",
        "verificacion": "id_verification",
        "visto":     "2026-09-02T09:38:44.271003+00:00",
        "firmado":   "2026-09-02T09:41:03.115577+00:00",
        "rechazado": null,
        "motivo_rechazo": null
      },
      {
        "nombre": "PEREZ ANA",
        "email": "perez@ejemplo.com",
        "telefono": null,
        "participacion": "signer",
        "estado": "sent",
        "verificacion": "email_otp",
        "visto": null,
        "firmado": null,
        "rechazado": null,
        "motivo_rechazo": null
      }
    ]
  }
}

Un id inexistente, mal formado, o de otra empresa responde siempre 404 envio_inexistente.

GET/api/v1/envios/:id/documentorequiere documentos:read

Una URL firmada al PDF sellado —con firma electrónica y sello de tiempo RFC 3161—. Se devuelve la URL y no los bytes: el archivo puede pesar megabytes, y así lo bajás directo del almacenamiento. La URL vence a los 10 minutos: pedila cuando la vas a usar, no la guardes, y no queda ninguna dirección permanente a un contrato dando vueltas.

{ "url": "https://…/firmado.pdf?token=…", "expira_en_segundos": 600 }

GET/api/v1/envios/:id/evidenciarequiere documentos:read

El expediente de evidencia en sus dos formas: el PDF para que lo lea una persona y el JSON para que lo procese un peritaje. Mismas URLs a 10 minutos.

{
  "expediente_pdf": "https://…/evidencia.pdf?token=…",
  "expediente_json": "https://…/evidencia.json?token=…",
  "expira_en_segundos": 600
}

expediente_pdf siempre viene cuando la respuesta es 200: si no se puede emitir, el extremo corta con 502 almacenamiento. expediente_json no: si su URL no se puede firmar viene en null con respuesta 200 —los expedientes anteriores a la versión pericial no lo tienen—. Comprobalo antes de bajarlo.

Los dos extremos responden 404 envio_inexistente si el id no es de tu empresa, y 409 mientras el sobre no esté completado y sellado —documento_no_sellado y evidencia_no_disponible—, con el estado actual en el mensaje: es la señal de esperar, no de que algo salió mal. Un 502 almacenamiento es transitorio: reintentá.

El nivel biometrica requiere el módulo de verificación de identidad habilitado en tu plan. Pedirlo sin el módulo responde 403 modulo_no_habilitado antes de crear nada. Pero ojo con el caso inverso: una plantilla biométrica en una empresa sin el módulo crea sobres avanzada sin avisar — el nivel de la respuesta es lo único que lo dice.

El cotejo del documento. Si mandás el cuit del destinatario, el número de documento se compara contra el que el firmante exhibe: una verificación con documento ajeno queda rechazada aunque la biometría pase. La base de cotejo se toma así: de un CUIT o CUIL de 11 dígitos se usan los ocho del medio, que son el DNI; un valor de 7 u 8 dígitos se toma como DNI. Puntos, guiones y ceros a la izquierda no importan. Con cualquier otra forma no hay base de cotejo y la verificación aprueba sin ese candado: si el dato te importa, validalo antes de mandarlo.

Cada firmante recibe su circuito por un canal — el enlace de firma, el código de acceso y la devolución del documento firmado viajan juntos por ahí, nunca duplicados en los dos. Un mismo envío puede mezclar firmantes de cada canal.

Si WhatsApp no acepta el mensaje, sale por correo como respaldo, la respuesta informa el canal que efectivamente entregó y el intento queda asentado en la trazabilidad del sobre. El canal de WhatsApp es de la plataforma, no se habilita por empresa; si no está disponible, todos los circuitos salen por correo. Y el respaldo también puede no entregar —una casilla inexistente—: por eso existe entregado.

La modalidad de la plantilla decide si firman todos a la vez o uno después del otro; la API no la puede cambiar por envío. Los firmantes sin papel se agregan al final del orden.

En modalidad sequential, todos reciben su enlace al despachar, igual que desde la pantalla. Quien abre el suyo antes de su turno ve un aviso de espera, y el mismo enlace funciona cuando le toca. El detalle del envío lo refleja: el primero en sent, los demás en pending hasta que les llegue el turno.

Todas las fechas son ISO-8601 en UTC, con microsegundos y desfase explícito: 2026-09-01T14:22:10.343361+00:00. Parseá con la biblioteca de fechas de tu lenguaje, no con una expresión regular sobre .000Z: la cantidad de decimales no está garantizada. Para mostrar en hora argentina, convertí a America/Argentina/Buenos_Aires del lado tuyo.

• Una clave por sistema, con los alcances mínimos. Revocar una no toca a las demás, y el registro de uso dice qué sistema hizo qué.
• Guardá la clave en tu gestor de secretos, nunca en el código ni en variables visibles del navegador.
• Los reintentos de creación duplican: POST /envios no es idempotente. Ante una respuesta perdida, buscá en GET /envios un sobre reciente con el titulo que mandaste antes de reintentar — por eso conviene que el título lleve tu número de operación.
• Guardá el id del envío junto a tu operación en el momento en que lo recibís: es lo que vas a necesitar para consultar, descargar y conciliar.
• Guardá los role_id, pero no para siempre: si alguien edita la plantilla y borra un papel, ese id deja de existir. Los papeles que no se tocan conservan el suyo.
• Poné fecha de expiración a las claves de integraciones que se prueban y se olvidan: una clave vencida avisa; una viva y olvidada, no.

Para que no lo descubras a fuerza de probar. Nada de esto es un olvido: son decisiones, y si alguna te bloquea, escribinos y la revisamos.

• No crea ni edita plantillas. Se armaron para que las diseñe una persona mirando el documento; una plantilla mal armada por integración se replica en todos los envíos.
• No sube documentos. Los PDF entran por la pantalla de Documentos, o se generan solos desde una plantilla redactada — que, de paso, deja el PDF generado en la biblioteca de documentos de tu empresa.
• No despacha un borrador, ni anula, ni reenvía. Un sobre creado con "enviar": false se envía desde la pantalla; anular y reemitir un enlace también.
• No elige el orden ni la modalidad de firma, ni el vencimiento del sobre: los hereda de la plantilla.
• No elige el canal explícitamente: WhatsApp si hay teléfono, correo si no.
• No entrega el informe del proveedor de identidad. Ese informe embute la imagen del documento del firmante. El veredicto —desagregado y con el número de sesión del proveedor— viaja dentro del expediente, que es donde un perito lo va a buscar.
• No informa el consumo del plan. El cupo no bloquea y el excedente se factura; el número está en Configuración → Facturación.
• No avisa solo. Para enterarte de una firma sin consultar, tu empresa puede configurar avisos a tu sistema desde Configuración → Webhooks; es un módulo aparte, con su propia documentación.

Cualquiera puede comprobar un documento firmado sin credenciales: la página pública de verificación calcula la huella SHA-256 del archivo en el navegador —el archivo nunca se sube— y responde si esa huella corresponde a un documento sellado, con la fecha del sello de tiempo y cuántas firmas reúne. La API no lo duplica: la prueba de una firma no debe depender de tener una clave.