Documentation API

1. Obtenir une clé API

Connectez-vous à votre compte administrateur et créez une clé API depuis les paramètres.

2. Faire votre première requête

Testez votre clé API en récupérant la liste de vos documents :

curl -X GET https://giga-signature.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

3. Créer votre premier document

Téléversez un PDF et ajoutez des signataires :

curl -X POST https://giga-signature.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Accept: application/json" \
  -F "file=@contrat.pdf" \
  -F "name=Mon premier document" \
  -F "signers[0][name]=Jean Dupont" \
  -F "signers[0][email]=jean.dupont@example.com"

Se connecter et obtenir une clé API

Authentifiez-vous avec vos identifiants pour recevoir une nouvelle clé API :

const response = await fetch('https://giga-signature.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    email: 'admin@example.com',
    password: 'secure-password',
    key_name: 'Production API Key'  // Optionnel
  })
});

const data = await response.json();
// Réponse:
{
  "success": true,
  "data": {
    "api_key": "sk_live_1234567890abcdef",
    "expires_at": "2025-12-31T23:59:59Z",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "admin@example.com"
    }
  }
}

Obtenir les informations de l'utilisateur actuel

const response = await fetch('https://giga-signature.com/api/v1/auth/me', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Accept': 'application/json'
  }
});

// Réponse avec détails complets de l'utilisateur et ses permissions

Rafraîchir la clé API

Générez une nouvelle clé API et révoquez automatiquement l'ancienne :

Se déconnecter

Révoque la clé API utilisée pour cette requête.

Lister les utilisateurs

Créer un utilisateur

const userData = {
  name: "Marie Dupont",
  email: "marie.dupont@example.com",
  role: "user",
  password: "SecurePass123!",     // Requis si send_invitation = false
  send_invitation: true           // Envoie un email d'invitation au lieu de définir le mot de passe
};

const response = await fetch('https://giga-signature.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(userData)
});

Mettre à jour un utilisateur

Modifiez les informations d'un utilisateur, son rôle ou réinitialisez son mot de passe.

Réinitialiser le mot de passe

Envoie un email de réinitialisation du mot de passe à l'utilisateur.

Créer un processus de signature

Créez un workflow complet avec plusieurs documents et signataires :

const processData = {
  name: "Contrat de partenariat 2025",
  expires_at: "2025-12-31T23:59:59Z",
  sequential_signing: false,  // Signature parallèle par défaut
  require_otp: true,
  otp_method: "choice",      // Le signataire choisit SMS ou Email
  documents: [
    { document_id: "doc_abc123", order: 1 },
    { document_id: "doc_def456", order: 2 }
  ],
  signers: [
    {
      name: "Jean Dupont",
      email: "jean.dupont@example.com",
      phone: "+33612345678",
      language: "fr",
      otp_method: "sms"  // Override pour ce signataire
    },
    {
      name: "Marie Martin",
      email: "marie.martin@example.com",
      language: "fr"
    }
  ]
};

const response = await fetch('https://giga-signature.com/api/v1/signature-processes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(processData)
});

Configurer les champs de signature

Définissez précisément où chaque signataire doit intervenir :

const fields = {
  fields: [
    {
      document_id: "doc_abc123",
      signature_id: "sig_123",  // Assigné à ce signataire
      type: "signature",
      label: "Signature Client",
      page: 3,
      position_x: 15,
      position_y: 70,
      width: 25,
      height: 10,
      required: true
    },
    {
      document_id: "doc_abc123",
      signature_id: null,      // Tous les signataires
      type: "date",
      label: "Date de signature",
      page: 3,
      position_x: 70,
      position_y: 85,
      width: 15,
      height: 5
    }
  ]
};

Envoyer aux signataires

Une fois les champs configurés, envoyez le processus aux signataires. Chacun recevra un email avec un lien unique pour signer.

Créer un document

Téléversez un PDF et définissez les signataires :

const formData = new FormData();
formData.append('file', pdfFile);
formData.append('name', 'Contrat de service 2025');
formData.append('signers[0][name]', 'Jean Dupont');
formData.append('signers[0][email]', 'jean.dupont@example.com');
formData.append('signers[1][name]', 'Marie Martin');
formData.append('signers[1][email]', 'marie.martin@example.com');

const response = await fetch('https://giga-signature.com/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Accept': 'application/json'
  },
  body: formData
});

const document = await response.json();
console.log('Document créé:', document.data.id);

Lister les documents

Récupérez vos documents avec pagination et filtres :

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total": 47,
    "per_page": 20
  }
}

Processus de signature

1. Le signataire reçoit un code OTP par email
2. Il dessine sa signature sur le document
3. Il valide avec le code OTP
4. La signature est apposée et certifiée

