Recursos públicos y privados

Según la criticidad y confidencialidad de los datos de la API, estos serán accesibles públicamente o no.

Recursos Públicos

Los recursos públicos son aquellos a los que puede acceder cualquier persona que conozca la url del recurso. Por ejemplo, entrando a sites verás todos los países en los que funciona MercadoLibre, y si conoces el Id de un usuario, podrás acceder a los datos que compartimos de manera pública, que son los mismos que se visualizan navegando el sitio: apodo, fecha de registración, país, ciudad, etc.

Recursos Privados

Algunos datos deben permanecer ocultos para la mayoría, para acceder a ellos es necesario realizar el flujo de autenticación y solicitar permisos a los usuarios a los cuales pertenecen para poder ver y modificar sus datos, así como realizar acciones en su nombre.



Siguiente
Consideraciones de diseño.

Please rate this

Autenticación y Autorización

La plataforma de Mercado Libre te permite trabajar con recursos públicos y privados de la API a través de llamadas HTTP con los verbos GET, PUT, POST, DELETE y OPTIONS.
El acceso a los recursos públicos, tales como sites y categories disponibles, se puede hacer en forma anónima pero los recursos privados y las acciones propias de los usuarios como publicar un artículo, responder preguntas o ver la información de ventas/compras requieren autorización mediante una aplicación.
Por tal motivo en la siguiente guía te explicaremos el significado de autenticación y el flujo de autorización que se debe seguir para obtener un access_token (llave de acceso a los recursos privados por cada usuario que autorice la aplicación- válida por 6 horas).
Por ejemplo:
Sin access_token (Recurso público)

https://api.mercadolibre.com/users/226384143/

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "country_id": "AR",
  "address": {
    "state": "AR-C",
    "city": "Palermo"
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "tags": [
    ]
  },
  "status": {
    "site_status": "active"
  }
}


Con access_token (Recurso privado)

 
 https://api.mercadolibre.com/users/226384143?access_token=$ACCESS_TOKEN

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_38730994@testuser.com",
  "identification": {
    "type": "DNI",
    "number": "1111111"
  },
  "address": {
    "state": "AR-C",
    "city": "Palermo",
    "address": "Test Address 123",
    "zip_code": "1414"
  },
  "phone": {
    "area_code": "01",
    "number": "1111-1111",
    "extension": "",
    "verified": false
  },
  "alternative_phone": {
    "area_code": "",
    "number": "",
    "extension": ""
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "shipping_modes": [
    "custom",
    "not_specified"
  ],
  "seller_experience": "ADVANCED",
  "bill_data": {
    "accept_credit_note": null
  },
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "canceled_transactions": 0,
    "transactions": {
      "period": "historic",
      "total": null,
      "completed": null,
      "canceled": {
        "total": null,
        "paid": null
      },
      "unrated": {
        "total": null,
        "paid": null
      },
      "not_yet_rated": {
        "total": null,
        "paid": null,
        "units": null
      }
    },
    "tags": [
    ]
  },
  "status": {
    "site_status": "active",
    "list": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "buy": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "sell": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "billing": {
      "allow": true,
      "codes": [
      ]
    },
    "mercadopago_tc_accepted": true,
    "mercadopago_account_type": "personal",
    "mercadoenvios": "not_accepted",
    "immediate_payment": false,
    "confirmed_email": false,
    "user_type": "simple_registration",
    "required_action": ""
  },
  "credit": {
    "consumed": 101.1,
    "credit_level_id": "MLA1"
  }
}

Contenidos:

Autenticación

La autenticación es el acto o proceso para el establecimiento o confirmación de algo o alguien como real.
En el caso de la autenticación de una persona consiste en verificar su identidad en función a uno o varios factores asegurando que los datos de quién los envió sean los correctos.

