> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segurança e melhores práticas em IA

Diretrizes de segurança para desenvolvedores que usam ferramentas de IA para criar integrações com o Localpayment. Proteja suas credenciais, gerencie os dados de pagamento com responsabilidade e revise o código gerado por IA antes de implantá-lo em produção.

As ferramentas de IA aceleram significativamente o desenvolvimento, mas, no contexto de pagamentos, avançar rapidamente sem medidas de segurança acarreta riscos reais. As diretrizes desta página ajudam você a obter os benefícios do desenvolvimento assistido por IA sem expor suas credenciais, os dados de seus clientes ou seu ambiente de produção a riscos desnecessários.

***

## Segurança de credenciais

> [!WARNING]
>
> Nunca cole chaves de API, tokens de acesso ou credenciais secretas em uma interface de bate-papo com IA. A maioria dos provedores de IA registra as conversas, e as credenciais compartilhadas em um bate-papo podem ser armazenadas, indexadas ou expostas.

**Regras a seguir:**

* Use **variáveis de ambiente** para todas as credenciais no código gerado por IA. Se a IA produzir uma chave fixa em um exemplo, substitua-a imediatamente.
* Use **credenciais do ambiente de teste** ao trabalhar com IA durante o desenvolvimento e os testes. As chaves de API do ambiente de teste são de baixo risco: elas não podem movimentar dinheiro real.
* Se você compartilhar acidentalmente uma chave de API de Produção em uma sessão de bate-papo, **faça a rotação dela imediatamente** no Business Portal do Localpayment (`https://ui.v3.localpayment.com` para Produção ou `https://ui.stage.localpayment.com` para Stage) e audite seu histórico recente de transações.
* Não compartilhe segredos de webhook, tokens JWT ou qualquer material de autenticação em prompts, mesmo que de forma "sanitizada" e aparentemente óbvia.

**Padrão de credenciais seguras em código gerado por IA:**

```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import os

# Always use environment variables — never hardcode credentials
API_KEY = os.environ["LOCALPAYMENT_API_KEY"]
BASE_URL = os.environ.get(
    "LOCALPAYMENT_BASE_URL", 
    "https://api.stage.localpayment.com"  # Default to Stage
)
```

***

## Dados do cliente e de pagamento

Não compartilhe dados reais de pagamento com ferramentas de IA, a menos que tenha verificado se os termos de processamento de dados do provedor são compatíveis com suas obrigações de conformidade.

**O que evitar colar em chats de IA:**

* Dados reais do titular do cartão (números do cartão, CVVs, datas de validade)
* Informações pessoais reais de clientes (números de identificação nacional, nomes completos combinados com dados de documentos)
* Cargas úteis reais de webhook contendo valores de transações e números de contas reais provenientes de produção
* Números de conta (CVU, CLABE, CCI) associados a clientes reais

**O que é seguro:**

* Cargas úteis de webhook sanitizadas ou fictícias (substitua os valores reais por marcadores como `XXXX` ou por valores de exemplo)
* Códigos de erro e códigos de status sem o contexto da transação
* Estruturas de requisição de API com valores de exemplo da documentação

**Exemplo: forma segura de solicitar ajuda para depurar webhooks:**

```
I'm receiving this webhook structure from Localpayment and I'm not sure 
how to parse the beneficiary fields. Here's a sanitized example:

{
  "externalId": "test-12345",
  "amount": 100,
  "beneficiary": {
    "bank": {
      "account": {
        "number": "0000000000000000000000"
      }
    }
  }
}

Which field identifies the virtual account that received the payment?
```

***

## Stage antes de Produção

Desenvolva e teste sempre a sua integração assistida por IA no **ambiente de teste (Stage)** antes de implantá-la em Produção.

