PATCH/v1/cards/{card_id}

Modifier une fiche

update_card

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

card_idstringobligatoire

Paramètres d’en-tête

Idempotency-Keystring
Clé permettant de réessayer une écriture sans risque : de 1 à 255 caractères ASCII imprimables ; un UUID v4 par opération logique est recommandé. Une nouvelle tentative avec la même clé dans les 24 heures n’exécute pas l’opération une seconde fois : elle renvoie la réponse enregistrée (statut, en-têtes et corps) avec l’en-tête Idempotency-Replayed: true. La même clé avec une méthode, un chemin, un Content-Type ou un corps différents renvoie 409 api.idempotency_mismatch ; tant que la première requête est en cours, 409 api.idempotency_in_progress avec Retry-After: 1. Après une réponse 5xx ou 429, la clé est libérée, et une nouvelle tentative exécute de nouveau l’opération. La clé est propre à l’organisation et à l’appelant (clé API, utilisateur ou clé de source personnalisée).
length ≥ 1, length ≤ 255
X-View-Asstring
Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

kb_view_asstring
Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : CardUpdate

external_idstring | null
Définit ou modifie l’external_id de la fiche ; "" ou null le supprime. Si une autre fiche de l’organisation l’utilise, la requête renvoie 409 cards.external_id_taken. L’external_id d’une fiche issue d’une source ne change pas (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Réponses

200Réponse réussie

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.
Idempotency-Replayed
true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valeurs autorisées: wholepartial
access_contactstring
Personne à contacter pour obtenir l’accès (uniquement si access=partial).
aclobject
Champs
- verifybooleanobligatoire
- writebooleanobligatoire
categorystringobligatoire
category_confidencenumber | nullobligatoire
category_lockedbooleanobligatoire
category_reviewbooleanobligatoire
category_sourceCategorySource | nullobligatoire
collectionstringobligatoire
collection_idintegerobligatoire
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Contenu de l’éditeur de la dernière version publiée. Le champ peut être absent ; dans ce cas, obtenez le contenu de l’éditeur à partir d’un brouillon (POST /v1/drafts avec card_id).
editing_lockEditingLock | null
Verrou de modification actif. Le champ peut être absent ; dans ce cas, l’éditeur apprend qui détient le verrou par la réponse 409 cards.locked de POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obligatoire
days_since_verifiedintegerobligatoire
errorstring | nullobligatoire
eventsarray of CardEvent
feedback_negintegerobligatoire
feedback_posintegerobligatoire
foldersarray of CardFolderRef
Liste des fiches uniquement : les dossiers qui contiennent la fiche (ceux que l’utilisateur voit), avec leurs chemins depuis la racine de la collection. Une liste vide signifie que la fiche n’est dans aucun dossier.
has_tablesboolean
Liste des fiches uniquement.
hidden_partsboolean
idstringobligatoire
jobJob | null
kindCardKindobligatoire
org_idintegerobligatoire
owner_activeboolean | null
owner_idinteger | nullobligatoire
owner_namestring | nullobligatoire
pagesinteger | nullobligatoire
parserstring | nullobligatoire
Analyseur du document sous forme de code neutre : document (structure complète : pages, titres, tableaux, pages numérisées), pdf (la couche texte du PDF), docx, xlsx, csv, markdown, html, text. La liste peut s’étendre.
partsarray of CardPartobligatoire
sensitivebooleanobligatoire
sha256string | nullobligatoire
sizeintegerobligatoire
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobligatoire
source_pathstring | nullobligatoire
source_urlstring | nullobligatoire
statusstringobligatoire
Valeurs autorisées: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobligatoire
titlestringobligatoire
trustnumberobligatoire
trust_if_verifiednumber
trust_partsTrustPartsobligatoire
updated_atstring (date-time)obligatoire
verificationVerificationobligatoire
verified_atstring (date-time) | nullobligatoire
verified_byinteger | nullobligatoire
verified_by_namestring | null
verifier_idsarray of integerobligatoire
verifiersarray of object
Champs
- activebooleanobligatoire
- idintegerobligatoire
- namestringobligatoire
verify_interval_daysintegerobligatoire
versionintegerobligatoire
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Paramètres d’analyse manuels (aperçu).
doc_kindDocKind | null
Type de document. null si le type n’est pas déterminé (par exemple, pour les fiches indexées avant l’introduction des types de documents).
doc_kind_confidencenumber | null
Degré de certitude quant au type de document, de 0 à 1.
doc_kind_sourcestring | null
Ce qui a déterminé le type : des règles (rules), un utilisateur (manual) ou la classification automatique. La liste peut s’étendre : traitez une valeur inconnue comme une classification automatique.
Valeurs autorisées: rulesmanualnull
invoiceDocInvoiceExtraction | null
Champs d’une facture, d’un avoir ou d’un reçu (uniquement pour ces types, et uniquement dans la fiche, pas dans la liste). null si vous n’avez pas accès au document entier, car les champs sont extraits du document entier.
warningsarray of ReviewWarning
Avertissements de l’analyse du document (ReviewWarning ; uniquement dans la fiche, pas dans la liste).
enrichmentCardEnrichmentStatus | null
État de l’enrichissement (uniquement dans la fiche, pas dans la liste). Le type de document, les champs de facture et les entrées financières sont ajoutés en arrière-plan après l’indexation et peuvent être recalculés plus tard ; ils apparaissent dans la fiche quand ils sont prêts. null signifie qu’aucun état n’est disponible (la fiche a été indexée sans enrichissement en arrière-plan).
external_idstring | null
ID de la fiche dans le système de l’intégrateur. Il est unique dans l’organisation parmi les fiches qui ne proviennent pas de sources ; null signifie qu’il n’est pas défini. /v1/cards-by-external-id/{external_id} lit et remplace la fiche par cet ID.
length ≤ 512
metadataMetadata

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← cards · Référence de l’API

curl -X PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Si ce champ est vide, une nouvelle clé est générée pour chaque requête.

Corps de la requête (JSON)