Algunos métodos de autenticación son:

  • Biomédicas, por huellas dactilares, retina del ojo, etc.
  • Tarjetas inteligentes que guardan información de los certificados de un usuario.
  • Métodos clásicos basados en contraseña.
  • Por ejemplo, para ingresar a Mercado Libre nos autenticamos a través del login (usuario y contraseña).

login

Autorización

La autorización es el proceso por el cual permitimos a alguien o a algo acceder a recursos privados.
Dentro de la autorización se deberá definir qué recursos y qué operaciones se pueden realizar ya que no es lo mismo otorgar permisos de sólo lectura, que lectura y escritura.

¿Cómo logramos la autorización? A través del Protocolo OAuth 2.0, uno de los más utilizados en plataforma abiertas (Twitter, Facebook, etc.) y método seguro para trabajar con recursos privados.

OAuth nos brinda:

  • Confidencialidad, el usuario no deberá revelar su clave en ningún momento.
  • Integridad, sólo podrán ver datos privados aquellas aplicaciones que tengan el permiso de hacerlo.
  • Disponibilidad, los datos siempre estarán disponibles en el momento que se necesiten.

Dentro de este protocolo existen 4 modos de funcionamiento posibles denominados Grant Types:

– The Authorization Code Grant Type (Server Side)
– The Implicit Grant Type (Client Side)
– The Password Credentials Grant Type
– The Client Credentials Grant Type

Si bien cada uno de ellos es utilizado para diferentes propósitos dependiendo del servicio que se está construyendo a continuación sólo explicaremos los dos primeros ya que son los que te permitirán trabajar con nuestros recursos y generar herramientas para todos los usuarios de Mercado Libre.

Client-side

El flujo de autorización Client side es el adecuado para las aplicaciones que ejecutan código del lado del cliente, por ejemplo aplicaciones desarrolladas en lenguaje javascript/ajax, Angular o aplicaciones mobile.
Para conocer más detalles sobre este flujo te sugerimos ir al tutorial “Autorización Client-Side

Server-side

El flujo de autorización Server side es el más adecuado para las aplicaciones que ejecutan código del lado del servidor, por ejemplo aplicaciones desarrolladas en lenguaje como Java, Grails, Go, etc.

Nota: Esta opción te será de utilidad para aplicaciones que ejecutan cron jobs para actualizar stock de productos u operar sin que un usuario esté interactuando directamente con la aplicación.
Si deseas conocer más detalles sobre este flujo te sugerimos ir al tutorial “Autorización Server-Side

¡Obtén tu access_token!

Introduzca el ID de la aplicación que acaba de crear:

*Please enter a valid Application ID
Información del usuarioJSON Response

-

Uso de nuestros SDK

Mediante el uso de nuestros SDKs el proceso de autorización será más simple ya que te ahorrará la codificación de todo el protocolo OAuth de cero.
¡Nuestra comunidad ya los está utilizando!
Ofrecemos SDK para:

Si descubres una mejora o sugerencia puedes brindarla a la comunidad generando un Pull Request dentro de nuestro repositorio GitHub.

Consideraciones

Validez y expiración de tokens
Cuando obtienes un access_token, será válido de inmediato y se podrá utilizar para realizar solicitudes a la API durante un período limitado de 6 horas.
Existen eventos que pueden invalidar un access_token antes del tiempo de expiración. Por ejemplo: cambio de contraseña por parte del usuario, la actualización del App Secret por parte de una aplicación y, por supuesto, la revocación de permisos a tu aplicación por parte del usuario.

Referencia de códigos de error

Error Mensaje de error Posible solución
invalid_client

client_id o client_secret inválido.

El client_id y/o client_secret provisto es inválido. Controla la información de tu aplicación y verifica los parámetros client_id y client_secret
invalid_grant

Para crear un access token el usuario {0} debe tener una sesión activa o tu aplicación debe solicitar autorización para el alcance offline_access.

