# 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:

1. **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.  
2. **Minimização:** É fortemente recomendado evitar tabulações, quebras de linha ou espaços extras dentro do corpo da mensagem JSON.  
3. **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

```json
{
  "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

```json
{
  "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`.