# Firmame — documentación para desarrolladores

> Firmame es un servicio de firma electrónica. Esta es la documentación de su API, cuya URL base es https://app.firmame.com.

- Cada página se sirve también en markdown: añade `.md` a su URL, por ejemplo https://devs.firmame.com/docs/autenticacion.md
- Especificación OpenAPI: https://devs.firmame.com/openapi.yaml
- Documentación completa en un solo archivo: https://devs.firmame.com/llms-full.txt
- Versión en inglés de este archivo: https://devs.firmame.com/en/llms.txt
- Toda petición se autentica con una firma HMAC: https://devs.firmame.com/docs/autenticacion. Si no coincide, la respuesta es `401` con cuerpo vacío.

- [Introducción](https://devs.firmame.com/docs): Integra la firma electrónica de Firmame en tu aplicación.
- [Inicio rápido con IA](https://devs.firmame.com/docs/inicio-rapido-ai): Dale esta documentación a tu asistente y pídele la integración. Prompt de arranque y URLs legibles por máquina.
- [Conceptos](https://devs.firmame.com/docs/conceptos): El vocabulario de Firmame.
- Autenticación
  - [Credenciales y firma](https://devs.firmame.com/docs/autenticacion): Cómo obtener tus credenciales y cómo se arma el encabezado de autenticación de cada petición.
  - [Errores 401](https://devs.firmame.com/docs/autenticacion/errores-401): Cómo diagnosticar una petición que devuelve 401, paso por paso.
- [SDKs](https://devs.firmame.com/docs/sdks): Instala o descarga el SDK de tu lenguaje, como firmame.ts para TypeScript. Se encargan de firmar cada petición por ti.
- Guías
  - [Crear y enviar un documento](https://devs.firmame.com/docs/guias/crear-documento): De un PDF a un documento firmado, con Firmame llevando las invitaciones.
  - [Firmantes y autoridades](https://devs.firmame.com/docs/guias/firmantes): Cómo elige cada persona su método de verificación, y cómo corregir un firmante a tiempo.
  - [Verificación de identidad](https://devs.firmame.com/docs/guias/verificacion-de-identidad): Comprueba que el firmante es una persona real, con identificación oficial y prueba de vida.
  - [Recuadros de firma en el documento](https://devs.firmame.com/docs/guias/recuadros-de-firma): Coloca las áreas de firma dibujándolas dentro del PDF, sin mandar coordenadas por API.
  - [Flujos de firma](https://devs.firmame.com/docs/guias/flujos): Orden de firma, recordatorios, expiración y cancelación.
  - [Expedientes](https://devs.firmame.com/docs/guias/expedientes): Varios documentos, una sola invitación y un solo orden de firma.
  - [Subir un documento a un expediente](https://devs.firmame.com/docs/guias/subir-documento-a-expediente): El mismo POST /developers/json de crear un documento, con document_set obligatorio.
  - [Templates](https://devs.firmame.com/docs/guias/templates): Registra un documento una vez y genera cada instancia mandando solo los datos.
  - [Código QR](https://devs.firmame.com/docs/guias/codigo-qr): Estampa un QR de verificación en el documento, en el mismo payload de creación.
  - [Gestor](https://devs.firmame.com/docs/guias/gestor): Asigna quién administra el documento dentro de tu organización.
  - [Correos certificados](https://devs.firmame.com/docs/guias/correos-certificados): Envía documentación con constancia de entrega, apertura y lectura.
  - [Endosos](https://devs.firmame.com/docs/guias/endosos): Transfiere un título de crédito ya firmado a un nuevo tenedor.
  - [NOM-151 y herramientas PDF](https://devs.firmame.com/docs/guias/nom151): Sella cualquier archivo o hash con constancia de conservación, y utilidades de PDF.
- Webhooks
  - [Cómo funcionan](https://devs.firmame.com/docs/webhooks): Firmame te avisa cuando algo pasa; tú usas ese aviso para descargar el documento.
  - [Suscripciones por evento (beta)](https://devs.firmame.com/docs/webhooks/suscripciones): Registra una URL distinta por tipo de evento vía API, en lugar de una sola en el panel.
- [Zapier](https://devs.firmame.com/docs/zapier): Conecta Firmame con miles de apps sin escribir código, con triggers y acciones listos para usar.
- Referencia de API
  - [Referencia de API](https://devs.firmame.com/docs/api)
  - Documentos: Crear, enviar y eliminar documentos.
    - [Crear un documento](https://devs.firmame.com/docs/api/documentos/create-document): El endpoint principal.
    - [Eliminar un documento](https://devs.firmame.com/docs/api/documentos/delete-document): Elimina un documento y descarta sus notificaciones pendientes.
    - [Restaurar un documento](https://devs.firmame.com/docs/api/documentos/restore-document): Reactiva un documento eliminado.
  - Webhooks y cuenta: Suscripciones a webhooks y consumo de la cuenta.
    - [Suscribirse a un evento](https://devs.firmame.com/docs/api/webhooks-y-cuenta/add-webhook): Registra una URL para recibir aviso cuando ocurra un evento.
    - [Cancelar la suscripción a un evento](https://devs.firmame.com/docs/api/webhooks-y-cuenta/delete-webhook): Elimina una suscripción por su id.
    - [Consultar los paquetes restantes](https://devs.firmame.com/docs/api/webhooks-y-cuenta/get-account-info): Devuelve lo que queda de los paquetes contratados.
    - [Consultar el detalle de paquetes](https://devs.firmame.com/docs/api/webhooks-y-cuenta/get-account-info-detail): Devuelve los paquetes de la cuenta uno por uno — cuántas piezas trae cada uno, cuántas ya se usaron y la ventana en la que es válido.
    - [Consultar el reporte de consumo](https://devs.firmame.com/docs/api/webhooks-y-cuenta/get-account-report): Devuelve lo que consumió la cuenta entre dos fechas — documentos creados, verificaciones realizadas, mensajes enviados — para conciliación y cobro interno.
    - [Un firmante firmó el documento](https://devs.firmame.com/docs/api/webhooks-y-cuenta/original-signed): Se dispara cada vez que alguien firma.
    - [Se encapsuló una firma](https://devs.firmame.com/docs/api/webhooks-y-cuenta/universal-signed): Se dispara cuando la firma ya se envolvió en la representación universal de validación a largo plazo.
    - [Ya se firmaron todos los recuadros](https://devs.firmame.com/docs/api/webhooks-y-cuenta/document-completed): El evento sobre el que conviene construir tu lógica de negocio: el documento ya está completamente firmado y listo para descargar con `GET /api/document/{type}/{ticket}`.
    - [Un firmante rechazó el documento](https://devs.firmame.com/docs/api/webhooks-y-cuenta/document-rejected): `meta` trae quién lo rechazó y el motivo que dio, hasta 300 caracteres.
    - [El flujo de firma expiró](https://devs.firmame.com/docs/api/webhooks-y-cuenta/workflow-expired): El flujo llegó a su `expirationDate` con firmas todavía pendientes.
    - [No se pudo entregar un mensaje de WhatsApp](https://devs.firmame.com/docs/api/webhooks-y-cuenta/whatsapp-error): El firmante nunca recibió su invitación.
    - [No se pudo entregar un SMS](https://devs.firmame.com/docs/api/webhooks-y-cuenta/sms-error): Misma forma y los mismos códigos que `whatsapp_error`.
    - [No se pudo entregar un correo](https://devs.firmame.com/docs/api/webhooks-y-cuenta/email-error): `meta` transmite lo que respondió el servidor de correo receptor, para que distingas un correo mal escrito de un buzón lleno.
    - [El documento original se selló con NOM-151](https://devs.firmame.com/docs/api/webhooks-y-cuenta/original-nom151-stamped): `meta` trae el sello mismo.
    - [El documento universal se selló con NOM-151](https://devs.firmame.com/docs/api/webhooks-y-cuenta/universal-nom151-stamped): Misma forma que `original_nom151_stamped`, para la representación universal.
    - [Una verificación de identidad no pasó](https://devs.firmame.com/docs/api/webhooks-y-cuenta/identity-verification-failed): Se manda para firmantes con `requireIdentityVerification`.
    - [Una verificación de identidad pasó](https://devs.firmame.com/docs/api/webhooks-y-cuenta/identity-verification-completed): Se confirmó la identidad del firmante y ya puede firmar.
  - N O M 151 y herramientas P D F: Sellado de tiempo, sello NOM-151 y utilidades de PDF por separado.
    - [Sellar un hash](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/get-timestamp): Emite un sello de tiempo NOM-151 sobre un hash cualquiera — no hace falta un documento.
    - [Validar un sello de tiempo](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/validate-timestamp): Comprueba un sello NOM-151 contra los datos que dice amparar.
    - [Sellar un PDF con NOM-151](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/stamp-pdf-with-nom151): Aplica un sello de tiempo NOM-151 a un PDF que ya tienes y devuelve el archivo sellado — para documentos firmados fuera de Firmame, o PDFs ya firmados a los que hay que agregarles el sello.
    - [Validar el sello NOM-151 de un PDF](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/validate-pdf-nom151): Verifica el sello NOM-151 embebido en un PDF: que el token sea genuino, que lo haya emitido una autoridad reconocida, y que el documento no haya cambiado desde entonces.
    - [Aplanar un PDF](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/print-pdf): Devuelve una versión aplanada del PDF — los campos de formulario se vuelven contenido estático, las capas se fusionan, y el resultado es un PDF imprimible simple.
    - [Obtener las dimensiones de una página](https://devs.firmame.com/docs/api/nom-151-y-herramientas-pdf/get-page-data): Devuelve el tamaño y la rotación de una página, para que calcules los rectángulos de los stickers y caigan donde esperas en vez de adivinar entre Carta y A4.
  - Descargas: Descargar documentos firmados, sellos NOM-151 y datos de correos certificados.
    - [Descargar un documento firmado](https://devs.firmame.com/docs/api/descargas/download-document): Descarga el PDF firmado, codificado en Base64 dentro de un sobre JSON, junto con su hash.
    - [Listar los sellos NOM-151 de un documento](https://devs.firmame.com/docs/api/descargas/list-nom151-stamps): Devuelve todos los sellos de tiempo NOM-151 aplicados al documento, cada uno con la autoridad que lo emitió, cuándo se emitió, y el token mismo.
    - [Descargar la revisión que ampara un sello](https://devs.firmame.com/docs/api/descargas/download-stamped-revision): Devuelve la revisión exacta del documento sobre la que se aplicó un sello NOM-151 — los bytes cuyo hash certifica el sello.
    - [Obtener los datos de un correo certificado](https://devs.firmame.com/docs/api/descargas/get-certified-email-data): Devuelve la evidencia de un correo certificado — a quién se envió, cuándo se entregó, cuándo se abrió, y el contenido que se mandó.
  - Consultas: Consultar documentos, reportes e historial de eventos.
    - [Listar documentos](https://devs.firmame.com/docs/api/consultas/list-documents): Lista los documentos creados en una ventana de tiempo, del más reciente al más viejo.
    - [Obtener el reporte de firmas de un documento](https://devs.firmame.com/docs/api/consultas/get-document-report): Devuelve el reporte forense completo del documento: cada firma con su posición, su cadena de certificados, su estado OCSP, su autoridad de sellado de tiempo, y si sigue siendo válida.
    - [Obtener el historial de un documento](https://devs.firmame.com/docs/api/consultas/get-document-history): El historial de un documento contiene información de la generación de un documento, envío, seguimiento y firmas.
    - [Descargar el historial de un documento en PDF](https://devs.firmame.com/docs/api/consultas/get-document-history-pdf): El mismo historial que [`GET /api/v1/document/{frmxId}/history/json`](https://devs.firmame.com/docs/api/consultas/get-document-history), pero como PDF listo para entregárselo a alguien.
    - [Obtener un documento desde una notificación de webhook](https://devs.firmame.com/docs/api/consultas/get-data-by-webhook): Convierte el `notification_id` de un webhook en el documento mismo.
  - Expedientes: Agrupa varios documentos en un mismo paquete de firma.
    - [Crear un expediente](https://devs.firmame.com/docs/api/expedientes/create-document-set): Crea un expediente vacío y devuelve su id.
    - [Subir un documento a un expediente](https://devs.firmame.com/docs/api/expedientes/subir-documento-a-expediente): El mismo POST /developers/json de crear un documento, con document_set obligatorio.
    - [Consultar un expediente](https://devs.firmame.com/docs/api/expedientes/get-document-set): Devuelve los documentos, los firmantes y el estado del expediente.
    - [Cerrar un expediente y arrancar su flujo](https://devs.firmame.com/docs/api/expedientes/close-document-set): Sella el expediente —ya no se le agregan documentos— y arranca el flujo de firma sobre todos los documentos que contiene.
    - [Agregar un firmante al expediente](https://devs.firmame.com/docs/api/expedientes/add-premade-sticker): Precarga un firmante para todo el expediente, sin ligarlo todavía a una página o posición.
    - [Quitar un firmante del expediente](https://devs.firmame.com/docs/api/expedientes/delete-premade-sticker): Elimina un firmante agregado antes con `POST /api/documentset/{uuid}/signer`.
  - Firmantes y flujos: Orden de firma, edición de firmantes, endosos y validación de identidad.
    - [Crear o editar el flujo de un documento](https://devs.firmame.com/docs/api/firmantes-y-flujos/update-workflow): Le pone un flujo de firma a un documento existente, cambia el que ya tiene, o lo cancela.
    - [Crear o editar el flujo de un expediente](https://devs.firmame.com/docs/api/firmantes-y-flujos/update-document-set-workflow): Ajusta el flujo de un expediente que ya cerraste: su expiración, cada cuánto insiste, qué lleva el correo de conclusión, o su cancelación.
    - [Editar un firmante](https://devs.firmame.com/docs/api/firmantes-y-flujos/update-signer): Corrige los datos de un firmante **antes de que haya firmado** — un correo mal escrito, el dato de verificación equivocado, o un cambio de autoridad.
    - [Endosar un documento](https://devs.firmame.com/docs/api/firmantes-y-flujos/prepare-endorsement): Agrega un endoso a un documento **completamente firmado** — el equivalente electrónico de endosar un pagaré.
  - Templates: Plantillas reutilizables guardadas en tu cuenta.
    - [Listar templates](https://devs.firmame.com/docs/api/templates/list-templates): Devuelve todas las plantillas guardadas en la cuenta dueña del web ID que firmó la petición.
    - [Obtener los campos de un template](https://devs.firmame.com/docs/api/templates/get-template-fields): Devuelve los campos que espera una plantilla, para que armes el payload de `POST /developers/json` sin adivinar los nombres de los placeholders.
    - [Dar de alta un template](https://devs.firmame.com/docs/api/templates/save-template): Registra una plantilla en tu cuenta, o la reemplaza si ya existe una con el mismo nombre.
    - [Dar de alta un template PDF desde bytes](https://devs.firmame.com/docs/api/templates/save-template-bytes): Igual que `POST /developers/template/save`, pero el cuerpo es el PDF crudo en vez de JSON — útil cuando el archivo es lo bastante grande como para que pese el sobrecosto de Base64.