El otorgamiento de la autorización provista es inválido, expiró, fue revocado o no coincide con el URI de redireccionamiento utilizado en la solicitud de autorización. Verifica que el parámetro redirect_uri sea el mismo configurado en tu aplicación (Administrador de Aplicaciones); si esto no resuelve el problema, realiza una nueva solicitud para obtener un código nuevo.
invalid_grant

Error en la validación del otorgamiento. Es posible que tu código de autorización o refresh token haya expirado o que ya haya sido utilizado.

Expiró o ya fue utilizado. Realiza una nueva solicitud para obtener un nuevo código o refresh_token.
invalid_grant

El client_id no coincide con el original.

El ID de cliente no coincide. No se encontró el parámetro client_id; para obtener tu client_id, consulta tu aplicación (Administrador de Aplicaciones).
invalid_grant

El redirect_uri no coincide con el original.

El URl de redireccionamiento no coincide con el original. El parámetro redirect_uri no es el mismo configurado en tu aplicación; para obtener un redirect_uri, consulta tu aplicación (Administrador de Aplicaciones)
invalid_scope

Alcance inválido.

El alcance solicitado es inválido, desconocido o está mal formado. Los valores permitidos para el parámetro alcance son: “offline_access”,”write”,”read”.
invalid_request

Cantidad incorrecta de parámetros con valores duplicados.

La solicitud no incluye un parámetro obligatorio, incluye un parámetro o valor de parámetro no soportado o está mal formada de otro modo. Verifica que los parámetros enviados sean válidos y no estén duplicados.
unsupported_grant_type

Tipo de otorgamiento no soportado: ${0}.

El server de autorización no soporta el tipo de otorgamiento. Los valores permitidos para grant_type son “authorization_code” o “refresh_token”.
forbidden

La llamada no autorizada acceder a este recurso.

La llamada no autoriza el acceso Se está utilizando el token de otro usuario.



Siguiente:
Realiza pruebas.

Please rate this

Realiza pruebas


En MercadoLibre no contamos con un ambiente de test o sandbox para realizar pruebas, usamos usuarios de test y probamos directamente producción.

La ventaja de trabajar con un usuario de test es que puedes simular las mismas acciones permitidas para un usuario real: Publicar, actualizar datos, preguntar, responder, comprar, vender, calificar, etc – entre usuarios de test -, sin abonar cargos o recibir sanciones y, al mismo tiempo, evitando perjudicar la reputación de un usuario real.

Este tutorial te orientará para comenzar a trabajar con nuestra API mientras tu aplicación se encuentra en desarrollo.

Contenidos:

Crea un usuario de test

Para crear un usuario de test debes tener un token. Si aún no tienes tu access_token, comienza aquí: Guía de Autenticación y Autorización.
Lo único que debes enviar en el JSON es el país donde deseas operar. Consulta nuestra API de Sites para conocer el site_id perteneciente a cada país.

Ejemplo:

curl -X POST -H "Content-Type: application/json" -d
'{
   	"site_id":"MLA"
}'
https://api.mercadolibre.com/users/test_user?access_token=...

Respuesta:

{
	"id":120506781,
    "nickname":"TEST0548",
    "password":"qatest328",
    "site_status":"active"
}

¡Excelente! En la respuesta recibes el User_id, apodo, contraseña y estado actual de tu nuevo usuario de test.

Consideraciones

  • Puedes crear hasta 10 usuarios de test con tu cuenta de mercadolibre.
  • Los usuarios de test no estarán activos durante mucho tiempo, pero una vez que expiran, puedes crear nuevos.
  • Los artículos deben titularse “Item de Prueba – Por favor, NO OFERTAR”.
  • En la medida de lo posible, publica en la categoría “Otros”.
  • Nunca publiques en “gold” ni “gold_premium” para que no llegue a nuestra página de inicio.
  • Los usuarios de test solo pueden operar con artículos de prueba: los usuarios de test solo pueden comprar, vender y formular preguntas sobre artículos de prueba.
  • Los usuarios de test sin actividad (comprar, preguntar, publicar, etc.) durante 60 días se eliminan de inmediato.
  • Estos artículos se eliminan en forma periódica.

