Magis5
Objetivo
O conector Magis5 integra a plataforma Fluid à API pública do Magis5, permitindo consultar e enviar pedidos, produtos, notas fiscais, etiquetas, anúncios e canais de venda.
É direcionado a clientes e equipes de suporte, oferecendo sincronização completa de dados de e-commerce entre o Magis5 e sistemas conectados via Fluid.
Requisitos (criando conexão
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
X-MAGIS5-APIKEY | string (secreto) | Sim | Chave de autenticação fornecida pela Magis5. Deve ser inserida no header das requisições. |
Autenticação:
A autenticação é feita exclusivamente via chave de API, passada no header:
Observações de segurança:
- O campo é marcado como fld_secret: true e não é exibido em logs ou interfaces públicas.
- A chave é gerada e controlada pelo próprio Magis5.
- Recomenda-se armazenar o valor em variáveis seguras (Vault) e revisar periodicamente sua validade.
Configurando um fluxo
- Formato: application/json.
- Paginação: via :limit e :page.
- Filtros: parâmetros como :status, :timestampFrom, :timestampTo, :structureType, :enableLink.
- Autenticação: header X-MAGIS5-APIKEY.
- Validação: todos os campos obrigatórios devem seguir o schema.
- Ambientes: definidos pela própria chave de API (sandbox ou produção).
Recursos e operações
Principais recursos suportados
Recurso | Operações disponíveis | Descrição |
|---|---|---|
Orders | GET /orders, GET /orders/:completeOrderNumber, POST /orders, PUT /orders/:completeOrderNumber, PATCH /orders/:completeOrderNumber | Criação, consulta e atualização de pedidos. |
Order detail required | GET /orders/details/required/queues | Consulta de detalhes obrigatórios de pedidos. |
Fulfillment | GET /fulfillments/queues, POST /fulfillments/queues/read | Controle de filas fulfillment. |
Invoices | GET /invoices/queues, POST /invoices/:completeOrderNumber, GET /invoices/documents/queues | Envio e leitura de notas fiscais. |
Products | GET /products, POST /products, PUT /products/:sku, PATCH /products/:sku | Criação e atualização de produtos. |
Ads | GET /ads/:sku, PUT /ads/prices/:sku | Consulta e atualização de anúncios. |
Labels | GET /labels/queues, GET /labels/:completeOrderNumber | Consulta e consumo de etiquetas. |
Channels | GET /channels, GET /channels/:channel | Listagem e pesquisa de canais de venda. |
Providers | GET /providers | Consulta de fornecedores. |
Callback | PUT /callbacks/stocks | Atualização de estoque via callback. |
Health | GET /health | Verificação do status da API. |
Na prática
Boas práticas
- Sempre incluir o header X-MAGIS5-APIKEY.
- Validar a chave antes da execução.
- Testar primeiro com chamadas de leitura (GET).
Disparando o fluxo
- Modos de execução: manual, evento externo ou agendamento.
- Validação: sucesso indicado por HTTP 200 ou 201; falhas retornam HTTP 4xx/5xx.
- Testes recomendados:
- GET /health para validar comunicação.
- GET /orders?limit=1 para confirmar acesso autenticado.
Conclusão
O conector Magis5 permite integração completa com os recursos principais da API Magis5 (pedidos, produtos, notas fiscais, anúncios e canais).
O modelo de autenticação via API Key simplifica a configuração e garante segurança, sem necessidade de autenticação via login.