API BizSign pour intégrateurs

#!/usr/bin/env bash
# Exemple de test : crée et active une demande réelle, avec un destinataire de test.
# Prérequis : bash, curl, jq, base64 ; un PDF et une application autorisée par l'offre.
set -euo pipefail
: "${BASE_URL:?Renseigner l’URL BizSign de votre environnement}"
: "${CLIENT_ID:?Renseigner le Client ID}"
: "${CLIENT_SECRET:?Renseigner le secret depuis votre gestionnaire de secrets}"
: "${TEST_SIGNER_EMAIL:?Renseigner une adresse de test sous votre contrôle}"
: "${TEST_SIGNER_PHONE:?Renseigner le mobile de test au format international}"
: "${PDF_PATH:?Renseigner le chemin d’un PDF de test}"
BASE_URL="${BASE_URL%/}"
export CLIENT_ID CLIENT_SECRET TEST_SIGNER_EMAIL TEST_SIGNER_PHONE

# Le secret passe dans le corps, sans interpolation dans une commande shell.
TOKEN=$(jq -nr '
  "grant_type=client_credentials&client_id=" + (env.CLIENT_ID|@uri)
  + "&client_secret=" + (env.CLIENT_SECRET|@uri)
  + "&scope=" + ("signature:read signature:write documents:read documents:write"|@uri)
' | curl --fail-with-body --silent --show-error \
  -H 'Content-Type: application/x-www-form-urlencoded' --data-binary @- \
  "$BASE_URL/api/compat/oauth/token" | jq -er '.access_token')
unset CLIENT_SECRET

api() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' "$@"
}
API_BASE="$BASE_URL/api/compat/yousign/v3"
REQUEST_ID=$(api -X POST "$API_BASE/signature_requests" \
  --data '{"name":"Test intégration BizSign","delivery_mode":"none"}' | jq -er '.id')
DOCUMENT_ID=$(base64 < "$PDF_PATH" | tr -d '\n' \
  | jq -Rs '{file:.,file_name:"test.pdf",nature:"signable_document"}' \
  | api -X POST "$API_BASE/signature_requests/$REQUEST_ID/documents" \
    --data-binary @- | jq -er '.id')
export DOCUMENT_ID
SIGNER_ID=$(jq -n '{
  info:{first_name:"Test",last_name:"Intégration",email:env.TEST_SIGNER_EMAIL,phone_number:env.TEST_SIGNER_PHONE},
  signature_level:"electronic_signature",
  signature_authentication_mode:"otp_sms",
  fields:[{document_id:env.DOCUMENT_ID,type:"signature",page:1,x:50,y:100,width:180,height:60}]
}' | api -X POST "$API_BASE/signature_requests/$REQUEST_ID/signers" \
  --data-binary @- | jq -er '.id')

# L’activation réserve les unités selon votre offre. Ce n’est pas une simulation.
api -X POST "$API_BASE/signature_requests/$REQUEST_ID/activate" > /dev/null
# Ouvrir signature_link dans un navigateur pour signer le PDF de test.
api "$API_BASE/signature_requests/$REQUEST_ID/signers/$SIGNER_ID" | jq '{status,signature_link}'
# Après signature : consulter l’état, puis télécharger le PDF.
api "$API_BASE/signature_requests/$REQUEST_ID" | jq '{id,status}'
# Quand status vaut done :
# api "$API_BASE/signature_requests/$REQUEST_ID/documents/$DOCUMENT_ID/download" -o signe.pdf

#!/usr/bin/env bash
# Recette du parcours client BizSign par l’API (#330) : jeton, demande à deux
# documents, participant, envoi explicite, signature dans le parcours réel,
# notifications, PDF finaux, preuves, confirmation Bitcoin, reprise.
# Prérequis : bash, curl, jq, base64, sha256sum ; deux PDF de test sans donnée
# personnelle ; une application autorisée par l’offre (scopes ci-dessous).
# Rien n’est simulé : l’envoi réserve les unités selon votre offre.
set -euo pipefail
: "${BASE_URL:?Renseigner l’URL BizSign de votre environnement}"
: "${CLIENT_ID:?Renseigner le Client ID}"
: "${CLIENT_SECRET:?Renseigner le secret depuis votre gestionnaire de secrets}"
: "${TEST_SIGNER_EMAIL:?Renseigner une adresse de test sous votre contrôle}"
: "${TEST_SIGNER_PHONE:?Renseigner le mobile de test au format international}"
: "${PDF_PATH:?Renseigner le chemin du premier PDF de test}"
: "${PDF2_PATH:?Renseigner le chemin du second PDF de test}"
WEBHOOK_URL="${WEBHOOK_URL:-}"          # facultatif : URL HTTPS de votre récepteur
POLL_SECONDS="${POLL_SECONDS:-30}"      # intervalle de relance de l’état
OUT_DIR="${OUT_DIR:-recette-$(date -u +%Y%m%dT%H%M%SZ)}"
BASE_URL="${BASE_URL%/}"
mkdir -p "$OUT_DIR"
export CLIENT_ID CLIENT_SECRET TEST_SIGNER_EMAIL TEST_SIGNER_PHONE

log() { printf '%s %s\n' "$(date -u +%H:%M:%S)" "$*" >&2; }
note() { # consigne une observation, jamais un secret ni une donnée personnelle
  jq -n --arg step "$1" --arg value "$2" --arg at "$(date -u +%FT%TZ)" \
    '{at:$at,step:$step,value:$value}' >> "$OUT_DIR/journal.jsonl"
}

# 1. Jeton — le secret passe dans le corps, jamais dans une ligne de commande.
TOKEN=$(jq -nr '
  "grant_type=client_credentials&client_id=" + (env.CLIENT_ID|@uri)
  + "&client_secret=" + (env.CLIENT_SECRET|@uri)
  + "&scope=" + ("signature:read signature:write documents:read documents:write webhooks:read webhooks:write"|@uri)
' | curl --fail-with-body --silent --show-error \
  -H 'Content-Type: application/x-www-form-urlencoded' --data-binary @- \
  "$BASE_URL/api/compat/oauth/token" | jq -er '.access_token')
unset CLIENT_SECRET
note "token" "obtenu"

api() { curl --silent --show-error -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' "$@"; }
must() { api --fail-with-body "$@"; }
YS="$BASE_URL/api/compat/yousign/v3"

# Version testée : le contrat OpenAPI public porte la version du produit.
VERSION=$(curl --silent --fail "$BASE_URL/api/openapi.json" | jq -r '.info.version // "inconnue"')
note "version" "$VERSION"

# 2. Notifications — les trois événements qui rythment le parcours. Extension
#    BizSign : signature_request.bitcoin_confirmed n’existe pas chez YouSign.
if [ -n "$WEBHOOK_URL" ]; then
  export WEBHOOK_URL
  WEBHOOK_ID=$(jq -n '{url:env.WEBHOOK_URL,
    events:["signature_request.activated","signature_request.done","signature_request.bitcoin_confirmed"]}' \
    | must -X POST "$YS/webhooks" --data-binary @- | jq -er '.id')
  note "webhook" "abonnement $WEBHOOK_ID"
fi

# 3. Demande — deux documents DISTINCTS, un participant avec un champ sur chacun.
REQUEST_ID=$(must -X POST "$YS/signature_requests" \
  --data '{"name":"Recette BizSign — deux documents","delivery_mode":"none"}' | jq -er '.id')
note "request" "$REQUEST_ID"
add_document() { # $1 chemin, $2 nom publié
  base64 < "$1" | tr -d '\n' \
    | jq -Rs --arg name "$2" '{file:.,file_name:$name,nature:"signable_document"}' \
    | must -X POST "$YS/signature_requests/$REQUEST_ID/documents" --data-binary @- | jq -er '.id'
}
DOC1=$(add_document "$PDF_PATH" "recette-1.pdf")
DOC2=$(add_document "$PDF2_PATH" "recette-2.pdf")
export DOC1 DOC2
SIGNER_ID=$(jq -n '{
  info:{first_name:"Test",last_name:"Recette",email:env.TEST_SIGNER_EMAIL,phone_number:env.TEST_SIGNER_PHONE},
  signature_level:"electronic_signature",
  signature_authentication_mode:"otp_sms",
  fields:[{document_id:env.DOC1,type:"signature",page:1,x:50,y:100,width:180,height:60},
          {document_id:env.DOC2,type:"signature",page:1,x:50,y:100,width:180,height:60}]
}' | must -X POST "$YS/signature_requests/$REQUEST_ID/signers" --data-binary @- | jq -er '.id')

# 4. Envoi EXPLICITE — c’est l’activation qui engage et réserve les unités.
#    Un refus de contrat (403 PLAN_LIMIT_REACHED, SIGNATURE_ACT_QUOTA_REACHED,
#    CONSENT_REQUIRED…) sort ici, lisible, et ne consomme rien.
must -X POST "$YS/signature_requests/$REQUEST_ID/activate" > /dev/null
note "activate" "envoyée"

# 5. Signature dans le parcours réel : ouvrir le lien dans un navigateur, sur
#    le mobile de test, et signer les deux documents (code SMS).
must "$YS/signature_requests/$REQUEST_ID/signers/$SIGNER_ID" \
  | jq -r '"Lien de signature : \(.signature_link)\nExpire le : \(.signature_link_expiration_date)"' >&2

# 6. Attendre la fin : ici par relance de l’état ; en production, par le
#    webhook signature_request.done. Les deux mènent au même téléchargement.
#    Signature terminée (status=done) ≠ PDF disponible ≠ Bitcoin confirmé.
until [ "$(must "$YS/signature_requests/$REQUEST_ID" | jq -r '.status')" = "done" ]; do
  log "en attente de la signature… (relance dans ${POLL_SECONDS}s)"; sleep "$POLL_SECONDS"
done
note "status" "done"

# 7. Chaque PDF final, par identifiant. 409 DOCUMENT_NOT_READY + Retry-After :
#    la finalisation est en cours, on attend le délai annoncé puis on rejoue.
#    409 DOCUMENT_FINALIZATION_FAILED : une reprise côté BizSign est nécessaire.
download_final() { # $1 id document, $2 fichier de sortie
  local code headers="$OUT_DIR/headers.tmp"
  while :; do
    code=$(api -D "$headers" -o "$2" -w '%{http_code}' \
      "$YS/signature_requests/$REQUEST_ID/documents/$1/download")
    case "$code" in
      200) sha256sum "$2" | cut -d' ' -f1; return 0 ;;
      409) if jq -e '.code=="DOCUMENT_NOT_READY"' "$2" > /dev/null 2>&1; then
             local wait; wait=$(grep -i '^Retry-After:' "$headers" | tr -dc '0-9'); wait="${wait:-$POLL_SECONDS}"
             log "document $1 : finalisation en cours, nouvel essai dans ${wait}s"; sleep "$wait"
           else
             log "document $1 : $(jq -r '.code // .detail' "$2") — reprise nécessaire, voir le support"; return 1
           fi ;;
      *) log "document $1 : HTTP $code"; cat "$2" >&2; return 1 ;;
    esac
  done
}
note "pdf1_sha256" "$(download_final "$DOC1" "$OUT_DIR/recette-1-signe.pdf")"
note "pdf2_sha256" "$(download_final "$DOC2" "$OUT_DIR/recette-2-signe.pdf")"

