Site parceiro (CLIENTE)
Orquestra inscrição, troca de código por token e envio de sync a partir do backend do parceiro.
Como usar a API
Última atualização: 13 de março de 2026
Guia final para integração de parceiros com foco em operação real, sem copiar código e com troubleshooting objetivo.
Base URL atual da API neste frontend
https://mangatracker-qkdy.onrender.com
Em produção, use a URL oficial da API. Os endpoints abaixo são relativos a essa base.
Quem participa
Usuário final
Gera código temporário no Manga Tracker e compartilha com o parceiro.
Manga Tracker (automático)
Valida domínio, credenciais, escopo, domínio permitido e regras de idempotência/sync.
Fluxo final do parceiro (sem copiar código)
1) Envie a inscrição pública
Cadastre o parceiro e guarde o id da inscrição para acompanhamento.
POST /integrations/public/apply
- Endpoint público com rate limit e proteção anti-abuso.
- O envio não ativa a integração automaticamente.
2) Verifique posse do domínio
Publique a prova de domínio e execute a verificação antes da aprovação.
POST /integrations/public/apply/{applicationId}/verify-domain
- DNS TXT é o caminho recomendado; arquivo .well-known é fallback.
- Aprovação fica bloqueada até status VERIFIED.
3) Consulte status quando necessário
Use o applicationId para polling de progresso e próxima ação.
GET /integrations/public/apply/{applicationId}/status
4) Aguarde aprovação
Após aprovação, as credenciais (partnerSlug e clientSecret) são enviadas por e-mail.
5) Usuário gera código de conexão
O usuário gera código temporário no Manga Tracker para vincular a conta ao parceiro.
6) Troque código por token no backend do parceiro
Use o endpoint de exchange com credenciais de parceiro e valide domínio de origem.
POST /integrations/connect/exchange
- Rotação: secret ativo e secret anterior são aceitos durante a janela de transição.
- Após expiração da janela, apenas o secret ativo autentica.
7) Envie sync de progresso
Envie eventos com idempotency key para retries seguros e resultado determinístico.
POST /integrations/sync
- Outcomes: created, updated ou noop.
- Health check opcional: GET /integrations/connection/status.
8) Configure webhooks de eventos
Cadastre endpoint por parceiro para receber eventos assinados e monitorar entregas/retries/DLQ.
POST/GET /integrations/admin/partners/{partnerId}/webhooks
- Assinatura HMAC SHA-256 em timestamp.body; valide antes de processar.
- Em falhas temporárias, a plataforma faz retry com backoff + jitter; no limite, evento vai para DLQ.
- Faça deduplicação do consumidor por x-mangalist-event-id.
Checklist de segurança
- Armazene clientSecret somente no backend.
- Use allowlist de domínio e envie sourceDomain.
- Use x-idempotency-key em todo retry.
- Rotacione secrets periodicamente com janela de transição.
- Use HTTPS fim a fim em produção.
Comportamento operacional
- Scope exigido no MVP: manga:write.
- chapter menor/igual ao atual retorna noop.
- Access token de integração expira em 30 dias.
- Rate limits e validações retornam erros claros por endpoint.
Erros comuns e troubleshooting
- 401 Missing partner credentials: clientSecret ausente para parceiro não público.
- 401 Invalid partner credentials: secret inválido ou janela do secret anterior expirada.
- 401 Invalid or expired connect code: gere novo código no Manga Tracker.
- 401 Connect code domain mismatch: alinhe sourceDomain no start e no exchange.
- 403 Missing manga:write scope: revise escopo da conexão/token.
- 403 Source domain is not allowed for partner: ajuste allowedDomains no admin.
- 429 Too many requests: respeite Retry-After e use backoff com jitter.
- Sync em noop: comportamento esperado quando capítulo não avançou.
Exemplos ponta-a-ponta
- Novo vínculo: start -> exchange -> sync(created).
- Progresso contínuo: sync(updated) com capítulo maior.
- Retry seguro: mesmo evento + mesma idempotency key mantêm resultado sem duplicidade.
- Rotação sem downtime: exchange aceita secret anterior na janela e migra para o novo.