Compra y vende entre usuarios de test

Para simular compras entre usuarios de test puedes utilizar tarjetas de prueba.
Nota: Ten en cuenta que los datos que deberás cargar son ficticios y que por seguridad no agregamos los nombres de los bancos en las tarjetas disponibles para hacer pruebas.


Siguiente:
Administra tus proyectos y aplicaciones.

Please rate this

Administra tus proyectos y aplicaciones

Como se ha explicado anteriormente, es necesario registrar una aplicación para poder conectarse con nuestra API. Dado que muchos desarrolladores poseen más de una aplicación existe la posibilidad de crear un proyecto como una forma de vincular todas las aplicaciones de las que son propietarios además, de esta manera podemos hacer un seguimiento.
La única forma de crear o actualizar una aplicación es a través de Applications Managers, donde también podrás trabajar a través de la API, crear y gestionar proyectos, ver todas tus aplicaciones, vincular los proyectos, saber cuántas aplicaciones de un usuario hay autorizadas – siempre y cuando tengas un access_token válido para ese usuario – y revoca la autorización del usuario no desea utilizar su aplicación o ser notificado ya través de la API.


Artículos relacionados:
Crea y administra tu proyecto.
Administra tus aplicaciones.

Please rate this

Consideraciones de diseño

Existen algunos temas que debes saber sobre nuestra API para facilitarte la vida.

Contenidos:

Todas las respuestas están codificadas con JSON

JSON es un estándar abierto basado en texto ligero diseñado para el intercambio de datos legibles por humanos. Nuestra API soporta y devuelve JSON por defecto.
También devolvemos respuestas HTML cuando estás navegando la API a través de un navegador web.
Para decidir qué respuesta devolvemos, utilizamos el encabezado Accept. Para superar la política del mismo origen, JSONP también está soportado.
La política del mismo origen es un concepto de seguridad importante. Para superarla, sugerimos utilizar JSONP y CORS.

Uso de JSONP

Si incluyes un parámetro callback, la API responderá con JSONP. El valor de este parámetro se utilizará como la función de callback.

Ejemplo:

$ curl https://api.mercadolibre.com/currencies/ARS

Respuesta:

{
  "id": "ARS",
  "description": "Peso argentino",
  "symbol": "$",
  "decimal_places": 2,
}

Para una respuesta JSONP, agrega un parámetro callback como éste:

$ curl https://api.mercadolibre.com/currencies/ARS?callback=foo

Respuesta:

foo(
	[
    	200,
    	{
            "ETag":"2995de5a04da39af0a8677b1d02d1cdb",
            "Vary":"Accept,Accept-Encoding",
            "Content-Type":"application/json;charset=UTF-8",
            "Cache-Control":"max-age=86400"
    	},
    	{
            "id":"ARS",
            "description":"Peso argentino",
        	"symbol":"$",
        	"decimal_places":2
    	}
	]
);

Como puedes ver, la respuesta es un conjunto de 3 valores:

  • Código de estado http
  • Encabezados de respuesta http
  • Cuerpo de la respuesta

Todas las respuestas JSONP siempre serán 200 OK. El propósito es darte la posibilidad de manejar respuestas 30x, 40x y 50x en el client side. Los datos reales de la respuesta están en el conjunto.

CORS

Cross-origin resource sharing (CORS) [compartir recursos de origen cruzado] es una especificación tecnológica del navegador web que define formas en las cuales un servidor web permite el acceso a sus recursos a través de una página web de un dominio diferente. Ésta es una manera de superar la política del mismo origen.
Todas las API devuelven un encabezado especial:

Access-Control-Allow-Origin: *

Esto permite al buscador acceder a la información provista por la API, aunque sea desde un dominio diferente.
Todos los principales navegadores cuentan con soporte para CORS.
Entonces, básicamente, esto significa que no tienes que hacer nada y puedes acceder a la API directamente desde tu navegador realizando llamadas ajax normales con todos los métodos estándares y evitando cosas como JSONP.