# 8. Preuves — état d’abord, puis exports. Le PDF de preuve existe dès la fin ;
#    l’OTS et l’archive attendent le premier ancrage ; bitcoin_confirmed est
#    une observation DISTINCTE, souvent plus tardive (aucun délai garanti).
V1="$BASE_URL/api/v1/workflows/$REQUEST_ID"
STATUS=$(must "$V1/proof/status")
echo "$STATUS" | jq '{documents_state,proof_state,ots_state,public_anchor_status,bitcoin_confirmed}' >&2
note "proof_status" "$(echo "$STATUS" | jq -c '{documents_state,proof_state,ots_state,bitcoin_confirmed}')"
must "$V1/proof?format=pdf" -o "$OUT_DIR/preuve.pdf"
for fmt in ots zip; do
  code=$(api -o "$OUT_DIR/preuve.$fmt" -w '%{http_code}' "$V1/proof?format=$fmt")
  [ "$code" = 200 ] && note "proof_$fmt" "téléchargé" || note "proof_$fmt" "HTTP $code $(jq -r '.detail' "$OUT_DIR/preuve.$fmt" 2>/dev/null)"
done

# 9. Reprise. Notification manquée : l’état ci-dessus se relit à tout moment,
#    aucun événement n’est nécessaire pour récupérer les fichiers. Notification
#    reçue deux fois : dédupliquer sur l’identifiant d’événement. Confirmation
#    Bitcoin attendue : relire proof/status jusqu’à bitcoin_confirmed=true,
#    puis retélécharger l’OTS et l’archive (l’empreinte ots_sha256 change).
if [ "$(echo "$STATUS" | jq -r '.bitcoin_confirmed')" != "true" ]; then
  log "Bitcoin non confirmé à cet instant : relire $V1/proof/status plus tard, puis reprendre l’OTS et l’archive."
fi
[ -n "${WEBHOOK_ID:-}" ] && must -X DELETE "$YS/webhooks/$WEBHOOK_ID" > /dev/null
rm -f "$OUT_DIR/headers.tmp"
log "Recette terminée. Journal sans secret : $OUT_DIR/journal.jsonl"