Referência da API

Listar contas do integrador#

• Escopocontas:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Página de contas.

  Cabeçalhos: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Criar a subconta de um cliente final#

• Escopocontas:escrever
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Corpo do pedido

application/json · obrigatório

{
  "codigoExterno": "vendedor-98213",
  "nome": "Loja Casa Bonita",
  "metadados": {
    "planoNoErp": "ouro"
  }
}

Respostas

• 201
  Subconta criada.

  Cabeçalhos: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id.

• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 403
  Escopo insuficiente, integrador ou conta pausada, ou origem não autorizada.

  Erro: FORBIDDEN.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

• 500
  Erro inesperado (sem detalhe interno).

  Erro: INTERNAL_ERROR.

{
  "data": {
    "id": "cta_01J9Z6K8X2M4R7T1Q3W5E8Y0U2",
    "codigoExterno": "vendedor-98213",
    "nome": "Loja Casa Bonita",
    "origem": "subconta",
    "situacao": "ativa",
    "ambiente": "producao",
    "metadados": {
      "planoNoErp": "ouro"
    },
    "criadoEm": "2026-10-10T14:03:22Z",
    "atualizadoEm": "2026-10-10T14:03:22Z"
  }
}

Detalhar uma conta#

• Escopocontas:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Conta encontrada.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Atualizar nome, metadados ou situação da subconta#

• Escopocontas:escrever
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Corpo do pedido

application/json · obrigatório

{
  "situacao": "pausada"
}

Respostas

• 200
  Conta atualizada.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Encerrar a subconta#

• Escopocontas:escrever
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 202
  Encerramento aceito.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

Listar produtos da conta#

• Escopoprodutos:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Página de produtos.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Detalhar o produto#

• Escopoprodutos:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Produto encontrado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Enviar ou atualizar a ficha do produto (única fonte)#

• Escopoprodutos:escrever
• Chave de APIsim
• Token OAuthsim

Parâmetros

Corpo do pedido

application/json · obrigatório

Ficha do produto — única fonte de dados e fotos (o Sellume não lê marketplace). Fotos e dados valem como oficiais, sob responsabilidade do integrador. Campos compatíveis com Bling (codigo, nome, descricaoCurta→descricao, descricaoComplementar, marca, gtin, midia.imagens.externas→imagens, midia.video→video, dimensões, variacoes), Tiny/Olist (codigo, nome, descricao_complementar, marca, gtin, anexos/imagens_externas), Magis5 (sku, title, description, brand, ean, images) e Shopping de Preços (nome, descrição, marca, EAN, categoria, imagem). O codigo vem do caminho.

{
  "nome": "Arandela LED de parede 12W luz quente",
  "descricao": "Arandela de alumínio com difusor de vidro jateado, ideal para corredores e varandas.",
  "descricaoComplementar": "Acompanha kit de fixação. Bivolt.",
  "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": "Material",
      "valor": "Alumínio"
    }
  ],
  "imagens": [
    {
      "url": "https://cdn.erp.exemplo.com.br/p/arandela-1.jpg",
      "ordem": 1,
      "principal": true
    },
    {
      "url": "https://cdn.erp.exemplo.com.br/p/arandela-2.jpg",
      "ordem": 2,
      "principal": false
    }
  ],
  "dimensoes": {
    "largura": 12,
    "altura": 25,
    "profundidade": 8,
    "unidade": "cm",
    "pesoLiquido": 0.6,
    "pesoBruto": 0.8,
    "unidadePeso": "kg"
  },
  "composicaoOferta": [
    {
      "item": "Arandela",
      "quantidade": 1
    }
  ],
  "garantia": "12 meses contra defeitos de fabricação",
  "avaliacoes": [
    {
      "nota": 5,
      "texto": "Iluminou bem o corredor e a instalação foi simples."
    }
  ],
  "perguntas": [
    {
      "pergunta": "Serve para área externa coberta?",
      "resposta": "Sim, para área coberta."
    }
  ],
  "anuncio": {
    "marketplace": "mercado_livre",
    "id": "MLB4123456789"
  }
}

Respostas

• 200
  Ficha atualizada (nova versão; conferência iniciada).
• 201
  Produto criado.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 413
  Corpo ou foto acima do tamanho permitido.

  Erro: PAYLOAD_TOO_LARGE.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Remover o produto#

• Escopoprodutos:escrever
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 204
  Produto removido.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Último resultado da conferência da versão atual#

• Escopoprodutos:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Última conferência da versão atual (concluída ou em andamento).
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Conferir os requisitos mínimos (obrigatório antes de gerar, grátis)#

