Firmas electrónicas

Envía cualquier documento a firmar electrónicamente: mandatos, contratos de compraventa, representaciones de entidad y declaraciones de extravío. El firmante recibe un email, firma desde el navegador y tú recibes el PDF firmado a través de un webhook.

Esta funcionalidad está en desarrollo. Los endpoints de firmas están publicados en la referencia API pero aún no están activos. Puedes planificar tu integración contra el contrato — el comportamiento descrito aquí es el definitivo.

Crea la solicitud de firma

Envía la solicitud en una llamada, el firmante recibe un email con el enlace para firmar y tú recibes un evento cuando el documento queda firmado.

1. Creas la firma

2. Recibes el evento

3. Obtienes el documento

Tu empresa

Punto

POST/v1/signatures/{type}

→201

Ver petición

{
  "signerEmail": "titular@ejemplo.com",
  "signerName": "Ana García López",
  "signerIdNumber": "12345678A"
}

Ver respuesta

{
  "id": "sigreq_3ab7kp",
  "type": "mandate-generic",
  "status": "pending",
  "signerEmail": "titular@ejemplo.com"
}

Enviamos la solicitud de firma al firmante↓

signature.status_changed←

webhook

Ver cuerpo

{
  "event": "signature.status_changed",
  "data": {
    "id": "sigreq_3ab7kp",
    "path": "/v1/signatures/sigreq_3ab7kp",
    "status": "signed",
    "downloadUrl": "https://api.punto.ai/v1/signatures/sigreq_3ab7kp/download",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

GET/v1/signatures/{id}

→200

Ver respuesta

{
  "id": "sigreq_3ab7kp",
  "type": "mandate-generic",
  "status": "signed",
  "signedPdfUrl": "https://api.punto.ai/v1/signatures/sigreq_3ab7kp/download?token=..."
}

Paso 1 — Creas la firma

Envía una llamada POST al endpoint del tipo de documento que necesitas firmar. Cada tipo tiene su propio conjunto de campos requeridos. La solicitud se crea directamente como confirmada.

▾

Autorización genérica para que nuestro gestor actúe en nombre del firmante ante la DGT u otros organismos. Útil cuando es un cliente que hará muchos trámites.

Campo		Descripción
`signerEmail`	obligatorio	Email del firmante al que se enviará la solicitud de firma. Ej: titular@ejemplo.com
`signerName`	obligatorio	Nombre completo del firmante. Ej: Ana García López
`signerIdNumber`	obligatorio	NIF o NIE del firmante. Ej: 12345678A

POST /v1/signatures/mandate-generic — Request

{
  "signerEmail": "titular@ejemplo.com",
  "signerName": "Ana García López",
  "signerIdNumber": "12345678A"
}

201 Created — Response

{
  "id": "sigreq_3ab7kp",
  "type": "mandate-generic",
  "status": "pending",
  "signerEmail": "titular@ejemplo.com"
}

Ver referencia completa de este endpoint →

Paso 2 — Recibes el evento

Punto envía un evento signature.status_changed a tu webhook cada vez que cambia el estado de la solicitud de firma. Cuando el estado es signed, el evento incluye una URL de descarga temporal para el PDF firmado.

signature.status_changed (firmado)

{
  "event": "signature.status_changed",
  "data": {
    "id": "sigreq_3ab7kp",
    "path": "/v1/signatures/sigreq_3ab7kp",
    "status": "signed",
    "downloadUrl": "https://api.punto.ai/v1/signatures/sigreq_3ab7kp/download",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

Paso 3 — Obtienes el documento firmado

Consulta la firma con el identificador recibido. Cuando el estado es signed, la respuesta incluye una URL prefirmada en signedPdfUrl para descargar el PDF firmado. La URL es válida durante un tiempo limitado.

GET /v1/signatures/{id} — 200 OK

{
  "id": "sigreq_3ab7kp",
  "type": "mandate-generic",
  "status": "signed",
  "signedPdfUrl": "https://api.punto.ai/v1/signatures/sigreq_3ab7kp/download?token=..."
}

Anexo — Estados de una firma

Estado	Descripción
`pending`	Solicitud creada, esperando que el firmante complete la firma
`signed`	El firmante ha completado la firma — el PDF está disponible
`expired`	La solicitud expiró sin ser firmada

Anexo — Eventos

Todos los eventos que Punto emite bajo la familia signature.*.

`signature.status_changed`

Se emite cada vez que cambia el estado de la solicitud de firma. Cuando el estado es signed, el payload incluye downloadUrl para descargar el PDF firmado directamente sin necesidad de consultar el endpoint GET.

signature.status_changed — firmado

{
  "event": "signature.status_changed",
  "data": {
    "id": "sigreq_3ab7kp",
    "path": "/v1/signatures/sigreq_3ab7kp",
    "status": "signed",
    "downloadUrl": "https://api.punto.ai/v1/signatures/sigreq_3ab7kp/download",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

signature.status_changed — expirado

{
  "event": "signature.status_changed",
  "data": {
    "id": "sigreq_3ab7kp",
    "path": "/v1/signatures/sigreq_3ab7kp",
    "status": "expired",
    "timestamp": "2025-08-19T10:30:00.000Z"
  }
}

Anexo — Otras acciones

Reenviar la solicitud de firma

Si el firmante no ha recibido el email o necesita un nuevo enlace, puedes reenviar la solicitud de firma:

POST /v1/signatures/{id}/resend — 200 OK

{
  "id": "sigreq_3ab7kp",
  "type": "mandate-generic",
  "status": "pending",
  "signerEmail": "titular@ejemplo.com"
}

Siguientes pasos

Trámites DGT — matriculaciones, transferencias y otros trámites
Informes DGT — solicita informes de vehículos sin crear un trámite
Referencia API — documentación completa de todos los endpoints