JSON array with the signers' data. Use this parameter when you are only going to send ONE contract. To send several contracts in a single request, use ENVIOS instead (see below).

Each element of the array must contain:
Nombre : (Required if VERIFICACIONIDENTIDAD=NO) Signer's first and last name.
NIF : (Required if VERIFICACIONIDENTIDAD=NO) Signer's NIF/DNI.
Email : (Optional but required if Telefono is not included) Signer's email.
Telefono : (Optional but required if Email is not included) Signer's mobile with international prefix without '+', e.g. '34600000001'.
Orden : (Optional) Signing order when there are several signers. The signer with the lowest Orden signs first.

If VERIFICACIONIDENTIDAD=SI, the Nombre and NIF fields are filled in automatically with the data verified during the identification process, so they can be omitted.

Example with two signers:

                      {"FIRMANTES": [
                          {
                            "Nombre":   "Pedro Aicart",
                            "NIF":      "00000000T",
                            "Email":    "pedro@dominio.com",
                            "Telefono": "34600000002",
                            "Orden":    1
                          },
                          {
                            "Nombre":   "Ana Aguado",
                            "NIF":      "00000001E",
                            "Telefono": "34600000001",
                            "Orden":    2
                          }
                        ]}

NEW in v4. JSON array to create multiple independent contracts in a single request. Each object in the array generates a contract.

Use this parameter instead of FIRMANTES + PERSONALIZACION when you need to send the same document to several people with different personalized variables. If you send ENVIOS, the root-level FIRMANTES and PERSONALIZACION fields are ignored.

Each object in the array must contain:
Firmantes : (Required) Array of signers for this contract (same structure as the root-level FIRMANTES parameter).
Variables : (Optional) Object with key/value pairs of replaceable variables in templates and messages for this specific contract. The keys are normalized to lowercase and accessed in templates as {{nombrevariable}}.

Example: two contracts with different variables

                      {"ENVIOS": [
                          {
                            "Firmantes": [
                              { "Nombre":"Juan García", "NIF":"11111111H", "Telefono":"34611111111", "Email":"juan@a.com", "Orden":1 }
                            ],
                            "Variables": { "importe":"100€", "plazo":"30 días" }
                          },
                          {
                            "Firmantes": [
                              { "Nombre":"Ana Pérez", "NIF":"22222222J", "Telefono":"34622222222", "Email":"ana@a.com", "Orden":1 }
                            ],
                            "Variables": { "importe":"250€", "plazo":"60 días" }
                          }
                        ]}

The response when using ENVIOS contains a Contratos array with one object per contract created (with ContratoId, ReportID, Firmantes, Documentos).

Identifier of a workflow previously saved in your panel. It has predefined documents, templates, signature type, etc. and you just need to define the signers in the request.

The request variables prevail over those of the workflow (e.g. if the workflow has TIPOFIRMA=ACEPTACION and the request sends TIPOFIRMA=BIOMETRICA, BIOMETRICA is used). Exception: DOCUMENTOS and FIRMASEMISOR are cumulative (those of the workflow are added to those of the request).

JSON array with the sender signatures (yours) saved in your account that you want to stamp on the signed documents. The system adds your signature and certificates to the document at the end of the process, completing the legal document. The boxes where they are stamped are defined with STAMPFIRMAEMISOR/STAMPFIRMASEMISOR in each PDF document.

Each element of the array must contain:
ID: Identifier of the handwritten or certified signature saved in your account. You can find it in the panel.

JSON array with the list of contract documents. Each element represents a PDF, a panel template or a checkbox.

Supported types (Tipo field):
  PLANTILLA : Template created in your panel. Requires Plantilla, Nombre, Aceptacion.
  PDF : PDF file in base64. Requires Contenido, Nombre, Aceptacion. Optionally StampFirmaEmisor/StampFirmaFirmante (legacy singular) or StampFirmasEmisor/StampFirmasFirmante (NEW v4 plural).
  CHECKBOX : Question to the signer (GDPR, etc.). Requires Texto, Inicial, Final.

