Nuestra API está basada en el protocolo REST, soporta tanto peticiones GET como POST, PUT y DELETE. En cada petición se deberá indicar como mínimo el método solicitado, por ejemplo:

http://api.bidobido.com:81/envios/hacerEnvio
http://api.bidobido.com:81/envios/consultarPrecioAgencia

• Entendemos por salida la respuesta del API a una petición.
• Entendemos por entrada la petición (o pregunta) al API.
• Los parámetros requeridos para que el método se ejecute han de enviarse en formato urlencode():

foo%26bar=some%3Dweird%2Fvalue

• En las cabeceras de la petición se indicarán tanto idioma como codificación y formato de salida, por ejemplo:

Accept: text/php,application/xml;q=0.5
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Accept-Language: es,en;q=0.5

• Las peticiones de tipo GET suelen usarse para consultas simples (select), las POST para inserciones (insert), las PUT para actualizaciones (updates) y las DELETE para eliminar (delete).

El API intentará devolver códigos HTTP apropiados para cada petición. El listado de los códigos es el siguiente:

• 200 OK: Todo correcto.
• 401 Unauthorized: Se han perdido las credenciales de autentificación o han sido incorrectas.
• 403 Forbidden: La petición ha sido entendida pero se ha rechazado. Un mensaje de error explicará el motivo del mismo. Este código de error normalmente es debido a una imposición de límites de peticiones por usuario.
• 404 Not Found: La petición está llamando a un método que no existe.
• 500 Internal Server Error: Algo se ha roto. Ponte en contacto con nosotros para ver el problema.
• 502 Bad Gateway: BidoBido está caído o en tareas de mantenimiento.

El API permite únicamente como formato de entrada parámetros a través de urlencode() mediante peticiones GET, POST, PUT y DELETE. Un ejemplo de petición sería el siguiente:

POST /envios/hacerEnvio HTTP/1.1\r\n
Host: api.bidobido.com\r\n
Accept: text/php,application/xml;q=0.9,text/plain;q=0.8\r\n
Accept-Language: es, en;q=0.50\r\n
Accept-Encoding: utf-8\r\n
WWW-Authenticate: Digest username="usuario", realm="secreto", nonce="4ea6751ea9cea", uri="/envios/consultarPrecio/", cnonce="MTI3NDQ0", nc="00000001", qop="auth", response="eaeaacadb7624deaeac9ee6d299eeaea", opaque="eaea994dcaeaeabc94eaea03b1eaea70"\r\n
Content-Type: application/x-www-form-urlencoded\r\n
Content-Length: 31\r\n
Connection: Close\r\n\r\n
foo%26bar=some%3Dweird%2Fvalue

• Accept: Especifica el formato en el que se devolverá la salida. Los formatos disponibles son los siguientes:

text/php (por defecto)
application/xml
text/xml
application/json
text/json
application/vnd.php.serialized
text/plain
text/html
application/csv

• Accept-Language: Especifica el idioma en el que se devolverá la salida. Los idiomas disponibles son los siguientes: es.
• Accept-Encoding: Especifica la codificación de la salida. Codificaciones disponibles: utf-8 e iso-8859-1.
• Content-Type: Especifica el formato de los parámetros de entrada, application/x-www-form-urlencoded (urlencode).
• Content-Lenght: Tamaño de los datos enviados (número de caracteres).
• WWW-Authenticate: String de identificación y validación (en caso de requerirlo el método).

• Los datos se pueden devolver en diferentes formatos según hemos visto en el apartado anterior, basta con indicarlo en su cabecera correspondiente. A continuación se detallan varios ejemplos de salida:

a:1:{s:10:"respuestas";a:1:{s:9:"respuesta";a:4:{i:0;a:6:{s:6:"nombre";s:3:"UPS";s:2:"id";i:1;s:8:"etiqueta";i:1;s:6:"seguro";i:1;s:6:"precio";s:4:"9.01";s:6:"moneda";s:3:"EUR";}i:1;a:6:{s:6:"nombre";s:16:"Tourline Express";s:2:"id";i:3;s:8:"etiqueta";i:0;s:6:"seguro";i:0;s:6:"precio";s:4:"8.10";s:6:"moneda";s:3:"EUR";}i:2;a:5:{s:6:"nombre";s:12:"Tourline 96H";s:2:"id";i:7;s:8:"etiqueta";i:0;s:6:"seguro";i:0;s:5:"error";a:2:{s:2:"id";i:112;s:5:"texto";s:39:"El paquete supera el peso máximo: 5 Kg";}}i:3;a:6:{s:6:"nombre";s:3:"DHL";s:2:"id";i:8;s:8:"etiqueta";i:0;s:6:"seguro";i:0;s:6:"precio";s:4:"7.78";s:6:"moneda";s:3:"EUR";}}}}

