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

===== Introduction =====
Welcome to the API documentation service transcript BaCAD barlists! This service offers a simple interface to extract data from a BaCAD barlist quickly, thanks to the translation of [[wp>Barcode|Barcode]] 2D.

{{:private:bvbs.png?nolink&40 |}}
BaCAD uses standard exchange data format [[http://www.bvbs.de|BVBS]].

===== Usage Restrictions =====
...

===== Authentication ====
The service is protected by HTTP Basic authentication (user / password pair) system. This identification is required to use each of the features described in this document.

===== Requests =====
The API returns barlist data detecting / decoding barcodes inside. You send the barlist in various formats:
  * [[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)

This document describes the required format of the URLs and parameters available.

A URL request to the service must be in the following form:
<code>
http://cloud.bacad.ch/steellist.php?parameters
ou
https://cloud.bacad.ch/steellist.php?parameters (secure SSL connection)
</code>

==== Parameters ====
Except for the document, each parameter can be specified either in the URL (method [[wp>GET_(HTTP)|GET]]) and then posted as given (method [[wp>POST_(HTTP)|POST]]). The parameters are:
  * ''format'': output format
  * ''uploadedfile'': document
  * output options

=== Output format ===
Output format is specified by the parameter '''format'''. The API actually support the following output formats:
  * **xml** returns the results in XML form in a content node <SteelListResponse>
  * **abs** (**A**llgemeine-**B**ewehrungs-**S**chnittstelle) returns the results as ASCII (according the standard [[http://www.bvbs.de|BVBS]])

=== Document ===
The document must be sent to the site according to the method [[wp>POST_(HTTP)|POST]] of the HTTP protocol, identified by '''uploadedfile'''.

=== Output options ===
Output options allow to enable/disable generation of additional data within the result:
  * Parameter '''posBvbs'''  equals '1' indicates that the service should include BVBS data (for each bar)
  * Parameter '''barXml''' equals '1' indicates that the service should include XML data (for each bar)

===== Replies =====
==== XML ====
For each valid request, the service returns a response'' 'SteelListResponse''' in the format specified in the request URL. Each response contains the following:
  * A status code **status**, which could be:
    * ''OK'' indicating that the request was successful
    * ''AUTH_FAILED'' indicating that the user ID has failed (pair user/password)
    * ''INVALID_REQUEST'' indicating that the request was not well-formatted
    * ''INVALID_API_KEY'' indicating that the key to use the API is incorrect
    * ''INVALID_FILE_TYPE'' indicating the type of the posted file is supported
    * ''FILE_OVER_SIZE_LIMIT'' indicating that the posted file is too large (oversized)
    * ''FILE_UPLOAD_ERROR'' indicating a download error
    * ''INTERNAL_ERROR'' indicating an internal error of the service
    * ''UNKNOWN_ERROR'' indicating an unknown error
  * An item ''document'' containing the items describing the project properties
    * An item ''project'' indicating the project's name
    * An item ''division'' indicating the division's name
  * A table of results (**pages**) containing:
    * An item ''num'' indiquant le numéro de la page
    * An item ''thumbnail'' indiquant l'URL (partiel) vers l'aperçu (image) de la page
    * A table of positions (**pos**) containing:
      * An item ''num'' indicating the number of the position
      * An item ''bvbs'' indicating the [[http://www.bvbs.de|BVBS]] code of the position
      * An item ''bar'' containing the items describing the characteristics of the bar
        * An item ''type'' indicating the type of the bar 2D, 3D, etc. Values could be the followings:
          * ''BF2D'' indicating une bar 2D
          * ''BF3D'' indicating une bar 3D
          * ''BFWE'' indicating une barh helix
        * A table of items ''dimension'' containing the items describing each bar's segement (according to its type)
          * Bar 2D
            * An item ''length'' indicating the length of the segment
            * An item ''radius'' indicating the radius of an arc segment (0 if straght segment)
            * An item ''angle'' indicating the angle value between the segement and the previous segment
          * Bar 3D
            * An item ''x'' indicating the first component of the vector of the segment
            * An item ''y'' indicating the second component of the vector of the segment
            * An item ''z'' indicating the third component of the vector of the segment
          * Bar helix
            * An item ''radius'' indicating the radius of the circle described by the helix
            * An item ''number'' indicating the number of loops described by the helix
            * An item ''spacing'' indicating the spacing between each rotations described by the helix

==== Examples ====
Here an example of an Xml reply:
<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>

The format of the bar's dimensions depends on the type of the bar:
Here an example for standard bar in 2D (type BF2D):
<code xml>
<dimension>
   <length>500</length>
   <radius>250</radius>
   <angle>45</angle>
</dimension>
</code>

Here an example for standard bar in 3D (type BF3D):
<code xml>
<dimension>
   <x>0</x>
   <y>0</y>
   <z>300</z>
</dimension>
</code>

Here an example for helix (type BFWE):
<code xml>
<dimension>
   <radius>200</radius>
   <number>6</number>
   <spacing>200</spacing>
</dimension>
</code>

ABS example:
<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 =====
A Html page is available for service tests: [[http://cloud.bacad.ch|clic here]].