Signer

This service executes the complete digital signature Flow and returns a response 202 Accepted immediately. The service processes the signing operation asynchronously asynchronously.

Implements Basic Electronic Signature (AdES - BES), providing a robust and reliable solution with significant advantages in regulatory compliance, security, interoperability, and ease of use.

Asynchronous callback

When the operation completes — whether successful or failed — the service sends a POST request to the URL specified in the parameter callbackUrl. If callbackHeadersare provided, they will be included in the callback request.

• Successful signature: Content-Type multipart/form-data. Returns the signed PDF document as an attachment.

• Failed signature: Content-Type application/json. Returns an error object with operationId and message of error.

Only image formats JPEG and PNG are supported for signature visualization. Other formats will result in an error.

Security recommendation: Always consume this API from your backend infrastructure instead of frontend applications. This approach protects sensitive data, prevents credential exposure, and ensures secure document handling throughout the signing process.

Endpoint

POST /signer

Headers

Name	Type	Required	Description
x-api-key	string	Yes	API Key for access authorization.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
document	string	Yes	PDF document to be digitally signed, encoded in format Base64 (RFC4648).
images	string[]	No	Array of signature visualization images to embed in the document. Each image must be encoded in Base64. Supported formats: JPEG, PNG.
image	string	No	Deprecated. Use the array images instead. Single image to embed as signature visualization, encoded in Base64.
page	integer	No	Target page number for placing the signature, zero-indexed. Default: 0 (first page).
position	string	No	Signature rectangle coordinates in pixels at 72 DPI: lower-left X, lower-left Y, upper-right X, upper-right Y. For A4 pages, valid ranges: X: 0-595, Y: 0-842. Format: x1,y1,x2,y2. Default: "135,210,480,300"
timezone	string	No	IANA time zone identifier for date/time formatting in signing metadata. Examples: America/Lima, Europe/Madrid, Asia/Tokyo. Default: "UTC"
signature	string[]	No	Custom text lines to display alongside the signature image. Supports dynamic placeholders: $(date)s is replaced with the current timestamp formatted according to dateFormat and timezone. Each array element represents one text line.
dateFormat	string	No	Date/time format string following the ISO 8601 standard with strftime directives. Supports %z for time zone offset. Example: %d/%m/%Y %H:%M:%S%z. Default: "%Y/%m/%d %H:%M:%S%z"
callbackUrl	string	Yes	Webhook URL to receive the signed document or the error notification. The service will send the results via POST to this endpoint asynchronously.
callbackHeaders	string	No	Optional HTTP headers to include in the callback request. Format: key=value pairs separated by semicolons. Example: Authorization=Bearer token;X-Custom=value

Request example

{
  "document": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...",
  "images": ["iVBORw0KGgoAAAANSUhEUgAAAEoAAABK..."],
  "page": 0,
  "position": "135,210,480,300",
  "timezone": "America/Lima",
  "signature": ["ID - 9999999", "Date - $(date)s"],
  "dateFormat": "%d/%m/%Y %H:%M:%S%z",
  "callbackUrl": "https://example.com/callback",
  "callbackHeaders": "Authorization=Bearer token123;Content-Type=application/json"
}

Responses

202 Accepted

The request was accepted and the signing operation is being processed asynchronously. The result will be sent to the provided callback URL.

Callback — Successful signature

Content-Type: multipart/form-data

The signed PDF document is returned as an attachment.

Callback — Failed signature

Content-Type: application/json

{
  "operationId": "910e181e-305c-4d9b-b42b-f177bf3b06ef",
  "error": "image: unknown format"
}

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}