# API Cloud Overview

The Get Smart API Cloud allows you to integrate your business applications with physical payment terminals (TPV-PC) through a standardized cloud interface. This service enables you to manage payments, refunds, and pre-authorizations using RESTful web services, while the physical terminal handles the interaction with the cardholder.

This guide explains the high-level architecture, technical standards, and communication protocols required to integrate with the solution.

## How It Works

The API operates on a **REST/JSON** paradigm. Your client application sends HTTP requests to the cloud endpoints, which then communicate with the specific physical terminal connected to the network.

The communication flow consists of two distinct phases:

1. **Synchronous Request:** You send a request (e.g., a payment command) to the API. The API validates the format and security of the message and immediately returns a response indicating if the request was accepted (`200 OK`) or rejected.  
2. **Asynchronous Notification:** Because interactions with a physical terminal (entering a PIN, tapping a card) take time, the final result of the operation is sent asynchronously. The system sends the final transaction data to a `urlNotificacion` you provide or via email if the URL notification fails.

## Technical Requirements

To ensure secure and reliable communication, your integration must adhere to the following standards:

* **Communication Protocol:** You must use **TLS 1.2** or higher for all connections.  
* **Network:** Access is performed through public lines (Internet).  
* **Encoding:** All messages must use **UTF-8** encoding.  
* **Format:** All messages consume and generate content in **JSON** format.

### JSON Formatting Rules

Strict JSON formatting rules apply to all requests. Failure to follow these rules may result in error responses.

<Callout type="warning">

Do not use `null` values. Optional fields that are not used, or conditional fields that are not required for a specific operation, must be omitted from the message entirely. Sending a field with a value of `null` is not permitted.

</Callout>

Additionally, avoid using tabs, line breaks, or unnecessary spaces within the JSON message body to prevent parsing errors.

## Request and Response Structure

Every interaction with the API follows a generic envelope structure containing two primary objects: `info` and `signature`.

### The `info` Object

This object contains the payload of your request or response. It includes the merchant identification, the operation details, and timestamps.

### The `signature` Object

Security is enforced through a signature field. Every request you send must be signed using your merchant key. Similarly, every response you receive includes a signature that you must verify to ensure the integrity and origin of the message.

## HTTP Status Codes

The API uses standard HTTP status codes to indicate the immediate result of the API call.

| Code | Status | Description |
| :---- | :---- | :---- |
| **200** | OK | The operation was received and validated correctly. |
| **201** | Created | Entity creation process completed successfully. |
| **401** | Unauthorized | The request lacks valid authentication credentials. |
| **403** | Forbidden | Access is permanently forbidden, regardless of authentication. |
| **404** | Not Found | The requested resource is not available. |
| **405** | Method Not Allowed | The HTTP method (e.g., GET vs POST) is not supported for this URI. |
| **415** | Unsupported Media Type | The request format is not supported (ensure you use JSON). |
| **429** | Too Many Requests | You have exceeded the consumption quotas for the API. |

## Next Steps

Now that you understand the general concepts, you can proceed to the integration steps:

1. [**Configure Environments and Credentials**](/en/get-smart/get-smart-api-cloud/first-steps/configure-environments-and-credentials): Learn how to manage test and production data.  
2. [**Authenticate Requests**](/en/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests): Implement the signature logic required for every API call.  
3. [**Process Your First Payment**](/en/get-smart/get-smart-api-cloud/first-steps/process-your-first-payment): Follow a step-by-step tutorial to complete a transaction.