> ## Documentation Index > Fetch the complete documentation index at: https://docs.alphagateway.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar produto > Cadastra um novo produto no catálogo da organização. O `externalId` pode ser informado ou será gerado automaticamente. ## OpenAPI ````yaml /openapi.json post /v1/products/create openapi: 3.0.3 info: title: Alpha Gateway API description: >- ## Introdução Bem-vindo à documentação da API do **Alpha Gateway** — sua plataforma de pagamentos. Com a API você pode receber pagamentos via QR Code PIX, boleto e links de pagamento, solicitar saques PIX, consultar o saldo e gerenciar produtos, tudo de forma programática. ## Resumo para integrar - **URL base:** `https://api.alphagateway.com.br`. Todas as rotas começam com `/v1`. - **Autenticação:** header `x-api-key` com a API Key criada no painel, na página **Integração**. A mesma URL atende homologação e produção: o ambiente é o da organização dona da chave. - **Formato:** JSON em UTF-8 na requisição e na resposta. Valores em reais com até duas casas decimais (ex.: `49.90`); datas em ISO 8601 (UTC). - **Sucesso:** `{ "message": "...", "response": { ... } }`. - **Erro:** `{ "response": null, "errors": ["..."] }`, com o status HTTP correspondente (400, 401, 403, 404, 409, 429, 500 ou 503). - **Idempotência:** cobranças, boletos e saques exigem um `idempotency` único por organização. Repetir a chamada com o mesmo valor não cria outra operação: a API responde 400 (409 nos links de pagamento) e o resultado da primeira chamada pode ser consultado pelo mesmo `idempotency`. - **Confirmações:** pagamentos, saques e devoluções são assíncronos. Receba o resultado por webhook (veja **Webhooks**) ou consulte a operação pelo `idempotency`. - **Testes:** no ambiente de homologação, os endpoints "Ambiente de teste" simulam o pagamento de cobranças e boletos sem dinheiro real. ## Para agentes de IA e ferramentas - Especificação OpenAPI 3.0 (JSON): `https://api.alphagateway.com.br/docs/public-api.json` - Resumo em markdown: `https://api.alphagateway.com.br/llms.txt` - Documentação completa em markdown: `https://api.alphagateway.com.br/llms-full.txt` Cada operação tem `operationId`, descrição de todos os campos, exemplo de requisição e de resposta e os erros possíveis. ## Servidor MCP Agentes de IA compatíveis com o Model Context Protocol (Claude, Cursor, VS Code e outros) podem usar a API como ferramentas pelo servidor MCP em `https://api.alphagateway.com.br/mcp` (transporte HTTP). - **Autenticação:** a mesma API Key, no header `x-api-key` (ou `Authorization: Bearer `). Use uma chave exclusiva para o agente, fácil de revogar. - **Ferramentas:** uma por operação desta documentação, com o mesmo `operationId` como nome. As regras da API valem igual: escopos, ambiente da organização, idempotência e IPs permitidos. Comece por `getAccountContext` para ver o ambiente e as permissões da chave. - **Permissões:** o agente faz tudo o que a chave permite. Os escopos são por funcionalidade: quem consulta saques também pode criá-los. Para um agente que não deve sacar, crie uma chave sem `PIX_OUT`; uma chave sem escopos permite inclusive saques, que em produção movimentam dinheiro de verdade. - **Restrições da chave:** chave com **domínios permitidos** não funciona no MCP (clientes de IA não enviam `Origin`). **IPs permitidos** só funcionam em clientes que rodam na sua máquina ou no seu servidor, como Claude Code, Cursor e VS Code. Configuração (Claude Code em `.mcp.json`, Cursor em `~/.cursor/mcp.json`). No Claude Code, `${ALPHA_API_KEY}` é lido da variável de ambiente, para a chave não ficar no arquivo; no Cursor, escreva `${env:ALPHA_API_KEY}`: ```json { "mcpServers": { "alpha-gateway": { "type": "http", "url": "https://api.alphagateway.com.br/mcp", "headers": { "x-api-key": "${ALPHA_API_KEY}" } } } } ``` No VS Code (`.vscode/mcp.json`) a chave raiz é `servers` em vez de `mcpServers`, e a chave vai num input (`"x-api-key": "${input:alpha-api-key}"`, declarado em `inputs` com `"type": "promptString"` e `"password": true`): o VS Code pede o valor na primeira conexão. No Claude Code pela linha de comando (a chave fica gravada na configuração do Claude Code): ```bash claude mcp add --transport http alpha-gateway https://api.alphagateway.com.br/mcp --header "x-api-key: sua-api-key-aqui" ``` version: 1.0.0 servers: - url: https://api.alphagateway.com.br description: Servidor da API security: - x-api-key: [] tags: - name: Cobranças - PIX description: >- Receba pagamentos gerando um QR Code PIX para compartilhar com seu cliente. ## Como funciona 1. **Gere a cobrança** — Use o endpoint de criar cobrança, que retorna o código PIX copia e cola 2. **Apresente ao cliente** — Exiba o QR Code ou o código copia e cola 3. **Teste em homologação** — No ambiente de testes, use o endpoint de simular pagamento para confirmar a cobrança manualmente 4. **Receba a confirmação** — Cadastre um endpoint de webhook assinando os eventos `pix_in.paid` e `pix_in.refunded` para receber uma notificação automática quando o pagamento for confirmado e a cada devolução (parcial ou total) 5. **Consulte quando precisar** — Verifique o status de qualquer cobrança a qualquer momento ## Status da Cobrança | Status | Descrição | |--------|-----------| | `CREATED` | Cobrança criada, aguardando geração do QR Code | | `WAITING_PAYMENT` | QR Code gerado, aguardando pagamento do cliente | | `PAID` | Pagamento confirmado | | `EXPIRED` | QR Code expirou sem pagamento | | `REFUNDED` | Pagamento devolvido por completo ao pagador | ## Devoluções Um PIX recebido pode ser devolvido ao pagador em uma ou mais devoluções parciais. Cada devolução concluída no banco é descontada do seu saldo pelo valor que saiu da conta (a taxa da cobrança não é devolvida) e gera um evento `pix_in.refunded`: com status `PARTIALLY_REFUNDED` e `partial: true` enquanto a soma das devoluções não chega ao valor do PIX, e com status `REFUNDED` e `partial: false` na devolução que completa o valor. A cobrança continua `PAID` até completar o valor; ao completar, passa a `REFUNDED`. Veja **Devoluções no webhook** na seção Webhooks. ## Webhook de Cobranças Quando um pagamento é confirmado ou devolvido por completo, você recebe uma notificação nos endpoints que assinam os eventos `pix_in.paid` e `pix_in.refunded`. **Exemplo de payload:** ```json { "event": "PIX_IN_UPDATE", "method": "PIX_IN", "status": "PAYED", "payer": { "fullname": "Nome do Pagador", "document": "12345678900" }, "pix": { "endToEndId": "E12345678202301011200abcdefghijkl", "txid": "txid-unico", "value": 100.00, "devolutions": [] }, "transactionId": "uuid-da-transacao", "idempotency": "sua-chave-idempotencia" } ``` > A URL do endpoint deve ser publicamente acessível (HTTPS recomendado) e retornar HTTP 200 para confirmar o recebimento. Consulte a seção **Webhooks** para detalhes de eventos e validação da assinatura HMAC. - name: Saques description: >- Envie pagamentos via PIX para qualquer chave PIX de destino. > No **ambiente de teste** o saque segue o mesmo fluxo da produção (resposta com status `ANALYSIS` e webhooks `pix_out.analysis` e `pix_out.paid`), mas não passa por banco nenhum: o pagamento é simulado, o saldo de teste é debitado e nenhum dinheiro é movimentado. ## Como funciona 1. **Solicite o saque** — Informe o valor, a chave PIX de destino e os dados do beneficiário. O saldo é reservado automaticamente e a resposta retorna com status `ANALYSIS` 2. **Acompanhe pelo webhook** — Cadastre um endpoint assinando os eventos `pix_out.*` (`pix_out.paid`, `pix_out.rejected`, `pix_out.error`, `pix_out.refunded`) para receber atualizações automáticas sobre o processamento 3. **Consulte quando precisar** — Verifique o status do saque a qualquer momento ## Status do Saque | Status | Descrição | |--------|-----------| | `ANALYSIS` | Saque solicitado, aguardando processamento | | `PROCESSING` | Em processamento pelo sistema bancário | | `PAID` | Saque confirmado e enviado ao destinatário | | `REJECTED` | Saque rejeitado (saldo devolvido) | | `ERROR` | Erro no processamento (saldo devolvido) | | `REFUNDED` | Saque devolvido por completo pelo recebedor após ter sido enviado | ## Devolução pelo recebedor O recebedor pode devolver um saque pago em uma ou mais devoluções parciais. A devolução também acontece quando o banco do recebedor devolve um pagamento já concluído (por exemplo, conta encerrada ou bloqueada); nesse caso costuma vir uma única devolução do valor total. Cada devolução concluída no banco é creditada no seu saldo disponível pelo valor que voltou (a taxa do saque não é devolvida) e gera um evento `pix_out.refunded`: com status `PARTIALLY_REFUNDED` e `partial: true` enquanto a soma das devoluções não chega ao valor do saque, e com status `REFUNDED` e `partial: false` na devolução que completa o valor. O saque continua `PAID` até completar o valor; ao completar, passa a `REFUNDED`. Veja **Devoluções no webhook** na seção Webhooks. ## Webhook de Saques Quando o status de um saque é atualizado, você recebe uma notificação nos endpoints que assinam os eventos `pix_out.*`. **Exemplo de payload:** ```json { "event": "PIX_OUT_UPDATE", "method": "PIX_OUT", "status": "PAID", "transactionId": "uuid-da-transacao", "idempotency": "sua-chave-idempotencia", "value": 100.00, "valueFee": 2.50, "valueLiquid": 102.50, "destination": { "pixKey": "chave-pix-destino", "pixType": "DOCUMENT" }, "customer": { "fullName": "Nome Completo", "document": "12345678900" }, "endToEndId": "E12345678202301011200abcdefghijkl", "messageError": null } ``` > A URL do endpoint deve retornar HTTP 200 para confirmar o recebimento. Em caso de falha, o sistema reenvia com backoff exponencial. Consulte a seção **Webhooks** para detalhes de eventos e validação da assinatura HMAC. - name: Cobranças - Boleto description: >- Emita boletos bancários registrados para seus clientes. O boleto é gerado com código de barras, linha digitável e QR Code (PIX do boleto), pronto para pagamento em qualquer banco. > Multa, juros e desconto são aplicados automaticamente conforme a configuração da sua organização no painel. ## Como funciona 1. **Emita o boleto** — Informe o valor, os dados do pagador (incluindo endereço) e, opcionalmente, a data de vencimento. A resposta já retorna `barcode`, `linhaDigitavel`, `qrcode` e `dueDate` 2. **Apresente ao cliente** — Compartilhe a linha digitável / QR Code, ou baixe o PDF do boleto pelo endpoint de segunda via 3. **Teste em homologação** — No ambiente de testes, use o endpoint de efetivar pagamento para confirmar o boleto manualmente 4. **Receba a confirmação** — Cadastre um endpoint de webhook assinando os eventos `boleto.paid`, `boleto.canceled` e `boleto.refunded` para receber notificações automáticas de mudança de status 5. **Consulte ou cancele quando precisar** — Verifique o status a qualquer momento, ou cancele (dê baixa) em um boleto ainda não pago > O endpoint de emissão exige que o escopo `BOLETO` esteja liberado na API Key. A emissão e o cancelamento só funcionam com as transações habilitadas para a organização. ## Data de vencimento e expiração - `dueDate` (opcional) — Data de vencimento do boleto no formato `YYYY-MM-DD`. Se omitida, é aplicado o vencimento padrão da organização. - `expirationDate` (opcional) — Data limite para pagamento após o vencimento, no formato `YYYY-MM-DD`. - `boletoType` (opcional) — Tipo do boleto: `OTHER` (padrão) ou `PROPOSAL`. ## Status do Boleto | Status | Descrição | |--------|-----------| | `CREATED` | Boleto registrado, aguardando pagamento | | `PROCESSING` | Pagamento em processamento pelo banco | | `PAID` | Pagamento confirmado | | `CANCELED` | Boleto cancelado / baixado antes do pagamento | | `REFUNDED` | Pagamento estornado após ter sido pago | ## Webhook de Boleto Quando o status de um boleto muda, você recebe uma notificação nos endpoints que assinam os eventos `boleto.paid`, `boleto.canceled` e `boleto.refunded`. **Exemplo de payload:** ```json { "event": "BOLETO_UPDATE", "method": "BOLETO", "status": "PAID", "transactionId": "01961234-abcd-7000-8000-000000000010", "idempotency": "boleto-12345", "value": 150.00, "valueFee": 3.50, "valueLiquid": 146.50, "boleto": { "barcode": "34191790010104351004791020150008998770000015000", "linhaDigitavel": "34191.79001 01043.510047 91020.150008 9 98770000015000", "qrcode": "00020126580014br.gov.bcb.pix...", "dueDate": "2025-04-10", "payment": { "paidValue": 150.00, "paidAt": "2025-04-08T13:20:00.000Z", "receiptUrl": "https://.../comprovante.pdf" } }, "payer": { "fullName": "João da Silva", "document": "12345678900" } } ``` > A URL do endpoint deve ser publicamente acessível (HTTPS recomendado) e retornar HTTP 200 para confirmar o recebimento. Consulte a seção **Webhooks** para detalhes de eventos e validação da assinatura HMAC. - name: Conta description: >- Informações da organização dona da API Key e saldo da carteira. ## Dados da conta - **Ambiente:** `PRODUCTION` movimenta dinheiro de verdade; `HOMOLOGATION` é o ambiente de teste. A mesma URL atende os dois: o ambiente é o da organização da chave. - **Permissões:** os escopos da chave (com acesso total, todos) e os meios de pagamento habilitados para a organização. - Qualquer API Key válida consulta, sem escopo específico. ## Saldo Consulte o saldo da carteira da sua organização (escopo `WALLET`). | Campo | O que representa | |-------|------------------| | `balanceAvailable` | Valor disponível para saques e operações | | `balanceLocked` | Valor bloqueado por alguma restrição | | `balancePendingRelease` | Valor aguardando liberação | Todos os valores são retornados em **Reais (BRL)**. - name: Webhooks - Endpoints description: >- Configure pela API os endpoints que recebem as notificações (o mesmo que a página **Integração** do painel faz) e acompanhe as entregas. ## Conceitos - **Escopo:** as rotas desta seção exigem uma API Key com o escopo `WEBHOOKS` (ou sem escopos, com acesso total). - **Endpoint:** URL pública (http ou https) que recebe um POST com o corpo JSON de cada evento assinado. Endereços internos (localhost, IP privado, nome sem domínio) são recusados. Cada URL só pode ser cadastrada uma vez por organização. - **Eventos:** use o campo `value` de `GET /v1/webhook-event-types` (ex.: `PIX_IN_PAYED`) ao criar ou atualizar um endpoint. - **Credencial de assinatura (`secret`):** retornada só na criação, na rotação e quando a URL do endpoint é trocada pela API (a troca gera uma credencial nova). Use-a para validar o header `Alpha-Signature` (veja **Webhooks**). Guarde-a com segurança. - **Entregas:** cada evento gera uma entrega por endpoint, com novas tentativas em caso de falha. Depois de esgotadas, a entrega fica `FAILED` e pode ser reenviada. - **Mudanças valem para as próximas notificações:** URL e credencial ficam gravadas em cada notificação quando ela é gerada; alterar, rotacionar ou remover o endpoint não muda as entregas já criadas. - name: Cobranças - Links description: >- Crie e compartilhe links de pagamento com seus clientes. O link direciona para uma página de checkout com os produtos selecionados. ## Formas de vincular produtos aos links de pagamento ### 1. Usando produto já cadastrado Informe o `externalId` de um produto existente no catálogo: ```json { "products": [ { "externalId": "SKU-001", "quantity": 2 } ] } ``` ### 2. Criando produto na hora Informe os dados do produto diretamente, sem precisar cadastrar antes: ```json { "products": [ { "name": "Produto X", "value": 49.90, "quantity": 1 } ] } ``` ## Vincular um cliente (opcional) Você pode vincular um `customer` ao link informando `fullName` e `document`. Quando vinculado, os dados do cliente **já aparecem preenchidos automaticamente na página de checkout**, agilizando o pagamento. ```json { "customer": { "fullName": "Maria Silva", "document": "12345678900" } } ``` ## Limite de pagamentos (opcional) Use `paymentLimit` para definir quantas vezes o link pode ser pago. **Use `0` ou omita o campo para não limitar** (pagamentos ilimitados). ## Métodos de Pagamento Aceitos | Método | Descrição | |--------|-----------| | `PIX_IN` | Pagamento via PIX | | `CARD` | Pagamento via cartão de crédito | | `BOLETO` | Pagamento via boleto bancário | - name: Produtos description: >- Gerencie o catálogo de produtos da sua organização. Produtos cadastrados podem ser reutilizados em links de pagamento. ## Conceitos - **`externalId`** — Identificador do produto no seu sistema. Pode ser informado na criação ou será gerado automaticamente. Use este campo para vincular seus produtos ao Alpha Gateway. - **`value`** — Preço do produto em Reais (BRL). Deve ser um número positivo. - Produtos cadastrados podem ser referenciados ao criar links de pagamento, evitando repetição de dados. - name: Primeiros Passos description: >- Siga os passos abaixo para integrar sua aplicação com o Alpha Gateway. ## 1. Crie sua API Key Acesse a página de **Integração** no painel, clique em **Criar Nova API Key**, dê um nome descritivo e copie a chave gerada. > A API Key é exibida apenas uma vez. Armazene-a em local seguro. ## 2. Faça sua primeira requisição Todas as requisições devem incluir o header `x-api-key` com sua chave: ```bash curl -X GET https://api.alphagateway.com.br/v1/wallet/balance/organization \ -H "x-api-key: sua-api-key-aqui" ``` ## 3. Teste no ambiente de homologação Sua organização começa no ambiente de **homologação**, onde você pode testar todas as funcionalidades sem processar transações reais. Use o endpoint de **simular pagamento** para confirmar cobranças manualmente durante os testes. ## 4. Ative a produção Quando estiver pronto, envie a documentação da empresa pelo painel e aguarde a aprovação. Após ativado, gere uma nova API Key para o ambiente de produção. --- ## Autenticação Todos os endpoints utilizam autenticação via **API Key** enviada no header `x-api-key`. Para maior segurança, você pode configurar **domínios e IPs permitidos** na página de Integração, restringindo de onde suas requisições podem ser feitas. ## Escopos da API Key Ao criar uma API Key, você pode restringi-la a funcionalidades específicas (escopos). Por exemplo, uma chave usada apenas para receber pagamentos pode ter acesso somente a `PIX_IN` e `CHECKOUT`. | Escopo | Acesso liberado | |--------|-----------------| | `PIX_IN` | Cobranças PIX (criar, consultar, efetivar homologação) | | `PIX_OUT` | Saques PIX (criar, consultar) | | `BOLETO` | Cobranças por boleto (emitir, consultar, cancelar, segunda via, efetivar homologação) | | `CHECKOUT` | Links de pagamento / checkout (criar, consultar) | | `WALLET` | Consulta de saldo da carteira | | `PRODUCTS` | Catálogo de produtos (criar, listar, consultar, atualizar) | | `WEBHOOKS` | Endpoints de webhook (criar, listar, atualizar, remover, rotacionar a credencial), entregas e reenvio | > Se nenhum escopo for selecionado, a chave tem **acesso total** a todas as funcionalidades. Chaves criadas antes desta funcionalidade continuam com acesso total (retrocompatível). > Os escopos são por funcionalidade, não por leitura ou escrita: quem consulta saques (`PIX_OUT`) também pode criá-los. Só `WALLET` é apenas leitura. Para uma integração ou um agente de IA que não deve sacar, não inclua `PIX_OUT`. Uma requisição feita com uma chave que não possui o escopo necessário retorna **HTTP 403**. --- ## Formato das Respostas Todas as respostas seguem um formato padrão. **Sucesso:** ```json { "message": "Mensagem descritiva", "response": { ... } } ``` **Erro:** ```json { "response": null, "errors": ["Descrição do erro"] } ``` - name: Webhooks description: >- O Alpha Gateway notifica seu sistema automaticamente quando eventos importantes acontecem — como a confirmação de um pagamento ou a conclusão de um saque. ## Como configurar 1. Acesse a página de **Integração** no painel (ou use as rotas de **Webhooks - Endpoints**, com uma API Key de escopo `WEBHOOKS`) 2. Crie um **Endpoint de Webhook** informando a URL pública do seu servidor e selecionando os eventos que deseja receber 3. Copie a **credencial** exibida na criação (mostrada apenas uma vez) — ela é usada para validar a assinatura HMAC 4. Seu servidor deve responder com um status **2xx** (ex.: 200) para confirmar o recebimento. Redirecionamento (3xx) não é seguido e conta como falha: cadastre a URL final 5. Em caso de falha, o sistema realiza novas tentativas de reenvio com backoff exponencial > Você pode cadastrar vários endpoints. Cada um recebe apenas os eventos que assina e possui sua própria credencial. Um mesmo evento é entregue a todos os endpoints que o assinam. ## Eventos disponíveis Ao criar ou atualizar um endpoint, assine pelo **valor** (coluna 1). O payload enviado identifica o evento pelo campo `event` (coluna 4) junto com o `status`; o nome legível (coluna 2) aparece só na lista de eventos e nas entregas. | Valor para assinar | Nome | Quando é disparado | `event` no payload | |--------------------|------|--------------------|--------------------| | `PIX_IN_PAYED` | `pix_in.paid` | Cobrança PIX paga | `PIX_IN_UPDATE` (`status` `PAYED`) | | `PIX_IN_REFUNDED` | `pix_in.refunded` | Cada devolução de uma cobrança PIX ao pagador: parcial (`PARTIALLY_REFUNDED`) ou a que completa o valor (`REFUNDED`) | `PIX_IN_UPDATE` | | `PIX_OUT_ANALYSIS` | `pix_out.analysis` | Saque solicitado (em análise) | `PIX_OUT_UPDATE` (`status` `ANALYSIS`) | | `PIX_OUT_PAID` | `pix_out.paid` | Saque confirmado | `PIX_OUT_UPDATE` (`status` `PAID`) | | `PIX_OUT_REJECTED` | `pix_out.rejected` | Saque rejeitado | `PIX_OUT_UPDATE` (`status` `REJECTED`) | | `PIX_OUT_ERROR` | `pix_out.error` | Erro no processamento do saque | `PIX_OUT_UPDATE` (`status` `ERROR`) | | `PIX_OUT_REFUNDED` | `pix_out.refunded` | Cada devolução de um saque pelo recebedor ou pelo banco dele: parcial (`PARTIALLY_REFUNDED`) ou a que completa o valor (`REFUNDED`) | `PIX_OUT_UPDATE` | | `CHECKOUT_PAID` | `checkout.paid` | Checkout / link de pagamento pago | `CHECKOUT_UPDATE` | | `CHECKOUT_CANCELED` | `checkout.canceled` | Checkout cancelado | `CHECKOUT_UPDATE` | | `CHECKOUT_REJECTED` | `checkout.rejected` | Pagamento com cartão recusado | `CHECKOUT_UPDATE` | | `CHECKOUT_REFUNDED` | `checkout.refunded` | Pagamento com cartão estornado | `CHECKOUT_UPDATE` | | `BOLETO_CREATED` | `boleto.created` | Boleto gerado | `BOLETO_UPDATE` | | `BOLETO_PAID` | `boleto.paid` | Boleto pago | `BOLETO_UPDATE` | | `BOLETO_CANCELED` | `boleto.canceled` | Boleto cancelado / baixado | `BOLETO_UPDATE` | | `BOLETO_REFUNDED` | `boleto.refunded` | Boleto estornado após pagamento | `BOLETO_UPDATE` | | `INVOICE_INSTALLMENT_PAID` | `invoice.installment_paid` | Parcela de fatura paga (ainda há parcelas em aberto) | `INVOICE_INSTALLMENT_PAID` | | `INVOICE_FULLY_PAID` | `invoice.fully_paid` | Fatura totalmente paga (última parcela quitada) | `INVOICE_FULLY_PAID` | | `INVOICE_INSTALLMENT_OVERDUE` | `invoice.installment_overdue` | Parcela de fatura vencida (passou da data de vencimento sem pagamento) | `INVOICE_INSTALLMENT_OVERDUE` | | `INVOICE_INSTALLMENT_CHARGE_FAILED` | `invoice.installment_charge_failed` | Cobrança automática da parcela no cartão falhou | `INVOICE_INSTALLMENT_CHARGE_FAILED` | | `INFRACTION_OPENED` | `infraction.opened` | Infração (MED PIX) aberta — saldo bloqueado | `INFRACTION_UPDATE` | | `INFRACTION_RESOLVED` | `infraction.resolved` | Infração (MED PIX) resolvida — saldo liberado ou debitado | `INFRACTION_UPDATE` | ## Segurança — Assinatura HMAC Toda requisição de webhook inclui o header `Alpha-Signature` para você verificar a autenticidade e a integridade do payload: ``` Alpha-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd ``` - `t` — timestamp Unix (segundos) de quando a notificação foi assinada - `v1` — HMAC-SHA256, em hexadecimal, da string `{t}.{corpo_bruto_da_requisição}` usando a **credencial do endpoint** como chave Para validar: recalcule o HMAC-SHA256 de `{t}.{corpo_bruto}` com a credencial do endpoint e compare com `v1` usando comparação de tempo constante. Rejeite se o timestamp `t` estiver fora de uma janela de tolerância (ex: 300 segundos). > Use o **corpo bruto (raw)** da requisição na verificação, não o JSON re-serializado. > Compatibilidade: integrações que usavam a configuração antiga (header `X-Webhook-Secret`) continuam funcionando — esse header ainda é enviado quando há uma credencial configurada. O `Alpha-Signature` é adicional e recomendado. --- ## Webhook de Cobrança (`PIX_IN_UPDATE`) Enviado quando uma cobrança PIX é paga (`PAYED`) e a cada devolução ao pagador: `PARTIALLY_REFUNDED` enquanto a soma das devoluções não chega ao valor do PIX e `REFUNDED` na devolução que completa (veja **Devoluções no webhook**). | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `PIX_IN_UPDATE` | | `method` | `string` | Sempre `PIX_IN` | | `status` | `string` | `PAYED`, `PARTIALLY_REFUNDED` ou `REFUNDED` | | `transactionId` | `string` | ID da transação no Alpha Gateway | | `idempotency` | `string` | Chave de idempotência enviada na criação | | `payer` | `object` | Dados do pagador (quando disponível) | | `payer.fullname` | `string` | Nome do pagador | | `payer.document` | `string` | CPF ou CNPJ do pagador | | `pix` | `object` | Detalhes do PIX | | `pix.endToEndId` | `string` | Identificador end-to-end do PIX | | `pix.txid` | `string` | ID da transação PIX | | `pix.value` | `string` | Valor pago | | `pix.devolutions` | `array` | Sempre vazio no pagamento (mantido por compatibilidade); as devoluções vêm em `devolutions` no evento `REFUNDED` | | `refundedAmount` | `number` | Total devolvido ao pagador até esta devolução (apenas nas devoluções) | | `devolutionSummary` | `object` | Resumo: `originalAmount` (valor do PIX), `refundedAmount` (devolvido), `pendingAmount` (sempre 0 na cobrança) e `remainingAmount` (o que falta devolver) (apenas nas devoluções) | | `devolutions` | `array` | Todas as devoluções do PIX até esta, em ordem (apenas nas devoluções) | | `partial` | `boolean` | `true` em devolução parcial; `false` na que completa o valor (apenas nas devoluções) | | `devolution` | `object` | A devolução que gerou este evento: `id`, `endToEndId`, `amount`, `refundedAt` e `medRefund` (apenas nas devoluções) | | `devolution.medRefund` | `boolean` | `true` quando a devolução é o reembolso de uma infração (MED PIX) já resolvida com reembolso: o valor já tinha saído do seu saldo pela infração, então não desconte de novo | | `devolutions[].id` | `string` | ID da devolução no Alpha Gateway | | `devolutions[].endToEndId` | `string` | Identificador end-to-end da devolução | | `devolutions[].amount` | `number` | Valor devolvido nesta devolução | | `devolutions[].refundedAt` | `string` | Data e hora da devolução (ISO 8601) | **Exemplo — Pagamento confirmado:** ```json { "event": "PIX_IN_UPDATE", "method": "PIX_IN", "status": "PAYED", "transactionId": "01961234-abcd-7000-8000-000000000001", "idempotency": "pedido-12345", "payer": { "fullname": "João da Silva", "document": "12345678900" }, "pix": { "endToEndId": "E12345678202301011200abcdefghijkl", "txid": "txid-unico-gerado", "value": "150.00", "devolutions": [] } } ``` **Exemplo — Segunda de duas devoluções, a que completa o valor:** ```json { "event": "PIX_IN_UPDATE", "method": "PIX_IN", "status": "REFUNDED", "partial": false, "transactionId": "01961234-abcd-7000-8000-000000000001", "idempotency": "pedido-12345", "payer": { "fullname": "João da Silva", "document": "12345678900" }, "pix": { "endToEndId": "E12345678202301011200abcdefghijkl", "txid": "txid-unico-gerado", "value": "150.00" }, "refundedAmount": 150.00, "devolutionSummary": { "originalAmount": 150.00, "refundedAmount": 150.00, "pendingAmount": 0, "remainingAmount": 0 }, "devolution": { "id": "01961234-abcd-7000-8000-0000000000d2", "endToEndId": "D12345678202501161000abcdefghijk", "amount": 100.00, "refundedAt": "2025-01-16T10:00:00.000Z", "medRefund": false }, "devolutions": [ { "id": "01961234-abcd-7000-8000-0000000000d1", "endToEndId": "D12345678202501151430abcdefghijk", "amount": 50.00, "refundedAt": "2025-01-15T14:30:00.000Z" }, { "id": "01961234-abcd-7000-8000-0000000000d2", "endToEndId": "D12345678202501161000abcdefghijk", "amount": 100.00, "refundedAt": "2025-01-16T10:00:00.000Z" } ] } ``` --- ## Webhook de Saque (`PIX_OUT_UPDATE`) Enviado quando o status de um saque é atualizado e a cada devolução pelo recebedor: `PARTIALLY_REFUNDED` enquanto a soma das devoluções não chega ao valor do saque e `REFUNDED` na devolução que completa (veja **Devoluções no webhook**). | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `PIX_OUT_UPDATE` | | `method` | `string` | Sempre `PIX_OUT` | | `status` | `string` | `PAID`, `REJECTED`, `ERROR`, `PARTIALLY_REFUNDED` ou `REFUNDED` | | `transactionId` | `string` | ID da transação no Alpha Gateway | | `idempotency` | `string` | Chave de idempotência enviada na criação | | `value` | `number` | Valor solicitado | | `valueFee` | `number` | Taxa cobrada | | `valueLiquid` | `number` | Total debitado do seu saldo (valor + taxa); o destinatário recebe `value` | | `destination.pixKey` | `string` | Chave PIX de destino | | `destination.pixType` | `string` | Tipo da chave: `DOCUMENT`, `EMAIL`, `PHONE` ou `RANDOM` | | `customer.fullName` | `string` | Nome do beneficiário | | `customer.document` | `string` | CPF ou CNPJ do beneficiário | | `endToEndId` | `string` | Identificador end-to-end (quando disponível) | | `messageError` | `string` | Mensagem de erro (apenas para `REJECTED` e `ERROR`) | | `refundedAmount` | `number` | Total devolvido pelo recebedor até esta devolução e creditado no saldo (apenas nas devoluções; a taxa não é devolvida) | | `devolutionSummary` | `object` | Resumo: `originalAmount` (valor do saque), `refundedAmount` (devolvido), `pendingAmount` (devolvido antes da confirmação e ainda não creditado) e `remainingAmount` (apenas nas devoluções) | | `devolutions` | `array` | Todas as devoluções do saque até esta, em ordem, com `id`, `endToEndId`, `amount` e `refundedAt` (apenas nas devoluções) | | `partial` | `boolean` | `true` em devolução parcial; `false` na que completa o valor (apenas nas devoluções) | | `devolution` | `object` | A devolução que gerou este evento: `id`, `endToEndId`, `amount` e `refundedAt` (apenas nas devoluções) | **Exemplo — Saque confirmado:** ```json { "event": "PIX_OUT_UPDATE", "method": "PIX_OUT", "status": "PAID", "transactionId": "01961234-abcd-7000-8000-000000000002", "idempotency": "saque-67890", "value": 100.00, "valueFee": 2.50, "valueLiquid": 102.50, "destination": { "pixKey": "12345678900", "pixType": "DOCUMENT" }, "customer": { "fullName": "Maria Oliveira", "document": "12345678900" }, "endToEndId": "E12345678202301011200abcdefghijkl" } ``` **Exemplo — Saque rejeitado:** ```json { "event": "PIX_OUT_UPDATE", "method": "PIX_OUT", "status": "REJECTED", "transactionId": "01961234-abcd-7000-8000-000000000002", "idempotency": "saque-67890", "value": 100.00, "valueFee": 2.50, "valueLiquid": 102.50, "destination": { "pixKey": "12345678900", "pixType": "DOCUMENT" }, "customer": { "fullName": "Maria Oliveira", "document": "12345678900" }, "messageError": "Chave PIX de destino inválida" } ``` **Exemplo — Saque devolvido por completo pelo recebedor (uma única devolução do valor total):** ```json { "event": "PIX_OUT_UPDATE", "method": "PIX_OUT", "status": "REFUNDED", "partial": false, "transactionId": "01961234-abcd-7000-8000-000000000002", "idempotency": "saque-67890", "value": 100.00, "valueFee": 2.50, "valueLiquid": 102.50, "destination": { "pixKey": "12345678900", "pixType": "DOCUMENT" }, "customer": { "fullName": "Maria Oliveira", "document": "12345678900" }, "endToEndId": "E12345678202301011200abcdefghijkl", "refundedAmount": 100.00, "devolutionSummary": { "originalAmount": 100.00, "refundedAmount": 100.00, "pendingAmount": 0, "remainingAmount": 0 }, "devolution": { "id": "01961234-abcd-7000-8000-0000000000d3", "endToEndId": "D98765432202501171200abcdefghijk", "amount": 100.00, "refundedAt": "2025-01-17T12:00:00.000Z" }, "devolutions": [ { "id": "01961234-abcd-7000-8000-0000000000d3", "endToEndId": "D98765432202501171200abcdefghijk", "amount": 100.00, "refundedAt": "2025-01-17T12:00:00.000Z" } ] } ``` --- ## Devoluções no webhook Cada devolução concluída no banco gera **um** webhook no mesmo evento de estorno (`pix_in.refunded` na cobrança, `pix_out.refunded` no saque), com o acumulado até ela: | Situação | `status` | `partial` | Status da transação depois | |----------|----------|-----------|----------------------------| | Devolução parcial (a soma ainda não chega ao valor) | `PARTIALLY_REFUNDED` | `true` | continua `PAID` | | Devolução que completa o valor | `REFUNDED` | `false` | `REFUNDED` | Por exemplo, um saque de R$ 100,00 devolvido em R$ 30,00, R$ 20,00 e R$ 50,00 gera três webhooks `pix_out.refunded`: `PARTIALLY_REFUNDED` com `refundedAmount` 30,00, `PARTIALLY_REFUNDED` com 50,00 e `REFUNDED` com 100,00. - Use `devolution.id` para não processar a mesma devolução duas vezes em caso de reenvio. - Considere a cobrança ou o saque devolvido por completo só quando `status` for `REFUNDED` (`partial: false`). - Saque devolvido antes da confirmação do pagamento: a devolução é avisada logo depois do `pix_out.paid`. **Exemplo — Saque de R$ 100,00: primeira devolução parcial (R$ 30,00):** ```json { "event": "PIX_OUT_UPDATE", "method": "PIX_OUT", "status": "PARTIALLY_REFUNDED", "partial": true, "transactionId": "01961234-abcd-7000-8000-000000000002", "idempotency": "saque-67890", "value": 100.00, "valueFee": 2.50, "valueLiquid": 102.50, "destination": { "pixKey": "12345678900", "pixType": "DOCUMENT" }, "customer": { "fullName": "Maria Oliveira", "document": "12345678900" }, "endToEndId": "E12345678202301011200abcdefghijkl", "refundedAmount": 30.00, "devolutionSummary": { "originalAmount": 100.00, "refundedAmount": 30.00, "pendingAmount": 0, "remainingAmount": 70.00 }, "devolution": { "id": "01961234-abcd-7000-8000-0000000000d1", "endToEndId": "D98765432202501171200abcdefghij1", "amount": 30.00, "refundedAt": "2025-01-17T12:00:00.000Z" }, "devolutions": [ { "id": "01961234-abcd-7000-8000-0000000000d1", "endToEndId": "D98765432202501171200abcdefghij1", "amount": 30.00, "refundedAt": "2025-01-17T12:00:00.000Z" } ] } ``` --- ## Webhook de Checkout (`CHECKOUT_UPDATE`) Enviado quando um pagamento via checkout ou link de pagamento é confirmado. | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `CHECKOUT_UPDATE` | | `status` | `string` | `PAID` | | `paymentMethod` | `string` | Método de pagamento utilizado (ex: `PIX`) | | `checkoutId` | `string` | ID do checkout | | `transactionId` | `string` | ID da transação no Alpha Gateway | | `value` | `number` | Valor pago | | `customer.fullName` | `string` | Nome do cliente | | `customer.document` | `string` | CPF ou CNPJ do cliente | | `products` | `array` | Lista de produtos do checkout | | `products[].externalId` | `string` | Identificador externo do produto | | `products[].name` | `string` | Nome do produto | | `products[].value` | `number` | Valor unitário do produto | | `products[].quantity` | `number` | Quantidade | | `paidAt` | `string` | Data e hora do pagamento (ISO 8601) | **Exemplo:** ```json { "event": "CHECKOUT_UPDATE", "status": "PAID", "paymentMethod": "PIX", "checkoutId": "01961234-abcd-7000-8000-000000000003", "transactionId": "01961234-abcd-7000-8000-000000000004", "value": 149.90, "customer": { "fullName": "Carlos Santos", "document": "98765432100" }, "products": [ { "externalId": "SKU-001", "name": "Camiseta Premium", "value": 49.90, "quantity": 1 }, { "externalId": "SKU-002", "name": "Boné Personalizado", "value": 100.00, "quantity": 1 } ], "paidAt": "2025-03-08T15:30:00.000Z" } ``` --- ## Webhook de Boleto (`BOLETO_UPDATE`) Enviado quando o status de um boleto é atualizado. Assine os eventos `boleto.paid`, `boleto.canceled` e `boleto.refunded` para receber estas notificações. | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `BOLETO_UPDATE` | | `method` | `string` | Sempre `BOLETO` | | `status` | `string` | `PAID`, `CANCELED` ou `REFUNDED` | | `transactionId` | `string` | ID da transação no Alpha Gateway | | `idempotency` | `string` | Chave de idempotência enviada na criação | | `value` | `number` | Valor solicitado | | `valueFee` | `number` | Taxa cobrada | | `valueLiquid` | `number` | Valor líquido | | `boleto.barcode` | `string` | Código de barras (quando disponível) | | `boleto.linhaDigitavel` | `string` | Linha digitável (quando disponível) | | `boleto.qrcode` | `string` | QR Code PIX do boleto (quando disponível) | | `boleto.dueDate` | `string` | Data de vencimento (quando disponível) | | `boleto.payment` | `object` | Dados do pagamento (apenas quando `status` = `PAID`) | | `boleto.payment.paidValue` | `number` | Valor efetivamente pago | | `boleto.payment.paidAt` | `string` | Data e hora do pagamento (ISO 8601) | | `boleto.payment.receiptUrl` | `string` | URL do comprovante (quando disponível) | | `payer.fullName` | `string` | Nome do pagador (quando disponível) | | `payer.document` | `string` | CPF ou CNPJ do pagador (quando disponível) | **Exemplo — Boleto pago:** ```json { "event": "BOLETO_UPDATE", "method": "BOLETO", "status": "PAID", "transactionId": "01961234-abcd-7000-8000-000000000010", "idempotency": "boleto-12345", "value": 150.00, "valueFee": 3.50, "valueLiquid": 146.50, "boleto": { "barcode": "34191790010104351004791020150008998770000015000", "linhaDigitavel": "34191.79001 01043.510047 91020.150008 9 98770000015000", "qrcode": "00020126580014br.gov.bcb.pix...", "dueDate": "2025-04-10", "payment": { "paidValue": 150.00, "paidAt": "2025-04-08T13:20:00.000Z", "receiptUrl": "https://.../comprovante.pdf" } }, "payer": { "fullName": "João da Silva", "document": "12345678900" } } ``` **Exemplo — Boleto estornado:** ```json { "event": "BOLETO_UPDATE", "method": "BOLETO", "status": "REFUNDED", "transactionId": "01961234-abcd-7000-8000-000000000010", "idempotency": "boleto-12345", "value": 150.00, "valueFee": 3.50, "valueLiquid": 146.50, "boleto": { "barcode": "34191790010104351004791020150008998770000015000", "linhaDigitavel": "34191.79001 01043.510047 91020.150008 9 98770000015000", "qrcode": null, "dueDate": "2025-04-10", "payment": null }, "payer": { "fullName": "João da Silva", "document": "12345678900" } } ``` --- ## Webhook de Fatura (`INVOICE_INSTALLMENT_PAID` / `INVOICE_FULLY_PAID`) Enviado quando uma parcela de fatura é paga via PIX no link de pagamento da parcela. Enquanto restarem parcelas em aberto, o evento é `INVOICE_INSTALLMENT_PAID`. Quando a parcela paga é a última em aberto, a fatura é totalmente quitada e o evento passa a ser `INVOICE_FULLY_PAID`. Assine os eventos `invoice.installment_paid` e `invoice.fully_paid` para receber estas notificações. | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | `INVOICE_INSTALLMENT_PAID` (há parcelas em aberto) ou `INVOICE_FULLY_PAID` (fatura quitada) | | `invoiceId` | `string` | ID da fatura | | `installmentId` | `string` | ID da parcela paga | | `installmentNumber` | `number` | Número da parcela paga (1, 2, 3...) | | `transactionId` | `string` | ID da transação PIX que pagou a parcela | | `value` | `number` | Valor pago (em reais) | | `paidAt` | `string` | Data e hora do pagamento (ISO 8601) | **Exemplo — Parcela paga (ainda há parcelas em aberto):** ```json { "event": "INVOICE_INSTALLMENT_PAID", "invoiceId": "01961234-abcd-7000-8000-000000000006", "installmentId": "01961234-abcd-7000-8000-000000000007", "installmentNumber": 1, "transactionId": "01961234-abcd-7000-8000-000000000008", "value": 100.50, "paidAt": "2025-03-08T15:30:00.000Z" } ``` **Exemplo — Fatura totalmente paga (última parcela):** ```json { "event": "INVOICE_FULLY_PAID", "invoiceId": "01961234-abcd-7000-8000-000000000006", "installmentId": "01961234-abcd-7000-8000-000000000009", "installmentNumber": 3, "transactionId": "01961234-abcd-7000-8000-00000000000a", "value": 100.50, "paidAt": "2025-03-08T15:30:00.000Z" } ``` > **Pagamento duplicado:** se uma parcela já quitada receber um novo pagamento (por exemplo, um PIX feito a partir de um link antigo), o valor é registrado como pagamento duplicado na parcela para conferência no painel, mas **nenhum evento de webhook é enviado** — o evento é disparado apenas no pagamento que efetivamente quita a parcela. ### Parcela vencida (`INVOICE_INSTALLMENT_OVERDUE`) Enviado quando uma parcela ultrapassa a data de vencimento sem pagamento. A verificação ocorre automaticamente em horário comercial. Assine o evento `invoice.installment_overdue` para receber esta notificação. Este payload não possui `transactionId`, pois a parcela ainda não foi paga. | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `INVOICE_INSTALLMENT_OVERDUE` | | `invoiceId` | `string` | ID da fatura | | `installmentId` | `string` | ID da parcela vencida | | `installmentNumber` | `number` | Número da parcela vencida | | `installmentCount` | `number` | Total de parcelas da fatura | | `value` | `number` | Valor da parcela (em reais) | | `dueDate` | `string` | Data de vencimento (ISO 8601) | **Exemplo:** ```json { "event": "INVOICE_INSTALLMENT_OVERDUE", "invoiceId": "01961234-abcd-7000-8000-000000000006", "installmentId": "01961234-abcd-7000-8000-000000000007", "installmentNumber": 1, "installmentCount": 3, "value": 100.50, "dueDate": "2025-03-05T00:00:00.000Z" } ``` --- ## Webhook de Infração / MED PIX (`INFRACTION_UPDATE`) Enviado quando o pagador de um PIX recebido abre uma contestação (MED PIX). Ao abrir a infração, o valor contestado é bloqueado temporariamente do saldo disponível até a resolução. Na resolução, o valor é liberado de volta (a favor do recebedor) ou debitado definitivamente (reembolso ao pagador). Assine os eventos `infraction.opened` e `infraction.resolved` para receber estas notificações. | Campo | Tipo | Descrição | |-------|------|-----------| | `event` | `string` | Sempre `INFRACTION_UPDATE` | | `method` | `string` | Sempre `INFRACTION` | | `status` | `string` | `LOCKED`, `UNDER_ANALYSIS`, `RESOLVED_FAVORABLE`, `RESOLVED_REFUNDED` ou `CANCELLED` | | `infractionId` | `string` | ID da infração no Alpha Gateway | | `externalId` | `string` | ID da infração no banco emissor | | `endToEndId` | `string` | Identificador end-to-end do PIX original em disputa | | `amount` | `number` | Valor contestado (em reais) | | `lockedAmount` | `number` | Valor efetivamente bloqueado do saldo (apenas na abertura) | | `deficitAmount` | `number` | Parte não bloqueada por saldo insuficiente, a recuperar (apenas na abertura) | | `splitLockedAmount` | `number` | Parte do valor contestado bloqueada das carteiras dos beneficiários do split da transação; `amount` = `lockedAmount` + `deficitAmount` + `splitLockedAmount` (apenas na abertura) | | `reason` | `string` | Motivo da contestação (quando disponível) | | `dueDate` | `string` | Prazo para análise, ISO 8601 (quando disponível) | | `payer.name` | `string` | Nome do pagador que contestou (apenas na abertura) | | `payer.taxId` | `string` | CPF ou CNPJ do pagador (apenas na abertura) | | `resolvedAt` | `string` | Data e hora da resolução, ISO 8601 (apenas na resolução) | ### Significado de cada `status` | Status | Significado | |--------|-------------| | `LOCKED` | Infração aberta. O valor contestado foi bloqueado do seu saldo disponível e permanece retido até a resolução. | | `UNDER_ANALYSIS` | Infração em análise pela instituição. O valor segue bloqueado enquanto a contestação é avaliada. | | `RESOLVED_FAVORABLE` | Resolvida a seu favor — a contestação foi recusada. O valor bloqueado é liberado de volta para o saldo disponível. | | `RESOLVED_REFUNDED` | Resolvida com reembolso ao pagador — a contestação foi aceita. O valor bloqueado é debitado definitivamente do seu saldo. | | `CANCELLED` | Infração cancelada pela instituição. Nenhum valor é retido e qualquer bloqueio existente é liberado. | **Exemplo — Infração aberta (`infraction.opened`):** ```json { "event": "INFRACTION_UPDATE", "method": "INFRACTION", "status": "LOCKED", "infractionId": "01961234-abcd-7000-8000-000000000005", "externalId": "1eff300e-c113-6a7e-a8e4-f8c7d2c22fce", "endToEndId": "E12345678202301011200abcdefghijkl", "amount": 150.00, "lockedAmount": 150.00, "deficitAmount": 0, "splitLockedAmount": 0, "reason": "scam", "dueDate": "2025-03-12T23:59:00.000Z", "payer": { "name": "João da Silva", "taxId": "12345678900" } } ``` **Exemplo — Infração resolvida (`infraction.resolved`):** ```json { "event": "INFRACTION_UPDATE", "method": "INFRACTION", "status": "RESOLVED_FAVORABLE", "infractionId": "01961234-abcd-7000-8000-000000000005", "externalId": "1eff300e-c113-6a7e-a8e4-f8c7d2c22fce", "endToEndId": "E12345678202301011200abcdefghijkl", "amount": 150.00, "resolvedAt": "2025-03-10T11:30:00.000Z" } ``` paths: /v1/products/create: post: tags: - Produtos summary: Criar produto description: >- Cadastra um novo produto no catálogo da organização. O `externalId` pode ser informado ou será gerado automaticamente. operationId: createProduct requestBody: content: application/json: schema: type: object properties: externalId: type: string description: >- Identificador do produto na sua aplicação (opcional; gerado automaticamente se omitido). Único por organização. name: type: string maxLength: 100 description: Nome do produto (até 100 caracteres). description: type: string maxLength: 500 description: Descrição do produto (opcional, até 500 caracteres). value: type: number exclusiveMinimum: true minimum: 0 description: 'Valor unitário em reais (ex.: 49.90).' required: - name - value additionalProperties: false example: externalId: plano-mensal name: Plano Mensal description: Assinatura mensal do serviço value: 49.9 required: true responses: '200': description: Requisição processada com sucesso content: application/json: schema: type: object properties: response: type: object properties: externalId: type: string description: Identificador do produto na sua aplicação. name: type: string description: Nome do produto. description: type: string nullable: true description: Descrição do produto, ou null. value: type: number description: Valor unitário do produto, em reais. createdAt: type: string description: Data de cadastro (ISO 8601). required: - externalId - name - description - value - createdAt additionalProperties: false description: >- Dados retornados pela operação; null quando não há conteúdo. message: type: string description: Mensagem que descreve o resultado. required: - response - message additionalProperties: false description: Requisição processada com sucesso example: message: Produto criado com sucesso response: externalId: plano-mensal name: Plano Mensal description: Assinatura mensal do serviço value: 49.9 createdAt: '2026-10-22T13:00:00.000Z' '400': description: >- Requisição inválida: campo ausente ou fora do formato, regra de negócio recusada, funcionalidade não habilitada para a organização ou `idempotency` já usado. Se `errors` disser que o `idempotency` já existe, a operação JÁ FOI CRIADA: consulte-a pelo mesmo `idempotency` e não gere outro. Nos demais casos, corrija conforme `errors` antes de tentar de novo. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - O valor da transação deve ser maior ou igual a R$1,00 '401': description: API Key ausente, inválida ou expirada no header `x-api-key`. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - API key inválida ou expirada '403': description: >- A API Key não tem o escopo desta funcionalidade, a origem (domínio ou IP) não está autorizada para a chave ou a organização está bloqueada. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - >- Credencial não possui permissão para esta funcionalidade, ajuste o escopo da credencial. '409': description: >- Conflito: o identificador informado (`idempotency` ou `externalId`) já está em uso na organização. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - Já existe um link de pagamento com este idempotency '429': description: >- Limite de requisições da API Key excedido. Aguarde alguns segundos e tente de novo. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - Limite de requisições excedido '500': description: >- Erro inesperado. Antes de repetir uma criação, consulte a operação pelo mesmo `idempotency`: se ela já existir, não crie outra. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - Erro interno '503': description: Serviço em manutenção programada. Tente de novo mais tarde. content: application/json: schema: type: object properties: response: nullable: true default: null description: Sempre null em respostas de erro. errors: type: array items: type: string default: [] description: Mensagens que explicam o erro. additionalProperties: false description: Ocorreu um erro ao processar a requisição example: response: null errors: - >- Este serviço está temporariamente indisponível devido a manutenção security: - x-api-key: [] components: securitySchemes: x-api-key: type: apiKey in: header name: x-api-key description: API Key da organização ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.