Todas las solicitudes/respuestas están codificadas con UTF-8

User: Are you really telling me that I can only use UTF-8 with MELI APIs?
Us: Yes.
User: Really?
Us: Yes.
User: Only?
Us: Yes. We hope this has been enlightening for you.
User: But, I must–
Us: Thank you, come again.
User: But–
Us: Thank you, come again.

Todas las fechas están codificadas con ISO 8601

Utilizamos ISO 8601 para codificar las fechas en las respuestas.
No todas las fechas utilizarán el mismo huso horario. Por eso, las fechas incluirán el huso horario correcto.

Manejo de errores

El formato estándar de un error es el siguiente:

{
  "message": "human readable text",
  "error": "machine_readable_error_code",
  "status": 400,
  "cause": [
  ],
}

Reducción de respuestas

Para contar con respuestas más breves, con menos datos, puedes agregar el parámetro atributos con una coma separando la lista de campos que se deberían incluir en la respuesta. Todos los demás campos de la respuesta original se ignorarán.
Esta característica solo está soportada para el conjunto de respuestas.

$ curl https://api.mercadolibre.com/currencies?attributes=id
[
  {
	"id": "BRL"
  },
  {
	"id": "UYU"
  },
  {
	"id": "CLP"
  },
  ...
]

Esta característica solo está soportada para el conjunto de respuestas
Filtra por ID de recursos
Si tienes una lista de los ID de los recursos que deseas recuperar, puedes evitar realizar N cantidad de llamadas para obtenerlos y hacerlo con una sola llamada. Esto se logra al agregar el parámetro ID a la cadena de consulta.

$ curl https://api.mercadolibre.com/currencies?ids=ARS,USD

Uso de OPCIONES

La API entregará documentación en formato JSON utilizando OPTIONS. Existe un formato estándar para obtener documentación de la API. Utiliza el método http OPTIONS para obtener una respuesta codificada con JSON que describirá la API con todos los métodos y conexiones permitidos entre otra parte de la API.

$ curl -X OPTIONS https://api.mercadolibre.com/currencies
{
	"name":"Monedas",
    "description":"Devuelve información correspondiente al ISO de las monedas que se usan en MercadoLibre.",
	"attributes": {
   	 "id":"ID de la moneda (Código ISO)",
        "description":"Denominación oficial de la moneda",
    	"symbol":"Símbolo ISO para representar la moneda",
        "decimal_places":"Número de decimales manejados con la moneda"
	},
	"methods": [
 	   {
            "method":"GET",
            "example":"/currencies/",
            "description":"Devuelve el listado con todas las monedas."
    	},
    	{
            "method":"GET",
            "example":"/currencies/:id",
        	"description":"Devuelve información con respecto a una moneda específica."
    	}
	],
	"related_resources":[],
	"connections": {
        "id":"/currencies/:id"
	}
}



Siguiente:
Registra tu aplicación.

Please rate this

Registra tu aplicación

Para registrar una aplicación, debes dirigirte a nuestro Administrador de Aplicaciones, seleccionar tu país e iniciar sesión.
Como la aplicación solo funciona para el país donde está registrado el usuario, necesitarás un usuario y una aplicación para cada país donde desees trabajar.
Una vez iniciada la sesión, deberás completar algunos detalles sobre tu aplicación y, luego, obtendrás un Client_Id y Secret_Key, necesarios para autenticarte con nuestra API.

Contenidos:

Datos de la Aplicación

Existen tres grupos de información en este formulario: Información Básica de la Aplicación, Autenticación y Seguridad y Configuraciones de Notificaciones.


https

Información básica de la aplicación

