# General API Standards and Headers

This document outlines the technical standards, HTTP headers, and message structures that apply to all endpoints in the Get Smart API Cloud. Adherence to these standards is mandatory for successful integration.

## Communication Standards

All interactions with the API must strictly follow these protocols.

| Requirement | Specification |
| :---- | :---- |
| **Protocol** | **TLS 1.2** or higher is required. |
| **Network** | Access is performed via public internet lines. |
| **Architecture** | RESTful Web Services consuming and producing **JSON**. |
| **Encoding** | **UTF-8** is mandatory for all messages. |

### JSON Formatting Rules

To ensure message integrity and correct parsing:

1. **No `null` Values:** Do not send fields with a value of `null`. If a field is optional and not used, omit it entirely from the JSON object.  
2. **Minimization:** It is strongly recommended to avoid tabs, line breaks, or extra spaces within the JSON message body.  
3. **Strict Types:** Respect the data types (String vs. Number) defined in the endpoint definitions.

## HTTP Headers

You must include the following headers in every request.

| Header | Value | Requirement | Description |
| :---- | :---- | :---- | :---- |
| `Content-Type` | `application/json` | **Mandatory** | Indicates the request body format. |
| `Accept` | `application/json` | **Mandatory** | Indicates the client expects JSON in response. |
| `Content-Length` | *(Integer)* | Optional | The size of the request body in bytes. |

## HTTP Status Codes

The API returns standard HTTP status codes to indicate the immediate result of the request processing.

| Code | Message | Meaning |
| :---- | :---- | :---- |
| **200** | `OK` | The operation was received and validated correctly. |
| **201** | `Created` | The entity creation process completed successfully. |
| **401** | `Unauthorized` | Invalid credentials. Authentication failed. |
| **403** | `Forbidden` | Access is permanently forbidden (logic error, not auth error). |
| **404** | `Not Found` | The requested resource (URL) does not exist. |
| **405** | `Method Not Allowed` | You used the wrong HTTP verb (e.g., GET instead of POST). |
| **415** | `Unsupported Media Type` | The request format is not supported (Check `Content-Type`). |
| **429** | `Too Many Requests` | You have exceeded the consumption quotas for the API. |

## Message Structure

Every API interaction (Request and Response) follows a standard "envelope" structure containing two top-level objects.

### Request Structure

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

| Field | Type | Required | Description |
| :---- | :---- | :---- | :---- |
| `info` | Object | **Yes** | The container for all business data. |
| `signature` | String | **Yes** | The SHA256 hash verifying the integrity of `info`. |

### Response Structure

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

## Common Data Formats

Unless specified otherwise in a specific endpoint reference, use these formats:

* **Amounts (`importe`):** `XXXXXXXXX.XX` (String or Double). Example: `10.50` or `0.01`. Max 12 chars.  
* **Timestamps:**  
  * In `info` root: `YYYYMMDD HHmmss` (e.g., `20250428 111217`)  
  * In `datosOperacion` (Queries): `YYYY-MM-DD-HH.mm.ss` or `YYYY-MM-DD HH:mm:ss` (Refer to specific endpoint docs).  
* **Booleans:** JSON `true` or `false`.