Common fields:
Tipo : PLANTILLA | PDF | CHECKBOX (Required)
Nombre : Name visible to the signer (PLANTILLA and PDF).
TipoDoc : NEW v4. CONTRATO (default) or AUTORIZACION.
GrupoAut : NEW v4. 1, 2 or 3. Only valid if TipoDoc=AUTORIZACION; indicates in which sequential group this document must be reviewed before the contract.

Fields for PLANTILLA:
Plantilla : ID of the panel template. Format {idUsuario}-{idPlantilla}.
Aceptacion : SI (the signer must reach the end by scrolling) | NO (can sign without scrolling).

Fields for PDF:
Contenido : PDF content in base64.
Aceptacion : SI | NO (same as PLANTILLA).
StampFirmaEmisor : (Legacy singular) ONE box for the sender's signature. Format: pag,x,y,tamx,tamy,H|V. E.g. 1,80,580,220,110,H.
StampFirmaFirmante : (Legacy singular) ONE box for the signer's signature. Same format.
StampFirmasEmisor : NEW v4. Array of strings — up to 10 sender boxes with the same format as the singular.
StampFirmasFirmante : NEW v4. Array of strings — up to 10 signer boxes.

Box format pag,x,y,tamx,tamy,H|V:
  pag : page (1-based).
  x : X coordinate of the left edge (0 = left edge of the page).
  y : Y coordinate of the top edge (0 = top edge of the page).
  tamx : box width.
  tamy : box height.
  H | V : page orientation. V (vertical, default A4): max width 595, max height 841. H (horizontal A4): max width 841, max height 595.

Fields for CHECKBOX:
Texto : The question or phrase the signer will see. It supports HTML links <a href="https://...">texto</a> (only http/https); standalone URLs are also linked automatically. Links open in a window within the signing process, without the signer leaving it. E.g.: Acepto la <a href="https://tudominio.com/politica-de-privacidad">Política de privacidad</a>.
Inicial : OFF (unchecked on load) | ON (checked on load).
Final : OFF (must remain unchecked to sign) | ON (must remain checked) | LIBRE (the signer decides).

Example: 2 authorizations (Group 1 and Group 2) + contract with 2 signer boxes

                          {"DOCUMENTOS": [
                              {
                                "Tipo":     "PDF",
                                "Nombre":   "NDA Confidencialidad",
                                "Contenido":"JVBERi0xLj...",
                                "TipoDoc":  "AUTORIZACION",
                                "GrupoAut": 1
                              },
                              {
                                "Tipo":     "PDF",
                                "Nombre":   "Política de Privacidad RGPD",
                                "Contenido":"JVBERi0xLj...",
                                "TipoDoc":  "AUTORIZACION",
                                "GrupoAut": 2
                              },
                              {
                                "Tipo":       "PDF",
                                "Nombre":     "Contrato Principal",
                                "Contenido":  "JVBERi0xLj...",
                                "TipoDoc":    "CONTRATO",
                                "Aceptacion": "SI",
                                "StampFirmasFirmante": [
                                  "1,80,500,180,80,H",
                                  "2,80,500,180,80,H"
                                ],
                                "StampFirmasEmisor": [
                                  "1,320,500,180,80,H"
                                ]
                              }
                            ]}

JSON array with documents the signer must ATTACH when signing (e.g. ID copy, receipt, etc.). Each element defines a descriptive text and which signer it is requested from.

Each element must contain:
Texto : Description of the requested document (e.g. 'Attach a copy of your DNI, both sides').
Firmante : 0 = all signers; 1, 2, ... = the signer with that index (1-based).

