# Clean Store — Documentação completa para agentes e integrações ## Resumo Clean Store é uma aplicação de e-mail temporário. O usuário pode criar uma caixa temporária pelo painel, acompanhar a inbox e abrir mensagens. Desenvolvedores podem integrar o serviço por HTTP usando uma chave de API, um token de sessão e o endereço da caixa. ## Conceitos de autenticação Existem dois valores diferentes: - `x-api-key`: chave de integração gerada pelo endpoint `POST /api/keys`. Ela identifica a aplicação que está consumindo a API. - `Authorization: Bearer TOKEN`: token de sessão retornado por `POST /api/token`. Ele autoriza a sessão de uma caixa específica. - `x-temp-email`: endereço da caixa consultada. Deve ser enviado nas operações de mensagens. A chave de API deve ser guardada no backend do cliente. O valor completo é exibido apenas na criação. O servidor armazena somente o hash da chave. ## Fluxo recomendado ### 1. Descobrir domínios ```http GET /api/domains x-api-key: SUA_CHAVE_DE_API ``` ### 2. Criar caixa ```http POST /api/accounts Content-Type: application/json x-api-key: SUA_CHAVE_DE_API { "address": "usuario@dominio.com", "password": "uma-senha-forte" } ``` ### 3. Autenticar a caixa ```http POST /api/token Content-Type: application/json x-api-key: SUA_CHAVE_DE_API { "address": "usuario@dominio.com", "password": "uma-senha-forte" } ``` Resposta esperada: ```json { "token": "TOKEN_DE_SESSAO", "id": "ID_DA_CONTA" } ``` ### 4. Listar mensagens ```http GET /api/messages x-api-key: SUA_CHAVE_DE_API Authorization: Bearer TOKEN_DE_SESSAO x-temp-email: usuario@dominio.com ``` ### 5. Consultar uma mensagem ```http GET /api/messages/ID_DA_MENSAGEM x-api-key: SUA_CHAVE_DE_API Authorization: Bearer TOKEN_DE_SESSAO x-temp-email: usuario@dominio.com ``` ### 6. Remover uma mensagem ```http DELETE /api/messages/ID_DA_MENSAGEM x-api-key: SUA_CHAVE_DE_API Authorization: Bearer TOKEN_DE_SESSAO x-temp-email: usuario@dominio.com ``` ## Códigos de confirmação As mensagens retornam conteúdo textual e, quando disponível, HTML. Uma aplicação cliente pode extrair um código de seis dígitos com uma expressão regular equivalente a `\\b\\d{6}\\b`. O Clean Store não deve ser usado para acessar contas de terceiros ou contornar controles de segurança. ## Respostas e erros - `200`: operação concluída. - `201`: recurso criado. - `204`: mensagem removida. - `400`: dados inválidos ou ausentes. - `401`: chave, token ou headers de caixa ausentes ou inválidos. - `404`: mensagem ou recurso não encontrado. - `503`: provedor de e-mail indisponível. ## Limites atuais O fluxo de consulta implementado usa polling controlado. Webhooks de saída e callbacks externos não devem ser considerados disponíveis até que sejam documentados separadamente. A documentação pública deve sempre refletir o comportamento real do servidor. ## Privacidade e segurança Não coloque tokens, senhas, chaves de API, mensagens ou endereços reais em prompts, arquivos públicos, exemplos indexáveis ou código de frontend. Use variáveis de ambiente e um backend intermediário para integrações reais.