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:

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.
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.

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.

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:

Configurar Ambientes e Credenciais: Saiba como gerenciar dados de teste e produção.
Autenticar Requisições: Implemente a lógica de assinatura necessária para cada chamada da API.
Processar Seu Primeiro Pagamento: Siga um tutorial passo a passo para concluir uma transação.