API Saara Online — Guia técnico pra integradores (Base)

Documentação técnica preliminar pra avaliação de integração com a API do Saara Online (marketplace multi-vendedor baseado em Medusa/Mercur). Cobre os 3 grupos de endpoint necessários pra um conector de ERP/plataforma: produtos, estoque e pedidos. Credencial de teste no final da página.

URL base

https://slb.saaraonline.com.br

Autenticação

Autenticação por sessão via e-mail/senha (padrão do Medusa v2). Cada integrador autentica com as credenciais da loja e recebe um token Bearer:

POST /auth/member/emailpass
Content-Type: application/json

{
  "email": "integracao-base@saaraonline.com.br",
  "password": "<fornecida à parte>"
}

Resposta:

{ "token": "eyJhbGciOi..." }

Todas as chamadas abaixo usam esse token, mais um header identificando a loja (necessário porque o sistema é multi-vendedor — um mesmo login pode ter acesso a mais de uma loja):

Authorization: Bearer <token>
x-seller-id: sel_xxxxxxxxxxxx

O token expira periodicamente (padrão Medusa, ~24h) — o integrador deve re-autenticar quando receber 401, não é necessário pedir um token novo pra cada chamada.

1. Produtos

Listar produtos da loja

GET /vendor/products?limit=20&offset=0

Resposta (exemplo real, ambiente de teste):

{
  "products": [
    {
      "id": "prod_01M328MZ5G6D6N31NQY167CE74",
      "title": "Bolsa Tote Bag Grande Texturizada com Bolsos Frontais",
      "status": "published",
      "thumbnail": "https://slb.saaraonline.com.br/static/....jpeg"
    }
  ],
  "count": 2,
  "offset": 0,
  "limit": 20
}

Detalhe de um produto (com variantes e itens de estoque)

GET /vendor/products/:id?fields=id,title,status,thumbnail,*variants,*variants.inventory_items
{
  "product": {
    "id": "prod_01M328MZ5G6D6N31NQY167CE74",
    "title": "Bolsa Tote Bag Grande Texturizada com Bolsos Frontais",
    "status": "published",
    "variants": [
      {
        "id": "variant_01M328MZD80TTK5M5VVJFWHD98",
        "title": "Verde",
        "sku": "skubg109-Verde",
        "weight": 470,
        "inventory_items": [
          { "inventory_item_id": "iitem_01M328MZFE5SZYGERAG13JK370" }
        ]
      }
    ]
  }
}

Criar / atualizar produto

POST /vendor/products
POST /vendor/products/:id   (atualização)
DELETE /vendor/products/:id

Payload de criação segue o schema padrão do Medusa Admin/Vendor API (título, descrição, variantes, opções, preços, categorias, imagens) — a documentação completa de campos é a própria documentação oficial do Medusa v2, já que o Mercur não altera esse contrato pra produtos.

2. Estoque

Consultar níveis de estoque de um item

GET /vendor/inventory-items/:inventory_item_id/location-levels
{
  "inventory_levels": [
    {
      "id": "ilev_01M328MZWFMMVY1QPP2AHESQYR",
      "inventory_item_id": "iitem_01M328MZFE5SZYGERAG13JK370",
      "location_id": "sloc_01M2VWBE6C578KN67FZ1ZWFQFP",
      "stocked_quantity": 5,
      "reserved_quantity": 0,
      "available_quantity": 5
    }
  ]
}

Atualizar quantidade em estoque

POST /vendor/inventory-items/:inventory_item_id/location-levels/:location_id

{ "stocked_quantity": 10 }

Toda loja tem 1 local de estoque (location_id) por padrão — devolvido junto na consulta de níveis acima.

3. Pedidos

Listar pedidos da loja

GET /vendor/orders?limit=20&offset=0
{
  "orders": [
    {
      "id": "order_01M2WR5CKY6B0QCN9X781PJBBK",
      "display_id": 636,
      "status": "pending",
      "email": "cliente@exemplo.com",
      "currency_code": "brl",
      "items": [
        {
          "product_id": "prod_01M2WP6J72HQP5D2FZ0NKB3PPS",
          "variant_sku": "TESTE-NFE-001",
          "quantity": 1,
          "unit_price": 5
        }
      ]
    }
  ]
}

Detalhe de um pedido

GET /vendor/orders/:id

Marcar como enviado (fulfillment + rastreio)

POST /vendor/orders/:id/fulfillments
POST /vendor/orders/:id/fulfillments/:fulfillment_id/shipments   (adiciona código de rastreio)
POST /vendor/orders/:id/fulfillments/:fulfillment_id/cancel
POST /vendor/orders/:id/fulfillments/:fulfillment_id/mark-as-delivered

Credencial de teste (temporária)

Login isolado numa loja de testes (sem dados reais de clientes/lojistas), pra avaliação. Pode ser revogado a qualquer momento.

Essa loja já tem 2 produtos de teste cadastrados (um simples, um com variação de cor + estoque) pra exercitar os exemplos acima.

Observações

Revision #1
Created 2026-09-24 22:36:03 UTC by Saara Online
Updated 2026-09-24 22:36:03 UTC by Saara Online