Padrões Gerais da API e Cabeçalhos

Este documento descreve os padrões técnicos, cabeçalhos HTTP e estruturas de mensagens que se aplicam a todos os endpoints na Get Smart API Cloud. A adesão a esses padrões é obrigatória para uma integração bem-sucedida.

Padrões de Comunicação

Todas as interações com a API devem seguir estritamente estes protocolos.

Requisito	Especificação
Protocolo	TLS 1.2 ou superior é obrigatório.
Rede	O acesso é realizado por meio de linhas públicas de internet.
Arquitetura	Web Services RESTful consumindo e produzindo JSON.
Codificação	UTF-8 é obrigatório para todas as mensagens.

Regras de Formatação JSON

Para garantir a integridade da mensagem e o processamento (parsing) correto:

Sem Valores null: Não envie campos com o valor null. Se um campo for opcional e não utilizado, omita-o totalmente do objeto JSON.
Minimização: É fortemente recomendado evitar tabulações, quebras de linha ou espaços extras dentro do corpo da mensagem JSON.
Tipos Estritos: Respeite os tipos de dados (String vs. Number) definidos nas especificações dos endpoints.

Cabeçalhos HTTP

Você deve incluir os seguintes cabeçalhos em cada requisição.

Cabeçalho	Valor	Requisito	Descrição
`Content-Type`	`application/json`	Obrigatório	Indica o formato do corpo da requisição.
`Accept`	`application/json`	Obrigatório	Indica que o cliente espera JSON na resposta.
`Content-Length`	(Inteiro)	Opcional	O tamanho do corpo da requisição em bytes.

Códigos de Status HTTP

A API retorna códigos de status HTTP padrão para indicar o resultado imediato do processamento da requisição.

Código	Mensagem	Significado
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`	Credenciais inválidas. A autenticação falhou.
403	`Forbidden`	O acesso é permanentemente proibido (erro de lógica, não erro de autenticação).
404	`Not Found`	O recurso solicitado (URL) não existe.
405	`Method Not Allowed`	Você usou o verbo HTTP incorreto (ex.: GET em vez de POST).
415	`Unsupported Media Type`	O formato da requisição não é suportado (Verifique o `Content-Type`).
429	`Too Many Requests`	Você excedeu as cotas de consumo da API.

Estrutura da Mensagem

Cada interação com a API (Requisição e Resposta) segue uma estrutura de “envelope” padrão contendo dois objetos de nível superior.

Estrutura de Requisição

{
  "info": {
    "comercio": "123456789",
    "terminal": 1,
    "timestamp": "YYYYMMDD HHmmss",
    "datosOperacion": { ... }
  },
  "signature": "SHA256_HASH_STRING"
}

Campo	Tipo	Obrigatório	Descrição
`info`	Object	Sim	O contêiner para todos os dados de negócio.
`signature`	String	Sim	O hash SHA-256 verificando a integridade do `info`.

Estrutura de Resposta

{
  "info": {
    "comercio": "123456789",
    "terminal": 1,
    "timestamp": "YYYYMMDD HHmmss",
    "resultado": {
      "codigo": "0",
      "descripcion": "Example Description"
    }
  },
  "signature": "SHA256_HASH_STRING"
}

Formatos de Dados Comuns

A menos que especificado de outra forma em uma referência de endpoint específico, use estes formatos:

Valores (importe): XXXXXXXXX.XX (String ou Double). Exemplo: 10.50 ou 0.01. Máx. 12 caracteres.
Timestamps: * Na raiz do info: YYYYMMDD HHmmss (ex.: 20250428 111217)
- Em datosOperacion (Consultas): YYYY-MM-DD-HH.mm.ss ou YYYY-MM-DD HH:mm:ss (Consulte a documentação do endpoint específico).
Booleanos: JSON true ou false.