Panorama Navigator — API Documentation v1.3.3

Introdução

Esta API permite a automação completa da troca de informações — ida e volta — entre o sistema ERP da empresa cliente e o Panorama Navigator.

📁

Troca de Arquivos

A integração ocorre por meio de troca de arquivos. A empresa envia arquivos com dados do ERP (transações, pedidos, cadastro de materiais) e, ao final do processamento, exporta os parâmetros calculados em formato CSV para atualizar seu ERP.

⚙️

Processos Dedicados

Cada tipo de arquivo da empresa possui um processo dedicado que realiza todas as traduções e transformações necessárias para adequar os dados ao formato do Panorama Navigator. Se a empresa tem 6 tipos de arquivo, são 6 processos configurados.

🔧

Configuração no SETUP

Os processos específicos de cada empresa são construídos pela equipe da SIO Panorama durante o período de SETUP da integração, garantindo total compatibilidade com os dados do cliente.

Autenticação & Segurança

A API utiliza autenticação baseada em tokens JWT com expiração curta. O sistema cliente deve obter um token antes de realizar qualquer operação e renová-lo automaticamente antes da expiração.

Onboarding

Durante a integração, a equipe da SIO Panorama fornece as credenciais client_id e client_secret exclusivas da sua empresa. Guarde-as com segurança.

Obter Token

Envie as credenciais para POST /auth/token. A API retorna um access_token JWT válido por 5 minutos (300 segundos).

Usar o Token

Inclua o token em todas as requisições no header:
Authorization: Bearer {access_token}

Renovação Automática

Monitore o campo expires_in. Renove o token antes da expiração chamando POST /auth/token novamente. Implemente retry em caso de 401.

Exemplo — Obtendo o Token

POST /v1/auth/token
Content-Type: application/json

{
  "client_id": "minha-empresa",
  "client_secret": "s3cr3t-k3y-abc123"
}

── Resposta (200 OK) ──

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

Exemplo — Usando o Token

GET /v1/catalogs
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

Endpoints

Visão geral de todos os endpoints disponíveis na API.

Método	Endpoint	Descrição	Grupo
POST	/auth/token	Obter token de acesso JWT	Auth
GET	/catalogs	Listar catálogos da empresa	Catálogos
POST	/files/upload-url	Solicitar URL para upload de arquivo	Arquivos
GET	/files	Listar arquivos de um processo	Arquivos
POST	/processing	Solicitar execução do processamento	Processamento
POST	/parameters/exports	Solicitar exportação de parâmetros	Parâmetros
GET	/parameters/exports/{exportId}	Consultar status e baixar exportação	Parâmetros

Estruturas de Dados

Detalhamento dos payloads de request e response de cada endpoint.

POST /auth/token

▾

Request Body

Campo	Tipo	Descrição
client_id	string	Identificador do cliente
client_secret	string	Chave secreta do cliente

Response (200)

Campo	Tipo	Descrição
access_token	string	Token JWT para autenticação
token_type	string	Sempre "Bearer"
expires_in	integer	Tempo de vida em segundos

GET /catalogs

▾

Query Parameters

Param	Tipo	Descrição
page	integer	Página (padrão: 1, máx 25/página)

Response (200) — cada item em data

Campo	Tipo	Descrição
id	uuid	Identificador único do catálogo
name	string	Nome do catálogo
created_at	datetime	Data de criação (UTC)

POST /files/upload-url

▾

Request Body

Campo	Tipo	Descrição
process_id	uuid	ID do processo que receberá o arquivo
file_name	string	Nome do arquivo com extensão (máx 255 chars)

Response (201)

Campo	Tipo	Descrição
file_id	uuid	ID único do arquivo registrado
upload_url	uri	URL pré-assinada para upload via PUT (expira em 15 min)
upload_url_expires_at	datetime	Expiração da URL (UTC)
created_at	datetime	Data de criação do registro (UTC)

GET /files

▾

Query Parameters

Param	Tipo	Descrição
process_id	uuid	ID do processo
page	integer	Página (padrão: 1, máx 25/página)

Response (200) — cada item em data

Campo	Tipo	Descrição
file_id	uuid	Identificador único do arquivo
file_name	string	Nome do arquivo
size_bytes	int64	Tamanho em bytes (nullable)
status	enum	pending · processing · completed · failed · partial
uploaded_at	datetime	Data do upload (UTC, nullable)

POST /processing

▾

Request Body (todos opcionais)

Campo	Tipo	Descrição
catalog_ids	uuid[]	IDs dos catálogos (omitir = global)
scheduled_at	datetime	Agendamento (omitir = imediato)

Response (202)

Campo	Tipo	Descrição
processing_id	uuid	ID da solicitação de processamento
catalog_ids	uuid[]	Catálogos específicos (null se global)
scheduled_at	datetime	Agendamento (nullable)
created_at	datetime	Data de criação (UTC)

POST /parameters/exports

▾

Request Body (opcional)

Campo	Tipo	Descrição
catalog_ids	uuid[]	IDs dos catálogos (omitir = todos os SKUs)