Démarrer avec l'API

Préversion

L’API publique n’est pas encore ouverte. En production, /api/v1 répond 404 à toute requête, et l’écran Paramètres → API n’est pas encore visible : cette page décrit le contrat visé, pas un service que vous pouvez appeler aujourd’hui.

Pour participer à la préversion, écrivez-nous depuis Aide → Contacter l’équipe.

L’API TAYO.pro permet à votre propre logiciel de lire vos projets, interventions, devis, factures et rappels de paiement. Dans sa version actuelle, elle ne fait que lire : aucun endpoint ne crée ni n’envoie de document. La liste exacte est dans la référence.

Elle est faite pour être appelée par un serveur, jamais depuis un navigateur : une clé d’API dans un paquet JavaScript est une clé publiée.

Ce qu’il faut avant de commencer

L’API est une option payante, en plus d’un abonnement au plan PLUS. Sans elle, tous les appels authentifiés répondent 403 addon_required.

Les clés se créent depuis Paramètres → API, sur l’application web uniquement, après avoir accepté les conditions d’utilisation de l’API.

Vos deux clés

Chaque entreprise dispose de deux clés, et c’est le préfixe qui décide de tout :

Clé	Ce qu’elle fait
tay_live_…	La clé de production : accède à vos données réelles.
tay_test_…	La clé de test : rejoue tout le parcours d’une requête, puis renvoie une réponse d’exemple sans rien toucher.

Le mode n’apparaît donc ni dans l’URL, ni dans le corps, ni dans un en-tête — uniquement dans la clé que vous présentez.

La clé n’est affichée qu’une fois

À la création, le texte complet de la clé apparaît une seule fois. Nous n’en conservons qu’une empreinte : nous sommes incapables de vous la réafficher. Si vous la perdez, cliquez sur Régénérer : l’ancienne clé est révoquée immédiatement, et toute intégration qui l’utilise cesse de fonctionner.

Authentifier un appel

La clé se présente dans l’en-tête Authorization, et nulle part ailleurs — une clé passée en paramètre de requête est refusée avec un 401, même si elle est valide.

curl https://app.tayo.pro/api/v1/me \
  -H "Authorization: Bearer tay_test_votre_cle"

{ "companyId": "…", "mode": "test" }

GET /me vous dit à quelle entreprise et à quel mode la clé correspond : c’est le premier appel à faire pour vérifier une clé. GET /ping, lui, ne demande aucune clé : il dit seulement si l’API répond.

L’URL de base est https://app.tayo.pro/api/v1.

Le mode test

Une requête présentée avec une clé tay_test_… traverse exactement la même chaîne qu’une requête réelle : authentification, comptage des quotas, et la même validation du corps et des paramètres. Puis elle s’arrête net avant la logique métier.

Concrètement, en mode test :

• rien n’est écrit, rien n’est supprimé ;
• aucun e-mail, aucun PDF, aucun appel à Tayo n’est déclenché ;
• la réponse respecte le schéma de la réponse de production ;
• les identifiants sont stables d’un appel à l’autre — prj_test_1 restera prj_test_1 — pour que vos tests puissent s’appuyer dessus.

C’est ce qui rend la mise en production sans surprise : vous avez déjà vu la forme exacte de chaque réponse.

Forcer un cas d’erreur avec Tay-Test-Scenario

Un intégrateur sérieux doit pouvoir tester ses branches d’erreur. L’en-tête Tay-Test-Scenario choisit la réponse que le mode test doit renvoyer :

Scénario	Ce que vous obtenez
success	Le cas nominal. C’est le défaut.
not_found	La ressource demandée n’existe pas.
validation_error	Le corps est refusé, avec le détail par champ.
send_failed	L’envoi au client a échoué.
quota_exceeded	Votre quota mensuel est épuisé.

Chaque endpoint accepte un sous-ensemble de ces valeurs — send_failed n’a aucun sens sur une lecture. Aujourd’hui, une liste accepte success et quota_exceeded, la lecture d’une ressource ajoute not_found. Une valeur hors de cet ensemble répond 400.

Cet en-tête est interdit en mode live

Avec une clé tay_live_…, Tay-Test-Scenario ne fait pas que ne rien faire : il répond 400 test_header_in_live_mode.

C’est volontaire. Un en-tête de test oublié dans du code de production est un défaut, et il vaut mieux qu’il se voie au premier appel plutôt que de passer inaperçu pendant des mois.

Passer en production

Remplacez la clé. C’est tout.

Les URL, les corps de requête, les schémas de réponse et les codes d’erreur sont identiques dans les deux modes — c’est l’objet même du mode test.

Comment se présentent les erreurs

Toute requête qui échoue renvoie la même enveloppe :

{
  "error": {
    "code": "invalid_argument",
    "message": "The request failed validation.",
    "details": [
      { "field": "amount", "code": "invalid_type", "message": "Expected number" }
    ]
  }
}

details n’est présent que sur une erreur de validation.

Statut	code	Quand
400	invalid_argument	La requête n’a pas passé la validation.
400	failed_precondition	L’opération est impossible dans l’état actuel.
401	unauthenticated	Clé absente, révoquée, ou mal présentée.
403	permission_denied	Cette clé n’a pas le droit de faire cela.
403	addon_required	L’option API n’est pas active sur l’entreprise.
404	not_found	La ressource n’existe pas.
409	already_exists	La ressource existe déjà.
409	delivery_in_flight	La livraison est déjà en attente d’une nouvelle tentative.
409	endpoint_deleted	Le point de terminaison de cette livraison n’existe plus.
409	endpoint_disabled	Le point de terminaison de cette livraison est désactivé.
409	retry_limit_reached	La livraison a atteint sa limite de relances manuelles.
429	rate_limited	Trop de requêtes par minute — ralentissez et réessayez. Voir Limites d’usage.
429	quota_exceeded	Le quota mensuel et sa tolérance de dépassement sont consommés. Voir Limites d’usage.
500	internal	Une erreur de notre côté.
503	unavailable	Service temporairement indisponible.

Les messages sont en anglais uniquement, et le resteront : un programme lit le code, et traduire la prose ne ferait que compliquer la recherche de ce qu’il cherche vraiment.

Si une réponse s’écarte de ce que la référence décrit, c’est une anomalie et sa correction est comprise dans l’option : voir Assistance API.