Les commandes ouvrent prochainement. D'ici là, écrivez à support@uliketechnology.com et un ingénieur vous répond.

Tous les guides

Assistants AI

Démarrage rapide de l'API : téléversement, vérification, devis

Les appels d'un fichier de carte au rapport de vérification, au prix et à la commande, avec curl et le client JavaScript, plus les erreurs rencontrées.

Pour les assistants AIMis à jour le 2026-11-178 min de lectureMarkdown brut pour les assistants AI

L'API et le serveur MCP décrits ici ouvrent avec les commandes.

Avant de commencer

Le téléversement, la vérification des fichiers et le devis fonctionnent sans compte, au moyen d'une session invité. Une commande demande un compte : voyez « D'un devis à une commande » ci-dessous. L'API se trouve à l'adresse propre du site, sous /api. Définissez-la une fois :

API=https://uliketechnology.com/api
F=board.zip

board.zip est un zip plat de vos fichiers Gerber et de perçage. Pour ce qu'il contient, voyez Fichiers pour la fabrication et l'assemblage. Les exemples ont besoin de curl et de jq.

Chaque requête à l'API après la session invité prend Authorization: Bearer <token>. Une clé API va dans le même en-tête à la place du token invité. Chaque erreur a la même forme :

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }

Décidez selon code. Le message est destiné aux développeurs.

Cinq petites images dans l'ordre : une clé, un fichier allant vers une adresse de téléversement, un sablier, une page de rapport avec des observations, et une étiquette de prix
  1. Session invité : le token est affiché une fois.
  2. Téléversement : PUT le zip à l'adresse que l'API indique, avec les en-têtes qu'elle indique.
  3. Terminez, puis interrogez de façon répétée jusqu'à ce que l'analyse soit terminée.
  4. Le rapport : observations, quelles vérifications ont été effectuées et lesquelles ne l'ont pas été.
  5. L'aperçu du prix.

Le flux avec curl

Lisez ce qui peut être commandé. Cela ne demande aucun token :

curl -s $API/v1/capabilities | jq '.options[].id'

Ouvrez une session invité. Le token est affiché une fois et dure 30 jours :

T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)

Annoncez le fichier. La réponse contient uploadId, designId, uploadUrl et requiredHeaders :

J=$(curl -s -X POST $API/v1/uploads -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"fileName\":\"board.zip\",\"sizeBytes\":$(stat -c %s $F),\"sha256\":\"$(sha256sum $F | cut -d' ' -f1)\",\"purpose\":\"design\"}")

Envoyez le fichier à l'adresse que la réponse indique, avec chaque en-tête de requiredHeaders (type de contenu, longueur et somme de contrôle ; sans eux, le téléversement est refusé avec 403). Terminez ensuite le téléversement :

curl -s -X PUT --data-binary @$F \
  $(echo $J | jq -r '.requiredHeaders | to_entries[] | "-H \(.key):\(.value)"') \
  "$(echo $J | jq -r .uploadUrl)"
curl -s -X POST $API/v1/uploads/$(echo $J | jq -r .uploadId)/complete -H "authorization: Bearer $T" | jq .design.status

Le statut est analysing au début. Lisez la conception jusqu'à ce qu'il change. Lorsqu'il est ready, le rapport se trouve dans la réponse :

D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'

Le titre est no_problems_in_checks_run, problems_found ou could_not_check. Lisez aussi checksRun et checksNotRun : une vérification qui n'a pas été effectuée n'est pas une réussite. Les autres statuts sont needs_mapping (définissez les couches avec PUT /v1/designs/{designId}/layer-mapping), needs_engineer et rejected.

Demandez un aperçu de prix. selection et destinationCountry sont requis ; un selection vide prend les valeurs par défaut :

curl -s -X POST $API/v1/quote-previews -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"designId\":\"$D\",\"quantities\":{\"boardsFabricated\":10,\"boardsAssembled\":0},\"selection\":{},\"destinationCountry\":\"DE\"}" \
  | jq '.mode, .reviewReasons, .totalMinor'

