Guia de segurança para parceiros

Ao publicar um aplicativo na Loja de Apps Yampi, você passa a ter acesso a dados de lojistas e, em muitos casos, aos dados dos clientes desses lojistas. Essa responsabilidade é sua — a Yampi não tem como auditar a infraestrutura, o código ou a arquitetura dos serviços de cada parceiro. Este guia não prescreve como construir sua aplicação. Ele descreve o que esperamos que você proteja, por que isso importa, e como agir quando algo der errado.

Você é responsável pelo que acessa

Quando um lojista instala seu app, ele está concedendo acesso a dados da loja dele — pedidos, clientes, produtos, informações financeiras. Esse consentimento é dado a você, não à Yampi. Isso significa que:

A segurança de como você armazena e usa esses dados é responsabilidade do seu produto.
A Yampi não monitora o que você faz com os dados acessados via API.
Em caso de vazamento ou uso indevido, o lojista prejudicado vai responsabilizar quem instalou o app.

Vale refletir periodicamente: se alguém invadisse seu sistema hoje, a que teria acesso? Dados de quantos lojistas estariam expostos?

Peça apenas o que você realmente precisa

A API Yampi funciona com um sistema de escopos — cada escopo define o que seu app pode fazer (ler pedidos, atualizar produtos, acessar clientes, etc.). É tentador solicitar todos os escopos disponíveis para evitar problemas futuros. Recomendamos não fazer isso. Cada permissão extra é uma superfície de risco a mais. Se seu app só precisa ler pedidos, não solicite permissão para alterar produtos. O lojista verá quais permissões você pede antes de instalar — e apps que pedem mais do que precisam geram desconfiança e podem ser removidos da Loja. Regra prática: solicite apenas o mínimo necessário para o app funcionar. Se precisar de mais permissões no futuro, solicite na hora certa. Consulte a lista completa de escopos disponíveis em Permissões de um aplicativo.

Autenticação: use OAuth 2.0

A Yampi exige OAuth 2.0 para todos os apps publicados na Loja. Não há alternativa aceita. O OAuth garante que o lojista autorize explicitamente o acesso do seu app, com permissões definidas e revogáveis a qualquer momento. Qualquer outra abordagem — como solicitar login e senha do lojista diretamente — é proibida e motivo de remoção da Loja. O que esperamos da sua implementação:

O fluxo de autorização redireciona corretamente e valida as respostas do servidor Yampi.
Os tokens de acesso são renovados antes de expirar.
O acesso é encerrado quando o lojista desinstala o app.

A implementação é responsabilidade da sua equipe. A documentação completa está em OAuth 2.0.

PKCE é obrigatório

O fluxo OAuth da Yampi é o Authorization Code com PKCE (RFC 7636), e não existe modo sem ele. A concessão não utiliza client_secret — o que impede que um segredo fique embarcado no seu app, mas também significa que o code devolvido no redirecionamento é a única credencial em trânsito. O PKCE fecha essa lacuna: você gera um code_verifier aleatório, envia o code_challenge derivado dele na autorização e apresenta o code_verifier original ao trocar o code pelo token. Quem interceptar o code sem ter o code_verifier não consegue trocá-lo por nada.

Gere um code_verifier novo e aleatório a cada autorização, com um gerador criptograficamente seguro. Reaproveitar o mesmo valor entre lojistas ou entre sessões anula a proteção do PKCE.

Os requisitos de formato do code_verifier e do code_challenge, com exemplos de geração, estão em OAuth 2.0.

Trate tokens com o mesmo cuidado de uma senha

Os tokens de acesso que seu app recebe após a autorização do lojista funcionam como chaves: quem os tiver pode agir em nome daquele lojista na API Yampi. Situações que vemos com frequência e que valem atenção:

