{
  "info": {
    "name": "Spondaro API",
    "description": "Collection Postman de l'API Spondaro : engagements (signature + acompte + caution) et signatures électroniques. Droit de rétractation (particuliers) : champs customer_type, withdrawal_exemption et service_starts_at à la création ; événements de webhook engagement.withdrawn (rétractation reçue, acompte à rembourser) et engagement.deposit_refunded (acompte remboursé, total ou partiel). Prix : 0,6 % des montants encaissés, minimum 1,50 € HT par engagement payé ; signature seule 10 gratuites par mois puis 0,25 € HT ; la réponse d'un engagement contient le devis figé dans le champ pricing. Au plafond de 30 € dus, la création est refusée avec l'erreur 422 billing_required (clés live).",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.spondaro.com/v1"
    },
    {
      "key": "api_key",
      "value": "sk_test_REPLACE_ME"
    },
    {
      "key": "engagement_id",
      "value": "REPLACE_ME"
    }
  ],
  "item": [
    {
      "name": "Créer un engagement (particulier : droit de rétractation de 14 jours)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/engagements",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/devis.pdf\",\n  \"title\": \"Location sono – samedi 14\",\n  \"signers\": [\n    {\n      \"name\": \"Jean Dupont\",\n      \"email\": \"jean@example.com\",\n      \"role\": \"Client\"\n    }\n  ],\n  \"deposit_amount_cents\": 15000,\n  \"hold_amount_cents\": 80000,\n  \"hold_until\": \"2026-11-16T18:00:00Z\",\n  \"customer_type\": \"consumer\",\n  \"service_starts_at\": \"2026-11-14T09:00:00Z\",\n  \"protection\": \"standard\",\n  \"webhook_url\": \"https://monsaas.com/api/webhook-spondaro\"\n}"
        },
        "description": "customer_type vaut « consumer » par défaut : le client particulier dispose de 14 jours pour se rétracter, et la page de signature lui présente l'information et la case de demande expresse d'exécution anticipée. service_starts_at est le début de la prestation."
      }
    },
    {
      "name": "Créer un engagement (client professionnel : pas de rétractation)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/engagements",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/devis.pdf\",\n  \"title\": \"Location sono – samedi 14\",\n  \"signers\": [\n    {\n      \"name\": \"Jean Dupont\",\n      \"email\": \"jean@example.com\",\n      \"role\": \"Client\"\n    }\n  ],\n  \"deposit_amount_cents\": 15000,\n  \"hold_amount_cents\": 80000,\n  \"hold_until\": \"2026-11-16T18:00:00Z\",\n  \"customer_type\": \"business\",\n  \"protection\": \"standard\",\n  \"webhook_url\": \"https://monsaas.com/api/webhook-spondaro\"\n}"
        },
        "description": "Un client professionnel n'a pas de droit de rétractation. À qualifier par le professionnel, sous sa responsabilité."
      }
    },
    {
      "name": "Créer un engagement (particulier, exception déclarée au droit de rétractation)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/engagements",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/devis.pdf\",\n  \"title\": \"Location sono – samedi 14\",\n  \"signers\": [\n    {\n      \"name\": \"Jean Dupont\",\n      \"email\": \"jean@example.com\",\n      \"role\": \"Client\"\n    }\n  ],\n  \"deposit_amount_cents\": 15000,\n  \"hold_amount_cents\": 80000,\n  \"hold_until\": \"2026-11-16T18:00:00Z\",\n  \"customer_type\": \"consumer\",\n  \"service_starts_at\": \"2026-11-14T09:00:00Z\",\n  \"protection\": \"standard\",\n  \"webhook_url\": \"https://monsaas.com/api/webhook-spondaro\",\n  \"withdrawal_exemption\": \"dated_service\"\n}"
        },
        "description": "Exception déclarée par le professionnel, sous sa responsabilité : dated_service (loisirs ou prestation à date ou période déterminée, L221-28 12°) ou custom_made (bien ou prestation personnalisés, L221-28 3°). Interdit avec customer_type=business. Elle est reportée dans le dossier de preuve."
      }
    },
    {
      "name": "Lister les engagements",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/engagements?limit=20"
      }
    },
    {
      "name": "Détail d'un engagement",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/engagements/{{engagement_id}}",
        "description": "Le bloc « withdrawal » donne l'état du droit de rétractation (not_applicable, not_started, open, closed, withdrawn), l'échéance du délai, la date et le canal de la rétractation, et l'échéance de remboursement. Le remboursement de l'acompte et l'enregistrement d'une rétractation se font depuis le tableau de bord, jamais automatiquement."
      }
    },
    {
      "name": "Libérer la caution",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/engagements/{{engagement_id}}/hold/release"
      }
    },
    {
      "name": "Prélever sur la caution",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/engagements/{{engagement_id}}/hold/capture",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"amount_cents\": 12000,\n  \"reason\": \"Enceinte rendue avec la membrane percée\"\n}"
        }
      }
    },
    {
      "name": "Créer une demande de signature",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/signatures",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/contrat.pdf\",\n  \"title\": \"Contrat de Prestation\",\n  \"signers\": [\n    { \"name\": \"Jean Dupont\", \"email\": \"jean@example.com\", \"role\": \"Client\" }\n  ],\n  \"redirect_url\": \"https://monsaas.com/success\",\n  \"webhook_url\": \"https://monsaas.com/api/webhook-signature\"\n}"
        }
      }
    },
    {
      "name": "Créer une demande de signature avancée (AES, avec OTP)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/signatures",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/contrat.pdf\",\n  \"title\": \"Contrat de Prestation\",\n  \"signature_level\": \"advanced\",\n  \"signers\": [\n    { \"name\": \"Jean Dupont\", \"email\": \"jean@example.com\", \"role\": \"Client\", \"phone\": \"+33612345678\" }\n  ],\n  \"redirect_url\": \"https://monsaas.com/success\",\n  \"webhook_url\": \"https://monsaas.com/api/webhook-signature\"\n}"
        },
        "description": "`signature_level: \"advanced\"` (AES/eIDAS) exige que chaque signataire vérifie son identité par un code à usage unique avant de signer. Le code est envoyé par SMS si Twilio est configuré et qu'un `phone` est fourni, sinon automatiquement par email."
      }
    },
    {
      "name": "Envoyer en masse (bulk send)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/signatures/bulk",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"document_url\": \"https://example.com/cgu.pdf\",\n  \"title\": \"Conditions générales 2026\",\n  \"recipients\": [\n    { \"name\": \"Jean Dupont\", \"email\": \"jean@example.com\" },\n    { \"name\": \"Alice Martin\", \"email\": \"alice@example.com\" }\n  ]\n}"
        }
      }
    },
    {
      "name": "Lister les demandes de signature",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/signatures?limit=20"
      }
    },
    {
      "name": "Détail d'une demande de signature",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/signatures/:id"
      }
    },
    {
      "name": "Annuler une demande de signature",
      "request": {
        "method": "DELETE",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/signatures/:id"
      }
    },
    {
      "name": "Créer un modèle réutilisable",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/templates",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"name\": \"Contrat de prestation standard\",\n  \"title\": \"Contrat de Prestation\",\n  \"document_url\": \"https://example.com/contrat-type.pdf\",\n  \"signer_roles\": [\n    { \"role\": \"Client\" },\n    { \"role\": \"Prestataire\" }\n  ]\n}"
        }
      }
    },
    {
      "name": "Lister les modèles",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/templates"
      }
    },
    {
      "name": "Instancier un modèle",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/templates/:id/signatures",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"signers\": [\n    { \"name\": \"Jean Dupont\", \"email\": \"jean@example.com\" },\n    { \"name\": \"Alice Martin\", \"email\": \"alice@example.com\" }\n  ]\n}"
        }
      }
    },
    {
      "name": "Révoquer un modèle",
      "request": {
        "method": "DELETE",
        "header": [
          {
            "key": "Authorization",
            "value": "Bearer {{api_key}}"
          }
        ],
        "url": "{{base_url}}/templates/:id"
      }
    }
  ]
}