API

Référence API Struct20022

La même API sert l'interface web, les fichiers, les clés API et les intégrations ERP. Les routes sont versionnées sous /v1.

Base URL et auth

Production

https://api.struct20022.cloud

Documentation

https://struct20022.cloud/api-reference

JWT Supabase : Authorization: Bearer <jwt>
Clé API : X-API-Key: struct20022_live_...

Options combinables

Option API	Nom	Coût max	Usage
structuring	Structuration	1 crédit	Adresse complète attendue, sans vérification d'existence.
completion	Complétion	1 crédit	Complète une adresse incomplète. Un résultat partiel ou non abouti garde la meilleure structure avec une fiabilité basse, sans débit en cas d'échec.
validation	Validation	1 crédit	Source officielle, seulement pour les pays couverts.

Adresse unique

curl -X POST https://api.struct20022.cloud/v1/addresses/structure \
  -H "X-API-Key: struct20022_live_..." \
  -H "Content-Type: application/json" \
  -d '{"address":"12 rue de la paix, 75002 Paris","features":{"structuring":true,"completion":true,"validation":false},"country":"FR"}'

# Validation seule : structured_address complet obligatoire
curl -X POST https://api.struct20022.cloud/v1/addresses/structure \
  -H "X-API-Key: struct20022_live_..." \
  -H "Content-Type: application/json" \
  -d '{"structured_address":{"street_name":"Rue de la Paix","building_number":"12","post_code":"75002","town_name":"Paris","country":"FR"},"features":{"structuring":false,"completion":false,"validation":true}}'

Fichiers

curl -X POST https://api.struct20022.cloud/v1/files/detect-columns \
  -H "X-API-Key: struct20022_live_..." \
  -F "file=@clients.xlsx"

curl -X POST https://api.struct20022.cloud/v1/files \
  -H "X-API-Key: struct20022_live_..." \
  -F "file=@clients.xlsx" \
  -F "structuring=true" \
  -F "completion=true" \
  -F "validation=false" \
  -F "output_format=xlsx" \
  -F "output_layout=enriched"

curl https://api.struct20022.cloud/v1/jobs/<job_id> \
  -H "X-API-Key: struct20022_live_..."

Le fichier source est supprimé en fin de job. Le résultat reste téléchargeable selon la durée de conservation du compte, de 0 à 365 jours. Côté API, cette durée s'envoie en heures via file_retention_hours. La validation seule sur fichier est acceptée ; les lignes non confirmées remontent en avertissement, sans débit du crédit de validation.

Crédits, paiements et confidentialité

curl https://api.struct20022.cloud/v1/billing/pricing

curl https://api.struct20022.cloud/v1/credits \
  -H "X-API-Key: struct20022_live_..."

curl https://api.struct20022.cloud/v1/billing/payments \
  -H "Authorization: Bearer <jwt>"

curl -X PUT https://api.struct20022.cloud/v1/legal/privacy-settings \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"file_retention_hours":0}'

Playground et erreurs

Le Playground dans /app/cles appelle l'endpoint réel avec la session active et affiche les champs ISO 20022.

auth_requiredOption payante ou ressource protégée appelée sans authentification.

insufficient_creditsSolde insuffisant pour le coût maximal estimé.

structured_address_requiredAucune adresse exploitable n'est fournie.

validation_unsupported_countryCode historique, aujourd'hui renvoyé comme avertissement (warning).

unsupported_formatFichier hors xlsx/xls/csv/tsv/txt/xml.

api_key_expiredClé API expirée.

file_retention_ack_requiredRègle de conservation des fichiers non acceptée.