Ir al contenido principal

Desarrollo de API

Actualizado hace más de 11 meses

Introducción

Bienvenido a la guía de desarrollo de API basada en nuestra estructura recomendada. Este documento tiene como objetivo ayudarte a construir una API que gestione eficientemente información clave como tiendas, clientes y ventas.

A través de esta estructura JSON sugerida, podrás implementar una solución que facilite la sincronización de datos, la automatización de procesos y el análisis avanzado.

Estructura General del Modelo JSON

Todas las respuestas de la API deben seguir la siguiente estructura:

{
  "page": 1,
  "per_page": 10,
  "total_items": 50,
  "total_pages": 5,
  "data": {
    "tiendas": [...],
    "clientes": [...],
    "ventas": [...]
  }
}

Paginación

Es fundamental que los endpoints soporten parámetros de paginación para controlar la cantidad de datos devueltos y facilitar la navegación entre páginas.

  • page: Número de la página actual.

  • per_page: Cantidad de elementos por página.

  • total_items: Número total de elementos disponibles.

  • total_pages: Número total de páginas disponibles.

Autenticación

La API debe utilizar autenticación mediante api_key. Esta clave debe ser enviada en la cabecera de cada solicitud: 

Authorization: Basic <api_key>

Buenas Prácticas

  • Validación de Datos: Verificar que todos los campos obligatorios estén presentes y correctamente formateados.

  • Datos: Aunque algunos campos son opcionales, recomendamos proporcionar la mayor cantidad de información posible. Esto permitirá aprovechar al máximo los datos procesados y habilitar análisis más precisos y completos.

  • Seguridad: Asegurar que todas las solicitudes estén autenticadas adecuadamente.

  • Disponibilidad: La API debe estar disponible el 100% del tiempo para garantizar una integración confiable.

  • Filtrabilidad: El endpoint debe permitir filtrar los datos por los campos document y createtime (fecha), facilitando así consultas específicas y optimizando el uso de la API.

Tiendas

Representa las sucursales o puntos de venta donde se realizan las transacciones.

Estructura

{
  "name": "A101",
  "display_name": "Sucursal Palermo",
  "branch_zone_code": "13",
  "branch_zone_name": "Buenos Aires"
}

Campos / Cabeceras de la entidad Tiendas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

name

String

Identificador único de la tienda

A101

Sí

display_name

String

Nombre de la tienda

Sucursal Palermo

Sí

branch_zone_code

String

Código de la zona

13

No

branch_zone_name

String

Nombre de la zona

Buenos Aires

No

❗En esta entidad no es posible incluir atributos extendidos

Clientes

Contiene la información detallada de los clientes.

❗Debes enviar al menos un identificador del cliente (document y/o email)

❗Los campos createtime y updatetime deben estar en horario UTC

Estructura

{
  "document": "30300300",
  "email": "[email protected]",
  "createtime": "2024-04-28 10:39:00",
  "updatetime": "2024-06-22 20:52:00",
  "first_name": "Christian",
  "last_name": "Vitale",
  "telephone": "1173682446",
  "birthdate": "1992-03-31",
  "gender": "M",
  "street": "ohm 2220",
  "city": "CABA",
  "state": "CABA",
  "department": "Villa Urquiza",
  "country": "Argentina",
  "postcode": "1431",
  "points": 100,
  "mailing_enabled": "disabled",
  "sms_enabled": "disabled"
  }
}

Campos / Cabeceras de la entidad Clientes

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document

String

Documento o cédula

30300300

Si

email

String

Email

[email protected]

Si

createtime

Datetime

Fecha creación del cliente [hora UTC]

2024-04-28 10:39:00

Si

updatetime

Datetime

Fecha actualización del cliente [hora UTC]

2024-06-22 20:52:00

Si

first_name

String

Nombre

Christian

No

last_name

String

Apellido

Vitale

No

telephone

String

Telefono

1173682446

No

birthdate

Date

Fecha de Nacimiento (sin hora)

1992-03-31

No

gender

Enum

Género ["M", "F", ""]

M

No

street

String

Calle

ohm 2220

No

city

String

Ciudad

CABA

No

state

String

Estado

CABA

No

department

String

Departamento

Villa Urquiza

No

country

String

País

Argentina

No

postcode

String

Código Postal

1431

No

points

Integer

Puntos

100

No

mailing_enabled

Enum

Habilitación para enviar mail ["enabled", "disabled"]

disabled

No

sms_enabled

Enum

Habilitación para enviar sms ["enabled", "disabled"]

disabled

No

Ventas

Registra las transacciones realizadas por los clientes.

❗Debes enviar al menos un identificador del cliente (document y/o email)

Estructura

