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:

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.
Minimization: It is strongly recommended to avoid tabs, line breaks, or extra spaces within the JSON message body.
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.