@firma-dev/sdk

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

const response = await firma.templates.getTemplate({
    id: "id"
});
console.log(response);

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.firma.dev/functions/v1/signing-request-api/templates/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "created_date": "2023-11-07T05:31:56Z",
  "seal_participants": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "order": 2,
      "seal": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "lineage_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "version": 123,
        "display_name": "<string>"
      },
      "status": "pending",
      "applied_at": "2023-11-07T05:31:56Z",
      "paused_at": "2023-11-07T05:31:56Z",
      "pause_reason": "seal_revoked_stop_pending",
      "swapped_from_seal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "triggered_by_recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sender_kind": "dashboard",
      "seal_out_of_scope": true
    }
  ],
  "description": "<string>",
  "document_url": "<string>",
  "document_url_expires_at": "2023-11-07T05:31:56Z",
  "page_count": 2,
  "expiration_hours": 168,
  "credit_cost": 1,
  "settings": {
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "allow_editing_before_sending": false,
    "use_signing_order": true,
    "hand_drawn_only": false,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "require_otp_verification": null,
    "disable_guided_navigation": true,
    "allow_presigning_download": true,
    "show_qr_code": true,
    "identity_editable_fields": [
      "<string>"
    ],
    "notify_identity_change_email": false
  },
  "recipients": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "jsmith@example.com",
      "first_name": "<string>",
      "designation": "Signer",
      "order": 2,
      "name": "<string>",
      "last_name": "<string>",
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "required_fields": [
        "<string>"
      ],
      "missing_fields": [
        "<string>"
      ],
      "required_read_only_fields": [
        {
          "variable_name": "<string>",
          "variable_defined_name": "<string>",
          "field_type": "<string>"
        }
      ],
      "ready_to_send": true
    }
  ],
  "fields": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "text",
      "page_number": 2,
      "required": true,
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variable_name": "<string>",
      "variable_defined_name": "<string>",
      "position": {
        "x": 50,
        "y": 50,
        "width": 50,
        "height": 50
      },
      "dropdown_options": [
        "<string>"
      ],
      "multi_group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "date_default": "2023-12-25",
      "date_signing_default": true,
      "format_rules": {
        "dateFormat": "MMMM dd, yyyy"
      },
      "validation_rules": {},
      "read_only": false,
      "read_only_value": "<string>"
    }
  ],
  "updated_date": "2023-11-07T05:31:56Z",
  "documents": [
    {
      "document_id": null,
      "position": 1,
      "label": null,
      "original_filename": null,
      "page_count": 3,
      "document_url": "https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example",
      "document_url_kind": "stored",
      "document_only_hash": null
    }
  ],
  "documents_version": 123,
  "documents_layout_version": 123
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Not Found",
  "message": "The requested resource was not found"
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

Modèles

Récupérer un Modèle

Récupère un modèle spécifique par ID. La réponse contient seal_participants : les participants de cachet du modèle dans l’ordre, limités à ceux dont le cachet appartient à l’entreprise de la clé API. Un participant de cachet dont le cachet est manquant ou appartient à une autre entreprise est omis, de sorte qu’une liste vide ou plus courte ne prouve pas que le modèle n’a pas d’autre participant de cachet enregistré.

GET

templates

{id}

@firma-dev/sdk

import { FirmaClient } from "@firma-dev/sdk";

const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

const response = await firma.templates.getTemplate({
    id: "id"
});
console.log(response);

import requests

url = "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.firma.dev/functions/v1/signing-request-api/templates/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firma.dev/functions/v1/signing-request-api/templates/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.firma.dev/functions/v1/signing-request-api/templates/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "created_date": "2023-11-07T05:31:56Z",
  "seal_participants": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "order": 2,
      "seal": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "lineage_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "version": 123,
        "display_name": "<string>"
      },
      "status": "pending",
      "applied_at": "2023-11-07T05:31:56Z",
      "paused_at": "2023-11-07T05:31:56Z",
      "pause_reason": "seal_revoked_stop_pending",
      "swapped_from_seal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "triggered_by_recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sender_kind": "dashboard",
      "seal_out_of_scope": true
    }
  ],
  "description": "<string>",
  "document_url": "<string>",
  "document_url_expires_at": "2023-11-07T05:31:56Z",
  "page_count": 2,
  "expiration_hours": 168,
  "credit_cost": 1,
  "settings": {
    "allow_download": true,
    "attach_pdf_on_finish": true,
    "allow_editing_before_sending": false,
    "use_signing_order": true,
    "hand_drawn_only": false,
    "send_signing_email": true,
    "send_finish_email": true,
    "send_expiration_email": true,
    "send_cancellation_email": true,
    "require_otp_verification": null,
    "disable_guided_navigation": true,
    "allow_presigning_download": true,
    "show_qr_code": true,
    "identity_editable_fields": [
      "<string>"
    ],
    "notify_identity_change_email": false
  },
  "recipients": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "jsmith@example.com",
      "first_name": "<string>",
      "designation": "Signer",
      "order": 2,
      "name": "<string>",
      "last_name": "<string>",
      "phone_number": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state_province": "<string>",
      "postal_code": "<string>",
      "country": "<string>",
      "title": "<string>",
      "company": "<string>",
      "required_fields": [
        "<string>"
      ],
      "missing_fields": [
        "<string>"
      ],
      "required_read_only_fields": [
        {
          "variable_name": "<string>",
          "variable_defined_name": "<string>",
          "field_type": "<string>"
        }
      ],
      "ready_to_send": true
    }
  ],
  "fields": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "text",
      "page_number": 2,
      "required": true,
      "recipient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variable_name": "<string>",
      "variable_defined_name": "<string>",
      "position": {
        "x": 50,
        "y": 50,
        "width": 50,
        "height": 50
      },
      "dropdown_options": [
        "<string>"
      ],
      "multi_group_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "date_default": "2023-12-25",
      "date_signing_default": true,
      "format_rules": {
        "dateFormat": "MMMM dd, yyyy"
      },
      "validation_rules": {},
      "read_only": false,
      "read_only_value": "<string>"
    }
  ],
  "updated_date": "2023-11-07T05:31:56Z",
  "documents": [
    {
      "document_id": null,
      "position": 1,
      "label": null,
      "original_filename": null,
      "page_count": 3,
      "document_url": "https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example",
      "document_url_kind": "stored",
      "document_only_hash": null
    }
  ],
  "documents_version": 123,
  "documents_layout_version": 123
}

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Not Found",
  "message": "The requested resource was not found"
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please wait before retrying.",
  "details": {
    "retry_after": 45
  }
}

