Conectando o Solomon

A integração pode estar em liberação gradual. Se o card não aparecer para sua conta, fale com o suporte.

Antes de começar

Tenha uma conta na plataforma e permissão para autorizar a conexão.

Credencial manual por chave de API, sem OAuth documentado. O lojista cria a chave no painel da Solomon, na tela de API Keys, e o segredo aparece uma única vez no momento da criação. Toda requisição leva o header `Authorization: Bearer SUA_API_KEY` e `Content-Type: application/json`. Cada chave pertence a UMA loja, e várias chaves de soluções diferentes podem conviver na mesma loja. A chave carrega escopos granulares escolhidos na criação, e cada endpoint exige o seu: 403 quando o escopo falta. Os ambientes são separados por host e por chave — chave de Sandbox (`https[:]//admin-api[.]sandbox[.]solomon[.]com[.]br/admin/v1`) não funciona em Live (`https[:]//admin-api[.]solomon[.]com[.]br/admin/v1`) e vice-versa, e usar a chave no host errado também devolve 403. Prazo de validade da chave não é documentado, mas a doc cita 401 para token expirado, então expiração existe sem prazo publicado.

• Chave de API: Painel da Solomon, tela de API Keys: clicar em criar nova chave e copiar o segredo, que é exibido uma única vez no momento da criação. Marque os escopos de leitura de custos e influenciadores para a Toca conseguir consultar.
• Ambiente (Live ou Sandbox): É o ambiente em que a chave foi criada no painel. Chave de Sandbox não funciona em Live e vice-versa, e o host muda com ele: admin-api[.]solomon[.]com[.]br em Live, admin-api[.]sandbox[.]solomon[.]com[.]br em Sandbox.

Passo a passo

1. Acesse Configurações → Integrações na Toca.
2. Localize o card Solomon e clique em Conectar.
3. Preencha os campos de credencial apresentados pelo formulário.
4. Confirme que o card indica a conexão e faça uma primeira consulta no chat.

O que a Toca acessa

• Listar custos adicionais
• Histórico de custos projetados
• Listar influenciadores
• Listar custos de influenciadores

Alterações disponíveis, sempre mediante aprovação explícita no chat:

• Envia um pedido da loja para a base de atribuição da Solomon, com valores em reais decimais (`totalPrice` 249[.]9), `currency` ISO 4217 e `createdAt`/`updatedAt` em ISO 8601, mais os dados do cliente e os itens. Entra numa fila (202) e passa a contar nos relatórios de atribuição da loja..
• Envia um produto e suas variantes (com `price` em reais decimais e `currency`) para a base da Solomon. Entra numa fila (202) e passa a aparecer no catálogo da plataforma..
• Cria um custo adicional da operação (nome, tipo, valor em reais, vigência e frequência `specific`, `daily`, `weekly` ou `monthly`), que passa a entrar no cálculo de margem da loja. O `additional_cost_id` é gerado pela própria API..
• Sobrescreve um custo adicional existente, identificado pelo `additional_cost_id` no corpo: nome, tipo, valor, vigência, situação e frequência. Trocar de frequência exige mandar `old_frequency`, porque o custo muda de gaveta..
• Remove de vez um custo adicional pelo `additional_cost_id` enviado no corpo, junto da `frequency`. O custo deixa de entrar no cálculo de margem, inclusive no histórico projetado. — operação destrutiva; revise os efeitos antes de autorizar.
• Cadastra um influenciador com campanha, categoria, custos e cupons, e gera links curtos rastreáveis públicos em track[.]solomon[.]com[.]br a partir das URLs informadas (validadas anti-SSRF: só HTTPS e host público), com UTMs montadas pela própria Solomon. O link nasce vivo e é o que vai para o público..
• Troca a categoria do influenciador identificado pelo `name` no corpo..
• Remoção permanente e irreversível, em níveis: apaga link pelo `short_code`, campanha e dados associados pelo `campaign_id` e, com `delete_influencer: true`, o influenciador inteiro, incluindo custos por nome e cadastro. O link curto apagado para de resolver para quem já o recebeu. — operação destrutiva; revise os efeitos antes de autorizar.
• Adiciona custos a um ou mais influenciadores: `fixed_fee` (cachê fixo em R$), `var_fee` (comissão variável em %), `value` (valor por entrega em R$), vigência, frequência e os marcadores `is_campaign_cost` (custo de campanha ou do influenciador) e `is_coupon_cost` (atribuição por cupom ou por cupom mais link)..
• Remove um custo de influenciador pelo `cost_id` e `frequency` enviados no corpo. A comissão deixa de entrar no cálculo, sem recuperação documentada. — operação destrutiva; revise os efeitos antes de autorizar.
• Vincula cupons a uma campanha de influenciador (`cupom`, `start_date`, `end_date`), para atribuir venda ao influenciador. A API valida que os períodos de um mesmo cupom não se sobreponham..
• Desvincula um cupom da campanha, pelo `campaign_id` e `cupom` no corpo. A venda com aquele cupom para de ser atribuída ao influenciador, sem desfazer documentado. — operação destrutiva; revise os efeitos antes de autorizar.