Replaceable variables in templates and messages. It must be a JSON string with a flat object of key/value pairs. The keys are normalized to lowercase and accessed in templates as {{nombrevariable}} (or equivalents [nombrevariable], (nombrevariable), ###nombrevariable###).

If you use ENVIOS (multi-send), define the variables in Variables within each send instead of here.

Type of signature to apply. IMPORTANT: you must use the TEXT, not the number.

ACEPTACION : Signature by explicit acceptance (Accept/Reject button).
OTP : Signature with a one-time OTP code. If you do not send CANALESOTP, the OTP will go via SMS to the signer's mobile.
BIOMETRICA : Biometric handwritten signature (default).
CERTIFICADO : Signature with the signer's electronic certificate or electronic DNI.

NEW. Environment/template of the signing process that the signer sees.

CLASICO : The usual signing process, step by step in full screen (default).
UNIFICADO : Single mobile-style page with numbered steps: the signer reads and accepts each document (with a full-screen viewer and full-read control), checks the consent boxes and signs at the end. The links in the legal text and in the boxes open in a modal window without leaving the process. The page texts and the corporate color are customizable per sender (request it from support).

The UNIFICADO environment covers: TIPOFIRMA ACEPTACION, OTP or BIOMETRICA, PDF/PLANTILLA documents (including authorizations with groups) and CHECKBOX boxes. If the request uses TIPOFIRMA=CERTIFICADO, VERIFICACIONIDENTIDAD=SI or DOCUMENTOSSOLICITADOS, the CLASICO environment will be applied.

Sender identifier (3-11 alphanumeric characters). Used in legacy SMS and as a fallback if you do not specify REMITENTE in each SMS channel.

Legacy v3. SMS/Email text when MEDIOCOMUNICACION is used and CANALESFIRMA is NOT sent. Ignored if you use CANALESFIRMA (each channel carries its own message). Replaceable variables: [NOMBRE], [NIF], [LINK], [TIPODOCUMENTO].

Legacy v3. Single notification channel. Ignored if you send CANALESFIRMA; instead use CANALESFIRMA to define one or several channels.

SMS : Send via SMS to the signer's mobile.
EMAIL : Send via email (default domain).
SMSCERTIFICADO : SMS with delivery certification.

Document type (free text, max 50 chars). It is substituted in the [TIPODOCUMENTO] placeholder of legacy messages. Default: 'Contrato'.

SI activates the online identity verification before signing (video + ID). Option with extra cost. Requires your account to be validated by support. If SI, the Nombre and NIF fields of FIRMANTES are optional (they are filled in after verification).

Integrator's internal reference (max 200 chars). It is returned in the reports and allows associating the contract with your external system. Accepts letters, digits, spaces and the characters . - _ ,

SI leaves the contract accessible for future download after signing; NO blocks future access after certification. Default: SI.

SI allows reminders to alternate channels (SMS and Email) if the signer has both defined; NO always uses the same channel. In v4 with CANALESFIRMA, the rotation is automatic among all the channels in the array, regardless of this parameter.

Number of automatic reminders to send to the signer if they have not signed (1-10). Each reminder uses the next channel in the cascade (rotation).

Signing deadline date in format YYYY-MM-DD HH:mm. Minimum: today + 1 hour. Maximum: today + 45 days. Default: next month, same day. After this date the contract expires without signature (status 150).

Language of the interface the signer will see on the signing screen. es (Spanish, default) | pt (Portuguese) | en (English).

If there are CHECKBOXES in DOCUMENTOS, the minimum number of boxes the signer must check in order to sign. Between 0 and the total number of checkboxes.

If there are CHECKBOXES in DOCUMENTOS, the maximum number of boxes the signer can check. Must be ≥ MINIMOCHECK.

NEW v4. Informative message (max 1000 chars) shown to the signer in a popup window when reaching the first authorization document. Useful to explain to the signer what they are going to review before signing the contract. Ignored if there are no documents with TipoDoc=AUTORIZACION.

NEW v4. Activates the deep validation of the channels (CANALESFIRMA and CANALESOTP) before creating the contract. Possible values:
  NO (default, recommended in PRODUCTION): only the fast structural validation is done (types, IDs present, sender format). The system does NOT query external services.
  SI (recommended in PREPRODUCTION): in addition to the structural one, it validates each channel against external sources:
    • EMAIL: checks that the email template exists in the DB and that its HTML contains {{LINK}} (signature) or {{CODE}} (OTP).
    • RCS: verifies the RCS template in the DB and that it contains the required placeholder.
    • WHATSAPP: calls Meta/Facebook to confirm that the template is approved in your WABA account, that the URL button points to https://firma.ws/ (signature), or that the BODY literally contains {{CODE}} (OTP).

⚠️ IMPORTANT NOTICE:
1. This validation adds significant latency (especially WhatsApp due to the external call to Meta). In bulk sends it can translate into extra seconds per contract.
2. If you launch bulk sends with VALIDARCANALES=SI, the high volume of requests to third-party services could cause those services to temporarily block your connection (rate limiting). Therefore, when you confirm that the channel configuration is correct, go back to NO.
3. Use SI only during integration or preproduction testing to detect errors in the channel configuration (non-existent templates, no placeholders, not approved, etc.) before going to production.

🛡️ Protection rate limit: to prevent the accidental use of SI in production from bringing down your access to Meta/RCS, the API imposes a limit of 10 requests with VALIDARCANALES=SI per minute and per user. If you exceed it, the API returns Res=-29 with the fields Reintentar (seconds remaining until the counter resets) and Limite (requests allowed per minute). Your requests with VALIDARCANALES=NO do not count in this counter and continue to work normally.

If the deep validation detects a problem, the API responds with Res=-24 and an Error field describing exactly which channel and which problem it has.

Type of response to return as the result of the call.
JSON - The response will be returned in JSON
XML - The response will be returned in XML
TXT - The response will be returned in Text format

NEW in v4. JSON array with the ordered list of channels through which to send the signing request. The system will try the first one; if it fails, it will move to the next automatically (cascade). If you configure reminders, each one will use the next available channel (rotation).

If you do NOT include CANALESFIRMA, the system internally builds a single channel from the legacy parameters MEDIOCOMUNICACION, MENSAJE and REMITENTE (v3 compat). That is, it is not required to keep your current v3 integration.

Each element of the array must carry the TIPO field and the fields specific to that type:

SMS — fields:
  TIPO: "SMS"
  REMITENTE: (Optional) SMS sender identifier, max 11 alphanumeric chars (default: 'FIRMA').
  MENSAJE: (Required) SMS text. It must contain {{LINK}} (or [LINK]) which will be replaced by the signing link.

EMAIL — fields:
  TIPO: "EMAIL"
  DOMINIO: (Required) It has two modes:
    (A) Own domain — e.g. su-dominio.com. To use it, it is ESSENTIAL that this domain is registered and validated in the Transactional Email service of your panel (DNS + verification process). If the domain is not validated the send will fail with code -25. This option allows the recipient to receive the email from your brand and improves deliverability.
    (B) Default domain — literal token pordefecto. Uses the generic domain configured by the system. It does NOT require prior validation or configuration. Use it when you do not want/cannot validate your own domain.
  REMITENTE: (Required if DOMINIO is an own domain, e.g. su-dominio.com) Full email of the sender; the part after @ MUST match DOMINIO EXACTLY. E.g. if DOMINIO=su-dominio.com, REMITENTE must be algo@su-dominio.com. (Optional if DOMINIO=pordefecto: if you omit it, the system uses the default sender.)
  IDPLANTILLA: (Required if DOMINIO is an own domain) Numeric ID of the transactional email template created in the panel; it must contain {{LINK}}. (Optional with pordefecto: if you omit it, the system's default template is used with the body of MENSAJEEMAIL.)
  ASUNTOEMAIL: (Optional) Email subject.
  MENSAJEEMAIL: (Optional, recommended only if DOMINIO=pordefecto without a template) Free email body when not using a user template.

⚠ Important reminder about the Email domain: ALWAYS use the pordefecto token for the generic domain. Do NOT use other internal tokens — they are deprecated for new integrators and exist only for compatibility with old data. If you are going to send from your own domain (su-dominio.com), validate it first in your panel » Transactional Email » Domains.

RCS — fields:
  TIPO: "RCS"
  IDAGENTE: (Required) ID of the RCS agent configured in the panel.
  IDPLANTILLA: (Required) ID of the RCS template; it must contain {{LINK}}.
  REMITENTE: (Optional) Commercial name shown to the recipient.

WHATSAPP — fields:
  TIPO: "WHATSAPP"
  IDTELEFONO: (Required) WhatsApp Business Phone Number ID configured in the panel.
  IDPLANTILLA: (Required) Name/ID of the WhatsApp template approved in Meta. The template MUST include a URL button pointing to https://firma.ws/.
  VARSCUSTOM: (Optional) Object with custom variables that the WhatsApp template expects (e.g. image header, etc.).

Cascade example SMS → Email (validated own domain) → WhatsApp
Here su-dominio.com must be previously validated in your Transactional Email panel. If you do NOT have it validated and only want to send from the system's generic domain, replace the EMAIL block with the one in the following example (with pordefecto).

                      {"CANALESFIRMA": [
                          {
                            "TIPO":      "SMS",
                            "REMITENTE": "FIRMA",
                            "MENSAJE":   "Hello {{NOMBRE}}, sign here: {{LINK}}"
                          },
                          {
                            "TIPO":         "EMAIL",
                            "DOMINIO":      "su-dominio.com",
                            "REMITENTE":    "contratos@su-dominio.com",
                            "IDPLANTILLA":  12345,
                            "ASUNTOEMAIL":  "Signature request"
                          },
                          {
                            "TIPO":        "WHATSAPP",
                            "IDTELEFONO":  "123456789012345",
                            "IDPLANTILLA": "firma_contrato_es"
                          }
                        ]}

In the EMAIL block: DOMINIO is your own domain (it must be validated), the part after the @ of REMITENTE must match DOMINIO, and the template IDPLANTILLA (from the panel) must contain {{LINK}}.

Variant with default domain (system's generic domain, does not require DNS validation):

                          {
                            "TIPO":         "EMAIL",
                            "DOMINIO":      "__pordefecto__",
                            "ASUNTOEMAIL":  "Signature request",
                            "MENSAJEEMAIL": "Click here to sign: {{LINK}}"
                          }

NEW in v4. JSON array with the channels through which to send the OTP code (5-digit PIN) when TIPOFIRMA=OTP. The structure is identical to CANALESFIRMA: each element carries TIPO and the specific fields.

Key difference: in templates and messages use {{CODE}} instead of {{LINK}}. The email/RCS/WhatsApp template for OTP must contain {{CODE}}.

If TIPOFIRMA=OTP and you do NOT include CANALESOTP, the system automatically builds an SMS channel to the signer's mobile with the message 'Your verification code is: {{CODE}}'. This is the legacy v3 behavior (the OTP was always sent via SMS).

If you want the OTP to arrive via Email/RCS/WhatsApp instead of SMS, define CANALESOTP explicitly.

Example: OTP via SMS and Email (validated own domain) simultaneously
The EMAIL block uses su-dominio.com: that domain MUST be validated in your Transactional Email panel. If you do not have it validated, replace it with pordefecto (see variant below).

                      {"CANALESOTP": [
                          {
                            "TIPO":      "SMS",
                            "REMITENTE": "FIRMA",
                            "MENSAJE":   "Your OTP code is: {{CODE}}"
                          },
                          {
                            "TIPO":         "EMAIL",
                            "DOMINIO":      "su-dominio.com",
                            "REMITENTE":    "otp@su-dominio.com",
                            "IDPLANTILLA":  67890,
                            "ASUNTOEMAIL":  "Your OTP code"
                          }
                        ]}

In the EMAIL block: DOMINIO is your own domain (it must be validated), the part after the @ of REMITENTE must match DOMINIO, and the template IDPLANTILLA (from the panel) must contain {{CODE}}.

Variant with default domain (generic domain, without validation):

                          {
                            "TIPO":         "EMAIL",
                            "DOMINIO":      "__pordefecto__",
                            "ASUNTOEMAIL":  "Your OTP code",
                            "MENSAJEEMAIL": "Your code is {{CODE}}"
                          }

ContratoID returned in the send function.

ReportID returned in the send function.

ContratoID returned in the send function.

ReportID returned in the send function.

Type of document to download:
CERTIFICADO — Complete certified document with all events (always PDF).
FIRMANTE — Copy for signers (only the signed document with stamped signatures). PDF if the contract has no authorization groups; ZIP if it has them (with one PDF per group + the contract PDF).