• Escopoprodutos:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Conferência concluída para a versão atual.
• 202
  Conferência em andamento para a versão atual.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

{
  "data": {
    "id": "cnf_01J9Z7Q2W3E4R5T6Y7U8I9O0P1",
    "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
    "versaoProduto": 3,
    "politica": "integradores.requisitos.v1",
    "situacao": "concluida",
    "conferidoEm": "2026-10-10T14:06:10Z",
    "resultados": [
      {
        "tipo": "galeria",
        "aprovado": true,
        "creditos": 60,
        "quantidadeMaximaImagens": 6,
        "quantidadesAprovadas": [
          3,
          6
        ],
        "pendencias": [
          {
            "codigo": "GALERIA_QUANTIDADE_ACIMA_DO_SUPORTADO",
            "severidade": "fraco",
            "campo": "atributos",
            "mensagem": "Com as informações atuais a galeria sustenta até 6 imagens. Para 10, envie mais características do produto."
          }
        ]
      },
      {
        "tipo": "video_apresentacao",
        "aprovado": true,
        "creditos": 120,
        "notaVideo": 7,
        "pendencias": [
          {
            "codigo": "SEM_AVALIACOES_OU_PERGUNTAS",
            "severidade": "fraco",
            "campo": "avaliacoes",
            "mensagem": "Sem avaliações nem perguntas, a fala não responde dúvidas de quem compra."
          }
        ]
      },
      {
        "tipo": "video_cinepremium",
        "aprovado": false,
        "creditos": 400,
        "notaVideo": 7,
        "pendencias": [
          {
            "codigo": "CINEPREMIUM_FOTOS_INSUFICIENTES",
            "severidade": "bloqueio",
            "campo": "imagens",
            "mensagem": "O CinePremium precisa de pelo menos 3 fotos aprovadas do produto, de lados diferentes. Há 2."
          }
        ]
      }
    ],
    "fotos": {
      "recebidas": 4,
      "aprovadas": 2,
      "principal": "foto-1",
      "itens": [
        {
          "id": "foto-1",
          "url": "https://cdn.erp.exemplo.com.br/p/arandela-1.jpg",
          "situacao": "aprovada",
          "largura": 1200,
          "altura": 1200,
          "tipo": "produto_limpo",
          "fundo": "liso",
          "pessoas": "nenhuma"
        },
        {
          "id": "foto-2",
          "url": "https://cdn.erp.exemplo.com.br/p/arandela-2.jpg",
          "situacao": "aprovada",
          "largura": 1000,
          "altura": 1000,
          "tipo": "produto_limpo",
          "fundo": "liso",
          "pessoas": "nenhuma"
        },
        {
          "id": "foto-3",
          "url": "https://cdn.erp.exemplo.com.br/p/arandela-3.jpg",
          "situacao": "descartada",
          "tipo": "produto_em_uso",
          "fundo": "ambiente",
          "pessoas": "adultos",
          "codigos": [
            "FOTO_COM_PESSOA"
          ]
        },
        {
          "id": "foto-4",
          "url": "https://cdn.erp.exemplo.com.br/p/arandela-4.jpg",
          "situacao": "reprovada",
          "largura": 480,
          "altura": 480,
          "codigos": [
            "FOTO_RESOLUCAO_BAIXA"
          ]
        }
      ]
    }
  }
}

{
  "data": {
    "id": "cnf_01J9Z7Q2W3E4R5T6Y7U8I9O0P1",
    "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
    "versaoProduto": 3,
    "politica": "integradores.requisitos.v1",
    "situacao": "em_andamento",
    "resultados": []
  }
}

Criar galeria de imagens (3, 6 ou 10)#

• Escopogeracoes:criar
• Chave de APIsim
• Token OAuthsim

Parâmetros

Corpo do pedido

application/json · obrigatório

{
  "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
  "quantidadeImagens": 6,
  "objetivo": "conversao",
  "referenciaExterna": "pedido-erp-55120"
}

Respostas

• 202
  Pedido recebido; a geração é assíncrona.

  Cabeçalhos: Location, Idempotent-Replayed, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id.

• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 402
  Saldo insuficiente — a cota do mês (teto do plano) acabou e não há crédito avulso guardado, ou o saldo pré-pago não cobre. Nada foi cobrado.

  Erro: INSUFFICIENT_CREDITS.

