# API Torre - TMS Kreative

Documentacao dos servicos de integracao, manutencao, consulta e tracking do TMS Kreative.

## 1. Informacoes gerais

### Base URL

```text
https://tms.kreativesistemas.com.br/api/v1
```

Todas as chamadas devem usar HTTPS e JSON.

### Autenticacao

O cliente recebe um token exclusivo por tenant/empresa. Enviar em todas as chamadas privadas:

```http
Authorization: Bearer {TOKEN_DA_EMPRESA}
Content-Type: application/json
Accept: application/json
```

O token identifica automaticamente o tenant. Nao envie esse token em JavaScript publico, aplicativo de terceiros ou pagina aberta ao consumidor final. Quando o cliente quiser oferecer consultas em seu proprio portal, o backend dele deve chamar esta API e repassar somente os dados autorizados.

Tambem e aceito o cabecalho `X-Api-Token`, mas o Bearer Token e o padrao recomendado.

### Restricao por IP

O tenant pode possuir uma lista de IPs autorizados. Se a lista estiver vazia, o token pode ser usado de qualquer origem. Se houver IPs cadastrados, chamadas de outras origens recebem `403 Forbidden`.

```json
{
  "success": false,
  "message": "IP nao autorizado para este token de API.",
  "ip": "200.200.200.200"
}
```

### Servicos disponiveis

| Ordem | Metodo | Endpoint | Finalidade |
| --- | --- | --- | --- |
| 1 | POST | `/torre/documentos/importacao` | Importar ou editar documentos e movimentos. |
| 2 | POST | `/torre/documentos/exclusao` | Excluir uma NF ainda sem movimentacao impeditiva. |
| 3 | POST | `/torre/romaneios/exclusao` | Excluir um romaneio e seus documentos permitidos. |
| 4 | POST | `/torre/consultas/status` | Consultar documentos por status e periodo. |
| 5 | POST | `/torre/consultas/comprovante` | Consultar os caminhos dos comprovantes de uma NF. |
| 6 | GET | `/torre/comprovantes/{id}/arquivo` | Visualizar ou baixar um comprovante privado. |
| 7 | POST | `/torre/consultas/notas` | Consultar NFs por CNPJ/CPF, papel e periodo. |
| 8 | GET/POST | `https://tms.kreativesistemas.com.br/tracking/{tenant}` | Tracking publico por documento, NF e papel. |
| 9 | POST | `/torre/cadastros/motoristas` | Importar ou atualizar motoristas. |
| 10 | POST | `/torre/cadastros/veiculos` | Importar ou atualizar veiculos. |

### Padrao das respostas de importacao e exclusao

```json
{
  "success": true,
  "message": "Importacao processada com sucesso.",
  "request_id": 123,
  "status": "processado",
  "total": 2,
  "processados": 2,
  "falhas": 0,
  "resultado": {
    "criados": [],
    "atualizados": [],
    "falhas": []
  }
}
```

## 2. Importacao e edicao de documentos

Importa entregas, coletas, transferencias e reentregas. O mesmo endpoint tambem edita um documento existente; esse comportamento e chamado de `upsert`.

```http
POST /torre/documentos/importacao
```

### Identificacao e atualizacao

- A requisicao recebe um array JSON.
- Cada item representa uma NF/CT-e/movimento.
- `tipomov = COL` cria ou atualiza uma coleta.
- Os demais tipos criam ou atualizam documentos operacionais.
- Se `chave_nfe` estiver preenchida, ela e o identificador principal.
- Sem chave, o documento e identificado por NF, CT-e e romaneio.
- O romaneio e localizado ou criado por romaneio, data, placa e, quando informado, motorista.
- Reenviar um documento existente atualiza os campos recebidos conforme as regras da integracao.

### Campos principais obrigatorios