Apposer une signature via API

const signatureData = {
  signer_email: "jean.dupont@example.com",
  signature_data: "data:image/png;base64,iVBORw0KGgoAAAANS...", // Image base64
  otp_code: "123456", // Code reçu par email
  position: {
    page: 1,        // Numéro de page
    x: 100,         // Position X
    y: 650,         // Position Y
    width: 200,     // Largeur
    height: 50      // Hauteur
  }
};

const response = await fetch(`https://giga-signature.com/api/v1/documents/${documentId}/signatures`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(signatureData)
});

Créer un webhook

Configurez un nouvel endpoint pour recevoir des événements :

const webhookConfig = {
  url: "https://api.votreapp.com/webhooks/giga-signature",
  events: [
    "document.uploaded",
    "signature.completed",
    "signature.refused",
    "process.completed"
  ],
  description: "Webhook production pour les signatures",
  is_active: true
};

const response = await fetch('https://giga-signature.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(webhookConfig)
});

const webhook = await response.json();
console.log('Secret webhook:', webhook.data.secret); // Conservez ce secret!

Lister vos webhooks

Récupérez la liste de tous vos webhooks configurés avec leur statut et dernière activité.

Tester un webhook

Envoyez un événement de test pour vérifier que votre endpoint fonctionne :

// Teste le webhook avec un payload exemple
const response = await fetch(`https://giga-signature.com/api/v1/webhooks/${webhookId}/test`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE'
  }
});

// Réponse avec le code HTTP et le temps de réponse
{
  "success": true,
  "message": "Test webhook sent successfully",
  "data": {
    "status": "success",
    "response_code": 200,
    "response_time": 0.245  // en secondes
  }
}

Consulter les logs de livraison

Surveillez les tentatives de livraison et diagnostiquez les problèmes :

Gérer vos webhooks

Workflow complet de signature

Créer un document, envoyer aux signataires et suivre le statut :

// 1. Créer le document
const formData = new FormData();
formData.append('file', contractFile);
formData.append('name', 'Contrat Commercial Q4 2025');
formData.append('signers[0][name]', 'Directeur Commercial');
formData.append('signers[0][email]', 'direction@company.com');
formData.append('signers[1][name]', 'Client ACME');
formData.append('signers[1][email]', 'legal@acme.com');

const createResponse = await fetch('https://giga-signature.com/api/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Accept': 'application/json'
  },
  body: formData
});

const document = await createResponse.json();
console.log('Document créé:', document.data.id);

// 2. Les signataires reçoivent automatiquement un email
// avec un lien vers la page de signature

// 3. Vérifier le statut périodiquement
const checkStatus = async () => {
  const statusResponse = await fetch(`https://giga-signature.com/api/v1/documents/${document.data.id}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY_HERE',
      'Accept': 'application/json'
    }
  });
  
  const status = await statusResponse.json();
  console.log('Statut:', status.data.status);
  console.log('Signatures:', status.data.signers);
  
  if (status.data.status === 'completed') {
    // 4. Télécharger le document signé
    const downloadResponse = await fetch(
      `https://giga-signature.com/api/v1/documents/${document.data.id}/download/signed`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY_HERE'
        }
      }
    );
    
    const blob = await downloadResponse.blob();
    // Sauvegarder le fichier...
  }
};

// Vérifier toutes les 30 secondes
const interval = setInterval(checkStatus, 30000);

Intégration avec webhooks

Recevoir des notifications en temps réel sans polling :

// Endpoint webhook dans votre application (Node.js/Express)
app.post('/webhooks/giga-signature', (req, res) => {
  // Vérifier la signature
  const payload = JSON.stringify(req.body);
  const signature = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== req.headers['x-signature']) {
    return res.status(401).send('Signature invalide');
  }
  
  // Traiter l'événement
  const event = req.body;
  
  switch (event.event) {
    case 'document.uploaded':
      console.log('Nouveau document:', event.data.document.id);
      break;
      
    case 'signature.completed':
      console.log('Signature reçue:', event.data.signature);
      // Mettre à jour votre base de données
      updateSignatureStatus(
        event.data.document.id,
        event.data.signature.email,
        'signed'
      );
      break;
      
    case 'document.completed':
      console.log('Document complété:', event.data.document);
      // Envoyer une notification
      sendNotification('Document signé par toutes les parties');
      // Déclencher votre workflow métier
      processCompletedContract(event.data.document.id);
      break;
      
    case 'signature.refused':
      console.log('Signature refusée:', event.data.signature);
      // Alerter l'équipe commerciale
      alertSalesTeam(event.data.document, event.data.signature.refusal_reason);
      break;
  }
  
  res.status(200).send('OK');
});