• 403
  Escopo insuficiente, integrador ou conta pausada, ou origem não autorizada.

  Erro: FORBIDDEN.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 422
  Produto sem conferência aprovada da versão atual para este tipo de geração. Recusado antes de qualquer custo. PRODUCT_NOT_VERIFIED = a versão atual ainda não foi conferida (ou a conferência está em andamento); PRODUCT_REQUIREMENTS_NOT_MET = conferida e reprovada para este tipo (ou a quantidade de imagens pedida passa do máximo sustentado). fields traz as pendências de bloqueio.

  Erro: PRODUCT_REQUIREMENTS_NOT_MET, PRODUCT_NOT_VERIFIED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

• 503
  Capacidade temporariamente indisponível (manutenção ou fila cheia).

  Cabeçalhos: Retry-After. Erro: SERVICE_UNAVAILABLE.

{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "na_fila",
    "creditosReservados": 60,
    "ambiente": "producao"
  }
}

Criar vídeo Apresentação ou CinePremium (fala automática)#

• Escopogeracoes:criar
• Chave de APIsim
• Token OAuthsim

Parâmetros

Corpo do pedido

application/json · obrigatório

{
  "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
  "tipo": "apresentacao",
  "avatar": "automatico",
  "referenciaExterna": "pedido-erp-55121"
}

Respostas

• 202
  Pedido recebido; a geração é assíncrona.

  Cabeçalhos: Location, Idempotent-Replayed, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id.

• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 402
  Saldo insuficiente — a cota do mês (teto do plano) acabou e não há crédito avulso guardado, ou o saldo pré-pago não cobre. Nada foi cobrado.

  Erro: INSUFFICIENT_CREDITS.

• 403
  Escopo insuficiente, integrador ou conta pausada, ou origem não autorizada.

  Erro: FORBIDDEN.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 422
  Produto sem conferência aprovada da versão atual para este tipo de geração. Recusado antes de qualquer custo. PRODUCT_NOT_VERIFIED = a versão atual ainda não foi conferida (ou a conferência está em andamento); PRODUCT_REQUIREMENTS_NOT_MET = conferida e reprovada para este tipo (ou a quantidade de imagens pedida passa do máximo sustentado). fields traz as pendências de bloqueio.

  Erro: PRODUCT_REQUIREMENTS_NOT_MET, PRODUCT_NOT_VERIFIED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

• 503
  Capacidade temporariamente indisponível (manutenção ou fila cheia).

  Cabeçalhos: Retry-After. Erro: SERVICE_UNAVAILABLE.

{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "na_fila",
    "creditosReservados": 60,
    "ambiente": "producao"
  }
}

Avatares oficiais para a Apresentação#

• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Avatares ativos.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

{
  "data": [
    {
      "codigo": "h01",
      "nome": "Bruno",
      "genero": "masculino",
      "idadeAparente": 22,
      "foto": "https://app.sellume.com.br/assets/avatares/h01/poster.jpg",
      "previaAnimada": "https://app.sellume.com.br/assets/avatares/h01/clipe-01.mp4",
      "tiposDeVideo": [
        "apresentacao"
      ]
    }
  ],
  "total": 1,
  "automatico": "Envie avatar: \"automatico\" (ou omita) para o Sellume escolher pelo produto."
}

Editar uma imagem, mudando só o que foi pedido#

• Escopogeracoes:criar
• Chave de APIsim
• Token OAuthsim

Parâmetros

Corpo do pedido

application/json · obrigatório

Só o que foi pedido muda; o restante da imagem é preservado.

{
  "tipo": "troca_de_cor",
  "cor": {
    "nome": "Branco",
    "hex": "#FFFFFF"
  },
  "parte": "corpo da arandela"
}

{
  "tipo": "ajuste",
  "instrucao": "Trocar o fundo da parede por um tom de cinza claro."
}

Respostas

• 202
  Pedido recebido; a geração é assíncrona.

  Cabeçalhos: Location, Idempotent-Replayed, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id.

• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 402
  Saldo insuficiente — a cota do mês (teto do plano) acabou e não há crédito avulso guardado, ou o saldo pré-pago não cobre. Nada foi cobrado.

  Erro: INSUFFICIENT_CREDITS.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 422
  Produto sem conferência aprovada da versão atual para este tipo de geração. Recusado antes de qualquer custo. PRODUCT_NOT_VERIFIED = a versão atual ainda não foi conferida (ou a conferência está em andamento); PRODUCT_REQUIREMENTS_NOT_MET = conferida e reprovada para este tipo (ou a quantidade de imagens pedida passa do máximo sustentado). fields traz as pendências de bloqueio.

  Erro: PRODUCT_REQUIREMENTS_NOT_MET, PRODUCT_NOT_VERIFIED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "na_fila",
    "creditosReservados": 60,
    "ambiente": "producao"
  }
}

Listar gerações#

