Boas práticas e troubleshooting

Monitoramento de status

Do's

• Consultar GET /merchants/{merchantId}/status a cada 30 segundos como heartbeat
• Armazenar o último status conhecido e alertar em caso de mudança
• Registrar logs quando status muda para ERROR
• Analisar todas as validações retornadas na resposta
• Usar o campo reopenable para determinar se a loja pode ser reabierta
• Implementar retry com backoff exponencial para erros 5xx

Don'ts

• Fazer polling com intervalo menor que 30 segundos (pode resultar em rate limit)
• Assumir que CLOSED significa problema (pode ser fora do horário esperado)
• Ignorar mensagens do campo message nas validações
• Tentar reabrir loja bloqueada por penalidade (reopenable: false)
• Confiar apenas no campo available sem analisar as validações

Gestão de interrupções

Do's

• Usar Interrupções para pausas que duram minutos/horas
• Sempre fornecer descrição clara do motivo
• Remover interrupções assim que o problema for resolvido
• Testar interrupções em desenvolvimento antes de usar em produção

Don'ts

• Usar Interrupções para fechamentos permanentes (altere opening-hours)
• Criar interrupções muito longas (máx 7 dias)
• Deixar interrupções ativas desnecessariamente
• Criar muitas interrupções sobrepostas

Gestão de horários

Do's

• Atualizar horários de funcionamento via API quando forem permanentes
• Incluir todos os dias da semana ao enviar com PUT /merchants/{merchantId}/opening-hours
• Testar validações de sobreposição antes de enviar
• Usar horários no formato HH:MM:SS (ex: 09:00:00)
• Calcular duração em minutos (ex: 360 minutos = 6 horas)

Don'ts

• Alterar horários para pausas curtas (use POST /merchants/{merchantId}/interruptions)
• Enviar apenas alguns dias (isso fecha os outros)
• Criar turnos sobrepostos no mesmo dia
• Misturar fusos horários (use o timezone configurado da loja)
• Usar PUT para adicionar horários (substitui completamente)

Tratamento de erros

Do's

• Capturar erros 400 BadRequest e informar o usuário sobre validação
• Capturar erros 409 InterruptionOverlap e sugerir ajustes de horário
• Capturar erros 401 Unauthorized e 403 Forbidden para revisar credenciais/permissões
• Implementar retry com backoff exponencial para 500 InternalServerError
• Validar que todos os campos obrigatórios estão presentes antes de chamar a API

Don'ts

• Ignorar erros de validação e tentar novamente com mesma requisição
• Assumir que token válido tem acesso a todas as lojas
• Fazer retry imediato em caso de sobreposição (espere e ajuste)
• Expor IDs de loja ou token em mensagens de erro para o usuário final
• Confiar apenas no código HTTP sem analisar o corpo da resposta

Limite de velocidade (Rate Limiting)

Do's

• Monitorar encabezados de limite de velocidade nas respostas da API
• Implementar backoff exponencial ao receber 429 Too Many Requests
• Distribuir requisições entre múltiplas lojas ao longo do tempo
• Armazenar em cache o status da loja quando possível
• Usar intervalo de polling de pelo menos 30 segundos

Don'ts

• Ignorar erros 429 Too Many Requests
• Fazer requisições consecutivas rápidas
• Fazer retry imediato em erros de limite de velocidade
• Fazer polling mais rápido que 30 segundos por loja

• Máximo: 1000 requisições por segundo em todos os endpoints
• Código de erro: 429

1. Extraia o encabezado Retry-After (se fornecido)
2. Aguarde a duração especificada antes de tentar novamente
3. Implemente backoff exponencial: 1s — 2s — 4s — 8s — 16s
4. Para problemas persistentes, reduza frequência de polling ou agrupe requisições

Troubleshooting

Status ERROR persistente

• Penalidade automática (ex: cancelamentos excessivos)
• Violação de Termos de Serviço (terms-service-violation)
• Pendências financeiras (payout-blocked)
• Problemas logísticos (logistics-blocked)
• Interrupção ativa (unavailabilities)

1. Chamar GET /merchants/{merchantId}/status
2. Analisar o array validations[] para encontrar qual código está em ERROR
3. Verificar o campo message para detalhes
4. Ações por tipo:
   • unavailabilities — Remova a interrupção com DELETE /interruptions/{id}
   • payout-blocked — Acesse Portal do Parceiro > Financeiro
   • terms-service-violation — Contacte suporte via Portal
   • logistics-blocked — Problema externo, aguarde resolução
5. Aguarde até 60 segundos para a plataforma processar a mudança
6. Se não resolver: abra um chamado

Interrupção não é removida

• Ainda há outra interrupção ativa não removida
• Sem permissão (403 Forbidden) — mas teria retornado erro
• Propagação assíncrona (sistema ainda está processando)

1. Aguarde 5 segundos (processamento assíncrono)
2. Chame GET /merchants/{merchantId}/interruptions para listar todas ativas
3. Remova todas as interrupções encontradas
4. Chame GET /merchants/{merchantId}/status para confirmar
5. Se persistir após alguns minutos: abra um chamado

Horários recusam atualização

• Turnos no mesmo dia se sobrepõem
• Horários em formato inválido
• Duração negativa ou zero

Cálculo: start + (duration / 60) = fim

Exemplo válido (FRIDAY):
- Turno 1: 05:00 + (420 min) = 12:00 (válido)
- Turno 2: 13:00 + (300 min) = 18:00 (válido)
- Turno 3: 19:00 + (210 min) = 22:30 (válido)

Exemplo INVÁLIDO:
- Turno 1: 09:00 + (300 min) = 14:00
- Turno 2: 13:00 + (300 min) = 18:00 (inválido — Sobrepõe!)

1. Verifique a resposta de erro para campos específicos
2. Use formatos corretos — dayOfWeek (MONDAY-SUNDAY), start (HH:MM:SS), duration (minutos)
3. Ressubmeta com turnos não-sobrepostos

Loja não recebe pedidos (status OK mas sem vendas)

• Catálogo vazio ou desabilitado
• Área de entrega configurada como vazia
• Fora do horário (verifique opening-hours)
• Sem polling regular (validação is-connected)

1. Verifique horários com GET /merchants/{merchantId}/opening-hours
2. Implemente polling GET /merchants/{merchantId}/status a cada 30 segundos
3. Verifique catálogo e áreas de entrega no Portal do Parceiro
4. Simule um pedido em ambiente de teste (se disponível)
5. Abra um chamado se tudo estiver correto