– app_id: Es tu client_id. Se debe utilizar para recuperar un access token.
– secret_key: También se utiliza para recuperar un access token. No compartas este secreto con nadie.
– name: Nombre de tu aplicación. Debe ser único.
– short_name: Nombre que MercadoLibre utiliza para generar el URL de tu aplicación.
– description: Esta descripción (hasta 150 caracteres) se mostrará cuando la aplicación solicite una autorización.

Autenticación y seguridad

– Callback URL: URI de redireccionamiento. URL para devolver usuarios a tu aplicación una vez que conceden acceso.
– Dominios: Authorized Javascript Origins [Orígenes de Javascript Autorizados]. Lista de nombres de dominio totalmente calificados, separados por coma, de todas las páginas que utilizarán la autenticación del client side. Solo sería necesaria si se utiliza la API de Javascript. No incluye protocolo, puerto ni “localhost”.
Estos dos atributos se explican en mayor detalle en la guía de Autenticación y Autorización.
– Scopes:

  • Lectura: Permite el uso de métodos API GET HTTP.
  • Escritura: Permite el uso de métodos API PUT, POST y DELETE HTTP.
  • Acceso Offline: Permite realizar una solicitud del server side y refresh token.

Notas:

  • Para crear una aplicación dentro del Application Manager es requisito obligatorio utilizar el protocolo HTTPS en su URI de redireccionamiento ya que de esta forma se asegura que el mensaje se envíe encriptado y sólo las personas autorizadas puedan leerlo.
  • Si aún sigues utilizando HTTP y quieren realizar cambios deberás configurar la nueva URL con HTTPS.

Consideraciones sobre scopes

Existen varios tipos de aplicaciones. No obstante, las dividiremos en tres grupos para explicar los scopes requeridos.
Aplicaciones de solo lectura: Aplicación que permite a un usuario anónimo o autenticado acceder a información personalizada de MELI. En este caso, un usuario anónimo podría buscar artículos, leer descripciones, etc. y un usuario autenticado puede ver la información personal. Si no realizas ninguna modificación a los datos de MELI (ninguna actualización de la información de usuario, publicación de artículos ni compra de artículos), todo lo que necesitas es un scope de lectura. Recuerda que cualquier intento por modificar datos a través de las API de Meli arrojaría error.
– Aplicaciones online de lectura/escritura: Este tipo de aplicación permite que un usuario anónimo realice ciertas operaciones de solo lectura en MELI, así como también permite a un usuario autenticado modificar datos, publicar nuevos artículos (vender), publicar pedidos (comprar), etc. En este caso, la aplicación requiere un scope de escritura para que el usuario pueda otorgar permisos de escritura y la aplicación actúe en su nombre. La aplicación podrá modificar datos en nombre del usuario mientras el access token tenga validez. Una vez expirado, el usuario debe renovar el token para volver a tener acceso.
– Aplicaciones offline de lectura/escritura: Si tu aplicación debe actuar en nombre del usuario aún cuando este último está offline, requerirá permiso de acceso offline por parte del usuario. Al solicitar este scope, una vez aceptada por el usuario, la aplicación tendrá tanto el access token para actuar en nombre del usuario como un refresh token para obtener un nuevo access token válido cuando expire el anterior.

Configuraciones de notificaciones

– Callback URL de Notificaciones: Configura el URL público del dominio donde deseas recibir las notificaciones para los diferentes temas.
– Topics: Lista de temas a los que deseas suscribirte. Existen seis temas posibles: orders, items, questions, created_orders y payments.

Accede a tu información de usuario con nuestros SDK

Nuestros SDK te permitirán acceder a tu perfil de usuario utilizando tu propia aplicación.

Realiza pruebas

Inicializa la API con tu client_id como se indica aquí:

MELI.init({client_id: 6092});
Así de fácil. Luego, la siguiente línea de código mostrará el primer nombre que registraste en MercadoLibre:
MELI.login(function() {
  MELI.get(
	"/users/me",{},
  	function(data) { alert("Hello "+data[2].first_name) }
  );
});



Siguiente:
Autorización.

Please rate this