| Configuração | Estágio | Produção |
| :- | :- | :- |
| **URL base da API** | `https://api.stage.localpayment.com` | `https://api.v3.localpayment.com` |
| **Business Portal** | `https://ui.stage.localpayment.com` | `https://ui.v3.localpayment.com` |
| **Transações** | Simulado: sem movimentação de dinheiro real | Real: fundos reais |
| **Credenciais** | Chaves da API Stage | Chaves de API de produção |
| **Seguro para desenvolvimento assistido por IA** | ✔ Sim | ⚠ Somente após validação |

> [!NOTE]
>
> O servidor Localpayment MCP expõe a documentação e a especificação da API, mas não executa solicitações. Todas as chamadas de API reais ocorrem no seu próprio código, usando suas credenciais. O risco do ambiente depende inteiramente das credenciais e da URL base que você usa na sua integração.

Observe que alguns recursos estão disponíveis **apenas em Produção** (por exemplo, a criação de aliases CVU na Argentina). A documentação de cada recurso indica explicitamente quando isso se aplica.

***

## Analisando o código gerado por IA

O código gerado por IA deve sempre ser revisado antes de ser integrado ou implantado. Em uma integração de pagamentos, erros podem ter consequências financeiras.

**Lista de verificação para revisão do código de integração do Localpayment gerado por IA:**

* **Sem credenciais fixas no código**: todas as chaves de API usam variáveis de ambiente
* **URL base correta**: URL de Stage para desenvolvimento, URL de Produção para implantação
* **O externalId é único**: o código gera IDs únicos por transação (por exemplo, UUID). externalIds duplicados causarão o erro `500`.
* **Idempotência do webhook**: o manipulador de webhook verifica se o `internalId` já foi processado antes de agir
* **Resposta HTTP 200**: o manipulador de webhook sempre retorna 200 OK após o processamento, mesmo para eventos que ele ignora
* **Somente HTTPS**: todas as chamadas de API usam HTTPS, nunca HTTP
* **Tratamento de erros**: os códigos de status de rejeição (5xx, 8xx, 9xx) são capturados e tratados, e não ignorados silenciosamente
* **Dados sensíveis não registrados em log**: chaves de API, dados de cartão e informações pessoais de clientes não são gravados nos logs

***

## Que dados o Localpayment pode visualizar?

Ao utilizar qualquer ferramenta de IA da Localpayment (servidor MCP, prompts do sistema do agente ou esta documentação), é importante compreender exatamente o que a Localpayment pode e não pode acessar:

| Dado | O Localpayment vê isso? | Detalhes |
| :- | :-: | :- |
| Seu código-fonte | Não | O código é processado localmente pela sua IDE/ferramenta e enviado ao seu provedor de IA (Anthropic, OpenAI, etc.), não à Localpayment. |
| Suas chaves de API ou credenciais | Não | Nunca enviado para o servidor MCP. Enviado apenas para os endpoints da API da Localpayment por meio de suas próprias chamadas HTTPS. |
| Seus arquivos de projeto ou arquitetura | Não | Permanece no seu dispositivo e com o seu provedor de IA. |
| Suas cargas úteis de webhook | Não | Nunca enviado para Localpayment por meio de ferramentas de IA |
| Consultas MCP (ex: "mostrar-me o endpoint X") | Sim | O servidor MCP recebe consultas de pesquisa sobre sua própria documentação pública. |
| Conteúdo da documentação fornecido | Sim | O servidor MCP disponibiliza documentação pública que qualquer pessoa pode ler em docs.localpayment.com. |

O servidor Localpayment MCP é um **servidor de documentação pública, somente leitura**. Ele não tem acesso à sua conta de comerciante na Localpayment, às suas transações nem a quaisquer dados que você tenha armazenado na Localpayment. Ele apenas disponibiliza a mesma documentação disponível publicamente em `https://docs.localpayment.com`.

***

## Políticas de dados de ferramentas de IA

Entender como seu provedor de IA lida com os dados que você compartilha faz parte do uso responsável.

| Ferramenta de IA | Notas sobre tratamento de dados |
| :- | :- |
| **Servidor Localpayment MCP** | Somente leitura. Retorna a documentação e a especificação da API. O processamento dos dados depende da plataforma ReadMe.com que hospeda o servidor. Consulte a [política de privacidade do ReadMe](https://readme.com/privacy) para obter detalhes. |
| **Claude (Anthropic)** | As conversas podem ser usadas para aprimorar os modelos, a menos que você opte por não participar por meio da API ou do contrato corporativo. |
| **ChatGPT (OpenAI)** | O histórico da conversa é mantido. Desative a opção "Melhorar o modelo para todos" nas configurações se estiver usando dados confidenciais. |
| **GitHub Copilot** | As sugestões de código são baseadas no contexto. Evite incluir credenciais ou informações pessoais identificáveis em arquivos abertos no editor. |
| **Cursor / Windsurf** | O contexto enviado aos provedores de IA depende da configuração. Consulte as configurações de privacidade do seu editor. |

> [!WARNING]
>
> **Antes de utilizar qualquer ferramenta de IA para processar dados de clientes ou transações, você deve avaliar suas obrigações de acordo com as regulamentações de proteção de dados e financeiras aplicáveis em cada país onde opera.** O uso de ferramentas de IA para processar dados pessoais, informações financeiras ou dados de transações de pagamento pode exigir bases legais específicas, contratos de processamento de dados (DPA) com o fornecedor de IA e salvaguardas técnicas, dependendo da sua jurisdição.
>
> As regulamentações aplicáveis por país de operação incluem, entre outras:
>
> * **Argentina**: Ley 25.326 de Protección de Datos Personales (LPDP) e regulamentos aplicáveis do BCRA
> * **Brasil**: Lei Geral de Proteção de Dados (LGPD, Lei 13.709/2018)
> * **Colômbia**: Ley 1581 de 2012 (Habeas Data) e Decreto 1074 de 2015
> * **México**: Ley Federal de Protección de Datos Personales en Posesión de los Particulares (LFPDPPP) e seu Reglamento
> * **Peru**: Ley 29733 de Protección de Datos Personales e seu Regulamento (D.S. 003-2013-JUS)
> * **Chile**: Ley 19.628 sobre Protección de la Vida Privada (e alterações em vigor)
> * **Equador**: Ley Orgánica de Protección de Datos Personales (LOPDP)
> * **Todos os mercados**: PCI DSS v4.0 para qualquer processamento que envolva dados de cartão de pagamento.
>
> Em todos os casos: (1) verifique se o seu fornecedor de IA assinou um Acordo de Processamento de Dados (DPA) que abrange os tipos de dados específicos que pretende compartilhar; (2) aplique a minimização de dados: compartilhe apenas o que é estritamente necessário; (3) nunca compartilhe dados de titulares de cartões, documentos de identificação nacionais ou números de contas financeiras com qualquer ferramenta de IA sem autorização legal explícita e controles técnicos adequados.

***

## Referência rápida

| Regra | Por que isso importa |
| :- | :- |
| Use as credenciais do Stage para desenvolvimento assistido por IA | Impede a movimentação de dinheiro real durante os testes. |
| Nunca cole chaves de API reais em chats de IA. | As chaves compartilhadas em chats podem ser registradas ou expostas. |
| Higienize os dados do webhook antes de compartilhá-los. | Protege os dados pessoais identificáveis (PII) e as transações dos clientes. |
| Analise o código gerado por IA antes de implantá-lo. | Previne vazamentos de credenciais e erros de lógica. |
| Use externalIds exclusivos | Evita erros de duplicação (erro 500) |
| Retorne HTTP 200 do seu manipulador de webhook. | Impede que o Localpayment tente novamente enviar notificações válidas. |

***

## Próximos passos

> [card] [Chaves de API e ambientes](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Gerencie suas credenciais de Stage e de Produção e compreenda as diferenças entre os ambientes.

> [card] [Receba notificações de pagamento](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Implemente o tratamento seguro e idempotente de webhooks para eventos de pagamento do Localpayment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.