Integre la firma electrónica en su stack

Inicio rápido

Tres pasos: cree una clave API desde los parámetros, codifique su PDF en base64, envíe. La respuesta contiene el `signUrl` que puede compartir directamente con el destinatario.

# 1. Upload the PDF (multipart) and capture the returned document id.
DOC_ID=$(curl -s -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contrat.pdf" | jq -r .id)

# 2. Create a DRAFT envelope referencing the uploaded document.
ENV_ID=$(curl -s -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"subject\": \"Contrat de prestation\",
    \"documentIds\": [\"$DOC_ID\"],
    \"recipients\": [
      { \"email\": \"client@example.com\", \"name\": \"Marie Dubois\", \"role\": \"SIGNER\" }
    ]
  }" | jq -r .id)

# 3. Dispatch the envelope — this sends the invitation email/SMS.
curl -X POST https://certyneo.com/api/v1/envelopes/$ENV_ID/send \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

// npm install @certyneo/sdk  (or call fetch directly)
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF (multipart).
const fd = new FormData();
fd.append("file", new Blob([pdfBuffer], { type: "application/pdf" }), "contrat.pdf");
const doc = await fetch("https://certyneo.com/api/v1/documents", {
  method: "POST", headers: auth, body: fd,
}).then((r) => r.json());

// 2. Create the DRAFT envelope.
const envelope = await fetch("https://certyneo.com/api/v1/envelopes", {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    subject: "Contrat de prestation",
    documentIds: [doc.id],
    recipients: [
      { email: "client@example.com", name: "Marie Dubois", role: "SIGNER" },
    ],
  }),
}).then((r) => r.json());

// 3. Dispatch — this triggers the invitation channel for every recipient.
await fetch(`https://certyneo.com/api/v1/envelopes/${envelope.id}/send`, {
  method: "POST", headers: auth,
});
console.log(envelope.id);

import os, requests

auth = {"Authorization": f"Bearer {os.environ['CERTYNEO_API_KEY']}"}

# 1. Upload the PDF (multipart).
with open("contrat.pdf", "rb") as f:
    doc = requests.post(
        "https://certyneo.com/api/v1/documents",
        headers=auth,
        files={"file": ("contrat.pdf", f, "application/pdf")},
    ).json()

# 2. Create the DRAFT envelope.
envelope = requests.post(
    "https://certyneo.com/api/v1/envelopes",
    headers={**auth, "Content-Type": "application/json"},
    json={
        "subject": "Contrat de prestation",
        "documentIds": [doc["id"]],
        "recipients": [
            {"email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER"},
        ],
    },
).json()

# 3. Dispatch — this triggers the invitation channel for every recipient.
requests.post(
    f"https://certyneo.com/api/v1/envelopes/{envelope['id']}/send",
    headers=auth,
)
print(envelope["id"])

Pruebe la API desde sus herramientas

La colección Postman y la ficha RapidAPI se generan desde la especificación OpenAPI que también documenta esta página. Los tres permanecen alineados con la API real, endpoint por endpoint, en lugar de divergir en el primer añadido.

Puntos finales disponibles

12 rutas que cubren el ciclo completo: sobres, documentos, webhooks, claves API. Todas las rutas aceptan un token bearer y devuelven JSON.

Plantillas de sobre

Una plantilla registra de una vez por todas el PDF, los roles y la ubicación de los campos de firma, luego se reutiliza en cada envío: pase su identificador en templateId en lugar de documentIds, y los campos posicionados se copian en el sobre creado.

