Getnet DocsGetnet Docs

Arquitetura da API Cloud

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

A Get Smart API Cloud foi projetada para preencher a lacuna entre o seu software de gestão baseado na nuvem e os terminais de pagamento físicos (TPV-PC). Ao contrário das APIs puramente de e-commerce, onde as transações ocorrem instantaneamente no navegador, os pagamentos físicos exigem interação humana (inserção de cartão, digitação de PIN).

Para acomodar isso, a API utiliza uma arquitetura assíncrona de duas fases. Entender esse fluxo é essencial para evitar erros comuns de integração, como presumir que uma transação está concluída ao receber a resposta HTTP inicial.

Fluxo de Dados de Alto Nível

O ciclo de vida de uma transação envolve três partes: Sua Aplicação, a API Cloud e o Terminal Físico.

  1. Iniciação (Síncrona): Sua aplicação envia uma requisição para a Cloud.
  2. Processamento (Físico): A Cloud instrui o Terminal a ser ativado. O cliente interage com o dispositivo.
  3. Conclusão (Assíncrona): A Cloud notifica sua aplicação sobre o resultado final.

Fase 1: A Requisição Síncrona

Quando você envia uma requisição (ex.: para /pago), a API Cloud realiza uma verificação de validação imediata.

  • O que acontece: O sistema verifica suas credenciais, a assinatura da mensagem e o formato JSON.
  • A Resposta: Você recebe uma resposta HTTP 200 OK imediata com um código de resultado.
  • Conceito Crucial: Um código de resultado "0" não significa que o pagamento foi aprovado. Significa simplesmente “Requisição Recebida e Validada.”
// Example Synchronous Response
{
    "resultado": {
        "codigo": "0" // The command was successfully queued for the terminal.
    }
}

Não trate esta resposta como um recibo. Nesta fase, nenhum dinheiro foi movimentado. O terminal pode nem ter acendido ainda. Você deve atualizar o status local do seu pedido para “Pendente” ou “Em Andamento”.

Fase 2: A Notificação Assíncrona

Uma vez que a fase síncrona é concluída, a API Cloud envia o comando para o ID do terminal específico definido na sua requisição.

  1. Interação: O terminal solicita a ação ao usuário. O usuário insere seu cartão e digita seu PIN.
  2. Geração de Resultado: O terminal comunica o resultado (Aprovada, Negada, Cancelada) de volta para a Cloud.
  3. Notificação: A API Cloud envia uma requisição POST para a urlNotificacion que você definiu na sua requisição inicial.

Esta notificação contém o resultado final da transação, incluindo códigos de autorização, dados do recibo e detalhes do cartão.

Fallback de Notificação

O sistema é projetado para garantir que você receba o resultado mesmo se o seu servidor estiver inacessível.

  • Canal Principal: urlNotificacion (HTTP POST).
  • Canal Secundário: Se a chamada para a sua URL falhar (ex.: seu servidor está inoperante ou retorna um erro), o sistema tenta enviar um e-mail para o endereço definido em correoNotificacion.

Requisitos do Sistema

Para participar desta arquitetura, sua integração deve atender a restrições específicas definidas no padrão.

Rede e Segurança

  • Protocolo: Todas as conexões devem ser protegidas via TLS 1.2 ou superior.
  • Acesso: A conectividade é estabelecida por meio de linhas públicas de internet; não são necessárias VPNs ou linhas alugadas dedicadas para a interface REST.
  • Codificação: Todos os dados devem ser codificados em UTF-8.

Restrições JSON

A API é rigorosa em relação aos tipos de dados para garantir a estabilidade em diferentes softwares de terminais.

  • Sem valores null: Os campos nunca devem ser definidos explicitamente como null. Se um campo for opcional e não tiver valor, ele deve ser totalmente omitido do objeto JSON.
  • Minimização: Embora não seja estritamente obrigatório para o processamento (parsing), recomenda-se evitar espaços em branco excessivos, tabulações ou quebras de linha em payloads de produção para evitar problemas de verificação de assinatura.

Próximos Passos