• Escopogeracoes:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Página de gerações (sem links de download; use o detalhe).
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Andamento e resultado, com links para baixar#

• Escopogeracoes:ler
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Geração encontrada.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

{
  "data": {
    "id": "ger_01J9Z8C4D5E6F7G8H9J0K1L2M3",
    "tipo": "galeria",
    "situacao": "concluida",
    "ambiente": "producao",
    "contaId": "cta_01J9Z6K8X2M4R7T1Q3W5E8Y0U2",
    "produtoId": "prd_01J9Z7A1B2C3D4E5F6G7H8J9K0",
    "versaoProduto": 3,
    "referenciaExterna": "pedido-erp-55120",
    "progresso": {
      "etapa": "entregue",
      "percentual": 100
    },
    "creditos": {
      "reservados": 60,
      "cobrados": 60,
      "devolvidos": 0
    },
    "valorCentavos": "definido no contrato",
    "criadoEm": "2026-10-10T14:07:00Z",
    "iniciadoEm": "2026-10-10T14:07:03Z",
    "concluidoEm": "2026-10-10T14:08:31Z",
    "resultados": {
      "imagens": [
        {
          "id": "img_01J9Z8F1A2B3C4D5E6F7G8H9J0",
          "posicao": 1,
          "url": "https://armazenamento.exemplo/assinado/img-1.png?token=...",
          "expiraEm": "2026-10-17T14:08:31Z",
          "largura": 1200,
          "altura": 1200,
          "formato": "image/png"
        }
      ]
    }
  }
}

Cancela uma geração que ainda está na fila#

• Escopogeracoes:criar
• Chave de APIsim
• Token OAuthsim

Parâmetros

Respostas

• 200
  Cancelada; situacao = cancelada e os créditos reservados devolvidos.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Saldo da carteira do integrador#

• Escopocreditos:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Saldo atual.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

{
  "data": {
    "modeloCobranca": "plano_mensal",
    "ambiente": "producao",
    "creditosDisponiveis": 3200,
    "creditosReservados": 60,
    "creditosDeRecarga": 1000,
    "valorCreditoCentavos": "definido no contrato",
    "creditosDeTeste": {
      "disponiveis": 0,
      "reservados": 0,
      "usados": 0,
      "concedidos": 0,
      "venceEm": null
    },
    "plano": {
      "codigo": "base",
      "nome": "Sellume API Base"
    },
    "ciclo": {
      "competencia": "2026-10",
      "creditosDoCiclo": 3000,
      "creditosUsados": 800,
      "creditosRestantes": 2200,
      "tetoAtingido": false,
      "terminaEm": "2026-11-11T13:00:00Z"
    },
    "atualizadoEm": "2026-10-10T14:10:00Z"
  }
}

Extrato detalhado (por conta, produto e geração)#

• Escopocreditos:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Página do extrato.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Cota do mês (créditos do ciclo do plano, que também são o teto)#

• Escopocreditos:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Situação do ciclo.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

{
  "data": {
    "competencia": "2026-10",
    "situacao": "aberta",
    "plano": {
      "codigo": "base",
      "nome": "Sellume API Base"
    },
    "creditosDoCiclo": 3000,
    "creditosUsados": 2700,
    "creditosRestantes": 300,
    "percentualUsado": 90,
    "tetoAtingido": false,
    "passouDoTeto": false,
    "comprouAvulso": false,
    "valorPagoCentavos": "definido no contrato",
    "inicio": "2026-10-11T13:00:00Z",
    "fechaEm": "2026-11-11T13:00:00Z"
  }
}

Plano atual, cota do mês, troca pendente, sugestão de subida e pacotes avulsos#

• Escopocreditos:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Plano e cota.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Planos disponíveis para este integrador (com o movimento possível a partir do atual)#

• Escopocreditos:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Catálogo do ambiente do integrador (o Enterprise sob medida dele, quando existe, no lugar do Enterprise do catálogo).
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

Compra um pacote avulso (devolve o link da página segura de pagamentos)#

• Escopocreditos:comprar
• Chave de APIsim
• Token OAuthnão (responde 403)

Corpo do pedido

application/json · obrigatório

{
  "pacote": "avulso_1000"
}

Respostas

• 201
  Link para pagar.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 403
  Escopo insuficiente, integrador ou conta pausada, ou origem não autorizada.

  Erro: FORBIDDEN.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

• 503
  Capacidade temporariamente indisponível (manutenção ou fila cheia).

  Cabeçalhos: Retry-After. Erro: SERVICE_UNAVAILABLE.

