Saltar al contenido principal

Primeros pasos con la API

Se trata de una API de estilo REST que utiliza JSON para la serialización y OAuth 2 para la autenticación, y sigue este modelo de versionado.

¿Por dónde empiezo?​

¿Quieres empezar con la integración de API? Aquí tienes una lista de verificación rápida:

  1. Regístrate como socio en Tienda Negocio.
  2. Una vez dentro del panel de administración de tu socio, ve a la sección "Aplicaciones" y crea tu app.
  3. Lea sobre cómo autenticar su aplicación con nosotros.
  4. Consulta la documentación de la API para comprender qué puedes hacer con tu aplicación.

Hacer una solicitud​

Todas las URL comienzan con https://developers.tiendanegocio.com/v1/. Ten en cuenta que v1 representa la versión actual de la API y es estrictamente necesario incluirla en todas las rutas para que tus peticiones funcionen.

Las solicitudes a la API requieren autenticación mediante un TOKEN, el cual debe enviarse en el header Authorization. Este TOKEN permite identificar automáticamente la tienda asociada a la petición.

Para solicitar todos los productos de la tienda, harías lo siguiente en curl:

curl -X 'GET' \
  'https://developers.tiendanegocio.com/v1/products' \
  -H 'accept: application/json' \
  -H 'Authorization: {TOKEN}'

Para crear un producto, debes incluir el encabezado Content-Type y los datos JSON:

curl -X 'POST' \
  'https://developers.tiendanegocio.com/v1/products' \
  -H 'accept: application/json' \
  -H 'Authorization: {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '[{ }]'

Autenticación​

Utilizamos el marco de trabajo OAuth 2 para que los usuarios autoricen a tu aplicación a usar Tienda Negocio en su nombre. En resumen, cuando un usuario la instala, puedes obtener un token de acceso (una cadena secreta que indica tus derechos sobre su tienda), el cual debes incluir en el encabezado de cada solicitud (como se muestra en el ejemplo anterior).

Lea la guía de autenticación para comenzar.

Identifica tu aplicación​

En cada solicitud a la API, debe incluir un encabezado User-Agent con el nombre de su aplicación y un enlace a la misma o su dirección de correo electrónico para que podamos ponernos en contacto con usted. Aquí tiene un par de ejemplos:

Agente de usuario: Super app (http://superapp.com/contact) o Agente de usuario: Awesome app (awesome@app.com)

Si no proporciona este encabezado, recibirá una respuesta 400 Bad Request.

Solo JSON​

Todos los datos se envían y reciben en formato JSON. Nuestro formato no incluye un elemento raíz y utilizamos snake_case para describir las claves de los atributos. Esto significa que debe enviar Content-Type: application/json; charset=utf-8 al enviar o recibir datos en Tienda Negocio.

Recibirás un código de respuesta 415 (Tipo de medio no compatible) si omites el encabezado Content-Type.

Errores del cliente​

Estos son los posibles tipos de errores del cliente en las llamadas a la API que reciben cuerpos de solicitud:

  • El envío de JSON no válido dará como resultado una respuesta 400 Bad Request.
HTTP/1.1 400 Solicitud incorrecta
Longitud del contenido: 34

{"error": "Problemas al analizar JSON"}
  • El envío de campos no válidos dará como resultado una respuesta 422 Entidad no procesable.
HTTP/1.1 422 Entidad no procesable
Longitud del contenido: 47

{
    "src": [
        "no puede estar en blanco"
    ]
}

Errores del servidor​

Si Tienda Negocio presenta problemas, es posible que vea un error 5xx. El error 500 indica que la aplicación no está disponible, pero también podría ver errores como 502 Bad Gateway, 503 Service Unavailable o 504 Gateway Timeout. En todos estos casos, es su responsabilidad volver a intentar la solicitud más tarde.

Limitación de velocidad​

Para controlar el tráfico entrante de la API, puede realizar un número limitado de solicitudes en un período de tiempo determinado. Actualmente, el método utilizado para limitar el uso de la API se basa en una implementación del algoritmo Leaky Bucket, donde el tamaño predeterminado del bucket es de 40 solicitudes con una tasa de fuga de 2 solicitudes por segundo, lo que significa que puede realizar hasta 2 solicitudes por segundo, con ráfagas de 40 solicitudes, sin recibir un error 429 (Demasiadas solicitudes). Utilizamos los siguientes encabezados para proporcionar información sobre el límite de uso:

  • x-rate-limit-limit: Número total de solicitudes permitidas en un período determinado, en este caso, el tamaño del bucket.

  • x-rate-limit-remaining: Solicitudes restantes para llenar completamente el bucket.

  • x-rate-limit-reset: Milisegundos restantes para vaciar completamente el bucket.

Importante: El límite de velocidad funciona entre cada tienda y aplicación.

Si la tienda es Next o Evolution (plantas superiores), el límite de tasa se multiplica por 10.

Ejemplos:

  1. Se ponen en cola 20 solicitudes a la vez: no se procesarán simultáneamente. Se procesarán según el límite de velocidad: 2 solicitudes/seg. El procesamiento de las 20 solicitudes tardaría 10 segundos.

  2. Se envían 4 solicitudes/seg: cada segundo llegan 4 solicitudes nuevas y salen 2. Por lo tanto, cada segundo hay 2 solicitudes en cola. Después de 20 segundos, tendremos 40 solicitudes en cola (máximo del bucket). En el segundo siguiente, dos se procesarán normalmente, pero las otras dos se perderán (ya que recibirán un error de nuestra API: estado 429).

  3. Se ponen en cola 50 solicitudes a la vez: dado que el bucket solo admite 40 solicitudes en cola, 10 se perderán (ya que recibirán un error de nuestra API: estado 429). Las otras 40 se procesarán según el límite de velocidad: 2 solicitudes/seg.

Paginación​

Las solicitudes que devuelven varios elementos no se paginarán de forma predeterminada. Debe especificar las páginas adicionales con el parámetro page. También puede establecer un tamaño de página personalizado de hasta 200 con el parámetro per_page.

curl -H 'Authentication: bearer ACCESS_TOKEN ' \
  -H 'User-Agent: MyApp (name@email.com)' \
  'https://developers.tiendanegocio.com/v1/123456/products?page=2&per_page=100'

Tenga en cuenta que la numeración de las páginas comienza en 1 y que si se omite el parámetro de página, se devolverá la primera página.

Para interactuar con el listado de resultados, la API responde con un objeto JSON que agrupa la data dentro del arreglo results, y provee la información de paginación dentro del objeto pagination.

{
  "pagination": {
    "total": 156,
    "page": 2,
    "per_page": 100,
    "next_page": "https://developers.tiendanegocio.com/v1/products?page=3&per_page=100"
  },
  "results": [
    // ... elementos devueltos ...
  ]
}

Dependiendo de tu petición, los campos de pagination pueden variar, pero en general representan lo siguiente:

  • total: Identifica la cantidad de resultados exactos que arroja la búsqueda en la base de datos.
  • page: Indica el número de la página enviada en la respuesta actual.
  • per_page: Cantidad máxima de resultados devueltos por página dentro de results.
  • next_page: Muestra la URL a solicitar de forma directa para obtener la próxima página.

Es una buena práctica utilizar el enlace de next_page provisto dentro de la respuesta para saltar a la próxima página en lugar de componer e incrementar tu propia variable de página en tu código. Adicionalmente, ten en cuenta que si el valor de next_page devuelto es null, significa que has llegado al final de los resultados y no existen más páginas por consultar.

Verbos HTTP​

Siempre que sea posible, la API se esfuerza por utilizar los verbos HTTP apropiados para cada acción.

HEAD: Se puede usar contra cualquier recurso para obtener solo la información del encabezado HTTP.

GET: Se usa para recuperar recursos.

POST: Se usa para crear recursos.

PUT: Se usa para reemplazar recursos o colecciones. Para las solicitudes PUT sin atributo de cuerpo, asegúrese de establecer el encabezado Content-Length en cero.

DELETE: Se usa para eliminar recursos.

Suspensión del acceso a la API por falta de pago​

Al ser un servicio de suscripción mensual, es posible que una tienda no renueve su servicio. En este caso, la tienda se desconectará y la API será inaccesible. La API también será inaccesible si la aplicación tiene un precio recurrente y no se paga a tiempo.

En cualquier caso, todas las llamadas API devolverán un 402 Payment Required respuesta, Guiones no se incluirá y Webhooks no será llamado. Asegúrese de manejar este código de error para notificar al usuario que necesita reanudar su pago en lugar de mostrar un error genérico del servidor.

Una vez realizado el pago requerido, la API vuelve a ser accesible.

Si su aplicación necesita saber cuándo se suspende o reanuda el acceso a la API (porque es posible que haya perdido un webhook y desee realizar una resincronización completa, por ejemplo), puede registrarse en app/suspended y app/resumed eventos que utilizan un Webhook.

Nota: estos webhooks no se activan cuando la aplicación se queda sin "días libres". En estos casos la API también será inaccesible, pero no se activarán webhooks.

Recursos API

  • Categorías
  • Clientes
  • Órdenes
  • Productos
  • Variantes
  • Dirección de clientes
  • Imagen de productos
  • Paginas
  • Blogs
  • Carritos abandonados

Idiomas e internacionalización​

Actualmente, las tiendas no manejan múltiples idiomas. Sin embargo, la API ya devuelve las respuestas en un formato preparado para internacionalización, por lo que algunas propiedades de Producto y Categoría se presentan como objetos por idioma.

Ayúdanos a mejorar​

Si tenés sugerencias, encontraste un error o querés proponernos una mejora para la API, podés escribirnos directamente a: