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 garantizar la estabilidad y disponibilidad de la API, se aplica un límite de solicitudes a todas las peticiones autenticadas. Actualmente, cada combinación de tienda y usuario puede realizar hasta 40 solicitudes en un período de 10 segundos. Si se supera este límite, la API responderá con el código de estado 429 (Too Many Requests). El control de límite no se basa en la dirección IP del cliente, sino en la combinación de los identificadores autenticados de la tienda y el usuario.

Ejemplos:

  1. Se envían 20 solicitudes de forma inmediata: Las 20 solicitudes se encuentran dentro del límite permitido de 40 solicitudes cada 10 segundos, por lo que serán procesadas normalmente.

  2. Se envían 50 solicitudes en menos de 10 segundos: Las primeras 40 solicitudes serán procesadas normalmente. Las 10 solicitudes restantes excederán el límite permitido y recibirán una respuesta con estado 429 (Too Many Requests).

  3. Se alcanzó el límite de 40 solicitudes: Una vez consumidas las 40 solicitudes permitidas, deberá esperar a que finalice la ventana de 10 segundos para poder realizar nuevas solicitudes sin recibir errores de límite de velocidad.

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: