Documentação da API

Início rápido

Da conta à primeira resposta

A API está disponível nos planos Profissional e Empresarial. O Token API fica preso ao Espaço ativo no momento da criação, age como a pessoa que gerou a chave e não acompanha uma troca posterior de Espaço na interface.

1. 1

   Confirme o Espaço

   Entre na Lecodaro Cloud, selecione o Espaço correto e leia o plano, a franquia e as permissões em GET /context.

2. 2

   Abra Integração no menu

   Dentro da plataforma, informe um nome claro para a integração e escolha somente leitura ou leitura e escrita. A mesma tela mostra o bloco MCP para agentes.

3. 3

   Copie o Token API

   O valor completo aparece uma única vez. Guarde-o num gerenciador de credenciais do servidor que fará a integração.

4. 4

   Teste o contexto

   Use GET /context para validar o Token API, o Espaço, a participação e o nível de acesso antes de chamar outro recurso.

curl https://cloud.lecodaro.com.br/api/v1/context \
  -H"Authorization: Bearer SEU_TOKEN_API" \
  -H"Accept: application/json"

Token API

Autenticação e acesso

• Cada pessoa mantém no máximo 2 Tokens API ativos por Espaço.
• Remover a pessoa do Espaço corta o acesso do Token API na chamada seguinte.
• Tokens API não expiram automaticamente nesta versão. Revogue os que não estiverem mais em uso.
• Recurso de outro Espaço responde 404 para não confirmar que existe.

Console interativo

Teste a API nesta página

A chamada sai do seu navegador diretamente para https://cloud.lecodaro.com.br/api/v1. O Token API não é salvo pela página, não entra em cookie e desaparece quando a aba é fechada ou recarregada. Cada teste consome o limite real do seu Espaço.

Escolha um endpoint e envie a chamada.

Contrato HTTP

Como montar as requisições

Respostas e erros

O que a API devolve

Sucesso devolve o recurso em data. Coleções acrescentam paginação. Erros trazem message e podem incluir error.code ou errors por campo. Toda resposta recebe X-Request-Id.

{"data": {"space": {"id": 123,"name":"Empresa exemplo"},"member": {"id": 456,"role":"owner"},"token": {"name":"Catálogo","abilities": ["read"]},"product_tree": {"levels": [{"id": 1,"position": 1,"name":"Marca"}, {"id": 2,"position": 2,"name":"Linha"}],"product_level":"Produto"},"brands": [{"id": 789,"name":"Marca exemplo"}]
  }
}

{"message":"Os dados informados são inválidos.","errors": {"title": ["O campo título é obrigatório."]
  }
}

Referência de payloads

Campos e regras por recurso

Os exemplos do console já carregam um corpo inicial para as principais escritas. Esta referência mostra os campos que mais afetam validação e comportamento.

Árvore e padrões de ficha

Migração para a árvore configurável

Desde 13/09/2026 cada Espaço organiza produtos numa árvore própria, de um a oito níveis, e todo produto tem padrão de ficha. A v1 continua valendo. Nível e pasta se identificam pelo id, padrão e campo pelo code, e produto pelo public_id. O nome aparece para leitura e nunca serve de chave.

POST /products
{
  "brand_id": 12,
  "line_id": 45,
  "name": "Aquecedor digital",
  "code": "AQ-2026",
  "family_code": "aquecedores"
}

GET /product-tree
GET /product-tree/nodes?q=Digital

POST /products
{
  "tree_node_id": 45,
  "name": "Aquecedor digital",
  "code": "AQ-2026",
  "family_code": "aquecedores"
}

{
  "brand_id": 12,
  "line_id": 45,
  "subline_id": null,
  "completeness_percent": 50
}

{
  "family_code": "aquecedores",
  "tree": {
    "node_id": 45,
    "level_id": 2,
    "path": [
      {"level_id": 1, "node_id": 12, "name": "Marca Exemplo"},
      {"level_id": 2, "node_id": 45, "name": "Digital"}
    ]
  },
  "completeness": {
    "percent": 50,
    "filled": 1,
    "total": 2,
    "missing_attribute_codes": ["potencia"]
  }
}

"mapping": [
  {"column": "SKU", "target": "product.code"},
  {"column": "Produto", "target": "product.name"},
  {"column": "Pasta", "target": "product.tree_node_id"}
]

rows[].preview: tree_node_id, tree_path e family_code
warnings[]: alvo da estrutura anterior no mapeamento

Deprecation: @1789268400
Sunset: Sat, 13 Mar 2027 03:00:00 GMT
Link: <.../documentacao-api#migracao-arvore>; rel="deprecation"
X-Lecodaro-Deprecated: products.body.brand_id

"warnings": [{
  "code": "deprecated",
  "id": "inbound.brand_name",
  "sunset_at": "2027-03-13T00:00:00-03:00"
}]

Eventos da árvore, dos padrões e da ficha

GET /product-events sem types devolve só os tipos que já existiam. Os novos se pedem pelo nome, por prefixo (types=product_tree.*) ou todos com types=*, e o webhook de saída assina cada tipo pelo nome. product.updated continua saindo junto. Mudança de estrutura é um evento por operação, com contagens: quando counts.products_affected for maior que zero, releia os produtos por GET /products?tree_node_id= ou ?family_code=. O evento nunca traz dado de pessoa nem id interno.

{
  "id": "981",
  "sequence": 42,
  "type": "product.moved",
  "occurred_at": "2026-09-13T10:15:00-03:00",
  "origin": "api",
  "subject": {"type": "product", "id": "00000000-0000-4000-8000-000000000001"},
  "product": {"public_id": "00000000-0000-4000-8000-000000000001", "code": "AQ-2026"},
  "changed_fields": ["tree_node_id"],
  "data": {
    "tree": {
      "from_node_id": 45,
      "to_node_id": 51,
      "path": [{"level_id": 1, "node_id": 12}, {"level_id": 2, "node_id": 51}]
    }
  }
}

Regras de uso dos campos e respostas de erro

Referência completa

Todos os endpoints

A lista é comparada automaticamente com as rotas registradas. Endpoint novo sem documentação e documentação de endpoint inexistente fazem o teste falhar.

Agentes e MCP

Como outra IA deve operar

{
  "base_url": "https://cloud.lecodaro.com.br/api/v1",
  "authentication": "Authorization: Bearer SEU_TOKEN_API",
  "first_call": "GET /context",
  "discovery": ["GET /mcp", "GET /openapi.json"],
  "quota_rule": "Se receber 429, pare e use Retry-After ou error.resets_at antes de tentar de novo."
}

Operação segura

Proteja a integração

Versão e mudanças

Contrato mantido junto do código