Autorisations

Authorization

string

header

requis

Clé API pour l'authentification. Utilisez votre clé API directement sans préfixe (par exemple, 'your-api-key'). Le préfixe Bearer est optionnel mais pas obligatoire.

Paramètres de chemin

string<uuid>

requis

Réponse

Modèle récupéré avec succès

Un modèle avec ses participants de cachet : toutes les clés de Template, plus seal_participants. seal_participants ne liste que les participants de cachet dont le cachet appartient à l'entreprise de la clé API : un participant de cachet dont le cachet est manquant ou appartient à une autre entreprise est omis, de sorte qu'une liste vide ou plus courte ne prouve pas que le modèle n'a pas d'autre participant de cachet enregistré.

string<uuid>

requis

Identifiant unique du modèle

name

string

requis

Nom du modèle

Maximum string length: 255

created_date

string<date-time>

requis

Timestamp de création du modèle

seal_participants

object[]

requis

Les participants de cachet du modèle dans l'ordre, limités à ceux dont le cachet appartient à l'entreprise de la clé API. Un participant de cachet dont le cachet est manquant ou appartient à une autre entreprise est omis, de sorte qu'une liste vide ou plus courte ne prouve pas que le modèle n'a pas d'autre participant de cachet enregistré.

Show child attributes

description

string | null

Description du modèle

document_url

string<uri>

URL pré-signée vers le document PDF. Il s'agit d'une URL signée à durée limitée pour un accès sécurisé, voir document_url_expires_at pour la date d'expiration. Les URL initiales sont valables 7 jours ; les URL rafraîchies sont valables 1 heure. Demandez une nouvelle récupération du modèle pour obtenir une URL fraîche si elle a expiré.

document_url_expires_at

string<date-time> | null

Timestamp ISO 8601 auquel document_url expirera. Après cette heure, l'URL retournera une erreur d'accès refusé. Récupérez à nouveau le modèle pour recevoir une nouvelle URL signée.

page_count

integer

Nombre de pages dans le document

Plage requise: x >= 1

expiration_hours

integer

défaut:168

Nombre d'heures avant l'expiration des demandes de signature créées à partir de ce modèle

Plage requise: x >= 1

credit_cost

integer

défaut:1

Nombre de crédits consommés lorsqu'une demande de signature est envoyée à partir de ce modèle. La valeur minimale est 1.

Plage requise: x >= 1

settings

object

Paramètres renvoyés par les endpoints de liste et de détail des demandes de signature. Les modèles utilisent le schéma TemplateSettings (sans champs d'identité).

Show child attributes

recipients

object[]

Destinataires du modèle (inclus dans la récupération d'un seul modèle)

Show child attributes

fields

object[]

Champs du modèle (inclus dans la récupération d'un seul modèle)

Show child attributes

updated_date

string<date-time>

Timestamp de dernière mise à jour du modèle

documents

object[]

Les documents du modèle dans l'ordre des positions (multi-documents ; présent uniquement pour les entreprises activées). Sur GET /templates (la liste) : une entrée de liste ne contient pas de document_url. Un élément dont l'ensemble de documents n'a jamais été modifié apparaît ici avec documents: [], tandis que son GET individuel renvoie son unique document (avec document_id null). Sur GET /templates/{id}, PUT /templates/{id} et POST /templates : un élément dont l'ensemble de documents n'a jamais été modifié renvoie son unique document, avec document_id null.

Show child attributes

documents_version

integer

Version de l'ensemble de documents, incrémentée à chaque modification de document (multi-documents ; entreprises activées uniquement).

documents_layout_version

integer

Version de la mise en page des documents, incrémentée lorsque des documents sont ajoutés, supprimés ou réordonnés (multi-documents ; entreprises activées uniquement). Les écritures de champs sur une demande de signature comportant plus d'un document la renvoient sous la forme documents_layout_version.