Estándares generales de la API y cabeceras

Este documento describe los estándares técnicos, las cabeceras HTTP y las estructuras de mensajes que se aplican a todos los endpoints en Get Smart API Cloud. El cumplimiento de estos estándares es obligatorio para una integración correcta.

Estándares de comunicación

Todas las interacciones con la API deben seguir estrictamente estos protocolos.

Requisito	Especificación
Protocolo	Se requiere TLS 1.2 o superior.
Red	El acceso se realiza a través de líneas públicas de Internet.
Arquitectura	Servicios web RESTful consumiendo y produciendo JSON.
Codificación	UTF-8 es obligatorio para todos los mensajes.

Reglas de formato JSON

Para garantizar la integridad del mensaje y el procesamiento (parsing) correcto:

Sin valores null: No envíes campos con un valor null. Si un campo es opcional y no se utiliza, omítelo por completo del objeto JSON.
Minimización: Se recomienda encarecidamente evitar tabuladores, saltos de línea o espacios adicionales dentro del cuerpo del mensaje JSON.
Tipos estrictos: Respeta los tipos de datos (String frente a Number) definidos en las definiciones de los endpoints.

Cabeceras HTTP

Debes incluir las siguientes cabeceras en cada petición.

Cabecera	Valor	Requisito	Descripción
`Content-Type`	`application/json`	Obligatorio	Indica el formato del cuerpo de la petición.
`Accept`	`application/json`	Obligatorio	Indica que el cliente espera JSON en la respuesta.
`Content-Length`	(Entero)	Opcional	El tamaño del cuerpo de la petición en bytes.

Códigos de estado HTTP

La API devuelve códigos de estado HTTP estándar para indicar el resultado inmediato del procesamiento de la petición.

Código	Mensaje	Significado
200	`OK`	La operación se recibió y validó correctamente.
201	`Created`	El proceso de creación de la entidad se completó satisfactoriamente.
401	`Unauthorized`	Credenciales no válidas. La autenticación ha fallado.
403	`Forbidden`	El acceso está permanentemente prohibido (error de lógica, no error de autenticación).
404	`Not Found`	El recurso solicitado (URL) no existe.
405	`Method Not Allowed`	Has utilizado el verbo HTTP incorrecto (p. ej., GET en lugar de POST).
415	`Unsupported Media Type`	El formato de la petición no está soportado (Comprueba el `Content-Type`).
429	`Too Many Requests`	Has superado las cuotas de consumo para la API.

Estructura del mensaje

Cada interacción de la API (Petición y Respuesta) sigue una estructura de “envolvente” estándar que contiene dos objetos de nivel superior.

Estructura de la petición

{
  "info": {
    "comercio": "123456789",
    "terminal": 1,
    "timestamp": "YYYYMMDD HHmmss",
    "datosOperacion": { ... }
  },
  "signature": "SHA256_HASH_STRING"
}

Campo	Tipo	Requerido	Descripción
`info`	Object	Sí	El contenedor de todos los datos de negocio.
`signature`	String	Sí	El hash SHA256 que verifica la integridad de `info`.

Estructura de la respuesta

{
  "info": {
    "comercio": "123456789",
    "terminal": 1,
    "timestamp": "YYYYMMDD HHmmss",
    "resultado": {
      "codigo": "0",
      "descripcion": "Example Description"
    }
  },
  "signature": "SHA256_HASH_STRING"
}

Formatos de datos comunes

A menos que se especifique lo contrario en la referencia de un endpoint específico, utiliza estos formatos:

Importes (importe): XXXXXXXXX.XX (Cadena o Double). Ejemplo: 10.50 o 0.01. Máx. 12 caracteres.
Marcas de tiempo (Timestamps): * En la raíz de info: YYYYMMDD HHmmss (p. ej., 20250428 111217)
- En datosOperacion (Consultas): YYYY-MM-DD-HH.mm.ss o YYYY-MM-DD HH:mm:ss (Consulta la documentación específica del endpoint).
Booleanos: JSON true o false.