Formatos de datos

Fechas y horas

Para nuestra API usamos ISO 8601. ISO 8601 es un estándar para representar fechas y horas en un formato legible por máquina. Especifica un conjunto de representaciones para fechas, horas e intervalos, incluyendo formatos estándar para representar fechas y horas con o sin zona horaria.

El formato consta de una serie de campos separados por puntuación, con los campos más significativos al inicio. El formato básico para representar una fecha y hora es:

YYYY-MM-DDTHH:MM:SSZ

Donde:

• YYYY es el año, representado en cuatro dígitos
• MM es el mes, representado en dos dígitos (01-12)
• DD es el día del mes, representado en dos dígitos (01-31)
• T es un separador que indica el inicio de la porción de hora del valor fecha-hora
• HH es la hora, representada en dos dígitos (00-23)
• MM es el minuto, representado en dos dígitos (00-59)
• SS es el segundo, representado en dos dígitos (00-59)
• Z es la zona horaria

Por ejemplo, la fecha y hora 2022-12-29T12:34:56Z representaría el 29 de diciembre de 2022 a las 12:34:56 (12:34 PM).

La API usa UTC, o tiempo universal coordinado, para el campo de fecha/hora. UTC es una referencia de tiempo estandarizada que es la misma en todo el mundo. Es el estándar primario por el cual el mundo regula relojes y tiempo. UTC está basado en relojes atómicos, que son relojes altamente precisos que miden las vibraciones de los átomos para determinar el paso del tiempo. Como UTC está basado en relojes atómicos, es extremadamente estable y preciso.

Valores monetarios

Para nuestra API, todo valor monetario debe estar en ISO 4217, que es un estándar internacional para representar monedas. Especifica un código de tres letras para cada moneda, así como la unidad menor de la moneda. Por ejemplo, el código para dólares estadounidenses es "USD".

Además, el campo amount para dinero se representa en centavos en lugar de la unidad base de la moneda. Esto permite una representación más precisa del monto, así como un cálculo y almacenamiento más sencillos de los valores monetarios. Por ejemplo, si quieres representar $10.50 en una API, almacenarías el monto como 1050 (en lugar de 10.50).

Esto se representaría así:

{
  "amount": 10000,
  "currency": "COP"
}

Esto representa un monto de 10000 centavos, o 100 pesos colombianos. La moneda se especifica usando el código ISO 4217 para pesos colombianos, que es "COP".

Números telefónicos

Tanto los números telefónicos nacionales como los internacionales se representan con E.164.

E.164 es un estándar para el formato de números telefónicos. Especifica un formato estandarizado que incluye un código de país, un código de destino nacional y un número de suscriptor local. El formato es el siguiente:

+[country code][national destination code][local subscriber number]

Por ejemplo, un número telefónico en Colombia podría tener el formato +57 300 555 0000, donde +57 es el código de país de Colombia, "300" es el código de destino nacional, y "555 0000" es el número de suscriptor local.