Antipadrão	Por que é um problema
Token em `localStorage` ou `sessionStorage`	Qualquer script executado na página lê o valor. Um XSS em qualquer dependência do frontend vira vazamento de token.
Token em variável de ambiente exposta no frontend	Variáveis de build (`NEXT_PUBLIC_`, `VITE_` e similares) são embutidas no bundle e ficam legíveis para qualquer visitante.
Token em log de erro ou APM	Logs costumam ter retenção longa e uma lista de leitores muito maior que a do banco de dados.
Token em banco de dados sem criptografia	Um dump de banco — por backup exposto ou SQL injection — entrega o acesso de todos os lojistas de uma vez.
Token commitado em repositório	Permanece no histórico do Git mesmo após remoção no commit seguinte.

Você não precisa usar uma solução específica. Mas é importante garantir que tokens não estejam acessíveis a pessoas não autorizadas — dentro ou fora da sua organização.

Tokens de lojista devem ser guardados e usados no seu backend. O navegador do lojista não precisa ver o token em momento algum: sua interface conversa com o seu servidor, e o seu servidor conversa com a API Yampi.

Um teste rápido: se alguém da equipe consegue ver o token de um lojista sem acesso privilegiado, vale revisar.

Rotação e revogação

O Access Token é válido por 10 minutos e o Refresh Token, por 30 dias. Seu app precisa de um processo automático de renovação — não dá para depender de intervenção manual em uma janela de 10 minutos.

Situação	O que fazer
`Access Token` próximo de expirar	Renove proativamente com o `refresh_token`, antes de a chamada falhar. Tratar o `401` como gatilho único de renovação funciona, mas gera erro em produção a cada ciclo.
`Refresh Token` próximo de 30 dias	Renove antes do vencimento. Se ele expirar, o lojista precisa autorizar o app de novo — o que aparece para ele como uma integração quebrada.
Lojista desinstalou o app	Descarte os tokens armazenados e interrompa as chamadas àquela loja.
Suspeita de comprometimento	Descarte os tokens afetados, force uma nova autorização e notifique a Yampi.

O formato da requisição de renovação está em OAuth 2.0.

Toda comunicação deve ser criptografada

Qualquer dado trafegado entre seu app e a API Yampi — ou entre seu app e o navegador do lojista — precisa usar HTTPS. Isso inclui a URL de redirecionamento que você cadastra no Painel de Parceiros. Em produção, nunca use endereços HTTP. A criptografia em trânsito é o mínimo esperado. Se você coleta ou armazena dados pessoais de lojistas ou clientes, também esperamos que esses dados estejam protegidos em repouso.

URL de redirecionamento

A URL de redirecionamento é para onde a Yampi devolve o code de autorização. Se ela puder ser manipulada, o code vai parar em outro lugar.

Use HTTPS em produção, sempre.
Cadastre a URL exata, sem coringas. Um caminho aberto como https://seuapp.com/* aceita qualquer redirecionamento dentro do domínio, inclusive páginas que você não controla.
Não use redirecionadores abertos nem URLs que repassem o destino por query string.

Durante o desenvolvimento, http://localhost/sua-url-de-redirecionamento é aceito. Essa exceção vale só para o ambiente local — o app publicado precisa apontar para uma URL HTTPS.

Valide a assinatura dos webhooks

Se seu app consome webhooks, a URL que os recebe é um endpoint público: qualquer pessoa pode enviar um POST para ela fingindo ser a Yampi. Processar um evento sem verificar a origem significa aceitar comandos de quem quiser. Toda requisição de webhook da Yampi traz o header X-Yampi-Hmac-SHA256. Para validar, calcule o HMAC-SHA256 do corpo bruto da requisição usando a chave secreta do webhook, codifique em Base64 e compare com o valor do header.

function hmac_signature(string $rawBody, string $webHookSecret): string
{
    return base64_encode(hash_hmac('sha256', $rawBody, $webHookSecret, true));
}

$rawBody = file_get_contents('php://input');
$assinatura = $_SERVER['HTTP_X_YAMPI_HMAC_SHA256'] ?? '';

