curl --request POST \
  --url https://api.example.com/api/v1/integration/documents \
  --header 'Content-Type: multipart/form-data' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --form 'payload={
  "creator": {
    "email": "ana.lopez@cliente.example",
    "firstName": "Ana",
    "lastName": "López"
  },
  "document": {
    "signatureType": "SIMPLE",
    "isSequential": true,
    "isIndexable": true
  },
  "participants": [
    {
      "role": "SIGNER",
      "firstName": "Luis",
      "lastName": "Martínez",
      "email": "luis.martinez@correo.example",
      "order": 1,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.1,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "SIGNER",
      "firstName": "Marta",
      "lastName": "Gómez",
      "email": "marta.gomez@correo.example",
      "order": 2,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.55,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "WITNESS",
      "firstName": "Eva",
      "lastName": "Ruiz",
      "email": "eva.ruiz@correo.example"
    }
  ]
}' \
  --form file=@example-file

{
  "success": true,
  "message": "El documento ya se había creado con este Idempotency-Key",
  "data": {
    "id": "2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "status": "PENDING_SIGNATURE",
    "signatureType": "SIMPLE",
    "fileName": "contrato.pdf",
    "createdAt": "2026-10-26T12:00:00.000Z",
    "creator": {
      "email": "ana.lopez@cliente.example"
    },
    "participantsCount": 2,
    "publicUrl": "https://app.firmalo.com/public/documents/2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "participants": [
      {
        "email": "luis.martinez@correo.example",
        "status": "PENDING",
        "signatureType": "SIMPLE",
        "order": 1
      }
    ]
  }
}

Integration Documents

Crear un documento PDF con su flujo de firmas

Es multipart/form-data con dos campos: file (el PDF, binario) y payload (texto con un JSON con creator, document y participants; su estructura es IntegrationDocumentPayloadDto).

La organización sale de la API key. El creador se identifica por su correo: si es miembro de la organización se usa su cuenta; si existe sin membresía, se le crea una con el rol INTEGRATION_DOCUMENT_CREATOR; si no existe, se crea como usuario provisional (sin contraseña). Sus datos nunca se sobrescriben.

Cada documento creado consume un crédito de la organización. Los participantes se invitan por correo.

Orden de firma. document.isSequential decide si participants[].order es obligatorio:

`document.isSequential`	`SIGNER`	`WITNESS`
`true` o se omite	`order` obligatorio: firman uno a la vez	No requiere `order` ni participa en él
`false`	`order` no es obligatorio: firman en cualquier momento	No requiere `order` ni participa en él

En un documento secuencial, order es un entero que inicia en 1 y debe ser único y consecutivo entre firmantes (1, 2, 3…). Es este valor, no la posición en participants, lo que define el orden. Si no se cumple, la respuesta es 422 con INVALID_SIGNING_ORDER o DUPLICATE_SIGNING_ORDER.

Ejemplo de payload: flujo secuencial (dos firmantes y un testigo):

{
  "creator": {
    "email": "ana.lopez@cliente.example",
    "firstName": "Ana",
    "lastName": "López"
  },
  "document": {
    "signatureType": "SIMPLE",
    "isSequential": true,
    "isIndexable": true
  },
  "participants": [
    {
      "role": "SIGNER",
      "firstName": "Luis",
      "lastName": "Martínez",
      "email": "luis.martinez@correo.example",
      "order": 1,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.1,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "SIGNER",
      "firstName": "Marta",
      "lastName": "Gómez",
      "email": "marta.gomez@correo.example",
      "order": 2,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.55,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "WITNESS",
      "firstName": "Eva",
      "lastName": "Ruiz",
      "email": "eva.ruiz@correo.example"
    }
  ]
}

Ejemplo de payload: flujo no secuencial (sin order):

{
  "creator": {
    "email": "ana.lopez@cliente.example",
    "firstName": "Ana",
    "lastName": "López"
  },
  "document": {
    "signatureType": "SIMPLE",
    "isSequential": false,
    "isIndexable": true
  },
  "participants": [
    {
      "role": "SIGNER",
      "firstName": "Luis",
      "lastName": "Martínez",
      "email": "luis.martinez@correo.example",
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.1,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "SIGNER",
      "firstName": "Marta",
      "lastName": "Gómez",
      "email": "marta.gomez@correo.example",
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.55,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "WITNESS",
      "firstName": "Eva",
      "lastName": "Ruiz",
      "email": "eva.ruiz@correo.example"
    }
  ]
}

Ejemplo con curl:

curl -X POST https://<host>/api/v1/integration/documents \
  -H "X-API-Key: $FIRMALO_API_KEY" \
  -H "Idempotency-Key: erp-contrato-2026-000184" \
  -F "file=@contrato.pdf;type=application/pdf" \
  -F 'payload={"creator":{"email":"ana.lopez@cliente.example","firstName":"Ana","lastName":"López"},"document":{"signatureType":"SIMPLE","isSequential":true},"participants":[{"role":"SIGNER","firstName":"Luis","lastName":"Martínez","email":"luis.martinez@correo.example","order":1,"signaturePositions":[{"page":1,"xRatio":0.1,"yRatio":0.8,"widthRatio":0.25,"heightRatio":0.08}]}]}'

curl --request POST \
  --url https://api.example.com/api/v1/integration/documents \
  --header 'Content-Type: multipart/form-data' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --form 'payload={
  "creator": {
    "email": "ana.lopez@cliente.example",
    "firstName": "Ana",
    "lastName": "López"
  },
  "document": {
    "signatureType": "SIMPLE",
    "isSequential": true,
    "isIndexable": true
  },
  "participants": [
    {
      "role": "SIGNER",
      "firstName": "Luis",
      "lastName": "Martínez",
      "email": "luis.martinez@correo.example",
      "order": 1,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.1,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "SIGNER",
      "firstName": "Marta",
      "lastName": "Gómez",
      "email": "marta.gomez@correo.example",
      "order": 2,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.55,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "WITNESS",
      "firstName": "Eva",
      "lastName": "Ruiz",
      "email": "eva.ruiz@correo.example"
    }
  ]
}' \
  --form file=@example-file

{
  "success": true,
  "message": "El documento ya se había creado con este Idempotency-Key",
  "data": {
    "id": "2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "status": "PENDING_SIGNATURE",
    "signatureType": "SIMPLE",
    "fileName": "contrato.pdf",
    "createdAt": "2026-10-26T12:00:00.000Z",
    "creator": {
      "email": "ana.lopez@cliente.example"
    },
    "participantsCount": 2,
    "publicUrl": "https://app.firmalo.com/public/documents/2be3b9d7-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "participants": [
      {
        "email": "luis.martinez@correo.example",
        "status": "PENDING",
        "signatureType": "SIMPLE",
        "order": 1
      }
    ]
  }
}

Authorizations

X-API-Key

string

header

required

API key de tu organización, con formato fma_live_<publicId>_<secret>. Se emite (y se rota o revoca) desde Integraciones en Firmalo; el secreto completo sólo se muestra al emitirla.

Ejemplo (no es una llave real): fma_live_0123456789abcdef_EjemploNoRealEjemploNoRealEjemploNoReal1234

La organización y el contexto de acceso salen de la llave: no se usan JWT, X-Account-Id ni X-Organization-Id. Llama a la API sólo desde tu backend; nunca expongas la llave en un navegador o una app móvil.

Headers

Idempotency-Key

string

required

Valor único elegido por ti para este documento (1 a 255 caracteres ASCII visibles), por API key, durante 24 horas. Repetir la petición con la misma clave y el mismo contenido devuelve el documento original sin subir, crear, cobrar ni notificar nada.

Example:

"erp-contrato-2026-000184"

Body

multipart/form-data

payload

object

required

Campo de texto con un JSON con creator, document y participants.

Show child attributes

Example:

{
  "creator": {
    "email": "ana.lopez@cliente.example",
    "firstName": "Ana",
    "lastName": "López"
  },
  "document": {
    "signatureType": "SIMPLE",
    "isSequential": true,
    "isIndexable": true
  },
  "participants": [
    {
      "role": "SIGNER",
      "firstName": "Luis",
      "lastName": "Martínez",
      "email": "luis.martinez@correo.example",
      "order": 1,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.1,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "SIGNER",
      "firstName": "Marta",
      "lastName": "Gómez",
      "email": "marta.gomez@correo.example",
      "order": 2,
      "signaturePositions": [
        {
          "page": 1,
          "xRatio": 0.55,
          "yRatio": 0.8,
          "widthRatio": 0.25,
          "heightRatio": 0.08
        }
      ]
    },
    {
      "role": "WITNESS",
      "firstName": "Eva",
      "lastName": "Ruiz",
      "email": "eva.ruiz@correo.example"
    }
  ]
}

file

required

PDF del documento a firmar, como archivo binario.

Response

Repetición de una petición anterior con el mismo Idempotency-Key: el documento original (Idempotent-Replayed: true)

success

boolean

required

Indica si la operación fue exitosa

Example:

true

message

enum<string>

required

Mensaje descriptivo del resultado de la operación

Available options:

Operación realizada con éxito,

Recurso creado correctamente,

Recurso no encontrado,

Datos de entrada inválidos,

No autorizado para realizar esta acción,

El firmante no está asociado al recurso,

El recurso ya existe,

Error interno del servidor

Example:

"Operación realizada con éxito"

data

object

required

Datos de la respuesta

Show child attributes