Integração

Status da integração

O Sellume confere a sua integração nas chamadas reais do ambiente de teste. Você vê o que falta e corrige sem precisar do suporte.

As etapas ficam verdes sozinhas, a partir das suas chamadas reais com a chave sk_test_. Você não marca nada. O mesmo quadro aparece no portal do integrador e em GET/integracao/status.

curl -s $B/integracao/status -H "Authorization: Bearer $K"

{
  "data": {
    "ambiente": "teste",
    "etapasConcluidas": 6,
    "etapasObrigatorias": 8,
    "producao": { "situacao": "bloqueada", "liberacao": null, "motivo": "Faltam 2 etapas." },
    "etapas": [
      { "codigo": "CHAVE_E_PRIMEIRA_CHAMADA", "situacao": "ok", "verificadoEm": "2026-10-10T13:02:11Z", "evidencia": { "requestId": "req_…" } },
      { "codigo": "AVISOS_ASSINATURA", "situacao": "falhou",
        "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." },
      { "codigo": "LIMITE_429", "situacao": "pendente" }
    ]
  }
}

Cada etapa tem situacao (pendente, ok ou falhou), verificadoEm, a evidencia que a provou (requestId, eventId ou geracaoId), a ultimaFalha em português, o comoConcluir e o link para esta documentação.

As 8 etapas#

Pedido de produção#

POST/integracao/pedido-producao (o mesmo pedido existe no portal):

• Todas as etapas obrigatórias verdes: o acesso de produção é liberado na hora (liberacao: automatica) e o portal permite criar a chave sk_live_, sempre com contrato vigente.
• Faltando etapa: 409 INTEGRATION_STEPS_PENDING. Em error.fields vem uma linha por etapa que falta: campo: etapas, codigo = código da etapa e mensagem = como concluir.
• Repetir depois de liberado devolve o mesmo acesso.
• Acesso suspenso pelo Sellume: 403 FORBIDDEN.

{
  "error": {
    "type": "INTEGRATION_STEPS_PENDING",
    "message": "Etapas da integração pendentes",
    "description": "Faltam 2 etapas do teste para liberar a produção. Veja GET /integracao/status.",
    "fields": [
      { "campo": "etapas", "codigo": "AVISOS_ASSINATURA", "mensagem": "Cadastre o endereço (POST /avisos), confira X-Sellume-Signature…" },
      { "campo": "etapas", "codigo": "LIMITE_429", "mensagem": "Envie uma chamada com X-Sellume-Teste: forcar-429 (só sk_test_) e espere o Retry-After antes da próxima." }
    ],
    "documentation": "https://docs.sellume.com.br/erros#INTEGRATION_STEPS_PENDING"
  }
}

Registro de chamadas#

Toda chamada à API fica registrada, com o "como corrigir" de cada erro. Toda resposta traz o cabeçalho X-Request-Id (req_…): é por ele que você acha uma chamada.

• GET/integracao/chamadas lista as chamadas, com filtros por data (de, ate), status (código exato, como 422, ou faixa: 2xx, 4xx, 5xx), metodo, endpoint (o modelo do endereço, como /galerias), codigoErro, contaId, chave e ambiente. A lista não traz os corpos.
• GET/integracao/chamadas/{requestId} traz o detalhe: data, endpoint, status, duração, código do erro, mensagem, causa (o que aconteceu nesta chamada), como corrigir, link da documentação e os corpos enviado e recebido.
• Os corpos ficam mascarados: Authorization, chaves, tokens, segredos whsec_, Idempotency-Key (parcial), e-mail, telefone, CPF e CNPJ. Cortados em 64 KB.
• Retenção: 30 dias com os corpos; depois, só os metadados até 90 dias.

curl -s "$B/integracao/chamadas?status=4xx" -H "Authorization: Bearer $K"
curl -s $B/integracao/chamadas/req_01J9Z9A1B2C3D4E5F6G7H8J9K0 -H "Authorization: Bearer $K"

Alertas por e-mail#

Os contatos do integrador recebem e-mail quando:

• a taxa de erro passa de 20% de respostas 4xx/5xx em 15 minutos, com pelo menos 50 chamadas;
• um endereço de aviso falha seguido há 1 hora, e quando ele é desligado;
• a cota do mês chega a 70% e 90% e quando bate o teto; e quando um pacote avulso é comprado em 2 ciclos seguidos (sugestão de subir de plano).

No máximo 1 e-mail por tipo a cada 6 horas. O alerta fecha sozinho quando a situação normaliza. Os alertas abertos também vêm em alertasAbertos do status.