| Campo | Tipo | Descricao |
| --- | --- | --- |
| `romaneio` | string | Numero do manifesto/romaneio. |
| `codmot` | string | Codigo, CPF ou identificador do motorista. |
| `nome_mot` | string | Nome do motorista. |
| `placa_veic` | string | Placa do veiculo. |
| `cte` | string | Numero do CT-e; pode ser `"0"`. |
| `seq_ent` | string/int | Sequencia de entrega. |
| `nf` | string | Numero da nota fiscal. |
| `tipomov` | string | `ENT`, `COL`, `TRA`, `REE` ou tipo acordado. |
| `datatransf` | string | Data no formato `YYYY-MM-DD`. |
| `endereco` | string | Endereco do destino/coleta. |
| `filial` | string | Filial de origem/base. |
| `filial_doc` | string | Filial do documento. |
| `tipoveic` | string | Tipo/modalidade do veiculo. |
| `cnpj_cliente` | string | Documento do cliente/remetente. |
| `uf` | string | UF do destino/coleta. |
| `avulso` | string/int | `0` ou `1`. |
| `fixo` | string/int | `0` ou `1`. |

### Campos opcionais mais utilizados

| Campo | Tipo | Descricao |
| --- | --- | --- |
| `chave_nfe` | string | Chave de acesso da NF-e. |
| `cliente` | string | Nome do cliente/remetente. |
| `nome_do_destino` | string | Nome do destinatario. |
| `cnpj_destinatario` | string | CNPJ/CPF do destinatario. |
| `cidade_de_destino` | string | Cidade do destino. |
| `bairro` | string | Bairro. |
| `cep_destino` | string | CEP do destino. |
| `cep_origem` | string | CEP da origem. |
| `volume` | number/string | Quantidade de volumes. |
| `peso` | number/string | Peso total. |
| `valor_da_mercadoria` | number/string | Valor da mercadoria. |
| `prazoentrega` | string | Previsao em `YYYY-MM-DD`. |
| `dt_prev_ent` | string | Previsao/agendamento em `YYYY-MM-DD HH:mm:ss`. |
| `obs` | string | Observacoes. |
| `refrigerado` | int/string | Indicador de refrigeracao. |

### Exemplo

```json
[
  {
    "romaneio": "52221",
    "codmot": "784512",
    "nome_mot": "JOSE MARIA LIBANO",
    "placa_veic": "BWE2G28",
    "cte": "0",
    "seq_ent": "1",
    "nf": "16446",
    "volume": "112",
    "peso": "1745",
    "valor_da_mercadoria": "3175.94",
    "cliente": "EMPRESA REMETENTE",
    "nome_do_destino": "CLIENTE DESTINATARIO",
    "cnpj_destinatario": "48727478000144",
    "tipomov": "ENT",
    "datatransf": "2026-08-13",
    "dt_prev_ent": "2026-08-13 14:30:00",
    "bairro": "CENTRO",
    "endereco": "RUA EXEMPLO 100",
    "filial": "SPO",
    "filial_doc": "SPO",
    "tipoveic": "A",
    "cnpj_cliente": "40165831000308",
    "uf": "MG",
    "avulso": "0",
    "refrigerado": "0",
    "fixo": "0"
  }
]
```

## 3. Exclusao de documentos

```http
POST /torre/documentos/exclusao
```

A exclusao usa `romaneio`, `nf` e `datatransf`. Ela e bloqueada quando o documento ja possui chegada, entrega, ocorrencia, comprovante, assinatura ou outra movimentacao impeditiva.

```json
[
  {
    "romaneio": "52221",
    "nf": "16446",
    "datatransf": "2026-08-13"
  }
]
```

Se a NF for o ultimo documento do romaneio, a entrega/romaneio vazio tambem pode ser removido.

## 4. Exclusao de romaneios

```http
POST /torre/romaneios/exclusao
```

Remove um romaneio completo pela combinacao de romaneio, placa e data. `codmot` e opcional. Todos os documentos precisam estar aptos para exclusao; um documento com movimentacao impede a exclusao do conjunto.

