Integração

Idempotência e limites

Duas proteções que o seu sistema precisa respeitar: a chave de idempotência evita cobrança duplicada, e o limite por minuto protege a API de excesso.

Idempotency-Key#

Obrigatório nos três POST que gastam crédito:

Regras:

Situação	Resposta
Sem o cabeçalho	`400` IDEMPOTENCY_KEY_REQUIRED
Chave nova	o pedido é processado normalmente
Mesma chave e mesmo corpo	a mesma resposta do primeiro pedido, com `Idempotent-Replayed: true`; nada é criado nem cobrado de novo
Mesma chave e outro corpo	`409` IDEMPOTENCY_KEY_REUSED

Use um UUID novo por pedido (de 8 a 120 caracteres: letras, números, _, -, : e .).
Gere a chave antes de chamar e grave junto do pedido no seu sistema. Se a chamada cair por tempo esgotado ou erro de rede, repita com a mesma chave: você recebe o resultado do primeiro pedido, sem gerar duas vezes.
A chave fica guardada por 7 dias, por integrador e ambiente.
POST/contas aceita Idempotency-Key opcional, com as mesmas regras.

bash

IDEM=$(uuidgen)
curl -s -i -X POST $B/galerias -H "Authorization: Bearer $K" -H "Idempotency-Key: $IDEM" \
  -H 'content-type: application/json' -d '{"produtoId":"prd_…","quantidadeImagens":3}'
# a mesma chamada de novo devolve a mesma resposta com:
# Idempotent-Replayed: true

A etapa IDEMPOTENCIA fica verde com Idempotency-Key em todas as chamadas que gastam crédito nos últimos 7 dias e pelo menos uma repetição segura (Idempotent-Replayed: true).

Limites por minuto#

Cada chave e cada integrador têm um limite de pedidos por minuto, definido pelo plano. Toda resposta traz:

Cabeçalho	O que é
`X-RateLimit-Limit`	pedidos permitidos na janela atual
`X-RateLimit-Remaining`	pedidos que ainda cabem na janela
`X-RateLimit-Reset`	segundos unix em que a janela recomeça

Outros limites: corpo do pedido até 1 MB; até 20 fotos por ficha, de até 15 MB cada; 10 conferências por produto por dia.

429 e Retry-After#

Passou do limite: 429 TOO_MANY_REQUESTS com Retry-After (segundos). O pedido não foi processado.

Espere pelo menos os segundos de Retry-After antes da próxima chamada com a mesma chave.
Não repita em laço: espalhe as chamadas e use uma fila do seu lado.
Ao repetir um POST que gasta crédito, use a mesma Idempotency-Key.

Node.js

async function chamar(url, opcoes, tentativas = 3) {
  for (let i = 0; i < tentativas; i += 1) {
    const resposta = await fetch(url, opcoes);
    if (resposta.status !== 429 && resposta.status !== 503) return resposta;
    const espera = Number(resposta.headers.get('Retry-After') ?? '5');
    await new Promise((ok) => setTimeout(ok, espera * 1000));
  }
  throw new Error('Limite de tentativas');
}

503 SERVICE_UNAVAILABLE também traz Retry-After e nada é cobrado.

Testar o 429#

Com a chave sk_test_, o cabeçalho X-Sellume-Teste: forcar-429 força um 429 com Retry-After: 5:

bash

curl -s -i $B/saldo -H "Authorization: Bearer $K" -H 'X-Sellume-Teste: forcar-429'
# HTTP/2 429 … retry-after: 5
sleep 5
curl -s $B/saldo -H "Authorization: Bearer $K"

A etapa LIMITE_429 fica verde quando a chamada seguinte da mesma chave chega depois do tempo pedido. Se ela chegar antes, a etapa não fica verde: espere e tente de novo. Com sk_live_ o cabeçalho é ignorado.