Écritures et tentatives sécurisées

Envoyer un payload de fiche plat#

Créez avec POST /{resource} et modifiez avec PATCH /{resource}/{id}. Envoyez les valeurs directement dans un objet JSON, sans enveloppe fields. PATCH ne modifie que les champs fournis. Décrivez d’abord la ressource pour connaître ses champs obligatoires et options valides. Les exemples utilisent une entreprise nommée Northfold ; votre espace peut imposer d’autres champs obligatoires.

• Une création renvoie 201, la fiche dans data et un en-tête Location.
• Une modification renvoie 200 et la fiche dans data.
• Les champs inconnus et valeurs invalides sont refusés plutôt qu’acceptés silencieusement.
• Une écriture nécessite une clé write et les permissions d’écriture du propriétaire sur la ressource et les champs.

# Set IDEMPOTENCY_KEY once for this logical operation; keep it for retries.
read -r -p 'Unique operation key: ' IDEMPOTENCY_KEY
curl --fail-with-body --include --request POST "$SQUARIO_API_BASE/companies" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"name":"Northfold"}'

# Use the actual id returned by creation and a new key for this operation.
read -r -p 'Company id: ' COMPANY_ID
read -r -p 'Unique update operation key: ' UPDATE_KEY
curl --fail-with-body --request PATCH "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $UPDATE_KEY" \
  --data '{"name":"Northfold Studio"}'

Écrire les champs personnalisés par clé#

Utilisez des propriétés plates cf__<key> ou un seul objet custom_fields. Ne mélangez pas les deux formats dans une requête. Remplacez integration_code par une vraie clé de champ modifiable issue du schéma de votre espace. Les règles de champs obligatoires et conditionnels sont appliquées côté serveur.

{
  "custom_fields": {
    "integration_code": "northfold-001"
  }
}

Archiver plutôt que supprimer définitivement#

DELETE /{resource}/{id} archive la fiche. Cette suppression est réversible ; vous pouvez envoyer un corps JSON facultatif contenant reason. Restaurez avec POST /{resource}/{id}/restore. Les deux opérations renvoient la fiche résultante dans data. Les listes actives excluent les archives, sauf avec include_archived=true.

read -r -p 'Unique archive operation key: ' ARCHIVE_KEY
curl --fail-with-body --request DELETE "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $ARCHIVE_KEY" \
  --data '{"reason":"Integration cleanup"}'

read -r -p 'Unique restore operation key: ' RESTORE_KEY
curl --fail-with-body --request POST "$SQUARIO_API_BASE/companies/$COMPANY_ID/restore" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header "Idempotency-Key: $RESTORE_KEY"

Réessayer une écriture de façon maîtrisée#

Chaque écriture de fiche et PUT/DELETE d’association accepte Idempotency-Key. Générez une clé unique par opération logique, conservez-la avec l’opération et réutilisez-la lors des nouvelles tentatives. Elle contient 1–255 caractères ASCII imprimables sans espaces et appartient à la clé API. L’empreinte inclut la méthode, le chemin /v1, la chaîne de requête et les octets exacts du corps.

Prévoir un résultat incertain#

L’idempotence réduit les doublons, mais ne garantit pas une exécution exactement une fois. Une réservation inachevée peut être reprise après cinq minutes ; une écriture validée juste avant une panne peut alors être rejouée. Après un échec ambigu, réessayez avec la clé et les octets d’origine, puis vérifiez la fiche avant de créer une nouvelle opération. Les lectures ignorent cet en-tête et seules les réponses réussies sont conservées.