{
  "data": {
    "pacote": "avulso_1000",
    "creditos": 1000,
    "valorCentavos": "definido no contrato",
    "valorCreditoCentavos": "definido no contrato",
    "validade": "sem_vencimento",
    "pagarEm": "https://pagamento.exemplo/c/pay/cs_exemplo",
    "linkExpiraEm": "2026-10-12T16:00:00Z"
  }
}

Listar endereços de aviso cadastrados#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Endereços cadastrados (máximo 5 por integrador e ambiente).
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

Cadastrar um endereço que recebe avisos#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Corpo do pedido

application/json · obrigatório

{
  "url": "https://erp.exemplo.com.br/webhooks/sellume",
  "eventos": [
    "geracao.concluida",
    "geracao.falhou",
    "creditos.baixos"
  ],
  "descricao": "Produção"
}

Respostas

• 201
  Endereço cadastrado.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

Cadastrar ou atualizar um endereço pelo url (idempotente)#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Corpo do pedido

application/json · obrigatório

Respostas

• 200
  Endereço já existia e foi atualizado.
• 201
  Endereço cadastrado (com o segredo, mostrado uma única vez).
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

Resultado de um teste de avisos (as três entregas)#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Teste encontrado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Disparar o teste de avisos (evento aviso.teste) e conferir a assinatura#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Corpo do pedido

application/json · opcional

Respostas

• 202
  Teste enfileirado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 429
  Limite de pedidos por minuto atingido.

  Cabeçalhos: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Erro: TOO_MANY_REQUESTS.

Detalhar um endereço de aviso#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Endereço encontrado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Alterar eventos, descrição ou reativar um endereço desligado#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Corpo do pedido

application/json · obrigatório

Respostas

• 200
  Endereço atualizado.
• 400
  Dados inválidos.

  Erro: VALIDATION_ERROR.

• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Remover um endereço de aviso#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 204
  Removido. Entregas pendentes para ele são canceladas.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Trocar o segredo de assinatura#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Novo segredo (mostrado uma única vez).
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Listar entregas (inclui as que falharam)#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Página de entregas.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

Reenviar uma entrega agora#

• Escopoavisos:gerenciar
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 202
  Reenvio enfileirado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 404
  Recurso não existe ou não pertence a este integrador.

  Erro: RESOURCE_NOT_FOUND.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.

Status da integração (etapas verificadas automaticamente)#

• Escopocontas:ler
• Chave de APIsim
• Token OAuthnão (responde 403)

Parâmetros

Respostas

• 200
  Etapas e situação do acesso de produção.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

{
  "data": {
    "ambiente": "teste",
    "etapasConcluidas": 6,
    "etapasObrigatorias": 8,
    "producao": {
      "situacao": "bloqueada",
      "liberacao": null,
      "motivo": "Faltam 2 etapas."
    },
    "etapas": [
      {
        "codigo": "CHAVE_E_PRIMEIRA_CHAMADA",
        "nome": "Chave de teste criada e primeira chamada autenticada",
        "situacao": "ok",
        "verificadoEm": "2026-10-10T13:02:11Z",
        "evidencia": {
          "requestId": "req_01J9Z5…"
        }
      },
      {
        "codigo": "AVISOS_ASSINATURA",
        "nome": "Avisos cadastrados e assinatura conferida",
        "situacao": "falhou",
        "verificadoEm": "2026-10-10T15:20:00Z",
        "ultimaFalha": "A entrega com assinatura errada recebeu 200; o seu endpoint precisa recusar com 400, 401 ou 403.",
        "comoConcluir": "Confira X-Sellume-Signature com o segredo whsec_ e recuse quando não bater.",
        "linkDocumentacao": "https://docs.sellume.com.br/avisos#assinatura"
      },
      {
        "codigo": "LIMITE_429",
        "nome": "Limite de uso tratado (respeitou Retry-After)",
        "situacao": "pendente",
        "comoConcluir": "Envie uma chamada com X-Sellume-Teste: forcar-429 e espere o Retry-After antes da próxima.",
        "linkDocumentacao": "https://docs.sellume.com.br/integracao#limite_429"
      }
    ]
  }
}

Pedir acesso de produção#

• Chave de APIsim
• Token OAuthnão (responde 403)

Respostas

• 200
  Acesso de produção liberado.
• 401
  Chave ou token ausente, inválido, revogado ou expirado.

  Erro: UNAUTHORIZED.

• 403
  Escopo insuficiente, integrador ou conta pausada, ou origem não autorizada.

  Erro: FORBIDDEN.

• 409
  Conflito de estado, duplicidade ou Idempotency-Key reutilizada com outro corpo.

  Erro: IDEMPOTENCY_KEY_REUSED.