Documentación de la API de Firma Electrónica

API REST para firma electrónica simple (SES) con sellado de tiempo RFC 3161 (eIDAS art. 25) y generación de contratos a partir de plantillas. Todas las respuestas son JSON salvo la descarga de documentos.

Autenticación

Todas las llamadas a la API requieren autenticación mediante un token Bearer enviado en la cabecera Authorization de cada petición. Solicita tu token a soporte@pastormap.com.

Cabecera requerida en cada petición:

Authorization: Bearer TU_TOKEN_DE_ACCESO

Firma de documentos

Flujo principal del servicio: subir un PDF, crear una solicitud de firma para un firmante, consultar el estado y gestionar los documentos.

POST /firma/documentos

Sube un documento PDF para ser firmado. La petición es de tipo multipart/form-data.

Parámetros (form-data)

  • file — el archivo PDF a firmar (obligatorio).
  • tenant — identificador del cliente o entidad propietaria.
  • uploaded_by — identificador de quién sube el documento.

Respuesta de ejemplo

{
  "document_id": "doc_a1b2c3d4",
  "filename": "contrato.pdf",
  "tenant": "ayuntamiento-ejemplo",
  "uploaded_at": "2026-06-05T10:30:00Z"
}

POST /firma/solicitudes

Crea una solicitud de firma para un documento previamente subido. Devuelve la URL de firma que se envía al firmante. Cuerpo en formato JSON.

Parámetros (JSON)

  • document_id — identificador del documento devuelto al subirlo.
  • signee_email — correo electrónico del firmante.
  • signee_name — nombre del firmante.
  • lang — idioma de la página de firma (por ejemplo es).

Respuesta de ejemplo

{
  "request_id": "req_e5f6g7h8",
  "signing_url": "https://firma.pastormap.com/sign/req_e5f6g7h8",
  "status": "pending"
}

GET /firma/solicitudes/{request_id}/estado

Consulta el estado de una solicitud de firma. Cuando la firma está completada incluye el sello de tiempo (TSA) y la firma RSA en base 64.

Parámetros (ruta)

  • request_id — identificador de la solicitud de firma.

Respuesta de ejemplo

{
  "status": "signed",
  "signed_at": "2026-06-05T11:05:42Z",
  "tsa_token_b64": "MIIF...",
  "rsa_signature_b64": "Qk9..."
}

GET /firma/documentos/{document_id}/solicitudes

Lista todas las solicitudes de firma asociadas a un documento.

Parámetros (ruta)

  • document_id — identificador del documento.

Respuesta de ejemplo

{
  "document_id": "doc_a1b2c3d4",
  "solicitudes": [
    {
      "request_id": "req_e5f6g7h8",
      "signee_email": "firmante@ejemplo.es",
      "status": "signed"
    }
  ]
}

DELETE /firma/documentos/{document_id}

Elimina un documento y todos sus datos asociados. Pensado para atender el derecho de supresión del RGPD (artículo 17).

Parámetros (ruta)

  • document_id — identificador del documento a eliminar.

Respuesta de ejemplo

{
  "document_id": "doc_a1b2c3d4",
  "deleted": true
}

Verificación

Comprueba la validez de una firma electrónica ya realizada.

GET /verificar/{document_id}

Verifica la firma de una solicitud: comprueba la firma RSA del documento y el sello de tiempo RFC 3161.

Parámetros (ruta)

  • document_id — identificador de la solicitud a verificar.

Respuesta de ejemplo

{
  "request_id": "req_e5f6g7h8",
  "valid": true,
  "signed_at": "2026-06-05T11:05:42Z",
  "tsa_valid": true,
  "rsa_valid": true
}

Contratos

Genera documentos PDF a partir de plantillas de contrato predefinidas.

GET /firma/contratos

Lista las plantillas de contrato disponibles.

Respuesta de ejemplo

{
  "contratos": [
    {
      "template_id": "arrendamiento",
      "nombre": "Contrato de arrendamiento"
    }
  ]
}

POST /firma/contratos/{template_id}/pdf

Genera el PDF de un contrato a partir de una plantilla, rellenando los datos enviados en el cuerpo JSON. Devuelve el archivo PDF.

Parámetros (ruta)

  • template_id — identificador de la plantilla de contrato.

Parámetros (JSON)

  • Los campos de la plantilla (varían según el contrato).

Respuesta

Archivo PDF (application/pdf) con el contrato generado.

Especificación completa

Para la lista exhaustiva de endpoints, esquemas y códigos de respuesta puedes consultar: