Pular para o conteúdo
sellumeDOCS · INTEGRADORES Portal do integrador

Começar

Começar

O caminho inteiro com a chave de teste — conta, ficha, conferência e geração — em chamadas curl que você pode copiar e rodar.

Tudo aqui usa uma chave sk_test_: nada é cobrado, as gerações devolvem mídia de exemplo e a conferência roda de verdade. Cada passo deixa verde uma etapa do Status da integração.

1. Receber o acesso ao portal#

O Sellume cadastra o seu integrador e convida a sua equipe por e-mail. Aceite o convite e entre no portal do integrador. Lá ficam as chaves de API, os endereços de aviso, o Status da integração, o registro de chamadas e o plano.

2. Criar a chave de teste#

No portal, abra Chaves de API e crie uma chave de teste. Ela começa com sk_test_ e aparece uma única vez: copie e guarde num cofre de segredos do seu servidor.

bash
B=https://api.sellume.com.br/v1
K=sk_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Primeira chamada#

bash
curl -s $B/saldo -H "Authorization: Bearer $K"
resposta (resumida)
{
  "data": {
    "modeloCobranca": "plano_mensal",
    "ambiente": "teste",
    "creditosDisponiveis": 0,
    "creditosReservados": 0,
    "atualizadoEm": "2026-10-11T13:02:11Z"
  }
}

Uma resposta 200 deixa verde a etapa CHAVE_E_PRIMEIRA_CHAMADA. Toda resposta traz X-Request-Id: com ele você acha a chamada no registro de chamadas.

4. Criar a subconta do seu cliente#

Uma subconta por cliente seu (cada vendedor do seu sistema). codigoExterno é o código dele no seu sistema e não se repete.

bash
curl -s -X POST $B/contas -H "Authorization: Bearer $K" \
  -H 'content-type: application/json' \
  -d '{"codigoExterno":"vendedor-98213","nome":"Loja Casa Bonita"}'
resposta 201
{
  "data": {
    "id": "cta_01J9Z6K8X2M4R7T1Q3W5E8Y0U2",
    "codigoExterno": "vendedor-98213",
    "nome": "Loja Casa Bonita",
    "origem": "subconta",
    "situacao": "ativa",
    "ambiente": "teste",
    "criadoEm": "2026-10-11T13:03:22Z",
    "atualizadoEm": "2026-10-11T13:03:22Z"
  }
}
bash
C=cta_01J9Z6K8X2M4R7T1Q3W5E8Y0U2

Repetir o mesmo codigoExterno devolve 409 com o id existente em error.fields. Etapa: SUBCONTA_CRIADA.

5. Enviar a ficha do produto#

A ficha é a única fonte de dados e fotos: o Sellume não lê o marketplace. Salve o exemplo abaixo como ficha.json e troque as fotos pelas suas.

