# 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:

1. **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.  
2. **Minimización:** Se recomienda encarecidamente evitar tabuladores, saltos de línea o espacios adicionales dentro del cuerpo del mensaje JSON.  
3. **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

```json
{
  "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

```json
{
  "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`.