mode vaut instant (le prix reste tel qu'affiché) ou review (un ingénieur le confirme) ; reviewReasons dit pourquoi. totalMinor est exprimé en unités mineures de la currency de la réponse, et il est absent lorsqu'un ingénieur doit chiffrer le travail. Pour conserver un devis, POST /v1/quotes prend le même corps.

Le même flux avec le client JavaScript

Le client @ulike/sdk enveloppe ces routes. C'est le client de notre propre site et ce n'est pas un paquet public ; voici sa forme, afin que vous puissiez écrire les mêmes appels avec fetch. Noms de méthodes :

import { createClient } from '@ulike/sdk';

let token;
const api = createClient({ baseUrl: 'https://uliketechnology.com/api', token: () => token });

const caps = await api.capabilities();
token = (await api.createGuestSession()).token;
const started = await api.uploadDesign({ name: 'board.zip', bytes }); // announce, PUT, complete
const view = await api.waitForDesign(started.design.id); // polls getDesign
const preview = await api.previewQuote({
  designId: view.design.id,
  quantities: { boardsFabricated: 10, boardsAssembled: 0 },
  selection: {},
  destinationCountry: 'DE',
});

Parmi les autres méthodes figurent createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders et cancelOrder. Les erreurs sont levées sous forme d'ApiClientError avec un status et un code.

La vérification pour une commande

Le rapport que vous obtenez après le téléversement est établi sur les seuls fichiers. Pour vérifier les fichiers par rapport à une commande, appelez POST /v1/designs/{designId}/validations (validateDesign) avec order contenant quantities et selection. La réponse est un état : running, failed ou done. Pendant running, lisez GET /v1/validations/{reportId} (getValidation) toutes les une à deux secondes jusqu'à ce qu'il soit done.

Une boucle de trois étapes : téléverser les fichiers, lire le rapport, corriger et téléverser à nouveau ; une flèche quitte la boucle vers une coche lorsque les fichiers sont propres
  1. Téléversez le zip.
  2. Lisez le rapport.
  3. Corrigez et téléversez comme une nouvelle conception. Arrêtez-vous et demandez à la personne lorsqu'une correction change la fonction, le prix ou le délai de livraison.
  4. Fichiers propres : lancez la vérification pour la commande.

Un devis ou un aperçu avec des options qui apportent d'autres limites (cuivre plus épais, autre épaisseur) a besoin d'une vérification pour cette sélection. S'il n'en existe aucune, une vérification est lancée, et l'aperçu porte le motif de revue file_check_pending et un check avec son reportId. Le prix est affiché tout de suite, mais le devis reste en review jusqu'à ce que cette vérification soit terminée. Lisez la vérification comme ci-dessus, puis demandez à nouveau l'aperçu.

Erreurs que vous rencontrerez

Code Statut Ce que cela signifie Ce qu'il faut faire
DESIGN_NOT_READY 422 La conception est encore en cours de lecture (details.status indique dans quel état), ou n'a pas encore de rapport. Lisez la conception jusqu'à ce que le statut ne soit plus analysing, puis demandez à nouveau.
VALIDATION_FAILED 400 La requête n'a pas la forme attendue, ou nomme une option ou une valeur que le catalogue n'a pas. details liste les points ou les problèmes. Corrigez le champ nommé dans details et envoyez à nouveau. Prenez les identifiants et les valeurs d'options depuis GET /v1/capabilities.
NOT_MANUFACTURABLE 422 La sélection est quelque chose que nous ne fabriquons pas. details.because porte les motifs. Changez la sélection ; ne réessayez pas la même. Demandez à la personne si le changement modifierait la carte.
ANONYMOUS_BUDGET_SPENT 429 Le quota journalier sans compte est épuisé. details.resetsOn est la date. Arrêtez-vous. Dites-le à la personne ; elle peut se connecter ou attendre jusqu'à cette date.
REVISION_CONFLICT 409 Une révision a nommé une base qui n'est plus la tête du devis. details porte les deux têtes. Lisez la tête avec GET /v1/quotes/{quoteId}, réappliquez votre changement dessus, et envoyez à nouveau.

Sont aussi possibles DESIGN_REJECTED (le téléversement a été refusé ; voyez details.reason), UNAUTHENTICATED pour un token manquant ou incorrect (un token incorrect est refusé même sur les routes publiques), FORBIDDEN pour une clé ou un token invité qui ne peut pas appeler la route, et FEATURE_DISABLED pour une route désactivée.

Le quota journalier sans compte

Une session invité a un quota journalier de calcul. Les téléversements et les vérifications lancées coûtent plus qu'une simple lecture, et l'ouverture de nombreuses sessions invité depuis une même adresse réseau est aussi comptée. Une vérification que le site lance de lui-même pour une nouvelle sélection est imputée au même quota. Lorsqu'il est épuisé, vous recevez ANONYMOUS_BUDGET_SPENT avec la date à laquelle il se réinitialise. Les appelants connectés ne sont pas comptés de cette manière.

D'un devis à une commande

Une commande est passée à partir d'un devis conservé qui appartient à un compte. Un token invité est refusé sur les routes de commande. Un programme travaille pour un compte de l'une des deux façons suivantes, toutes deux décrites sur Pour les développeurs et les assistants :

  • Une clé API. La personne la crée dans son compte sous Clés API et choisit ce qu'elle peut faire. Envoyez-la comme Authorization: Bearer ulk_…. Un devis créé avec la clé appartient au compte. Une clé de test (ulk_test_…) ne fonctionne que sur des données d'exemple.
  • La connexion pour les programmes. Un assistant s'enregistre lui-même, la personne voit ce qu'il demande à faire sur une page du site et appuie sur Autoriser, et l'assistant reçoit un token limité à ces autorisations.

Lisez les adresses enregistrées avec GET /v1/addresses. Une adresse est ajoutée ou modifiée par la personne dans le navigateur. L'adresse d'expédition doit se trouver dans le destinationCountry du devis.

Passez la commande avec POST /v1/orders. La route demande un en-tête Idempotency-Key : une nouvelle clé de 8 à 80 caractères visibles par commande visée, et la même clé à nouveau quand vous réessayez :

curl -s -X POST $API/v1/orders -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" \
  -d "{\"quoteId\":\"$Q\",\"expectedTotalMinor\":$TOTAL,\"shipToAddressId\":\"$SHIP\",\"billToAddressId\":\"$BILL\",\"paymentMethod\":\"bank_transfer\",\"termsVersion\":\"$TERMS\",\"dangerousGoods\":false}"

expectedTotalMinor est le totalMinor du devis que la personne a accepté. termsVersion nomme la version des conditions de vente que la personne a acceptée. dangerousGoods dit si l'envoi contient des batteries ou d'autres marchandises dangereuses.

Aucune commande n'est passée par cet appel. La réponse est APPROVAL_REQUIRED (422) avec details.approvalUrl, pour une clé API comme pour le token d'un assistant connecté. Donnez ce lien à la personne. Elle l'ouvre, se connecte, voit la commande et le total, et approuve ou refuse. Le lien fonctionne une fois, expire après 24 heures, et cesse de fonctionner si le devis ou le total change.

Après l'approbation, la commande existe : listez les commandes du compte avec GET /v1/orders et lisez-en une avec GET /v1/orders/{orderId}. Elle porte order.number, le numéro de facture pro forma dans proFormaNumber, le compte à payer dans sellerBank et, sous payments, le bankReference à écrire sur le virement.

Le paiement se fait par virement bancaire, effectué par la personne. Aucune clé et aucun assistant ne peuvent payer. Suivez la commande avec GET /v1/orders/{orderId}. Un ingénieur confirme chaque commande avant la production.

Code Statut Ce que cela signifie Ce qu'il faut faire
APPROVAL_REQUIRED 422 Une personne connectée doit d'abord approuver. details.approvalUrl est la page. Donnez le lien à la personne. Ne cherchez pas de moyen de contourner cela.
TOTAL_MISMATCH 422 expectedTotalMinor n'est pas le total du devis. details.totalMinor est le total. Relisez le devis et montrez le prix à la personne avant de demander à nouveau.
QUOTE_EXPIRED 410 Le devis a dépassé sa validité. Révisez le devis pour un nouveau prix, et montrez-le à la personne.
CONFLICT 409 details.reason vaut quote_ordered ou quote_not_priced (un ingénieur doit d'abord donner un prix). Ne réessayez pas. Dites-le à la personne.
INTAKE_CLOSED 503 Aucune commande n'est acceptée pour le moment. details.reopensOn est la date, quand il y en a une. Arrêtez-vous. Dites-le à la personne.

Le même service est proposé aux assistants comme outils nommés via un serveur MCP : voyez Ce qu'est le MCP et comment les agents commandent.