# Visión general de API Cloud

Get Smart API Cloud te permite integrar tus aplicaciones de negocio con terminales de pago físicos (TPV-PC) a través de una interfaz estandarizada en la nube. Este servicio te permite gestionar pagos, devoluciones y preautorizaciones utilizando servicios web RESTful, mientras que el terminal físico gestiona la interacción con el titular de la tarjeta.

Esta guía explica la arquitectura de alto nivel, los estándares técnicos y los protocolos de comunicación necesarios para integrarse con la solución.

## Cómo funciona

La API opera bajo el paradigma **REST/JSON**. Tu aplicación cliente envía peticiones HTTP a los endpoints en la nube, que a su vez se comunican con el terminal físico específico conectado a la red.

El flujo de comunicación consta de dos fases diferenciadas:

1. **Petición síncrona:** Envías una petición (p. ej., un comando de pago) a la API. La API valida el formato y la seguridad del mensaje y devuelve inmediatamente una respuesta indicando si la petición ha sido aceptada (`200 OK`) o rechazada.  
2. **Notificación asíncrona:** Debido a que las interacciones con un terminal físico (introducir el PIN, lectura de tarjeta) requieren tiempo, el resultado final de la operación se envía de forma asíncrona. El sistema envía los datos finales de la transacción a una `urlNotificacion` que proporciones o por correo electrónico si la notificación por URL falla.

## Requisitos técnicos

Para garantizar una comunicación segura y fiable, tu integración debe cumplir los siguientes estándares:

* **Protocolo de comunicación:** Debes utilizar **TLS 1.2** o superior para todas las conexiones.  
* **Red:** El acceso se realiza a través de líneas públicas (Internet).  
* **Codificación:** Todos los mensajes deben utilizar la codificación **UTF-8**.  
* **Formato:** Todos los mensajes consumen y generan contenido en formato **JSON**.

### Reglas de formato JSON

Se aplican reglas estrictas de formato JSON a todas las peticiones. El incumplimiento de estas reglas puede dar lugar a respuestas de error.

<Callout type="warning">

No utilices valores `null`. Los campos opcionales que no se utilicen, o los campos condicionales que no sean necesarios para una operación específica, deben omitirse completamente del mensaje. No se permite el envío de un campo con valor `null`.

</Callout>

Asimismo, evita el uso de tabuladores, saltos de línea o espacios innecesarios dentro del cuerpo del mensaje JSON para evitar errores de procesamiento.

## Estructura de petición y respuesta

Cada interacción con la API sigue una estructura de envolvente genérica que contiene dos objetos principales: `info` y `signature`.

### El objeto `info`

Este objeto contiene el payload de tu petición o respuesta. Incluye la identificación del comercio, los detalles de la operación y las marcas de tiempo.

### El objeto `signature`

La seguridad se garantiza mediante un campo de firma. Cada petición que envíes debe estar firmada utilizando tu clave del comercio. Del mismo modo, cada respuesta que recibas incluye una firma que debes verificar para asegurar la integridad y el origen del mensaje.

## Códigos de estado HTTP

La API utiliza códigos de estado HTTP estándar para indicar el resultado inmediato de la llamada a la API.

| Código | Estado | Descripción |
| :---- | :---- | :---- |
| **200** | OK | La operación se ha recibido y validado correctamente. |
| **201** | Created | El proceso de creación de la entidad se ha completado satisfactoriamente. |
| **401** | Unauthorized | La petición carece de credenciales de autenticación válidas. |
| **403** | Forbidden | El acceso está permanentemente prohibido, independientemente de la autenticación. |
| **404** | Not Found | El recurso solicitado no está disponible. |
| **405** | Method Not Allowed | El método HTTP (p. ej., GET frente a POST) no está soportado para esta URI. |
| **415** | Unsupported Media Type | El formato de la petición no es soportado (asegúrate de usar JSON). |
| **429** | Too Many Requests | Se han excedido las cuotas de consumo de la API. |

## Siguientes pasos

Una vez comprendidos los conceptos generales, puedes proceder con los pasos de integración:

1. [**Configurar entornos y credenciales**](/es/get-smart/get-smart-api-cloud/first-steps/configure-environments-and-credentials): Aprende a gestionar los datos de prueba y producción.  
2. [**Autenticar peticiones**](/es/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests): Implementa la lógica de firma requerida para cada llamada a la API.  
3. [**Procesar tu primer pago**](/es/get-smart/get-smart-api-cloud/first-steps/process-your-first-payment): Sigue un tutorial paso a paso para completar una transacción.