A integração está em homologação: o contrato foi preparado a partir da documentação e ainda precisa ser confirmado em conta real. Confira os dados importantes no painel da plataforma.

Manutenção da conexão

Se o acesso for revogado ou as credenciais mudarem, reconecte pelo card da plataforma. Não compartilhe credenciais no chat.

Problemas comuns

• O card não aparece: a liberação pode depender da sua conta; fale com o suporte.
• A conexão foi recusada: confira as permissões e os dados informados na plataforma.
• Uma consulta não retorna o esperado: confira o painel e informe ao suporte qual consulta falhou.
• Ponto pendente de homologação: Paginação: a doc das quatro listagens (GET /admin/v1/costs, /costs/historical, /influencers e /influencers/costs) não declara nenhum parâmetro de página, tamanho ou cursor, nem objeto de meta na resposta — declarei modo `none`, mas falta medir em conta real com volume se a resposta vem inteira ou se há corte silencioso. `tamanhoPagina` fica NÃO DECLARADO.
• Ponto pendente de homologação: itemsPath não é uniforme e esse é o risco mais caro: em GET /admin/v1/costs o `data` é objeto com as gavetas `monthly`, `weekly`, `daily` e `specific` (mapa de id para custo), enquanto nas outras três é array. Declarei `data`, mas a leitura de custos precisa de override por endpoint ou volta vazia com cara de 'não há custo'.
• Ponto pendente de homologação: Rate limit: a doc confirma duas janelas independentes por recurso (30 minutos e teto diário) e os headers, mas diz que os valores variam por plano e volume e não publica número nenhum. Falta ler `X-RateLimit-Limit` numa conta real para declarar o teto.
• Ponto pendente de homologação: Limites de consulta NÃO DECLARADOS: a doc não informa janela máxima de data para `start`/`end` em GET /admin/v1/costs/historical, nem teto de itens por resposta. Falta medir com intervalo longo.
• Ponto pendente de homologação: Unidade monetária declarada como reais a partir da doc (totalPrice 249[.]9, item price 199[.]9, currency BRL ISO 4217, e `fixed_fee`/`value` descritos em R$), mas o exemplo de `value` em custo adicional é o inteiro 3500 sem unidade explícita na página de listagem — falta um smoke em conta real confirmando que custo adicional é reais e não centavos.
• Ponto pendente de homologação: Validade da chave de API não documentada: a doc cita 401 para token expirado mas não publica prazo nem caminho de renovação, e não há refresh. Falta saber se a chave expira e em quanto tempo.
• Ponto pendente de homologação: Não há endpoint de leitura de pedido, produto, jornada nem relatório de atribuição na doc pública — o lado de vendas é só ingestão (202 assíncrono). Falta confirmar com a Solomon se existe API de métricas não publicada; sem ela a integração não responde faturamento nem ROAS.
• Ponto pendente de homologação: Confirmação de gravação: pedido e produto respondem 202 (enfileirado) e não há rota de consulta de status da fila nem de releitura, então não há como verificar se o registro entrou. Falta descobrir se existe webhook ou endpoint de status.
• Ponto pendente de homologação: Identificação por texto livre: PUT e DELETE de influenciador usam o `name` como chave no corpo. Falta medir o comportamento com homônimo antes de liberar a remoção, porque o alvo errado é irreversível.
• Ponto pendente de homologação: Cor da marca e ícone do card NÃO DECLARADOS: não encontrei página oficial de identidade visual aberta nesta pesquisa.
• Ponto pendente de homologação: Base URL por ambiente: Live e Sandbox têm hosts distintos e a chave não funciona no host errado (403). Falta decidir se o ambiente vira campo de credencial de verdade ou se a integração só suporta Live.