Démarrer avec l'API

L’API TAYO.pro vous donne accès à vos projets, devis, factures et rappels depuis votre propre logiciel. 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 un module complémentaire payant, en plus d’un abonnement PLUS. Sans lui, tous les appels répondent 403 addon_required.

Les clés se créent depuis Paramètres → API, et seul un administrateur peut le faire.

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_…`	Agit sur vos vraies données.
`tay_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.

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://staging.tayo.pro/api/v1/ping \
  -H "Authorization: Bearer tay_live_votre_cle"

L’URL de base est https://staging.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. Une valeur hors de cet ensemble répond 400.

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`	Le module API n’est pas actif 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 le module : voir Assistance.