```json
[
  {
    "romaneio": "52221",
    "placa_veic": "BWE2G28",
    "codmot": "784512",
    "datatransf": "2026-08-13"
  }
]
```

## 5. Consulta por status e periodo

Consulta notas fiscais pelo status operacional e pelo horario correspondente ao status.

```http
POST /torre/consultas/status
```

| Campo | Obrigatorio | Tipo | Descricao |
| --- | --- | --- | --- |
| `status` | Sim | string | Ex.: `ocorrencia`, `entregue`, `chegada`, `em_rota`. |
| `dataHoraInicial` | Sim | datetime | Inicio em `YYYY-MM-DD HH:mm:ss`. |
| `dataHoraFinal` | Sim | datetime | Fim em `YYYY-MM-DD HH:mm:ss`. |
| `comprovante` | Nao | boolean | Quando `true`, inclui disponibilidade, caminho e URL. |
| `limite` | Nao | int | Padrao 500; maximo 1.000. |

Para `ocorrencia`, o periodo e aplicado em `ocorrencia_at`. Para `entregue`, e aplicado em `entregue_at`. Nos demais status, usa `ultima_atualizacao_status_at`.

### Exemplo: ocorrencias

```json
{
  "status": "ocorrencia",
  "dataHoraInicial": "2026-08-13 00:00:00",
  "dataHoraFinal": "2026-08-13 11:59:59"
}
```

### Exemplo: entregas com comprovante

```json
{
  "status": "entregue",
  "dataHoraInicial": "2026-08-13 00:00:00",
  "dataHoraFinal": "2026-08-13 11:59:59",
  "comprovante": true
}
```

Quando `comprovante` for omitido ou `false`, os campos de comprovante nao sao enviados. Quando for `true`, cada documento pode receber:

```json
{
  "comprovante": true,
  "comprovantes": [
    {
      "tipo": "entrega",
      "caminho": "comprovantes/2026/08/arquivo.jpg",
      "url": "https://tms.kreativesistemas.com.br/api/v1/torre/comprovantes/123/arquivo",
      "recebido_at": "2026-08-13 10:45:20"
    }
  ]
}
```

O cliente pode baixar o arquivo pela URL e, se precisar, converter o conteudo para Base64 em seu proprio sistema. A requisicao do arquivo tambem deve enviar o Bearer Token.

## 6. Consulta/captura de comprovante

Consulta uma NF e devolve todos os comprovantes vinculados.

```http
POST /torre/consultas/comprovante
```

Informe a chave da NF-e ou o numero da NF. CT-e e romaneio podem complementar a identificacao.

```json
{
  "chave_nfe": "35260840165831000308550010000164461234567890"
}
```

```json
{
  "nf": "16446",
  "cte": "123456",
  "romaneio": "52221"
}
```

A resposta inclui `comprovante`, `comprovantes[].id`, `comprovantes[].caminho` e `comprovantes[].url`. Sem arquivo vinculado, `comprovante` sera `false` e a lista estara vazia.

### Acesso ao arquivo privado

Os comprovantes copiados para o TMS nao ficam publicados em `/storage`. Para visualizar ou baixar, faca um `GET` na URL retornada em `comprovantes[].url`, enviando o mesmo `Authorization: Bearer {TOKEN_DA_EMPRESA}` usado nas consultas. O token precisa pertencer ao tenant do comprovante e continua sujeito a restricao de IP, quando configurada.

```http
GET /api/v1/torre/comprovantes/123/arquivo
Authorization: Bearer {TOKEN_DA_EMPRESA}
```

Uma requisicao sem credenciais, com token de outro tenant ou para um arquivo inexistente nao recebe a imagem.

## 7. Consulta de notas por CNPJ/CPF e periodo

Permite ao transportador ou distribuidor alimentar um portal proprio com as NFs relacionadas ao cliente consultado.