{
  "document": "36872489",
  "email": "[email protected]",
  "invoice_number": "FAC0230321",
  "createtime": "2020-01-23 16:32:05",
  "channel": "in-store",
  "branch_name": "A101",
  "shipping": 500.0,
  "gross": 9000.0,
  "tax": 1400.0,
  "discount": 2000.0,
  "total": 9400.0,
  "payment_type": "debit",
  "payment_brand": "Visa",
  "payment_bank": "Banco Galicia",
  "payment_installments": 6,
  "seller_name": "Gil Gunderson",
  "seller_external_id": "10",
  "SKU": "AB123324",
  "product_name": "Celular Moto Z",
  "brand": "Motorola",
  "quantity": 2,
  "unit_price": 1000.0,
  "variations": "Color: Blanco | Talle: XXXL",
  "custom_attributes": {
    "cupon_descuento": "PROMO2025"
  }
}

Campos / Cabeceras de la entidad Ventas

Campo

Tipo

Descripción

Ejemplo

Obligatorio

document

String

Documento o cédula del cliente

36872489

Si

email

String

Email del cliente

[email protected]

Si

invoice_number

String

Número de la Factura (ID)

FAC0230321

Si

createtime

String

Fecha y Hora de la Venta

2020-01-23 16:32:05

Si

channel

Enum

Canal de venta ["web", "in-store"]

in-store

Si

branch_name

String

Código de la tienda donde se realizó la venta. Se debe utilizar el campo 'name' del archivo de Tiendas.

A101

Si

shipping

Float

Costo de Envío

500

No

gross

Float

Subtotal (Sin impuestos, sin envíos y sin descuentos)

9000

Si

tax

Float

Impuestos de la Factura

1400

No

discount

Float

Descuento de la factura

2000

Si

total

Float

Total de la Factura

9400

Si

payment_type

Enum

Medio de pago ['credit', 'debit', 'mercadopago', 'todopago', 'cash', 'other']

debit

Si

payment_brand

String

Marca de la Tarjeta

Visa

No

payment_bank

String

Banco emisor de la tarjeta

Banco Galicia

No

payment_installments

Integer

Cantidad de cuotas

6

No

seller_name

String

Nombre del Vendedor

Gil Gunderson

No

seller_external_id

String

Id externo del vendedor

10

No

SKU

String

Código del producto (productReferenceCode de Vtex)

AB123324

Si

product_name

String

Nombre del producto

Celular Moto Z

Si

brand

String

Marca del producto

Motorola

No

quantity

Integer

Cantidad de unidades

2

Si

unit_price

Float

Precio unitario del producto (Sin impuestos y descuentos)

1000

Si

variations

String

Características por las que se puede agrupar productos. Por ejemplo: color, talle, temporada (Formato llave valor, separados por pipes "|")

Color: Blanco | Talle: XXXL

No

👉 En el JSON, el nombre del campo para un atributo extendido se debe enviar en el formato custom_attributes.{nombre_atributo}. Este atributo será creado automáticamente en WoowUp utilizando el nombre especificado en la clave del objeto custom_attributes.

Ejemplo de json

{
  "page": 1,
  "per_page": 10,
  "total_items": 50,
  "total_pages": 5,
  "data": {
    "tiendas": [
      {
        "name": "A101",
        "display_name": "Sucursal Palermo",
        "branch_zone_code": "13",
        "branch_zone_name": "Buenos Aires"
      }
      // ... más tiendas
    ],
    "clientes": [
      {
        "document": "30300300",
        "email": "[email protected]",
        "createtime": "2024-04-28T10:39:00Z",
        "updatetime": "2024-06-22T20:52:00Z",
        "first_name": "Christian",
        "last_name": "Vitale",
        "telephone": "1173682446",
        "birthdate": "1992-03-31",
        "gender": "M",
        "street": "Ohm 2220"
        "city": CABA,
        "state": CABA,
        "department": Villa Urquiza,
        "country": Argentina,
        "postcode": 1432,
        "points": 100,
        "mailing_enabled": enabled,
        "sms_enabled": enabled,
  // ... otros campos según sea necesario utilizando custom_attributes
      }
      // ... más clientes
    ],
    "ventas": [
      {
        "document": "36872489",
        "email": "[email protected]",
        "invoice_number": "FAC0230321",
        "createtime": "2020-01-23T16:32:05Z",
        "channel": "in-store",
        "branch_name": "A101",
        "shipping": 500.0,
        "gross": 9000.0,
        "tax": 1400.0,
        "discount": 2000.0,
        "total": 9400.0,
        "payment_type": "debit",
        "payment_brand": "Visa",
        "payment_bank": "Banco Galicia",
        "payment_installments": 6,
        "seller_name": "Gil Gunderson",
        "seller_external_id": "10",
        "SKU": "AB123324",
        "product_name": "Celular Moto Z",
        "brand": "Motorola",
        "quantity": 2,
        "unit_price": 1000.0,
        "variations": "Color: Blanco | Talle: XXXL",
        "custom_attributes": {
           "cupon_descuento": "PROMO2025"
        // ... otros campos según sea necesario utilizando custom_attributes
      }
      // ... más ventas
    ]
  }
}

Artículos relacionados
Integración SQL para Tiendas Físicas
Integración de Tiendas Físicas con Archivos CSV
2. Entidad Tiendas
3. Entidad Clientes: Gestión de la información y atributos personalizados de los clientes
4. Entidad Ventas: Registro y gestión de transacciones
¿Ha quedado contestada tu pregunta?