> ## Documentation Index > Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração: > > 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token. > 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo. > > Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos. # Guia de segurança para parceiros > O que esperamos que você proteja ao acessar dados de lojistas via API Yampi, e como agir quando algo der errado. 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](/apps/criacao-e-configuracao/permissoes-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](/auth/oauth). ### 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](/auth/oauth#2-redirecionamento-para-autorização-utilizando-pkce). *** ## 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-que-fazer-quando-algo-der-errado). | O formato da requisição de renovação está em [OAuth 2.0](/auth/oauth#5-atualize-os-tokens). *** ## 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. ```php theme={"system"} 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](/api-reference/introduction-webhook). *** ## 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](https://www.gov.br/anpd/pt-br/canais_atendimento/agente-de-tratamento/comunicado-de-incidente-de-seguranca-cis)). 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. Descarte os tokens possivelmente comprometidos e interrompa as chamadas à API feitas em nome das lojas afetadas. Levante quais lojistas foram atingidos, quais dados ficaram expostos e por quanto tempo. Você vai precisar dessas informações nos dois passos seguintes. Envie um e-mail para [integre@yampi.com.br](mailto: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. Havendo dados pessoais envolvidos, comunique cada lojista atingido. É ele, como controlador, que responde à ANPD — e o [prazo de 3 dias úteis](#suas-obrigações-sob-a-lgpd) corre a partir da ciência dele. 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](/apps/testes-e-validacao/submissao-de-aplicativos-para-homologacao), revise: * 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 * 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 * 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 * 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 * Há um responsável interno definido para lidar com incidentes de segurança * A equipe sabe que deve notificar [integre@yampi.com.br](mailto: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](/apps/criacao-e-configuracao/diretrizes-para-aplicativos-na-yampi). *** ## 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 * [Autenticação](/auth/auth) * [OAuth 2.0](/auth/oauth) * [Permissões de um aplicativo](/apps/criacao-e-configuracao/permissoes-de-um-aplicativo) * [Diretrizes para aplicativos na Yampi](/apps/criacao-e-configuracao/diretrizes-para-aplicativos-na-yampi) * [Webhooks](/api-reference/introduction-webhook) * [Painel de Parceiros](https://partners.yampi.com.br) * [LGPD — Lei nº 13.709/2018](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) *** ## 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](mailto:integre@yampi.com.br).