Créer et modifier

L'écriture ne concerne que le CRM. La facturation est en lecture seule.

Une écriture passe par les mêmes règles que dans l'application : champs obligatoires, règles conditionnelles, détection de doublons. La fiche créée ou modifiée a la clé pour auteur, sous son nom : « Clé API « Make — factures » ».

Créer une fiche

curl https://acme.deltia.co/api/v1/crm/entities/societes/records \
  -H "Authorization: Bearer dlt_…" \
  -H "Content-Type: application/json" \
  -d '{ "fieldValues": { "raison_sociale": "Initech", "effectif": 12 } }'

La réponse est 201 Created, avec la fiche complète telle qu'un GET la relirait, et l'en-tête Location qui pointe sur elle.

Le corps accepte deux clés, et seulement deux :

• fieldValues (obligatoire) : les valeurs, par nom de champ ;
• scopeIds (facultatif) : les périmètres de la fiche.

Les périmètres. Une clé rattachée à un seul périmètre y range la fiche d'office. Une clé rattachée à plusieurs périmètres doit choisir : sans scopeIds, l'API répond 400 validation, avec les périmètres possibles dans errors[].allowed. Un périmètre hors de ceux de la clé est refusé de la même façon.

Modifier une fiche

curl -X PATCH https://acme.deltia.co/api/v1/crm/entities/societes/records/8f2… \
  -H "Authorization: Bearer dlt_…" \
  -H "Content-Type: application/json" \
  -d '{ "fieldValues": { "effectif": 14, "site_web": null } }'

La modification est partielle :

• un champ absent du corps reste tel quel ;
• un champ à null est effacé ;
• un champ obligatoire ne peut pas être effacé.

Le corps n'accepte que fieldValues : les périmètres d'une fiche ne changent pas par l'API. La réponse est 200 OK, avec la fiche complète.

Les valeurs attendues

À la lecture, un lien revient sous la forme { id, displayName } ; à l'écriture, on n'envoie que l'identifiant.

Ne s'écrivent pas : identifiant et numéro automatique, auteur, formule, somme, propriété d'une fiche liée, lien interne, crédit, journal, fichier et image. Les envoyer est refusé.

Les refus

Une écriture refusée pour ses valeurs répond 400 validation, avec une erreur par champ dans errors :

{
  "type": "https://docs.deltia.co/developers/api/errors#validation",
  "title": "Validation failed",
  "status": 400,
  "errors": [
    { "path": "fieldValues.numero", "code": "read_only", "message": "…" },
    { "path": "fieldValues.licorne", "code": "unknown_field", "message": "…" }
  ]
}

Trois refus viennent des droits, pas des valeurs :

• 403 permission-denied : la clé n'a pas le verbe (create ou update) sur cette entité ;
• 403 entity-operation-disabled : la clé a le verbe, mais l'entité a désactivé l'opération dans le CRM ;
• 403 record-owner-forbidden : l'entité réserve la modification d'une fiche à son créateur, et la fiche n'a pas été créée par cette clé.

Une entité où la clé ne peut pas créer. Si l'entité exige un champ que la clé ne peut pas écrire, aucune création n'est possible par l'API, quel que soit le corps envoyé. C'est le cas d'un champ obligatoire :

• d'un type qui ne s'écrit pas (fichier, image, crédit, journal, formule…) ;
• ou masqué à toutes les clés, alors que le CRM l'exige quand même (un champ visible seulement par l'auteur de sa valeur).

Pour une telle entité, create n'apparaît pas dans les verbes de /me, de /crm/entities ni de l'OpenAPI de la clé. Un POST répond 403 entity-operation-disabled, et non 400 validation : le corps n'y est pour rien, et nommer un champ masqué révélerait qu'il existe. Il faut changer la configuration de l'entité : rendre le champ facultatif, ou le rendre visible à la clé s'il est d'un type qui s'écrit. Un champ fichier à échéance n'est jamais exigé à la création, et ne bloque donc rien. Un champ obligatoire réservé à des rôles que la clé n'a pas ne bloque rien non plus : le CRM ne l'exige pas d'elle.

Une fiche hors des périmètres de la clé répond 404, exactement comme une fiche qui n'existe pas.

Un corps de plus de 1 Mio répond 413 payload-too-large, avant toute lecture de la fiche.