La API de BuroTex trata de dar un acceso universal a sus servicios de forma programática, con el objetivo de integrarlos allá donde sea necesario. La API tiene las siguientes características generales:
A continuación se detallan los requisitos que son necesarios para utilizar la API de BuroTex:
Para ilustrar las peticiones a la API se utilizarán ejemplos basados en curl, fácilmente extrapolables a otras herramientas. Se aconseja probar las peticiones a la API con este tipo de herramientas antes de la implementación de los servicios.
Content-Type: application/json Accept: application/jsonPor ejemplo, en curl, se escribiría:
-H "Content-Type:application/json" -H "Accept:application/json"
{"token": "TOKEN"}
Por ejemplo, en curl, se escribiría:
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
Si el token proporcionado no fuera válido, se muestra un error autoexplicativo:
{"result": "ko", "errors": "API token no reconocido"}
Authorization:Basic USER_PWD_BASE64El valor de USER_PWD_BASE64 depende de cada cuenta y tiene una estructura muy sencilla. Se debe concatenar la dirección de correo del usuario seguido de su contraseña de acceso, separado por dos puntos, sin espacios intermedios. Una vez hecho esto se debe convertir a Base64, obteniendo una cadena de caracteres codificada, que es la que se debe utilizar:
BASE64(usuario@correo.es:contraseña) ===> dXN1YXJpb0Bjb3JyZW8uZXM6Y29udHJhc2XDsWE=Por ejemplo, en curl, se escribiría:
-H "Authorization:Basic dXN1YXJpb0Bjb3JyZW8uZXM6Y29udHJhc2XDsWE="De forma más legible, curl permite indicar lo mismo sin tener que hacer la conversión a Base64:
-u "usuario@correo.es:contraseña"Si no fuera posible identificar al usuario en el sistema, se muestra un error autoexplicativo según corresponda:
{"errors": {"reason": "El usuario y/o la contraseña son incorrectos."}}
{"errors": {"reason": "Debes entrar como usuario registrado antes de continuar."}}
Aquí se detallan todas las peticiones disponibles en el servicio web de BuroTex:
URL: /usuarios
Método HTTP: POST
Cabeceras: Content-Type: application/json, Accept: application/json
Parámetros: {"user": {"email": "EMAIL", "password": "CLAVE", "password_confirmation": "CLAVE"}}
Parámetros adicionales: {"token": "TOKEN"}
Requisitos: email válido, clave mínima de 6 caracteres.
Por ejemplo, en curl se podría escribir así una petición completa de prueba:
curl -X POST -k
-H "Content-Type:application/json" -H "Accept:application/json"
-d "{\"user\": {\"email\": \"usuario@correo.es\",
\"password\": \"12345678\", \"password_confirmation\": \"12345678\"},
\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios
Si el usuario se crea correctamente, el servicio web responde con éxito. Esta respuesta será siempre la misma para todas las operaciones satisfactorias sobre la API que no devuelvan ninguna información adicional:
{"result": "ok"}
Los errores posibles en la petición son autoexplicativos, y tienen un formato uniforme:
{"result": "ko", "errors": {"password": "Demasiado corta"}}
{"result": "ko", "errors": {"password": "No coincide", "password": "Demasiado corta"}}
{"result": "ko", "errors": {"email": "Este email ya existe y pertenece a otro usuario"}}
{"result": "ko", "errors": {"email": "Formato inválido"}}
URL: /usuarios/entrar
Método HTTP: POST
Cabeceras: Content-Type: application/json, Accept: application/json
Parámetros: {"user": {"email": "EMAIL", "password": "CLAVE"}}
Parámetros adicionales: {"token": "TOKEN"}
Requisitos: combinación válida de usuario y contraseña.
Por ejemplo, en curl se podría escribir así una petición de acceso al sistema:
curl -X POST -k
-H "Content-Type:application/json" -H "Accept:application/json"
-d "{\"user\": {\"email\": \"usuario@correo.es\", \"password\": \"12345678\"},
\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios/entrar
Cuando el usuario ha accedido correctamente, el servicio web responde con éxito. Si no fuera posible acceder al sistema, se muestra un error autoexplicativo:
{"errors": {"reason": "El usuario y/o la contraseña son incorrectos."}}
Ya que en todas las peticiones de la API especifican un usuario del sistema explícitamente y se deben hacer las peticiones de forma independiente, esta petición de acceso al sistema se puede emplear sobre todo para conocer si el usuario en cuestión ya está dado de alta o no.
URL: /usuarios/datos
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente
Por ejemplo, en curl se podría consultar la información de la cuenta de un usuario:
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios/datos
Los datos de la cuenta se reciben en este formato:
{
"editURL": "http://burotex.com/usuarios/editar?auth_token=AUTH_TOKEN",
"recargaURL": "http://burotex.com/credito/nuevo?auth_token=AUTH_TOKEN",
"info": [
{
"title": "Tus datos",
"rows":[
{"value": "usuario@correo.es", "key": "Tu correo"},
{"value": "3,00€", "key": "Tu saldo"},
{...}
]
},
{...}
]
}
Además se tiene acceso a dos URLs muy útiles. La primera, editURL da acceso directo al usuario en cuestión a la página de edición de su propia cuenta. En el segundo caso, se puede incrementar el saldo de la cuenta visitando recargaURL. En ambos casos, al disponer de un AUTH_TOKEN, se permite el acceso inmediato al contenido sin tener que identificarse nuevamente. Estos tokens varían periódicamente para aumentar la seguridad.
URL: /usuarios
Método HTTP: PUT
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"user": {"email": "NUEVOEMAIL", "current_password": "CLAVE",
"password": "NUEVACLAVE", "password_confirmation": "NUEVACLAVE"}}
Parámetros adicionales: {"token": "TOKEN"}
Requisitos: usuario identificado, nuevo email válido y nueva clave mínima de 6 caracteres
Como es una petición que requiere un usuario registrado, es imprescindible añadir la cabecera de Authorization. El valor de USER_PWD_BASE64 se consigue según lo indicado
anteriormente.
curl -X PUT -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"user\": {\"email\": \"usuarionuevo@correo.es\", \"current_password\": \"12345678\",
\"password\": \"87654321\", \"password_confirmation\": \"87654321\"},
\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios
Si no fuera posible realizar la modificación, se muestran los correspondientes errores autoexplicativos:
{"result": "ko", "errors": {"current_password": "Requerido"}}
{"result": "ko", "errors": {"current_password": "Esta no es tu clave"}}
{"result": "ko", "errors": {"password": "Demasiado corta"}}
{"result": "ko", "errors": {"password": "No coincide"}}
URL: /usuarios/saldo
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente
Por ejemplo, en curl se podría conocer el saldo de un usuario así:
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios/saldo
La información del mensaje se devuelve con este formato:
{
"cash": {"currency": "EUR", "cents": "7200"},
"rechargeURL": "http://burotex.com/credito/nuevo?auth_token=AUTH_TOKEN"
}
Además del saldo del usuario, se proporciona la URL de recarga, incluyendo un AUTH_TOKEN exclusivo, de forma que si se visita dicha dirección, el usuario en cuestión ya estaría logado en el sistema y podría recargar su saldo inmediatamente. Este token varía periódicamente para aumentar la seguridad.
URL: /mensajes
Método HTTP: POST
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"message": {"body": "MENSAJE", "destination": "MOVIL_DESTINATARIO",
"name" : "PERSONA_REMITENTE", "dni": "NIF_REMITENTE"}}"
Parámetros adicionales: {"token": "TOKEN"}
Parámetros opcionales: {"message": {"company_sender": "EMPRESA_REMITENTE",
"nif_sender": "NIF_EMPRESA_REMITENTE"},
"destination_name" :"NOMBRE_DESTINATARIO"}}"
Requisitos: un número válido de móvil del destinatario, un mensaje máximo de 706 caracteres
y el nombre y el nif del remitente, ambos presentes.
Como es una petición que requiere un usuario registrado, es imprescindible añadir la cabecera de Authorization. El valor de USER_PWD_BASE64 se consigue según lo indicado
anteriormente.
curl -X POST -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"message\": {\"body\": \"Mensaje de prueba\", \"destination\": \"666666666\",
\"name\": \"Juan Pruebas\", \"dni\": \"00000000X\",
\"company_name\": \"Empresa de Juan\", \"nif_sender\": \"B00000000\",
\"destination_name\": \"Nombre destinatario de Juan\"},
\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/mensajes
Cuando el BuroTex se ha enviado correctamente, el servicio web responde con éxito, indicando que se refiere a una acción relacionada con un mensaje, a diferencia de otras respuestas, que se pueden referir por ejemplo al acceso y modificación de cuentas de usuario. Además, se obtiene el identificador único del mensaje, con el cual es posible
consultar el estado
y
descargar el certificado asociado.
{"result": "ok", "relation": "message", "id": "33220"}
Inmediatamente después del envío exitoso, se pone marcha un proceso que consulta periódicamente su estado en la red móvil. Una vez que el sistema posee un estado final de entrega o no entrega, el usuario recibe un correo electrónico con la notificación exclusiva que incluye el acceso personalizado al certificado en PDF, el cual ha sido expedido en ese mismo instante por RedAbogacía (Consejo General de la Abogacía Española). En el caso del entorno de pruebas para la API, esta notificación no se recibe nunca, ya que el envío del BuroTex no se realiza en ningún caso, sino que simplemente se simula, una vez que los requisitos de envío se han cumplido.
{"result": "ko", "errors": {"name": "Requerido", "dni": "Requerido", "destination": "Requerido",
"destination": "Inválido", "body": "Requerido"}, "relation": "message"}
{"result": "ko", "errors": "Mensaje demasiado largo, reduce su tamaño", "relation": "message"}
En el caso de un mensaje demasiado largo, conviene tener en cuenta que el texto del mensaje se conforma con partes fijas y variables. Cada mensaje consta de una cabecera, un cuerpo y un apéndice final. La cabecera se redacta formalmente en función de si se incluyen o no los parámetros opcionales: empresa remitente, nif de empresa remitente y nombre del destinatario. En todo caso, la cabecera incluye el nombre de la persona remitente, así como su nif. El apéndice final hace referencia al servicio de SMS certificados de BuroTex.com. El cuerpo es el espacio restante hasta un máximo de 706 caracteres, que es el máximo que el sistema puede enviar en la actualidad.
{"result": "ko", "url": "http://burotex.com/credito/nuevo?auth_token=AUTH_TOKEN",
"code": -1, "errors": "Has agotado tu crédito. Increméntalo via web", "relation": "message"}
Este mensaje de error ha de ser explicado más profundamente al ser más complicado que los demás. Existen dos campos adicionales respecto a otros mensajes de error:
URL: /vistaprevia
Método HTTP: POST
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"message": {"body": "MENSAJE", "name" : "PERSONA_REMITENTE", "dni": "NIF_REMITENTE"}}"
Parámetros adicionales: {"token": "TOKEN"}
Parámetros opcionales: {"message": {"company_sender": "EMPRESA_REMITENTE",
"nif_sender": "NIF_EMPRESA_REMITENTE"},
"destination_name" :"NOMBRE_DESTINATARIO"}}"
Requisitos: mensaje máximo de 706 caracteres, nombre y nif del remitente, ambos presentes.
Como es una petición que requiere un usuario registrado, es imprescindible añadir la cabecera de Authorization. El valor de USER_PWD_BASE64 se consigue según lo indicado
anteriormente.
curl -X POST -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"message\": {\"body\": \"Prueba\", \"name\": \"Juan Pruebas\", \"dni\": \"00000000X\"},
\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/vistaprevia
El resultado obtenido contiene la longitud del mensaje escrito, los caracteres disponibles restantes, el coste del mensaje si se llegara a enviar y la vista previa en sí misma.
{
"size": 6,
"max_chars_left": 679,
"cost": "3,00€",
"preview": "Juan Pruebas, con NIF 00000000X, le comunica: Prueba [SMS Certificado - burotex.com]"
}
Hay tener en cuenta que el texto del mensaje se conforma con partes fijas y variables. Cada mensaje consta de una cabecera, un cuerpo y un apéndice final. La cabecera se redacta formalmente en función de si se incluyen o no los parámetros opcionales: empresa remitente, nif de empresa remitente y nombre del destinatario. En todo caso, la cabecera incluye el nombre de la persona remitente, así como su nif. El apéndice final hace referencia al servicio de SMS certificados de BuroTex.com. El cuerpo es el espacio restante hasta un máximo de 706 caracteres, que es el máximo que el sistema puede enviar en la actualidad.
{
'relation': 'preview',
'result': 'ko',
'errors': 'Faltan parámetros obligatorios'
}
URL: /mensajes
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente
Por ejemplo, en curl se consultaría el histórico de envíos de esta forma:
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/mensajes
El listado de mensajes del usuario se devuelve con una estructura predefinida. Además, están ordenados según fueron enviados, estando primero el más reciente:
{"info":
[
{
"id": "2",
"title": "13-09-2011 17:01",
"rawtitle": "2011-09-13T17:01:19+02:00",
"rows": [
{"key": "destination", "value": "666666666", "label": "Destino"},
{"key": "livestatus", "value": "PENDIENTE DE ENTREGA", "label": "Estado"},
{"key": "body", "value": "Mensaje de prueba", "label": "Mensaje"}
]
},
{
"id": "1",
"title": "11-09-2011 12:13",
"rawtitle": "2011-09-11T12:13:19+02:00",
"rows": [
{"key": "destination", "value": "666666667", "label": "Destino"},
{"key": "livestatus", "value": "ENTREGADO AL USUARIO", "label": "Estado"},
{"key": "body", "value": "Mensaje de prueba 2", "label": "Mensaje"}
]
},
{...}
]
}
La fecha indicada se refiere a la fecha de envío del mensaje. En cuanto al estado en el que se encuentra, cada vez que se consulte el histórico se actualiza con la información proporcionada por el servidor, pudiendo acceder así a la información en tiempo real.
URL: /mensajes/:id
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente, id de mensaje existente y perteneciente al usuario
El id del mensaje identifica unívocamente al mensaje y se debe añadir a la URL. El id de cada mensaje se puede obtener del
histórico de envíos
o del mensaje de ok de
enviar un BuroTex.
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/mensajes/33220
La información del mensaje se devuelve con este formato:
{
"datetime": "11-09-2011 12:13",
"body": "Mensaje de prueba",
"destination": "666666666",
"livestatus": "ENTREGADO AL USUARIO"
}
La fecha indicada se refiere a la fecha de envío del mensaje. En cuanto al estado en el que se encuentra, cada vez que se consulte el estado se actualiza, obteniendo así la información en tiempo real. Para el entorno de pruebas de la API siempre se devolverá el estado "MENSAJE NO PROCESADO".
{:result => :ko, :errors => "Mensaje no existente", :relation => "message"}
{:result => :ko, :errors => "Mensaje no perteneciente al usuario indicado", :relation => "message"}
URL: /usuarios/remitente
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente
Por ejemplo, en curl se podría consultar el último remitente de la siguiente forma:
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/usuarios/remitente
El último remitente se recibe con este formato, devolviendo su nombre y su nif, que son los campos obligatorios para un nuevo BuroTex:
{"name": "Juan Pruebas", "nif": "00000000X", "tariff1": "3€", "tariff2": "4€", "relation": "sender"}
Como puede apreciarse, además de obtener los datos del remitente, también accedemos a las dos bandas de precios que existen en BuroTex. Esto puede ser útil a la hora de hacer cálculos de número de caracteres empleados al enviar un BuroTex, si fuera necesario. Como se indicaba anteriormente en la
petición de envío de un BuroTex,
el mensaje corto (tariff1) tiene un máximo de 246 caracteres y el mensaje largo (tariff2) tiene un máximo de 706 caracteres.
Además, se indica que la información está relacionada con el remitente (sender) a diferencia de otras peticiones de la API, en que se indica otro valor.
URL: /mensajes/:id/pdf
Método HTTP: GET
Cabeceras: Content-Type: application/json, Accept: application/json
Cabecera adicional: Authorization:Basic USER_PWD_BASE64
Parámetros: {"token": "TOKEN"}
Requisitos: usuario existente, id de mensaje existente y perteneciente al usuario
El id del mensaje identifica unívocamente al mensaje y se debe añadir a la URL. El id de cada mensaje se puede obtener del
histórico de envíos
o del mensaje de ok de
enviar un BuroTex.
curl -X GET -k
-H "Content-Type:application/json" -H "Accept:application/json"
-u "usuario@correo.es:contraseña"
-d "{\"token\": \"9c644785115455c1af4d13626acad4fd\"}"
https://burotex.com/mensajes/33220/pdf
La información de la descarga se devuelve con este formato:
{
"date": "03-10-2011 18:50",
"rawdate": "2011-10-03T18:50:03+02:00",
"pdfURL": "http://assets.burotex.com/csv/2011/10/3201103231652101611_1264773834054270332.pdf"
}
La fecha indicada se refiere a la fecha de recuperación del certificado. La fecha de entrega del mensaje será parte del contenido del PDF, así como el destinatario y el contenido del mismo. En cuanto a pdfURL es la URL personalizada de descarga directa del certificado. Para el entorno de pruebas de la API siempre se devolverá el mismo valor, un PDF de prueba disponible
aquí.
{:result => :ko, :errors => "Mensaje no existente", :relation => "message"}
{:result => :ko, :errors => "Mensaje no perteneciente al usuario indicado", :relation => "message"}
BuroTex es tu proveedor de SMS certificados con custodia. Y éstas son nuestras condiciones de uso y política de privacidad.
Ofrecemos nuestros servicios con la garantía de nuestro socio tecnológico RedAbogacía, empresa del Consejo General de la Abogacía Española.
Escríbenos en cualquier momento a info@burotex.com. Te escucharemos y nos adaptaremos a tus necesidades. No lo dudes.