• • Las plantillas se crean desde el panel de control (Plantillas → Nueva plantilla), donde deposita el documento y posiciona los campos con el ratón — este es el camino más simple. La API también permite crearlas mediante POST /api/v1/templates, proporcionando los documentos, los roles y los campos; tenga en cuenta que los campos se posicionan con coordenadas absolutas (página, x, y, ancho, alto), por lo que debe conocer la maquetación del PDF.
• • En una cuenta que aún no ha registrado ninguna plantilla, GET /api/v1/templates devuelve una lista vacía. Este es el comportamiento normal, no un defecto de autenticación.
• • La lista contiene solo las plantillas que pertenecen al usuario propietario de la clave API. Una plantilla creada por un colega no aparece, ni siquiera dentro de un espacio de trabajo compartido: genere la clave desde la cuenta que posee la plantilla.
• • templateId y documentIds se excluyen mutuamente: envíe uno u otro, nunca ambos ni ninguno.
• • Proporcione al menos tantos destinatarios SIGNER como roles de firmantes tenga la plantilla, de lo contrario la creación se rechaza con un 400. El campo signerCount devuelto por la lista indica el número esperado.
• • El nivel de firma de la plantilla se hereda por el sobre, a menos que la solicitud pase explícitamente signatureLevel.

# 1. Discover the templates saved on this account.
curl -s https://certyneo.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# {
#   "data": [
#     { "id": "cmdq7f4k80001s6y2h1xa9pl3", "name": "Contrat de prestation",
#       "signerCount": 2, "documentCount": 1, "signatureLevel": "SIMPLE" }
#   ],
#   "pagination": { "page": 1, "pageSize": 20, "total": 1, "pages": 1 }
# }
#
# An empty "data" array means no template exists on this account yet —
# create one from the dashboard, it is not an authentication problem.

# 2. Create the envelope FROM the template: no documentIds and no field
#    coordinates, both are carried by the template. Pass one SIGNER
#    recipient per signer role, in the template's role order.
curl -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "templateId": "cmdq7f4k80001s6y2h1xa9pl3",
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" },
      { "email": "legal@example.com", "name": "Paul Martin", "role": "SIGNER" }
    ]
  }'

# 3. The envelope is DRAFT at this point — POST /envelopes/{id}/send
#    dispatches it, exactly as in the quick-start above.

Envío del documento: dos formas aceptadas

POST /api/v1/documents acepta el archivo de dos formas, a su elección. Los mismos controles se aplican en ambos casos: tipos permitidos, límite de 50 Mo, verificación de firma binaria y análisis antivirus.

• • En multipart/form-data, con una parte denominada file. Esta es la forma clásica, la de curl -F y de la mayoría de las bibliotecas.
• • En cuerpo bruto: los bytes del archivo constituyen el cuerpo de la solicitud, y el encabezado Content-Type proporciona su tipo (application/pdf por ejemplo). Útil desde una herramienta que transmite el contenido tal cual, sin envolver la solicitud — esto es lo que hace el conector Power Automate.
• • En cuerpo bruto, el nombre del archivo no tiene lugar en el cuerpo: indíquelo a través del encabezado X-File-Name o el parámetro ?fileName=. Sin él, el documento se nombra según su tipo.
• • Un tipo no soportado responde 415 nombrando las dos formas aceptadas, y un cuerpo anunciado como multipart pero ilegible responde 400. Ninguno de los dos es un error de servidor.

# a. multipart/form-data — the classic shape.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contrat.pdf;type=application/pdf"

# b. raw body — the file bytes ARE the body, typed by Content-Type.
#    The filename has nowhere to live in the body, so pass it as a header
#    (or ?fileName=). Without it the document is named after its type.
curl -X POST https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/pdf" \
  -H "X-File-Name: contrat.pdf" \
  --data-binary "@contrat.pdf"

# Both return the same 201 with the document id to pass as documentIds.

Colocación de campos de firma

Sin plantilla, un sobre creado a partir de documentIds no tiene ningún campo preposicionado: el firmante recibe el documento sin ubicación para firmar. La matriz fields, transmitida en la misma llamada de creación, coloca cada campo al punto exacto — es el equivalente, en el lado de la API, de lo que una plantilla registra de una vez por todas.

