Indica

API v1 beta

API para lojas parceiras

Envie o catálogo da sua loja para aparecer nas buscas do Indica, ao lado das maiores lojas do país. Preço, estoque e frete vêm sempre de você; o Indica compara, recomenda e leva a pessoa até a sua página.

Endereço base: https://api.indicacompras.com.br/v1

Baixar Markdown

Para quem é

  • Hub de lojas: um acesso só para todas as lojas. Cada loja é cadastrada com o código que o hub já usa e o CNPJ dela; cada produto diz de qual loja é.
  • Loja direta: a mesma integração, com uma loja só.

Como funciona

  1. Você recebe uma chave de homologação (ik_test_…), que grava numa área que não aparece no site.
  2. Cadastra a loja e envia os produtos. Cada produto mostra o estado dele: em análise, no ar ou por que não entrou.
  3. Com tudo certo, recebe a chave de produção (ik_live_…). O Indica aprova cada loja e os produtos entram nas buscas.
  4. Quando o clique é registrado, a pessoa chega à sua página com o parâmetro indica_click. Guarde esse código: é ele que identifica a venda que veio do Indica.

Regras que valem para todos

  • A comissão nunca muda a ordem das ofertas: seus produtos competem por preço, relevância e qualidade.
  • Produto sem atualização há mais de 48 horas sai das buscas até o próximo envio.
  • Frete não informado aparece como “a calcular”, nunca como grátis.
  • Nenhum dado de comprador é enviado ou recebido.
  • SKU único por parceiro: hubs devem usar um prefixo por loja.

Comissão esperada

No cadastro da empresa, informe default_commission. O produto pode ter sua própria commission, que prevalece sobre a geral. Aceitamos percentual ou valor fixo em reais por unidade.

{"type":"percentage","rate":6.5}
{"type":"fixed","amount_cents":900}

O painel mostra a estimativa por unidade. Comissão ausente é desconhecida, e receita depende de pedido pago.

Pedidos pagos e métricas

Consulte GET /clicks para receber os cliques. Quando o cliente pagar, envie POST /conversions; use novos eventos para cancelamentos e estornos parciais ou totais. O relatório GET /reports/commission reúne os números por loja e período.

Guarde indica_click por 30 dias. A regra de comissão do primeiro recebimento do pedido pago fica preservada. O saldo é esperado: não confirma recebimento de comissão pelo Indica.

Em homologação, crie um clique com POST /sandbox/clicks para testar o ciclo sem afetar a produção.

Em breve: campanhas/cupons, distribuição na vitrine e no WhatsApp, fechamento financeiro e portal do parceiro.

Convenções

  • JSON em UTF-8; dinheiro em centavos inteiros (29990 = R$ 299,90); datas ISO 8601 com fuso.
  • Chave no cabeçalho Authorization: Bearer ik_test_….
  • Erros no formato RFC 9457, com cada campo inválido listado em errors.
  • Escritas aceitam Idempotency-Key: repetir a mesma rota e corpo em até 24 h devolve a resposta original.
  • Até 600 escritas e 1.200 leituras por minuto por chave; acima disso, 429 com Retry-After.

Primeiro teste

curl https://api.indicacompras.com.br/v1/me \
  -H "Authorization: Bearer ik_test_SUA_CHAVE"

Testar e baixar

Clique em Authorize, cole sua chave de homologação e use Try it out em qualquer operação disponível abaixo. O contrato também está em openapi.json e openapi.yaml, para importar no Postman, no Insomnia ou num gerador de cliente.

Integrando com um agente de IA?

Entregue a ele o guia.md: a API inteira num arquivo só, com instruções para o agente, campos, exemplos, erros e a lista do que precisa funcionar antes da chave de produção.

Quer integrar sua loja ou seu hub? Fale com a equipe do Indica para receber a chave de homologação.