====== BaCAD Steel List Barcodes Transcription API ======
version 0.2 (beta)
\\ 18.01.2012

===== Introduction =====
Bienvenue sur la documentation de l'API du service de retranscription de liste de fer BaCAD ! Ce service vous offre une interface simple pour extraire les données d'une liste de fer BaCAD, de manière rapide, grâce à la traduction des [[wp>Barcode|codes-barres]] 2D.

{{:private:bvbs.png?nolink&40 |}}
BaCAD utilise la norme d'échange de données d'armature [[http://www.bvbs.de|BVBS]].

===== Limitations d'utilisation =====
...

===== Authentification ====
Le service est sécurisé par un système d'authentification basique HTTP (paire user/password). Cette identification est nécessaire pour utiliser chacune des fonctionnalités présentées dans ce document.

===== Requêtes =====
L'API renvoie les données d'une liste de fer BaCAD en détectant/décodant les codes barres à l'intérieur. Vous envoyez la liste de fer sous plusieurs formats possibles:
  * [[wp>Portable_Document_Format|Pdf]] (Portable Document Format)
  * Images
    * [[wp>JPEG|JPEG]]
    * [[wp>Portable_Network_Graphics|PNG]] (Portable Network Graphics)
    * [[wp>Graphics_Interchange_Format|GIF]] (Graphics Interchange Format)

Ce document décrit le format requis des URLs et les paramètres disponibles.

Un URL de requête au service doit se présenter sous la forme suivante:
<code>
http://cloud.bacad.ch/steellist.php?parameters
ou
https://cloud.bacad.ch/steellist.php?parameters (connexion sécurisée SSL)
</code>

==== Paramètres ====
Excepté pour le document, chaque paramètre peut être spécifié soit dans l'URL (méthode [[wp>GET_(HTTP)|GET]]) ou alors comme donnée postée (méthode [[wp>POST_(HTTP)|POST]]). Les paramètres sont les suivants:
  * ''format'': formats de sortie
  * ''uploadedfile'': document
  * options de sortie

=== Formats de sortie ===
Le format de sortie est spécifié grâce à la variable '''format'''. L'API supporte actuellement les formats de sortie suivant:
  * **xml** retourne les résultats sous forme XML, contenu dans un noeud <SteelListResponse>
  * **abs** (**A**llgemeine-**B**ewehrungs-**S**chnittstelle) retourne les résultats sous forme ASCII (selon la norm [[http://www.bvbs.de|BVBS]])

=== Document ===
Le document doit être envoyé sur le site selon la méthode [[wp>POST_(HTTP)|POST]] du protocole HTTP, sous le nom '''uploadedfile'''.

=== Options de sortie ===
Les options de sortie permettent d'activer/désactiver la génération de données supplémentaires dans le résultat:
  * Le paramètre '''posBvbs'''  à '1' indique que le service doit inclure les données BVBS (pour chaque barre) au résultat
  * Le paramètre '''barXml''' à '1' indique que le service doit inclure les données XML (pour chaque barre) au résultat

===== Réponses =====
==== XML ====
Pour chaque demande valide, le service renvoie une réponse '''SteelListResponse''' dans le format indiqué dans l'URL de requête. Chaque réponse contient les éléments suivants:
  * Un code d'état **status**, qui peut avoir l'une des valeurs suivantes:
    * ''OK'' indiquant que la requête a été un succès
    * ''AUTH_FAILED'' indiquant que l'identification de l'utilisateur a échoué (paire user/password)
    * ''INVALID_REQUEST'' indiquant que la requête a été mal-formées
    * ''INVALID_API_KEY'' indiquant que la clé d'utilisation de l'API est incorrecte
    * ''INVALID_FILE_TYPE'' indiquant que le type du fichier posté n'est supporté
    * ''FILE_OVER_SIZE_LIMIT'' indiquant que le fichier posté est trop volumineux (taille excessive)
    * ''FILE_UPLOAD_ERROR'' indiquant une erreur de téléchargement du fichier
    * ''INTERNAL_ERROR'' indiquant une erreur interne du service
    * ''UNKNOWN_ERROR'' indiquant une erreur inconnue
  * Un élément ''document'' contenant les éléments décrivant les propriétés du document
    * Un élément ''project'' indiquant le nom du projet
    * Un élément ''division'' indiquant le nom de la division
  * Un tableau de résultats (**pages**) contenant:
    * Un élément ''num'' indiquant le numéro de la page
    * Un élément ''thumbnail'' indiquant l'URL (partiel) vers l'aperçu (image) de la page
    * Un tableau de positions (**pos**) contenant:
      * Un élément ''num'' indiquant le numéro de la position
      * Un élément ''bvbs'' indiquant le code [[http://www.bvbs.de|BVBS]] de la position
      * Un élément ''bar'' contenant les éléments décrivant les caractéristiques de la barre
        * Un élément ''type'' indiquant le type de la barre 2D, 3D, etc. Les valeurs peuvent être les suivantes:
          * ''BF2D'' indiquant une barre en 2 dimensions
          * ''BF3D'' indiquant une barre en 3 dimensions
          * ''BFWE'' indiquant une barre en spirale
        * Un tableau d'élément ''dimension'' contenant les éléments décrivant chaque segment de la barre (selon son type)
          * Barre 2D
            * Un élément ''length'' indiquant la longueur du segment
            * Un élément ''radius'' indiquant le rayon du segment arrondi (0 si segment droit)
            * Un élément ''angle'' indiquant la différence d'angle entre le segment et son prédécesseur
          * Barre 3D
            * Un élément ''x'' indiquant la première composante du vecteur du segment
            * Un élément ''y'' indiquant la deuxième composante du vecteur du segment
            * Un élément ''z'' indiquant la troisième composante du vecteur du segment
          * Barre spirale
            * Un élément ''radius'' indiquant le rayon du cercle décrit par la spirale
            * Un élément ''number'' indiquant le nombre de rotations décrites par la spirale
            * Un élément ''spacing'' indiquant l'espace entre chaque rotations décrites par la spirale

==== Exemples ====
Voici un exemple (partiel) du retour au format Xml:
<code xml>
<SteelListResponse>
   <status>OK</status>
   <document>
      <project>MyProject</project>
      <division>MyDivision</division>
      <language>FR</language>
   </document>
   <page>
      <num>1</num>
      <thumbnail>/foo/bar.png</thumbnail>
      <pos>
         <bvbs>BF2D@Hj00@r001@ia@p1@l3280@n6@e2.912@d12@gB500B@s72@v@Gl160@w90@l2960@w90@l160@w0@C69@CRLF</bvbs>
         <project>MyProject</project>
         <list>MyList</list>
         <revision>Revision</revision>
         <num>8</num>
         <count>42</count>
         <length>1000</length>
         <weight>1.2<weight>
         <steel>B500B</steel>
         <diameter>12</diameter>
         <bending>46</bending>
         <bar>
            <type>BF2D</type>
            <dimensions>
               <dimension>
                  <length>500</length>
                  <radius>250</radius>
                  <angle>45</angle>
               </dimension>
            </dimensions>
         </bar>
      </pos>
   </page>
</SteelListResponse>
</code>

Le format des dimensions de barre varie selon le type de barre.
Voici un exemple pour les barres standards (type BF2D):
<code xml>
<dimension>
   <length>500</length>
   <radius>250</radius>
   <angle>45</angle>
</dimension>
</code>

Un exemple pour les barres en 3 dimensions (type BF3D):
<code xml>
<dimension>
   <x>0</x>
   <y>0</y>
   <z>300</z>
</dimension>
</code>

Un exemple pour les spirales (type BFWE):
<code xml>
<dimension>
   <radius>200</radius>
   <number>6</number>
   <spacing>200</spacing>
</dimension>
</code>

Un exemple ABS:
<code>
BF2D@Hj00@r001@ia@p1@l3280@n6@e2.912@d12@gB500B@s72@v@Gl160@w90@l2960@w90@l160@w0@C69@
BF2D@Hj00@r001@ia@p2@l5280@n6@e4.688@d12@gB500B@s72@v@Gl160@w90@l4960@w90@l160@w0@C84@
BF2D@Hj00@r001@ia@p3@l2370@n11@e1.461@d10@gB500B@s60@v@Gl140@w90@l2230@w0@C71@
BF2D@Hj00@r001@ia@p4@l1960@n6@e1.208@d10@gB500B@s60@v@Gl1960@w0@C96@
</code>

===== Test =====
Une page Html est à disposition pour tester le service: [[http://cloud.bacad.ch|cliquez ici]].