ficha.json
{
  "nome": "Arandela LED de parede 12W luz quente",
  "descricao": "Arandela de parede em alumínio com difusor de vidro jateado e LED integrado de 12 W. A luz quente (3000 K) deixa corredores, varandas cobertas e halls mais aconchegantes, sem ofuscar. O corpo em alumínio pintado de preto fosco não enferruja e dissipa o calor do LED, o que aumenta a vida útil. Instalação simples com o kit de fixação que acompanha o produto. Bivolt automático: funciona em 127 V e 220 V sem ajuste.",
  "descricaoComplementar": "Acompanha kit de fixação (2 buchas e 2 parafusos) e manual de instalação.",
  "marca": "Lumina Casa",
  "modelo": "AR-12Q",
  "gtin": "7891234567895",
  "categoria": {
    "codigo": "ilum-arandelas",
    "nome": "Arandelas",
    "caminho": "Casa > Iluminação > Arandelas"
  },
  "atributos": [
    {
      "nome": "Cor",
      "valor": "Preto fosco"
    },
    {
      "nome": "Potência",
      "valor": "12 W"
    },
    {
      "nome": "Temperatura de cor",
      "valor": "3000 K (luz quente)"
    },
    {
      "nome": "Material",
      "valor": "Alumínio e vidro jateado"
    },
    {
      "nome": "Tensão",
      "valor": "Bivolt automático (127 V e 220 V)"
    },
    {
      "nome": "Fluxo luminoso",
      "valor": "960 lúmens"
    },
    {
      "nome": "Uso",
      "valor": "Interno e área externa coberta"
    }
  ],
  "imagens": [
    {
      "url": "https://seu-servidor.com.br/fotos/arandela-frente.jpg",
      "ordem": 1,
      "principal": true
    },
    {
      "url": "https://seu-servidor.com.br/fotos/arandela-lateral.jpg",
      "ordem": 2
    },
    {
      "url": "https://seu-servidor.com.br/fotos/arandela-costas.jpg",
      "ordem": 3
    },
    {
      "url": "https://seu-servidor.com.br/fotos/arandela-acesa.jpg",
      "ordem": 4
    }
  ],
  "dimensoes": {
    "largura": 12,
    "altura": 25,
    "profundidade": 8,
    "unidade": "cm",
    "pesoLiquido": 0.6,
    "pesoBruto": 0.8,
    "unidadePeso": "kg"
  },
  "composicaoOferta": [
    {
      "item": "Arandela LED",
      "quantidade": 1
    },
    {
      "item": "Kit de fixação",
      "quantidade": 1
    }
  ],
  "garantia": "12 meses contra defeitos de fabricação",
  "avaliacoes": [
    {
      "nota": 5,
      "texto": "Iluminou bem o corredor e a instalação foi simples.",
      "data": "2026-08-14"
    },
    {
      "nota": 5,
      "texto": "Acabamento preto fosco muito bonito, a luz é bem quente.",
      "data": "2026-09-02"
    },
    {
      "nota": 4,
      "texto": "Boa luminária, uso na varanda coberta há um mês sem problema.",
      "data": "2026-09-20"
    }
  ],
  "perguntas": [
    {
      "pergunta": "Serve para área externa coberta?",
      "resposta": "Sim, para área externa coberta."
    },
    {
      "pergunta": "Precisa de transformador?",
      "resposta": "Não, é bivolt automático."
    },
    {
      "pergunta": "A lâmpada pode ser trocada?",
      "resposta": "O LED é integrado e não precisa de troca."
    }
  ],
  "provaSocial": {
    "totalAvaliacoes": 214,
    "notaMedia": 4.8,
    "vendidos": 1350
  },
  "anuncio": {
    "marketplace": "mercado_livre",
    "id": "MLB4123456789"
  }
}

O código do produto no seu sistema (SKU) vai no caminho:

bash
curl -s -X PUT $B/contas/$C/produtos/SKU-ARANDELA-12W \
  -H "Authorization: Bearer $K" -H 'content-type: application/json' \
  -d @ficha.json
resposta 201 (resumida)
{
  "data": {
    "id": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
    "contaId": "cta_01J9Z6K8X2M4R7T1Q3W5E8Y0U2",
    "codigo": "SKU-ARANDELA-12W",
    "nome": "Arandela LED de parede 12W luz quente",
    "situacao": "conferindo",
    "versao": 1,
    "fotos": { "recebidas": 4, "aprovadas": 0 },
    "criadoEm": "2026-10-11T13:04:00Z",
    "atualizadoEm": "2026-10-11T13:04:00Z"
  }
}
bash
P=prd_01J9Z7A1B2C3D4E5F6G7H8J9K0

Cada envio com conteúdo diferente cria uma versão nova e inicia a conferência sozinho. Envio idêntico ao anterior não cria versão.

6. Ler a conferência#

bash
curl -s -X POST $B/produtos/$P/conferencia -H "Authorization: Bearer $K"

200 traz o resultado pronto; 202 quer dizer que ainda está conferindo (chame de novo em alguns segundos ou espere o aviso produto.conferido).

resposta 200 (resumida)
{
  "data": {
    "id": "cnf_01J9Z7Q2W3E4R5T6Y7U8I9O0P1",
    "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
    "versaoProduto": 1,
    "situacao": "concluida",
    "resultados": [
      { "tipo": "galeria", "aprovado": true, "quantidadeMaximaImagens": 6, "quantidadesAprovadas": [3, 6],
        "pendencias": [{ "codigo": "GALERIA_QUANTIDADE_ACIMA_DO_SUPORTADO", "severidade": "fraco", "campo": "atributos" }] },
      { "tipo": "video_apresentacao", "aprovado": true, "notaVideo": 7, "pendencias": [] },
      { "tipo": "video_cinepremium", "aprovado": false, "notaVideo": 7,
        "pendencias": [{ "codigo": "CINEPREMIUM_FOTOS_INSUFICIENTES", "severidade": "bloqueio", "campo": "imagens" }] }
    ]
  }
}

Leia um resultado por tipo:

  • aprovado: true — esse tipo pode ser pedido. Na galeria, só as quantidades de quantidadesAprovadas.
  • bloqueio reprova o tipo; fraco aprova, mas a qualidade cai.
  • Cada codigo tem causa e como corrigir no catálogo de erros. Cada foto volta com o resultado da triagem em fotos.itens.