if (! hash_equals(hmac_signature($rawBody, $webHookSecret), $assinatura)) {
    http_response_code(401);
    exit;
}

Três detalhes que costumam quebrar a validação ou enfraquecê-la:

O Base64 é calculado sobre o HMAC em formato binário — é o quarto argumento true do hash_hmac().
Use o corpo exatamente como recebido. Desserializar e serializar de novo altera espaçamento e ordem de chaves, e a assinatura deixa de bater.
Compare com uma função de tempo constante (hash_equals em PHP, crypto.timingSafeEqual em Node). Comparar com == abre espaço para ataque de temporização.

Valide antes de processar o evento. Se a assinatura não bater, descarte a requisição. Os eventos disponíveis e o formato do payload estão em Webhooks.

Suas obrigações sob a LGPD

Ao acessar dados de clientes dos lojistas via API Yampi, você se torna um operador de dados nos termos da Lei Geral de Proteção de Dados (Lei nº 13.709/2018). O lojista é o controlador — mas você tem obrigações legais próprias. Na prática, isso significa:

Você só pode usar os dados acessados para a finalidade declarada do app.
Não pode compartilhar, vender ou cruzar esses dados com outras bases sem justificativa legal.
É importante ter uma política de retenção: por quanto tempo você guarda os dados? O que acontece quando o lojista desinstala o app?
Em caso de incidente envolvendo dados pessoais, você precisa comunicar o lojista com agilidade, porque o prazo legal corre para ele.

Como operador, sua obrigação é comunicar o controlador — o lojista —, e não a ANPD diretamente. É o lojista que comunica a ANPD, no prazo de 3 dias úteis contados do conhecimento de que o incidente afetou dados pessoais (Resolução CD/ANPD nº 15/2024). Como esse prazo começa a correr a partir da ciência do lojista, qualquer demora sua em avisá-lo consome o tempo dele.

Se você ainda não conta com um DPO (Encarregado de Dados) ou assessoria jurídica em LGPD, vale buscar esse suporte antes de publicar um app que acessa dados pessoais.

O que fazer quando algo der errado

Incidentes acontecem. O que diferencia um parceiro confiável não é nunca ter problemas — é saber como agir quando eles aparecem. Trate como incidente qualquer um destes cenários:

Acesso não autorizado a tokens de lojistas
Vazamento de dados de lojistas ou clientes
Vulnerabilidade ativa sendo explorada no seu app
Comportamento anômalo na integração com a API

A ordem abaixo importa: conter antes de comunicar evita que o incidente continue crescendo enquanto você investiga.

Contenha o acesso

Descarte os tokens possivelmente comprometidos e interrompa as chamadas à API feitas em nome das lojas afetadas.

Avalie o alcance

Levante quais lojistas foram atingidos, quais dados ficaram expostos e por quanto tempo. Você vai precisar dessas informações nos dois passos seguintes.

Notifique a Yampi

Envie um e-mail para integre@yampi.com.br com uma descrição do ocorrido, o impacto estimado e as ações já tomadas. Quanto mais rápido, melhor.A Yampi pode suspender temporariamente o acesso do app à API enquanto o incidente é investigado — não como punição, mas para proteger os lojistas afetados.

Notifique os lojistas afetados

Havendo dados pessoais envolvidos, comunique cada lojista atingido. É ele, como controlador, que responde à ANPD — e o prazo de 3 dias úteis corre a partir da ciência dele.

Corrija e acompanhe

Feche a falha que originou o incidente, refaça o fluxo de autorização para obter tokens novos e monitore se o comportamento anômalo cessou.

Não espere ter certeza absoluta para notificar. Se você suspeita que algo está errado, comunique. A transparência ágil protege você e os lojistas.

Governança contínua

Segurança não termina no deploy. Seu produto precisa ter respostas claras para três perguntas a qualquer momento:

Quem na sua organização é responsável pela segurança da integração com a Yampi?
O quê está sendo monitorado ativamente — tokens, acessos, dependências, comportamento anômalo?
Como você saberia se algo desse errado hoje?

Se alguma dessas perguntas não tiver dono, vale resolver antes de seguir em frente. Não é necessário ter um time dedicado — é necessário ter alguém com responsabilidade clara e um processo mínimo funcionando.

Checklist antes de publicar

Antes de submeter seu app para homologação, revise:

Acesso e autenticação

O app usa exclusivamente OAuth 2.0 para autenticar com a Yampi
Um code_verifier novo e aleatório é gerado a cada autorização
Apenas os escopos necessários foram solicitados
O acesso é encerrado quando o lojista desinstala o app

Proteção de tokens e credenciais

Nenhum token ou credencial está exposto em código-fonte, logs ou frontend
Tokens são armazenados com controle de acesso adequado
A renovação do Access Token e do Refresh Token é automática
Há processo para revogar e renovar tokens em caso de comprometimento

Comunicação e infraestrutura

Toda comunicação com a API Yampi usa HTTPS
A URL de redirecionamento cadastrada usa HTTPS em produção e não contém coringas
A assinatura X-Yampi-Hmac-SHA256 é validada antes de processar qualquer webhook

Dados e conformidade

O app processa apenas os dados necessários para sua função declarada
Há política definida de retenção e exclusão de dados
A equipe conhece as obrigações do app sob a LGPD

Incidentes

Há um responsável interno definido para lidar com incidentes de segurança
A equipe sabe que deve notificar integre@yampi.com.br em caso de incidente

Com todos os itens revisados, seu app atende ao que avaliamos em segurança. A homologação verifica também os demais critérios das diretrizes para aplicativos.

Consequências do não cumprimento

Apps que violarem as diretrizes de segurança da Yampi estão sujeitos a:

Suspensão do acesso à API
Remoção da Loja de Apps
Cancelamento do status de Parceiro Tech

Em casos que envolvam dados pessoais de lojistas ou clientes, o parceiro também pode responder civil e administrativamente nos termos da LGPD.

Referências

Precisa de suporte?

Dúvidas sobre segurança ou sobre os requisitos para publicação? Fale com o time pelo e-mail integre@yampi.com.br.

Criação e configuração

Testes e Validação

Publicação e Visibilidade

Parcerias e Acesso ao Painel

Você é responsável pelo que acessa

Peça apenas o que você realmente precisa

Autenticação: use OAuth 2.0

PKCE é obrigatório

Trate tokens com o mesmo cuidado de uma senha

Rotação e revogação

Toda comunicação deve ser criptografada

URL de redirecionamento

Valide a assinatura dos webhooks

Suas obrigações sob a LGPD

O que fazer quando algo der errado

Governança contínua

Checklist antes de publicar

Consequências do não cumprimento

Referências

Precisa de suporte?

​Você é responsável pelo que acessa

​Peça apenas o que você realmente precisa

​Autenticação: use OAuth 2.0

​PKCE é obrigatório

​Trate tokens com o mesmo cuidado de uma senha

​Rotação e revogação

​Toda comunicação deve ser criptografada

​URL de redirecionamento

​Valide a assinatura dos webhooks

​Suas obrigações sob a LGPD

​O que fazer quando algo der errado

​Governança contínua

​Checklist antes de publicar

​Consequências do não cumprimento

​Referências

​Precisa de suporte?

Você é responsável pelo que acessa

Peça apenas o que você realmente precisa

Autenticação: use OAuth 2.0

PKCE é obrigatório

Trate tokens com o mesmo cuidado de uma senha

Rotação e revogação

Toda comunicação deve ser criptografada

URL de redirecionamento

Valide a assinatura dos webhooks

Suas obrigações sob a LGPD

O que fazer quando algo der errado

Governança contínua

Checklist antes de publicar

Consequências do não cumprimento

Referências

Precisa de suporte?