Array
(
    [respuestas] => Array
        (
            [respuesta] => Array
                (
                    [0] => Array
                        (
                            [nombre] => UPS
                            [id] => 1
                            [etiqueta] => 1
                            [seguro] => 1
                            [precio] => 9.01
                            [moneda] => EUR
                        )
 
                    [1] => Array
                        (
                            [nombre] => Tourline Express
                            [id] => 3
                            [etiqueta] => 0
                            [seguro] => 0
                            [precio] => 8.10
                            [moneda] => EUR
                        )
 
                    [2] => Array
                        (
                            [nombre] => Tourline 96H
                            [id] => 7
                            [etiqueta] => 0
                            [seguro] => 0
                            [error] => Array
                                (
                                    [id] => 112
                                    [texto] => El paquete supera el peso máximo: 5 Kg
                                )
 
                        )
 
                    [3] => Array
                        (
                            [nombre] => DHL
                            [id] => 8
                            [etiqueta] => 0
                            [seguro] => 0
                            [precio] => 7.78
                            [moneda] => EUR
                        )
 
                )
 
        )
 
)

<respuestas>
	<respuesta>
		<nombre>UPS</nombre>
		<id>1</id>
		<etiqueta>1</etiqueta>
		<seguro>1</seguro>
		<precio>9.01</precio>
		<moneda>EUR</moneda>
	</respuesta>
	<respuesta>
		<nombre>Tourline Express</nombre>
		<id>3</id>
		<etiqueta>0</etiqueta>
		<seguro>0</seguro>
		<precio>8.10</precio>
		<moneda>EUR</moneda>
	</respuesta>
	<respuesta>
		<nombre>Tourline 96H</nombre>
		<id>7</id>
		<etiqueta>0</etiqueta>
		<seguro>0</seguro>
		<error>
			<id>112</id>
			<texto>El paquete supera el peso máximo: 5 Kg</texto>
		</error>
	</respuesta>
	<respuesta>
		<nombre>DHL</nombre>
		<id>8</id>
		<etiqueta>0</etiqueta>
		<seguro>0</seguro>
		<precio>7.78</precio>
		<moneda>EUR</moneda>
	</respuesta>
</respuestas>

A través de la cabecera Accept-Language puedes seleccionar el idioma de salida. El idioma por defecto del API es el castellano. Listado de idiomas soportados:

• es (castellano)

A través de la cabecera Accept-Encoding puedes seleccionar la codificación de salida. La codificación por defecto del API es utf-8. Listado de codificaciones soportadas:

• utf-8
• iso-8859-1

Existe un número limitado de peticiones al API. Este límite está impuesto para garantizar la calidad del servicio, la función que lo impone es dinámica de forma que el límite puede variar ligeramente en función al uso que cada cliente exija. Las peticiones que excedan el límite mostrarán un código de estado:

• 403 Forbidden: La petición ha sido entendida pero se ha rechazado. Un mensaje de error explicará el motivo del mismo. Este código de error normalmente es debido a una imposición de límites de peticiones por usuario.

Si alguna vez recibes una respuesta del tipo 403 deberás ser paciente puesto que has alcanzado el límite. El tiempo de restricción es proporcional al número de respuestas 403 recibidas (a más peticiones denegadas, mayor tiempo de baneo).

El método de identificación y validación usado es Auth-Digest. Este método trata de generar varias keys en función a parámetros como el usuario, contraseña, método de la petición (url)… En base a parámetros como los siguientes:

username="usuario",
realm="secreto",
nonce="4ea6751ea9cea",
uri="/envios/consultarPrecio/",
cnonce="MTI3NDQ0",
nc="00000001",
qop="auth",
response="eaeaacadb7624deaeac9ee6d299eeaea",
opaque="eaea994dcaeaeabc94eaea03b1eaea70"

Se crean keys de este tipo, que serán las encargadas de identificar y validar la petición:

$A1 = md5('usuario:key_api:password');
$A2 = md5('http://api.bidobido.com:envios/hacerEnvio');
$response_valido = md5($A1.':'.$digest['nonce'].':'.$digest['nc'].':'.$digest['cnonce'].':'.$digest['qop'].':'.$A2);

Si estás empezando o vas a empezar a utilizar nuestra API quizás deberías familiarizarte con nuestro FAQ (Preguntas Frecuentes), saber que existe y que puedes contribuir con tus propias cuestiones a enriquecer el conocimiento del mismo.