• • Las coordenadas están en puntos PDF, origen en la esquina superior izquierda de la página y eje Y hacia abajo (una página A4 mide 595 × 842 puntos). x e y designan la esquina superior izquierda del campo, width y height su tamaño.
• • pageNumber comienza en 1, documentIndex comienza en 0. Un número de página más allá del documento no se rechaza en la creación: el campo se ignora en el momento de la firma y no aparece en ninguna parte — es lo primero que hay que verificar cuando falta un campo en la llamada.
• • recipientEmail debe corresponder a uno de los destinatarios de la misma llamada, sin distinción de mayúsculas y minúsculas. De lo contrario, la creación falla enumerando todas las líneas defectuosas, lo que evita corregirlas una por una.
• • fields y templateId se excluyen mutuamente: una plantilla ya lleva su propio diseño. Por lo tanto, la matriz fields solo se utiliza con documentIds.
• • Tipos aceptados: SIGNATURE, INITIALS, DATE_SIGNED, TEXT, CHECKBOX y RADIO_GROUP. required es verdadero por defecto; placeholder y dateFormat son opcionales, y options solo se retiene para RADIO_GROUP.
• • Un sobre acepta un máximo de 100 campos, 20 documentos y 50 destinatarios — los límites de su plan pudiendo ser inferiores.

# Ad-hoc envelope WITH pre-placed fields — no template involved.
# Coordinates are PDF points, origin TOP-LEFT of the page, +Y downwards
# (A4 = 595 x 842 pt). x / y are the field box's top-left corner.
#
# The last field is positioned by ANCHOR instead of by eye: the server
# locates "Signature du client" in the PDF and computes the spot. x / y
# stay required there — they are the fallback if the text is not found.
curl -X POST https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cmdq7f4k80001s6y2h1xa9pl3"],
    "recipients": [
      { "email": "client@example.com", "name": "Marie Dubois", "role": "SIGNER" }
    ],
    "fields": [
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "x": 90, "y": 640, "width": 180, "height": 44 },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "DATE_SIGNED",
        "x": 320, "y": 640, "width": 140, "height": 30,
        "dateFormat": "DD/MM/YYYY" },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "TEXT",
        "x": 90, "y": 700, "width": 200, "height": 30,
        "placeholder": "Fonction", "required": false },
      { "recipientEmail": "client@example.com", "documentIndex": 0,
        "pageNumber": 2, "fieldType": "SIGNATURE",
        "anchorText": "Signature du client", "anchorPlacement": "below",
        "anchorIndex": 0,
        "x": 90, "y": 640, "width": 180, "height": 44 }
    ]
  }'

# The envelope is DRAFT at this point — POST /envelopes/{id}/send
# dispatches it, exactly as in the quick-start above.

Autenticación

Cada llamada lleva una clave API en el encabezado Authorization. Las claves se generan desde Configuración → Claves API y solo se muestran una vez.

GET /api/v1/account/me HTTP/1.1Host: certyneo.com
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# 200 OK
{ "data": { "id": "usr_…", "email": "you@example.com", "plan": "BUSINESS", "environment": "live" } }

• • Formato: sk_live_… en producción, sk_test_… para la zona de pruebas. Encabezado: Authorization: Bearer <clé>.
• • Alcances: envelopes, documents, webhooks, seals — en lectura (:read) o escritura (:write). La escritura implica la lectura; el alcance * otorga todos los derechos.
• • Las claves sk_test_ crean recursos en el entorno de pruebas, excluidos de la cuota y la facturación.
• • Errores: 401 clave inválida, 403 alcance insuficiente, 429 límite de velocidad excedido, 402 cuota mensual alcanzada.

Forma de las respuestas

Un punto a conocer antes de escribir tu cliente: las colecciones se encapsulan en un objeto data, mientras que los recursos unitarios se devuelven planos. Leer response.data.data en un recurso unitario devuelve por lo tanto undefined.

// GET /api/v1/envelopes
// Collections are WRAPPED in a "data" array.
{
  "data": [
    { "id": "env_abc123", "subject": "Contrat", "status": "SENT" }
  ]
}

// GET /api/v1/envelopes/{id}
// Single resources are returned FLAT — no "data" envelope.
{
  "id": "env_abc123",
  "subject": "Contrat",
  "status": "COMPLETED",
  "recipients": [ /* … */ ]
}