API for programs
This page explains how a program can upload a PDF, send it for signing, follow its status and download the result and its evidence. Everything here exists in the service today; what does not exist is listed under Not available today.
Authentication
Every call carries the Authorization header with the word Bearer and your API key. Without the header, or with a key that does not exist, the answer is 401.
Authorization: Bearer $FIRMA_API_KEY
In the examples the key is kept in the environment variable FIRMA_API_KEY. Do not paste it into code or share it.
Your account keys are created, revoked and rotated on the API keys page. Go to my API keys
If the account plan does not include API access, the answer is 403.
MCP management permission is selected when creating a new key. It does not restrict REST API access: an API key can still use its routes. Do not share a key with an assistant if you require read-only access across all channels.
Operations
Each operation is shown with its HTTP method and its path. Parts in braces are identifiers returned by the service itself.
- Upload a PDF:
POST /firma/documentos - Send for signing:
POST /firma/solicitudes - Check the status of a request:
GET /firma/solicitudes/{request_id}/estado - See the requests of a document:
GET /firma/documentos/{document_id}/solicitudes - Download the signed PDF:
GET /firma/documentos/{document_id}/signed-pdf - Read the evidence summary:
GET /firma/documentos/{document_id}/resumen-evidencias - Download the evidence package (ZIP):
GET /firma/documentos/{document_id}/paquete-evidencias - Delete a document:
DELETE /firma/documentos/{document_id} - Register an automatic notice (webhook):
POST /firma/webhooks - List the automatic notices:
GET /firma/webhooks - Remove an automatic notice:
DELETE /firma/webhooks/{webhook_id} - Send a test notice:
POST /firma/webhooks/{webhook_id}/test - See the notice delivery log:
GET /firma/webhooks/deliveries
curl examples
Words in capitals, such as DOCUMENT_ID or REQUEST_ID, are replaced with the real values returned by the service.
Upload a PDF
curl -X POST "https://ambarmark.com/firma/documentos" -H "Authorization: Bearer $FIRMA_API_KEY" \
-F "file=@contrato.pdf;type=application/pdf" -F "tenant=TENANT" -F "uploaded_by=ann@example.org" -F "lang=es"
In the upload, tenant is the identifier of the space your key belongs to and uploaded_by is the email of the person uploading the document. If tenant does not match the key, the answer is 403.
Send for signing
curl -X POST "https://ambarmark.com/firma/solicitudes" -H "Authorization: Bearer $FIRMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"document_id": "DOCUMENT_ID", "signee_email": "ann@example.org", "signee_name": "Ann Example", "lang": "es"}'
Important: when a request is created, the invitation email goes out at that moment and the request counts towards your plan usage. There is no review step in between.
The answer includes request_id, signing_url, status and email_sent. If email_sent is false, the email could not be sent and you can pass the link on another way.
Check the status of a request
curl "https://ambarmark.com/firma/solicitudes/REQUEST_ID/estado" -H "Authorization: Bearer $FIRMA_API_KEY"
See the requests of a document
curl "https://ambarmark.com/firma/documentos/DOCUMENT_ID/solicitudes" -H "Authorization: Bearer $FIRMA_API_KEY"
Download the signed PDF
curl -o firmado.pdf "https://ambarmark.com/firma/documentos/DOCUMENT_ID/signed-pdf" -H "Authorization: Bearer $FIRMA_API_KEY"
Read the evidence summary
curl "https://ambarmark.com/firma/documentos/DOCUMENT_ID/resumen-evidencias?formato=texto" -H "Authorization: Bearer $FIRMA_API_KEY"
Register an automatic notice (webhook)
curl -X POST "https://ambarmark.com/firma/webhooks" -H "Authorization: Bearer $FIRMA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.org/avisos", "secret": "WEBHOOK_SECRET", "events": ["all_signed"]}'
Send a test notice
curl -X POST "https://ambarmark.com/firma/webhooks/WEBHOOK_ID/test" -H "Authorization: Bearer $FIRMA_API_KEY"
Request statuses
The status field of the status check takes one of these values:
- pending: created, no invitation sent yet.
- email_sent: the invitation has been sent by email.
- otp_sent: the person has been sent their one-time code.
- signed: signed.
- cancelled: cancelled; it can no longer be signed.
- rejected: the person declined to sign.
- expired: the link has expired. Today a link lasts 7 days.
Evidence summary
Once everyone has signed, the evidence summary is read with the same key as the signed PDF. With no other parameter it returns an HTML page; with formato=texto it returns plain text. If the document is not fully signed, the answer is 409.
The evidence package is a ZIP with the signed PDF, the report, the history and their SHA-256 fingerprints.
Automatic notices (webhooks)
A webhook is a notice AmbarMark sends to a server of yours when something happens. It is registered with an account key; in a team space, only whoever manages the space can do it.
When registering it you send the address, which must start with https and point to a public address, a secret of at least 16 characters and the list of events.
Events that are sent
- all_signed: everyone on the document has signed.
- document_signed: one person has signed.
- signing_expired: the signing link has expired.
- signing_rejected: one person declined to sign.
Each notice is a POST with a JSON body with these fields: event, tenant, timestamp, document (id, filename, sha256) and signing_request (id, signee_email, signee_name, signed_at, status). In the signing events, if the request carried a quote or confirmation, its data is added.
The document.sha256 field is the fingerprint of the original PDF that was uploaded, not of the signed PDF.
Headers of each notice: X-Firma-Signature carries the hexadecimal HMAC-SHA256 signature of the exact body, made with your secret; X-Firma-Event carries the event name; X-Firma-Delivery carries a unique delivery identifier.
If your server does not answer, the connection fails or it answers with a 5xx error, it is retried up to 3 attempts in total, waiting 4 to the power of the retry number minus one, in seconds. A 4xx answer is not retried. Redirects are not followed and count as not delivered. Each attempt waits at most 5.0 seconds.
Allowed destination ports: 443 (HTTPS).
The test notice makes a single attempt with a sample event that carries "test": true. 5 tests are allowed every 60 seconds; above that the answer is 429 with the Retry-After header.
The delivery log can be filtered by status and by webhook, returns 50 deliveries per page and keeps those of the last 30 days.
Check that the notice comes from AmbarMark
Compute the signature over the bytes received, without reformatting the JSON, and compare it with the X-Firma-Signature header. An example in Python:
import hashlib, hmac
def signature_ok(body: bytes, header_value: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header_value)
Errors
Errors come as JSON with a detail field giving the reason. Some detail texts are only in Spanish.
- 400: the file is not a valid PDF, is over the maximum upload size, or a required field is missing.
- 401: the Authorization header is missing or the key is not valid.
- 403: the plan does not include API, the key cannot use that space, or in a team you do not manage that resource.
- 404: the document, request or webhook does not exist or is not in your account.
- 409: you asked for the evidence of a document that is not fully signed yet.
- 413: the request body is over the allowed maximum.
- 422: the data sent does not have the expected format, or the webhook address is not safe.
- 429: you reached the daily maximum of invitations or of test notices.
- 503: the service cannot check keys at that moment, or the PDF tools are busy; in that case the Retry-After header is sent.
Limits
These are the values this service runs with today.
- PDF to sign: up to 10 MB.
- Request body: up to 64 MB.
- Signing invitations per account per day: 50. Accounts without a paid plan: 5.
- Signing link validity: 7 days.
- PDF tools: files up to 50 MB and 2 jobs at a time.
PDF tools by API
Besides signing, there are operations to work with PDF files. All are POST with the same key:
POST /firma/tools/compressPOST /firma/tools/extract-pagesPOST /firma/tools/flattenPOST /firma/tools/images-to-pdfPOST /firma/tools/infoPOST /firma/tools/mergePOST /firma/tools/metadataPOST /firma/tools/ocrPOST /firma/tools/office-to-pdfPOST /firma/tools/page-numbersPOST /firma/tools/pdf-to-imagesPOST /firma/tools/protectPOST /firma/tools/redactPOST /firma/tools/rotatePOST /firma/tools/splitPOST /firma/tools/to-pdfaPOST /firma/tools/unprotectPOST /firma/tools/watermark
MCP server (AI assistants)
An AI assistant can connect over MCP at /firma/mcp (POST) with the same API key in the Authorization: Bearer header. Every answer is scoped to the account space of the key. There is a limit of 120 calls per minute per space.
Available tools:
listar_modelos_documento: available document models with required fields, always reviewed by the customer.resumen_cuenta: overview: completed, pending, rejected or expired documents, frequent signers and templates.listar_documentos: lists the documents of the space, with a state filter (including rejected and expired), search by name or reference, by signer, and paging.estado_documento: detail of one document and the state of every signer, with the plain-language summary they saw.listar_firmantes_habituales: the frequent signers address book, searchable by name or email.listar_plantillas_firma: saved signing templates, with their signers, message and summary.subir_documento: prepares a base64 PDF with title and reference.crear_desde_modelo: prepares a model with its fields; requires modelo_revisado=true.enviar_documento: prepares signers (nombre/correo), message, summary, language and order; accepts a saved plantilla_id.enviar_masivo: prepares nombre,correo CSV with one copy per person, within plan caps and quota.recordar_firma: prepares a reminder within product cooldown, state and daily limits.reenviar_invitacion: prepares resend to the same address with the same controls as a reminder.cancelar_documento: prepares cancellation of open requests; does not delete documents or existing signatures.duplicar_documento: prepares a draft copy of the original without signatures or previous links.actualizar_referencia: prepares a change to the customer reference.editar_firmante: prepares editing an address-book contact; does not change already sent requests.guardar_firmante: prepares adding an address-book contact.guardar_plantilla_firma: prepares a signing template with recipients and content within the plan limit.estado_operacion: checks the result without executing changes; never retry partial sends automatically.
Existing keys keep read-only MCP access. To manage, create a new key with MCP management enabled. Each tool prepares a private proposal for 10 minutes. Open revision_url in your account, review the PDF, recipients, content and plan usage, then confirm with your session (and password when required). Only that page executes the change once. Use estado_operacion to check progress. There is no document deletion or signing for other people. Proposals are lost on service restart; results are available only during those 10 minutes.
Not available today
- Test environment: there is none. Any key works with real data, sends real emails and counts towards plan usage. To try it out, use email addresses of your own.
- MCP requires human web review for each change. REST API sends still execute directly without that review.
- Notices for document sent, document opened or upcoming deletion: they do not exist.