> ## Documentation Index > Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt > Use this file to discover all available pages before exploring further. # Glossário > Conceitos e termos técnicos da Alpa explicados de forma simples Encontrou um termo que não conhece? Este glossário explica os principais conceitos e termos técnicos usados na documentação da Alpa de forma simples e direta. ## Autenticação e Segurança ### Bearer Token Também chamado de **API Key** ou **chave de API**, é o método de autenticação usado para autorizar suas requisições à API da Alpa. A chave é enviada no header HTTP `Authorization: Bearer SUA_API_KEY`. Sem uma chave válida, nenhuma requisição será aceita. ### Webhook Secret String secreta configurada ao criar uma assinatura de webhook. Garante que as notificações recebidas vieram realmente da Alpa. Deve ser validada no seu servidor para evitar requisições maliciosas. ### HTTPS Versão segura do HTTP que usa criptografia TLS/SSL. Todos os endpoints da Alpa e as URLs de webhook **precisam obrigatoriamente usar HTTPS**. ### TLS/SSL Protocolos de segurança que criptografam a comunicação na internet. Utilizados em todas as conexões com a API da Alpa. ## Ambientes e Modos ### Ambiente de Desenvolvimento Modo de testes onde as transações são **simuladas** e nenhum valor real é movimentado. Na Alpa, o ambiente é definido **pela chave de API utilizada**: chaves de desenvolvimento geram transações de teste. ### Ambiente de Produção Modo real onde as transações são processadas e valores reais são movimentados. Requer conta verificada e chave de API de produção. ### Sandbox Outro nome para o ambiente de desenvolvimento/testes. Ideal para desenvolver e validar sua integração antes de ir para produção. ## Pagamentos e Cobranças ### Link de Pagamento URL reutilizável gerada pela Alpa que pode ser compartilhada com clientes para receber pagamentos via PIX, cartão ou boleto. Pode ter estoque limitado, cupons, parcelamento e URLs de redirecionamento configuráveis. ### Checkout Processo onde o cliente finaliza a compra e realiza o pagamento. Pode acontecer numa página gerenciada pela Alpa (via link de pagamento) ou diretamente na sua aplicação. ### Gateway de Pagamento Plataforma intermediária que processa pagamentos entre o cliente e o vendedor. A Alpa é um gateway de pagamento que facilita transações PIX, cartão e boleto. ### Transação Registro de uma operação financeira. Cada transação tem um ID único, status, método de pagamento e informações do cliente. ### PIX Sistema de pagamento instantâneo brasileiro que permite transferências 24h/7 em segundos, sem custo para o pagador. ### Boleto Método de pagamento brasileiro que gera um código de barras para pagamento em bancos, lotéricas ou internet banking. Pode levar até 3 dias úteis para compensar. ### Parcelamento Divisão do pagamento em múltiplas parcelas mensais no cartão de crédito. Pode ser com ou sem juros. ### Payout / Saque Transferência do saldo da sua conta Alpa para sua chave PIX ou conta bancária. Métodos suportados: PIX e TED. ## Estrutura de Dados ### Centavos Unidade usada pela API para representar valores monetários. 100 centavos = R\$ 1,00. **Exemplo:** `10000` = R\$ 100,00. ### Slug Identificador único e legível usado em URLs de links de pagamento. Gerado automaticamente, mas pode ser personalizado. **Exemplo:** `meu-produto-premium` ### Metadata Campo opcional que permite armazenar informações adicionais personalizadas junto com recursos da API (transações, links de pagamento, etc.). Aceita qualquer objeto JSON. **Exemplo:** ```json theme={null} { "metadata": { "pedido_interno": "12345", "origem": "site", "campanha": "black-friday" } } ``` ### External ID Identificador único do seu sistema para relacionar recursos da Alpa com registros internos. Útil para buscar transações usando seus próprios códigos de pedido. ### UUID Identificador único de 128 bits gerado automaticamente para identificar recursos na API. Formato: `550e8400-e29b-41d4-a716-446655440000`. ## Cupons e Descontos ### Cupom Código promocional que oferece desconto em uma compra. Pode ser percentual (ex: 10% off) ou valor fixo (ex: R\$ 5,00 off). Suporta limite de usos e validade. ### Desconto Percentual Tipo de desconto aplicado como porcentagem sobre o valor total. **Exemplo:** Cupom de 15% em uma compra de R$ 100,00 → desconto de R$ 15,00. ### Desconto Fixo Tipo de desconto com valor fixo independente do total da compra. **Exemplo:** Cupom de R\$ 20,00 em qualquer compra. ## Afiliados ### Programa de Afiliados Configuração criada por um anunciante que define a comissão paga a afiliados que indicarem clientes. Cada programa tem sua taxa de comissão e regras próprias. ### Link de Afiliado URL única gerada para cada afiliado dentro de um programa. Rastreia as vendas originadas por aquele afiliado. ### Comissão Valor pago automaticamente ao afiliado quando uma venda é realizada através do seu link. Calculada com base nas regras do programa. ## Status ### Status da Transação * **PENDING**: Aguardando pagamento * **PAID**: Pago e confirmado * **CANCELLED**: Cancelada * **EXPIRED**: Expirada * **REFUNDED**: Reembolsada ### Status do Saque * **PENDING**: Solicitação recebida, aguardando processamento * **PROCESSING**: Em processamento * **COMPLETED**: Concluído com sucesso * **CANCELLED**: Cancelado * **FAILED**: Falhou ## Webhooks ### Webhook Mecanismo onde a Alpa **envia notificações automáticas** para o seu servidor sempre que algo importante acontece (como um pagamento confirmado), sem você precisar consultar a API constantemente. ### Assinatura de Webhook Configuração que define para qual URL e para quais eventos a Alpa deve enviar notificações. Uma conta pode ter múltiplas assinaturas. ### Evento Ação que dispara um webhook. Exemplos: `transaction.paid`, `payment_link.expired`, `withdrawal.completed`. Cada evento contém informações sobre o que aconteceu. ### Payload Dados enviados pela Alpa no corpo da notificação HTTP ao seu endpoint de webhook. ## URLs e Endpoints ### Base URL Endereço raiz de todas as requisições à API: `https://alpa-sistema-api.onrender.com` ### Endpoint URL específica que executa uma função na API. **Exemplo:** `POST /api/v1/payment-links` cria um novo link de pagamento. ### Return URL URL para onde o cliente é redirecionado ao clicar em "voltar" no checkout, antes de completar o pagamento. ### Completion URL URL para onde o cliente é redirecionado **após completar** o pagamento com sucesso. ## Padrões Técnicos ### REST Estilo arquitetural para APIs que usa métodos HTTP padrão: GET (consultar), POST (criar), PATCH (atualizar), DELETE (remover). ### JSON Formato de dados leve e legível usado para troca de informações entre sistemas. Toda a API da Alpa usa JSON. ### ISO 8601 Padrão internacional para datas e horários. Formato: `2026-01-15T10:30:00Z`. ### BRL Código ISO 4217 para Real Brasileiro (R\$). Moeda padrão de toda a API. ### CPF / CNPJ Documentos de identificação brasileiros. CPF para pessoas físicas (11 dígitos) e CNPJ para empresas (14 dígitos). ## Estrutura de Resposta Todas as respostas da API seguem o padrão: ```json theme={null} { "data": { }, "error": null, "success": true } ``` * Se `success` for `true`, a operação foi bem-sucedida e os dados estarão em `data` * Se `success` for `false`, a operação falhou e a mensagem de erro estará no campo `error` ### Códigos HTTP comuns * **200 OK** — Sucesso * **201 Created** — Recurso criado com sucesso * **400 Bad Request** — Requisição inválida (verifique os parâmetros) * **401 Unauthorized** — API Key ausente ou inválida * **404 Not Found** — Recurso não encontrado * **429 Too Many Requests** — Rate limit atingido * **500 Internal Server Error** — Erro interno da Alpa *** Entre em contato com nosso suporte: [suporte@usealpa.com](mailto:suporte@usealpa.com)