API: Conceptos básicos de desarrollo

Peticiones HTTP

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).

Códigos de respuesta HTTP

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.

Formatos de Entrada

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).

Formatos de Salida

  • 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:

text/php (serializado)

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";}}}}

text/php (no serializado)

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
                        )
 
                )
 
        )
 
)

application/xml

<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>

Idioma

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)

Codificación

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

Límites

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).

Identificación y Validación

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);

Códigos de error

N errorMensaje
49555450 Tracking sin id de envío asociado
50525353 El paquete supera el peso volumétrico máximo: alto*ancho*largo >
50535155 El paquete supera el peso máximo: %d Kg
50535198 Faltan datos en la dirección de envío
50565449 No tenemos datos para ese envío
52995254 Faltan datos en la dirección de envío origen
52999953 Error código zona envío destino
54575153 El paquete tiene Alto o Ancho o Largo mayor a 350cm
55485750 El paquete tiene Ancho menor a 1cm
56515198 Fallo al intentar generar envío
57485256 El paquete supera el peso volumétrico máximo: alto+ancho+largo >
57525449 El paquete tiene peso menor a 1Kg
97525198 Sin datos
97549752 Error código zona envío origen
98495299 Error al grabar el envío en fichero. Id envío desconocido.
98515697 Uno de los paquetes supera el peso volumétrico máximo: ( %d * %d * %d) / %d > %d Kg
99515749 Error en el formato del teléfono destino
101505455 Error en la poblacion destino. País: %s Población: %s Código postal: %s
102539799 El paquete supera el peso volumétrico máximo: %d Kg
499910053 Error en el formato del teléfono origen
505510054 Error en la poblacion origen. País: %s Población: %s Código postal: %s
521005153 Error en la delegación, código postal: %s pais: %s
524949102 Error en los datos de los Paquetes
525257100 No tenemos tarifa para el código postal (origen - destino)
545552102 Error al grabar la etiqueta en el fichero.
555710197 Error código pais origen
565510151 Error código pais destino
569753102 No tenemos datos para ese tracking
571029857 Error al grabar el envío en fichero.
971019797 Error en los datos de la dirección origen
981005398 Error en los datos de la dirección destino
985310048 Error al calcular el peso del envio
995054101 Faltan datos en la dirección de envío destino
1015448102 El paquete tiene Largo menor a 1cm
5210057102 Sin información
5210148102 Error al calcular los gastos de envío
5510210155 El paquete tiene Alto menor a 1cm
5710010256 Error en el código aeropuerto destino
%s y %d serán cambiados los números de los tamaños y los pesos que se usen al llamar al api.
 

Existe un FAQ

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.

~~DISCUSSION:off~~