Um tipo aprovado deixa verde a etapa PRODUTO_APROVADO.

7. Pedir a galeria#

Todo POST que gasta crédito exige Idempotency-Key: um valor novo por pedido. Guarde a chave para poder repetir o mesmo pedido com segurança.

bash
IDEM=$(uuidgen)   # sem uuidgen: IDEM=$(node -e "console.log(crypto.randomUUID())")
curl -s -i -X POST $B/galerias -H "Authorization: Bearer $K" \
  -H "Idempotency-Key: $IDEM" -H 'content-type: application/json' \
  -d '{"produtoId":"'$P'","quantidadeImagens":3}'
resposta 202
{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "na_fila",
    "creditosReservados": 0,
    "ambiente": "teste"
  }
}

Rode o mesmo comando de novo (mesma $IDEM, mesmo corpo): a resposta é a mesma, com o cabeçalho Idempotent-Replayed: true, e nada é criado de novo. Isso deixa verde a etapa IDEMPOTENCIA. Mais em Idempotência e limites.

bash
G=ger_01J9Z8C4D5E6F7G8H9J0K1L2M3

8. Acompanhar até concluir#

bash
curl -s $B/geracoes/$G -H "Authorization: Bearer $K"

Consulte a cada 5 a 10 segundos até situacao ser concluida (ou parcial / falhou), ou espere o aviso geracao.concluida.

resposta 200 (resumida)
{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "concluida",
    "ambiente": "teste",
    "progresso": { "etapa": "entregue", "percentual": 100 },
    "resultados": {
      "imagens": [
        { "id": "img_01J9Z8F1A2B3C4D5E6F7G8H9J0", "posicao": 1, "url": "https://…", "expiraEm": "2026-10-18T13:08:31Z", "largura": 1200, "altura": 1200 }
      ]
    }
  }
}

Os links são assinados e temporários (expiraEm): baixe e guarde do seu lado, ou consulte de novo para receber links novos. Etapa: GALERIA_TESTE.

9. Pedir um vídeo#

bash
curl -s -X POST $B/videos -H "Authorization: Bearer $K" \
  -H "Idempotency-Key: $(uuidgen)" -H 'content-type: application/json' \
  -d '{"produtoId":"'$P'","tipo":"apresentacao","avatar":"automatico"}'

A fala é automática: o sistema escolhe a melhor opção que passou nas travas de qualidade. No teste volta um vídeo de exemplo em cerca de 15 segundos. Consulte GET/geracoes/{geracaoId} como no passo 8: o resultado traz resultados.video (MP4) e fala. Etapa: VIDEO_TESTE. Detalhes em Vídeos.

10. Avisos e pedido de produção#

Cadastre o endereço do seu servidor que recebe avisos. PUT /avisos cadastra ou atualiza pelo url, sem duplicar:

bash
curl -s -X PUT $B/avisos -H "Authorization: Bearer $K" -H 'content-type: application/json' \
  -d '{"url":"https://erp.exemplo.com.br/webhooks/sellume","eventos":["produto.conferido","geracao.concluida","geracao.falhou","creditos.baixos","cota.alerta"]}'

A resposta 201 traz o segredo (whsec_…) uma única vez. Com ele o seu endpoint confere a assinatura de cada aviso (exemplos em Node, PHP e Python). Depois dispare o teste de assinatura:

bash
curl -s -X POST $B/avisos/teste -H "Authorization: Bearer $K"     # 202 com a lista de testes: guarde o id tst_…
curl -s $B/testes-de-avisos/tst_… -H "Authorization: Bearer $K"

São três entregas: a válida precisa receber 2XX; a de assinatura errada e a de carimbo antigo precisam receber 400, 401 ou 403. As três certas deixam verde a etapa AVISOS_ASSINATURA.

Teste do limite e pedido de produção#

Force um 429 (só com sk_test_), espere o Retry-After e faça outra chamada:

bash
curl -s -i $B/saldo -H "Authorization: Bearer $K" -H 'X-Sellume-Teste: forcar-429'
sleep 5
curl -s $B/saldo -H "Authorization: Bearer $K"

Acompanhe as 8 etapas e peça a produção:

bash
curl -s $B/integracao/status -H "Authorization: Bearer $K"
curl -s -X POST $B/integracao/pedido-producao -H "Authorization: Bearer $K"

Com as 8 etapas verdes, o acesso de produção é liberado na hora e o portal permite criar a chave sk_live_ (sempre com contrato vigente). Faltando etapa, a resposta é 409 INTEGRATION_STEPS_PENDING, com uma linha por etapa que falta. Veja Status da integração.