```http
POST /torre/consultas/notas
```

### Regras de papel

- Tenant Transportador: pode consultar por `remetente` ou `destinatario`.
- Tenant Distribuidor: pode consultar por `destinatario`.
- A consulta por destinatario atende os dois perfis.
- O periodo usa `data_emissao` da NF.

| Campo | Obrigatorio | Tipo | Descricao |
| --- | --- | --- | --- |
| `cnpj` | Sim | string | CNPJ/CPF do remetente ou destinatario. |
| `papel` | Sim | string | `remetente` ou `destinatario`. |
| `dataInicial` | Sim | date | Inicio em `YYYY-MM-DD`. |
| `dataFinal` | Sim | date | Fim em `YYYY-MM-DD`. |
| `comprovante` | Nao | boolean | Inclui comprovantes somente quando `true`. |
| `limite` | Nao | int | Padrao 500; maximo 1.000. |

```json
{
  "cnpj": "40165831000308",
  "papel": "remetente",
  "dataInicial": "2026-08-01",
  "dataFinal": "2026-08-31"
}
```

```json
{
  "cnpj": "48727478000144",
  "papel": "destinatario",
  "dataInicial": "2026-08-01",
  "dataFinal": "2026-08-31",
  "comprovante": true
}
```

## 8. Tracking publico

O tracking publico e indicado quando o consumidor final precisa consultar uma NF sem receber o token privado da API.

Pagina completa:

```text
https://tms.kreativesistemas.com.br/tracking/{tenant}
```

Versao incorporada:

```text
https://tms.kreativesistemas.com.br/tracking/{tenant}/embed
```

```html
<iframe
  src="https://tms.kreativesistemas.com.br/tracking/lvtbh/embed"
  width="100%"
  height="520"
  style="border:0; width:100%; min-height:520px;"
  loading="lazy"
></iframe>
```

| Campo | Tipo | Descricao |
| --- | --- | --- |
| `documento` | string | CPF/CNPJ relacionado a NF. |
| `nota_fiscal` | string | Numero da nota fiscal. |
| `papel` | string | `remetente` ou `destinatario`. |

O tracking precisa estar habilitado no cadastro do tenant.

## 9. Importacao/atualizacao de motoristas

```http
POST /torre/cadastros/motoristas
```

Recebe um array JSON. O identificador principal e o CPF; `codigo_externo` pode ser usado conforme a integracao acordada.

```json
[
  {
    "nome": "JOSE MARIA LIBANO",
    "cpf": "12345678901",
    "codigo_externo": "784512",
    "cnh": "12345678900",
    "validade_cnh": "2027-12-31",
    "telefone": "11999999999",
    "email": "motorista@empresa.com.br",
    "transportador_documento": "12345678000199",
    "status": "active"
  }
]
```

## 10. Importacao/atualizacao de veiculos

```http
POST /torre/cadastros/veiculos
```

Recebe um array JSON. A placa e o identificador principal.

```json
[
  {
    "placa": "BWE2G28",
    "tipo_veiculo": "VUC",
    "tipo": "A",
    "marca": "IVECO",
    "modelo": "DAILY",
    "ano": "2024",
    "capacidade_kg": "2000",
    "capacidade_m3": "12.5",
    "transportador_documento": "12345678000199",
    "status": "active"
  }
]
```

## 11. Codigos HTTP

| Codigo | Uso |
| --- | --- |
| `200` | Requisicao processada. |
| `400` | Requisicao malformada. |
| `401` | Token ausente ou invalido. |
| `403` | IP ou recurso nao autorizado. |
| `422` | Campo, periodo ou regra de negocio invalida. |
| `500` | Erro interno inesperado. |

## 12. Compatibilidade com o legado

O endpoint legado abaixo continua registrado para integracoes existentes:

```http
POST /api/v1/importacao/torre
```

Para novas integracoes, utilize os endpoints `/api/v1/torre/...` descritos neste documento.