Formatos y convenciones

En toda la API implementamos ciertas prácticas de formateo para los datos que mostramos y solicitamos.

El intercambio de datos de esta API se hace usando JSON.

Tipos de atributo

Por lo general, cuando se trate de números, estos utilizaran un tipo integer o float en vez de un string.

Hay excepciones para campos que se podrían indicar como strings, por ejemplo para identificadores externos de envío o paquete. Estos aceptarán números pero se almacenarán y devolverán como strings.

Los atributos opcionales se deberán indicar como null.

Fechas

Las fechas se deberán formatear de la forma YYYY-MM-DD. O sea, 4 dígitos para el año, 2 dígitos para el mes (con un cero inicial de 1 al 9) y 2 dígitos para el día (con un cero inicial de 1 al 9). Ejemplo: 2024-04-25.

Los timestamps deberán formatearse de acuerdo al estándar ISO 8601. Siempre deberán estar en la zona horaria UTC. Ejemplo: 2023-05-24T22:05:12.000000Z

Latitud y Longitud

Se indica como un decimal y sugerimos incluir 6 lugares decimales para una precisión adecuada. Ejemplo: -34.232342

Peso y dimensiones

Donde se deban indicar medidas, por ejemplo al definir paquetes, utilizamos siempre las siguientes unidades de medida en el sistema métrico:

• Peso: se indica en gramos, con números enteros (sin decimales).

• Dimensiones: se indica en centímetros, con números enteros (sin decimales).

• Temperatura: se indica en grados Celsius, con números enteros (sin decimales).

Booleanos

La API los devolverá como true o false.

Por lo general también aceptará que se le envíe valores 1 o 0.

Números de teléfono

Los números de teléfono que se envíen, por ejemplo en los datos de dirección, deben estar formateados en el estándar internacional E.164 de numeración telefónica, que se compone de un más (+), el código de país y el del suscriptor, incluyendo el código de área, con un máximo de 15 dígitos.

Ejemplos de números correctamente formateados de distintos países:

• 🇦🇷 [phone] (fijo) o [phone] (móvil)

• 🇨🇱 [phone] (fijo) o [phone] (movil)

• 🇲🇽 [phone]

• 🇺🇸 [phone]

El uso de éste estándar contribuye a disponer de números válidos, reduce el fraude y mejora la entregabilidad de mensajes o llamados a sus destinatarios.