# Visão Geral da API Cloud

A Get Smart API Cloud permite integrar suas aplicações de negócio com terminais de pagamento físicos (TPV-PC) por meio de uma interface padronizada na nuvem. Este serviço possibilita gerenciar pagamentos, estornos e pré-autorizações utilizando web services RESTful, enquanto o terminal físico lida com a interação com o portador do cartão.

Este guia explica a arquitetura de alto nível, os padrões técnicos e os protocolos de comunicação necessários para a integração com a solução.

## Como Funciona

A API opera no paradigma **REST/JSON**. Sua aplicação cliente envia requisições HTTP para os endpoints na nuvem, que se comunicam com o terminal físico específico conectado à rede.

O fluxo de comunicação consiste em duas fases distintas:

1. **Requisição Síncrona:** Você envia uma requisição (ex.: um comando de pagamento) para a API. A API valida o formato e a segurança da mensagem e retorna imediatamente uma resposta indicando se a requisição foi aceita (`200 OK`) ou rejeitada.  
2. **Notificação Assíncrona:** Como as interações com um terminal físico (inserção de PIN, aproximação do cartão) levam tempo, o resultado final da operação é enviado de forma assíncrona. O sistema envia os dados finais da transação para uma `urlNotificacion` fornecida por você ou via e-mail, caso a notificação por URL falhe.

## Requisitos Técnicos

Para garantir uma comunicação segura e confiável, sua integração deve seguir os seguintes padrões:

* **Protocolo de Comunicação:** É necessário utilizar **TLS 1.2** ou superior para todas as conexões.  
* **Rede:** O acesso é realizado por meio de linhas públicas (Internet).  
* **Codificação:** Todas as mensagens devem utilizar a codificação **UTF-8**.  
* **Formato:** Todas as mensagens consomem e geram conteúdo no formato **JSON**.

### Regras de Formatação JSON

Regras estritas de formatação JSON se aplicam a todas as requisições. O não cumprimento dessas regras pode resultar em respostas de erro.

<Callout type="warning">

Do not use `null` values. Campos opcionais que não forem utilizados, ou campos condicionais que não sejam necessários para uma operação específica, devem ser totalmente omitidos da mensagem. O envio de um campo com valor `null` não é permitido.

</Callout>

Além disso, evite o uso de tabulações, quebras de linha ou espaços desnecessários dentro do corpo da mensagem JSON para evitar erros de processamento (parsing).

## Estrutura de Requisição e Resposta

Cada interação com a API segue uma estrutura de envelope genérica que contém dois objetos principais: `info` e `signature`.

### O Objeto `info`

Este objeto contém o payload da sua requisição ou resposta. Ele inclui a identificação do estabelecimento, os detalhes da operação e os timestamps.

### O Objeto `signature`

A segurança é aplicada por meio de um campo de assinatura. Cada requisição enviada deve ser assinada utilizando sua chave de estabelecimento. Da mesma forma, cada resposta recebida inclui uma assinatura que você deve verificar para garantir a integridade e a origem da mensagem.

## Códigos de Status HTTP

A API utiliza códigos de status HTTP padrão para indicar o resultado imediato da chamada da API.

| Código | Status | Descrição |
| :---- | :---- | :---- |
| **200** | OK | A operação foi recebida e validada corretamente. |
| **201** | Created | O processo de criação da entidade foi concluído com sucesso. |
| **401** | Unauthorized | A requisição carece de credenciais de autenticação válidas. |
| **403** | Forbidden | O acesso é permanentemente proibido, independentemente da autenticação. |
| **404** | Not Found | O recurso solicitado não está disponível. |
| **405** | Method Not Allowed | O método HTTP (ex.: GET vs POST) não é suportado para esta URI. |
| **415** | Unsupported Media Type | O formato da requisição não é suportado (certifique-se de usar JSON). |
| **429** | Too Many Requests | Você excedeu as cotas de consumo da API. |

## Próximos Passos

Agora que você compreende os conceitos gerais, pode prosseguir para as etapas de integração:

1. [**Configurar Ambientes e Credenciais**](/pt/get-smart/get-smart-api-cloud/first-steps/configure-environments-and-credentials): Saiba como gerenciar dados de teste e produção.  
2. [**Autenticar Requisições**](/pt/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests): Implemente a lógica de assinatura necessária para cada chamada da API.  
3. [**Processar Seu Primeiro Pagamento**](/pt/get-smart/get-smart-api-cloud/first-steps/process-your-first-payment): Siga um tutorial passo a passo para concluir uma transação.