# API Cloud Architecture

The Get Smart API Cloud is designed to bridge the gap between your cloud-based management software and physical payment terminals (TPV-PC). Unlike purely e-commerce APIs where transactions happen instantly in the browser, physical payments require human interaction (inserting a card, entering a PIN).

To accommodate this, the API uses a **two-phase asynchronous architecture**. Understanding this flow is essential to avoid common integration errors, such as assuming a transaction is complete when you receive the initial HTTP response.

## High-Level Data Flow

The lifecycle of a transaction involves three parties: Your **Application**, the **API Cloud**, and the **Physical Terminal**.

1. **Initiation (Synchronous):** Your application sends a request to the Cloud.  
2. **Processing (Physical):** The Cloud instructs the Terminal to activate. The customer interacts with the device.  
3. **Completion (Asynchronous):** The Cloud notifies your application of the final result.

## Phase 1: The Synchronous Request

When you send a request (e.g., to `/pago`), the API Cloud performs an immediate validation check.

* **What happens:** The system verifies your credentials, the message signature, and the JSON format.  
* **The Response:** You receive an immediate HTTP 200 OK response with a result code.  
* **Crucial Concept:** A result code of `"0"` **does not mean the payment is approved**. It means **"Request Received and Validated."**

```
// Example Synchronous Response
{
    "resultado": {
        "codigo": "0" // The command was successfully queued for the terminal.
    }
}
```

<Callout type="warning">

Do not treat this response as a receipt. At this stage, no money has moved. The terminal might not have even lit up yet. You should update your local order state to "Pending" or "In Progress."

</Callout>

## Phase 2: The Asynchronous Notification

Once the synchronous phase is complete, the API Cloud pushes the command to the specific terminal ID defined in your request.

1. **Interaction:** The terminal prompts the user. The user inserts their card and enters their PIN.  
2. **Result Generation:** The terminal communicates the outcome (Approved, Denied, Cancelled) back to the Cloud.  
3. **Notification:** The API Cloud sends a `POST` request to the `urlNotificacion` you defined in your initial request.

This notification contains the **final** result of the transaction, including authorization codes, ticket data, and card details.

### Notification Fallback

The system is designed to ensure you receive the result even if your server is unreachable.

* **Primary Channel:** `urlNotificacion` (HTTP POST).  
* **Secondary Channel:** If the call to your URL fails (e.g., your server is down or returns an error), the system attempts to send an email to the address defined in `correoNotificacion`.

## System Requirements

To participate in this architecture, your integration must meet specific constraints defined in the standard.

### Network and Security

* **Protocol:** All connections must be secured via **TLS 1.2** or higher.  
* **Access:** Connectivity is established over public internet lines; no VPN or dedicated leased lines are required for the REST interface.  
* **Encoding:** All data must be **UTF-8** encoded.

### JSON Constraints

The API is strict regarding data types to ensure stability across different terminal softwares.

* **No `null` values:** Fields must never be explicitly set to `null`. If a field is optional and has no value, it must be omitted from the JSON object entirely.  
* **Minimization:** While not strictly enforced for parsing, it is recommended to avoid excessive whitespace, tabs, or newlines in production payloads to prevent signature verification issues.

## Next Steps

* [**Signature Logic and Security**](/en/get-smart/get-smart-api-cloud/core-concepts/signature-logic-and-security)**:** Understand the security algorithm that protects these messages.  
* [**Set up Webhooks and Notifications**](/en/get-smart/get-smart-api-cloud/integration-guides/set-up-webhooks-and-notifications)**:** Learn how to build the endpoint to receive the asynchronous notifications described in Phase 2.