{ "info": { "name": "Appmax API", "description": "Coleção da API da Appmax, organizada por recurso.\n\n**Como usar**\n1. Nas variáveis da coleção, preencha `client_id` e `client_secret` com as credenciais da loja (tela **API** do painel).\n2. Rode **Autenticação → Gerar access token**. O token é salvo em `access_token` e usado por todos os requests.\n3. Os valores padrão apontam para o **Sandbox**. Para Produção, troque `base_url` por `https://api.appmax.com.br` e `auth_url` por `https://auth.appmax.com.br/oauth2/token`.\n\nNunca compartilhe a coleção com o `client_secret` preenchido. Documentação: https://docs.appmax.com.br", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{access_token}}", "type": "string" } ] }, "item": [ { "name": "Autenticação", "item": [ { "name": "Gerar access token", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Guarda o token na coleção: os demais requests já usam {{access_token}}.", "const { access_token } = pm.response.json();", "if (access_token) pm.collectionVariables.set(\"access_token\", access_token);" ] } } ], "request": { "auth": { "type": "noauth" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "grant_type", "value": "client_credentials" }, { "key": "client_id", "value": "{{client_id}}" }, { "key": "client_secret", "value": "{{client_secret}}" } ] }, "url": { "raw": "{{auth_url}}", "host": [ "{{auth_url}}" ] }, "description": "Troca o Client ID e o Client Secret da loja por um access token (OAuth 2.0 client credentials). O token vale 1 hora e não há refresh token: quando expirar, rode este request de novo." } } ] }, { "name": "Clientes", "item": [ { "name": "Criar ou atualizar cliente", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Junior\",\n \"last_name\": \"Almeida\",\n \"email\": \"junior.almeida@email.com\",\n \"phone\": \"51983655100\",\n \"document_number\": \"25226493029\",\n \"address\": {\n \"postcode\": \"91520270\",\n \"street\": \"Rua Francisco Carneiro da Rocha\",\n \"number\": \"582\",\n \"complement\": \"Casa\",\n \"district\": \"Moinhos de Ventos\",\n \"city\": \"Porto Alegre\",\n \"state\": \"RS\"\n },\n \"ip\": \"127.0.0.1\",\n \"products\": [\n {\n \"sku\": \"9000010\",\n \"name\": \"Livro de receitas\",\n \"quantity\": 1,\n \"unit_value\": 12300,\n \"type\": \"digital\"\n }\n ],\n \"tracking\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"teste\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/customers", "host": [ "{{base_url}}" ], "path": [ "v1", "customers" ] }, "description": "Cria ou atualiza um cliente identificado pela combinação\n`first_name + last_name + email + phone + ip`.\n\n::: warning\nPara criar um cliente, você precisa ter feito a coleta de IP utilizando\no script [Appmax JS](/guides/appmax-js).\n:::\n\n::: tip\nSe enviar apenas os campos obrigatórios, o cliente será registrado como\n\"carrinho abandonado\" e pode ser atualizado depois pela mesma rota.\n:::" } } ] }, { "name": "Pedidos", "item": [ { "name": "Criar um pedido", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"customer_id\": 29,\n \"products_value\": 12300,\n \"discount_value\": 0,\n \"shipping_value\": 3999,\n \"products\": [\n {\n \"sku\": \"9000010\",\n \"name\": \"Livro de receitas\",\n \"quantity\": 1,\n \"unit_value\": 12300,\n \"type\": \"digital\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders", "host": [ "{{base_url}}" ], "path": [ "v1", "orders" ] }, "description": "Cria um novo pedido na Appmax. Um pedido deve estar sempre vinculado a um\ncliente previamente criado.\n\n::: warning Pré-requisito\nPara criar um pedido, você precisa ter o `customer_id` do cliente. Caso\nainda não tenha, veja\n[Criar ou atualizar cliente](/api-reference/customers/criar-atualizar).\n:::\n\nArmazene o `order_id` retornado, pois ele será necessário para efetuar o\npagamento ou consultar o status do pedido. Para entender como o valor\ntotal é calculado, veja\n[Cálculo do valor total](/api-reference/orders/calculo-valor)." } }, { "name": "Consultar dados de um pedido", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/{{order_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "{{order_id}}" ] }, "description": "Consulta os detalhes de um pedido previamente criado para um merchant.\nBasta informar o ID do pedido na URL.\n\nVeja a [lista completa de status](/guides/status-pedidos) para entender\no campo `status` retornado." } }, { "name": "Criar um pedido unificado", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"customer\": {\n \"name\": \"Vegeta Príncipe\",\n \"email\": \"vegetaprincipe@email.com\",\n \"phones\": {\n \"mobile_phone\": {\n \"area_code\": \"11\",\n \"number\": \"988887777\"\n }\n }\n },\n \"ip\": \"1.2.3.4\",\n \"items\": [\n {\n \"amount\": 2000,\n \"description\": \"Chaveiro do Caneta\",\n \"quantity\": 2,\n \"code\": \"sku910\"\n }\n ],\n \"shipping\": {\n \"address\": {\n \"line_1\": \"Rua do Rei Vegeta, 999, Distrito Real\",\n \"line_2\": \"Palácio de Vegeta, Sala do Trono\",\n \"zip_code\": \"90265\",\n \"city\": \"Cidade Vegeta\",\n \"state\": \"BA\"\n },\n \"amount\": 1000\n },\n \"payments\": [\n {\n \"boleto\": {\n \"document_number\": \"19100000000\"\n },\n \"payment_method\": \"boleto\",\n \"split\": [\n {\n \"amount\": 1200,\n \"recipient_id\": \"72ccc884-edb6-5699-9eee-51ab34165e14\",\n \"refund_charge_percentage\": 0\n }\n ]\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/unified-order", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "unified-order" ] }, "description": "Permite criar pedidos completos em uma única requisição, centralizando\ndados do cliente, produtos, frete, pagamentos e split de pagamentos.\n\n**Responsabilidade da rota**\n\n- Receber payloads de pedido em formato unificado\n- Criar o cliente automaticamente quando *customer_id* não for informado\n- Criar a configuração de *split de pagamentos*\n- Validar estrutura e regras de negócio\n- Normalizar os dados para o modelo aceito pela Appmax\n- Encaminhar o pedido para o fluxo de cobrança\n\n**Métodos de pagamento suportados**\n\n| Método | Regras principais |\n|--------|-------------------|\n| Cartão de crédito | Exige *token* ou objeto *card* completo |\n| Pix | Exige *document_number* |\n| Boleto | Exige *document_number* |" } }, { "name": "Criar um pedido unificado flexível", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ip\": \"1.2.3.4\",\n \"items\": [\n {\n \"amount\": 2000,\n \"description\": \"Chaveiro do Caneta\",\n \"quantity\": 2,\n \"code\": \"sku910\"\n }\n ],\n \"payments\": [\n {\n \"payment_method\": \"pix\",\n \"split\": [\n {\n \"amount\": 1200,\n \"recipient_id\": \"72ccc884-edb6-5699-9eee-51ab34165e14\"\n }\n ]\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/unified-order/partner-flexible", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "unified-order", "partner-flexible" ] }, "description": "Permite criar pedidos completos em uma única requisição, centralizando\ndados do cliente, produtos, frete, pagamentos e split de pagamentos. Para\npagamentos via PIX, o customer pode ser opcional conforme configuração\ninterna.\n\n**Responsabilidade da rota**\n\n- Receber payloads de pedido em formato unificado\n- Resolver a identificação do cliente:\n - Utilizar customer_id quando informado\n - Criar um novo cliente quando apenas customer for informado\n - Em cenários de PIX com configuração habilitada, cria automaticamente um system customer (cliente com dados reaproveitados de um usuário vinculado ao site), tornando opcional customer, customer_id e document_number (pix).\n- Criar a configuração de *split de pagamentos*\n- Validar estrutura e regras de negócio\n- Normalizar os dados para o modelo aceito pela Appmax\n- Encaminhar o pedido para o fluxo de cobrança\n\n**Métodos de pagamento suportados**\n\n| Método | Regras principais |\n|--------|-------------------|\n| Cartão de crédito | Exige *token* ou objeto *card* completo |\n| Pix | Não exige o *document_number* quando a configuração de customer opcional estiver habilitada. |\n| Boleto | Exige *document_number* |" } }, { "name": "Total líquido do pedido", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/orders/total-liquid/{{order_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "total-liquid", "{{order_id}}" ] }, "description": "Retorna o detalhamento do valor líquido de um pedido (`order_id`),\nincluindo taxas, comissões e o total líquido a receber pelo produtor.\n\n**Autenticação:** header `secret` (API Gateway)." } }, { "name": "Cadastrar código de rastreio", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 2,\n \"shipping_tracking_code\": \"EEEASDASDAS1239A\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/shipping-tracking-code", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "shipping-tracking-code" ] }, "description": "Cadastra um código de rastreio em um pedido criado na Appmax.\n\n::: warning\nPara que os saques do merchant sejam aprovados, é necessário atualizar\no pedido com o código de rastreamento da entrega.\n:::" } }, { "name": "Criar um upsell", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"upsell_hash\": \"4000114202503117156088040208561001715608804\",\n \"products_value\": 12300,\n \"products\": [\n {\n \"sku\": \"9000010\",\n \"name\": \"Livro de receitas\",\n \"quantity\": 1,\n \"unit_value\": 12300,\n \"type\": \"digital\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/upsell", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "upsell" ] }, "description": "Cria um upsell vinculado a um pedido cujo pagamento já gerou o\n`upsell_hash` (retornado pelo pagamento por cartão de crédito)." } } ] }, { "name": "Pagamentos", "item": [ { "name": "Pagamento com cartão de crédito", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 12345,\n \"customer_id\": 407,\n \"payment_data\": {\n \"credit_card\": {\n \"token\": \"422146c7523a46119d6073ea56193913\",\n \"holder_document_number\": \"19100000000\",\n \"holder_name\": \"Teste teste\",\n \"installments\": 1,\n \"soft_descriptor\": \"MYSTORE\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/credit-card", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "credit-card" ] }, "description": "Cria um pagamento por cartão de crédito vinculado a um pedido existente.\nPermite parcelamento e personalização do soft descriptor.\n\n::: warning\nAntes de criar um pagamento, você precisa ter:\n- `order_id` — ID do pedido ([criar pedido](/api-reference/orders/criar-pedido))\n- `customer_id` — ID do cliente ([criar cliente](/api-reference/customers/criar-atualizar))\n:::\n\n::: info\nConsulte [Cálculo de parcelas](/api-reference/payments/parcelas) para\nobter os valores corretos com as taxas configuradas antes de enviar um\npagamento parcelado.\n:::" } }, { "name": "Pagamento via Pix", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 113,\n \"payment_data\": {\n \"pix\": {\n \"document_number\": \"19100000000\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/pix", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "pix" ] }, "description": "Gera as instruções de pagamento via Pix para um pedido existente:\nQR Code (imagem base64) e código EMV (copia-e-cola).\n\n::: tip Exiba um cronômetro de expiração\nNa página de sucesso, mostre o QR Code, o copia-e-cola e um cronômetro\ncom o tempo restante até `pix_expiration_date`. Calcule a contagem\nregressiva **dinamicamente a partir desse campo** — não fixe um tempo\nde expiração no seu código, pois esse valor pode variar.\n:::" } }, { "name": "Pagamento via boleto", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 113,\n \"payment_data\": {\n \"boleto\": {\n \"document_number\": \"19100000000\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/boleto", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "boleto" ] }, "description": "Cria um boleto bancário vinculado a um pedido existente. Retorna o link\ndo PDF e a linha digitável.\n\nO boleto é uma opção de pagamento **offline**: o cliente paga em um\nbanco, lotérica ou pelo internet banking, fora do seu checkout.\n\n::: tip Exiba o boleto na página de sucesso\nMostre a opção de baixar o PDF (`pdf_url`) e de copiar a linha\ndigitável (`digitable_line`) na página de sucesso, para que o cliente\npossa efetuar o pagamento pelo canal de sua preferência.\n:::\n\n::: warning Não abra o PDF em iframe\nO download do boleto (`pdf_url`) deve **redirecionar o cliente para\noutra página**, e não ser aberto embutido em um iframe na sua página\nde checkout/sucesso.\n:::" } }, { "name": "Pagamento com Apple Pay", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 123,\n \"customer_id\": 456,\n \"payment_data\": {\n \"apple_pay\": {\n \"installments\": \"3\",\n \"holder_document_number\": \"22233344450\",\n \"soft_descriptor\": \"EXEMPLOLOJA\",\n \"payment_data\": {\n \"data\": \"exemplo\",\n \"signature\": \"signature\",\n \"header\": {\n \"publicKeyHash\": \"Z...\",\n \"ephemeralPublicKey\": \"MFk...==\",\n \"transactionId\": \"trx....wvu\"\n },\n \"version\": \"EC_v1\"\n },\n \"payment_method\": {\n \"displayName\": \"Visa 3714\",\n \"network\": \"Visa\",\n \"type\": \"credit\"\n },\n \"transaction_identifier\": \"trx....wvu\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/apple-pay", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "apple-pay" ] }, "description": "O Apple Pay é uma solução de pagamento digital da Apple que permite realizar compras com cartão de crédito de forma rápida, segura e\nconveniente em dispositivos compatíveis (iPhone, iPad, Apple Watch e Mac).\n\nUtilizando tokenização e autenticação biométrica (Face ID ou Touch ID),\no Apple Pay elimina a digitação manual dos dados do cartão a cada compra,\nreduzindo o tempo de checkout e aumentando a conversão. Além disso,\ntransações via Apple Pay não possuem risco de chargeback por fraude.\n\n::: warning Compatibilidade\nO Apple Pay só é exibido no navegador Safari (macOS ou iOS) e em\ndispositivos Apple com suporte ao método. Em outros navegadores, o botão\nnão aparece.\n:::\n\n## Antes de começar: escolha o seu modelo de integração\n\nEsta é a decisão que mais gera dúvidas. Existem dois modelos de integração\ncom Apple Pay pela Appmax, e a diferença está em quem registra o domínio\njunto à Apple e em quem controla o `merchantIdentifier`.\n\n::: warning Em todos os modelos, você hospeda o arquivo `.well-known`\nIndependentemente do modelo abaixo, é sempre responsabilidade do lojista\n(ou do integrador, em nome da loja) publicar o arquivo\n`.well-known/apple-developer-merchantid-domain-association` na raiz de\ncada domínio onde o Apple Pay será usado — inclusive no modelo integrado.\nVeja o passo a passo completo, com o arquivo para download, em\n[Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio).\n:::\n\n| Aspecto | Modelo integrado (loja integrada / integrador via AppStore) | Fluxo direto |\n| --- | --- | --- |\n| Quem cadastra o domínio na Apple | A Appmax, por API, sob a conta/merchant Apple da Appmax | O próprio lojista, na conta Apple dele |\n| Quem hospeda o `.well-known` | O lojista/integrador, em todos os casos | O lojista hospeda o arquivo na raiz do domínio |\n| `merchantIdentifier` | Gerido pela Appmax, compartilhado entre vários domínios do integrador | Do próprio lojista |\n| Indicado para | Plataformas/integradores que operam várias lojas (ex.: e-commerce SaaS) | Lojista único que gerencia a própria conta Apple |\n\n::: info Como saber qual é o seu caso?\nSe você é uma plataforma/integrador e instala o app da Appmax em nome de\nvárias lojas (fluxo de AppStore, com `client_id`/`external_id` por loja),\nvocê está no **modelo integrado**. Se você é um lojista configurando o\nApple Pay diretamente na sua própria conta Apple, você está no\n**fluxo direto**. Nos dois casos, você precisa publicar o arquivo\n`.well-known` (veja o aviso acima).\n:::\n\nOs passos abaixo indicam, quando relevante, o que muda entre os dois modelos.\n\n## Glossário\n\n| Termo | Descrição |\n| --- | --- |\n| Apple Pay | Solução de pagamento da Apple para compras seguras via Apple Wallet, com autenticação biométrica e criptografia ponta a ponta. |\n| Apple Token (Apple Pay Token) | Objeto JSON criptografado retornado pela PaymentSheet após o usuário confirmar o pagamento, contendo `paymentData`, `paymentMethod` e `transactionIdentifier`. É o cartão tokenizado e serve para efetivar o pagamento na API Appmax. Gerado por transação. |\n| PaymentSheet | Interface nativa do Apple Pay que exibe valor, métodos disponíveis e solicita autenticação (Face ID, Touch ID ou senha). |\n| Merchant Session | Sessão JSON assinada pela Apple, válida para um domínio e `merchantIdentifier`. Valida o site antes de exibir a PaymentSheet. Obtida em tempo real a cada transação. |\n| `.well-known/apple-developer-merchantid-domain-association` | Arquivo estático de validação de domínio da Apple, vinculado ao `merchantIdentifier` (não à transação). Responsabilidade do lojista em **todos** os modelos de integração — veja [Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio). |\n| `external_id` | UUID que identifica o par (app instalado + loja). Gerado na instalação e usado nas chamadas da CDN. Veja [Instalação do Aplicativo](/guides/instalacao). |\n\n## Pré-requisitos\n\n- **Navegador compatível** — Safari (macOS ou iOS).\n- **Carteira Apple configurada** — ao menos um cartão Visa ou Mastercard no Apple Wallet.\n- **Instalação do app** feita com o parâmetro `domain_name` (passo 1).\n- **Arquivo `.well-known` publicado** e domínio validado junto à Apple (passo 2).\n- **Appmax JS incluído e inicializado** com os callbacks (passo 3).\n\nComponentes do fluxo:\n\n- **Script JS:** `https://scripts.appmax.com.br/appmax.min.js` (produção) — em sandbox use `https://scripts.sandboxappmax.com.br/appmax.min.js`.\n- **Domínio validado** junto à Apple.\n- **Requisição de pagamento** para a API Appmax com `appleToken`, `order_id` e `customer_id` válidos.\n\n## 1. Autorizar a instalação do aplicativo\n\nRegistre o aplicativo na Appmax informando o domínio:\n\n```bash\ncurl --location 'https://api.appmax.com.br/app/authorize' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer SEU_TOKEN' \\\n --data '{\n \"app_id\": \"APP_ID\",\n \"external_key\": \"EXTERNAL_KEY\",\n \"url_callback\": \"URL_CALLBACK\",\n \"domain_name\": \"subdominio.dominio.com.br\"\n }'\n```\n\n::: info\nO parâmetro `domain_name` deve conter subdomínio + domínio (ex.:\n`minhaloja.minhaintegracao.com.br`). Também é possível enviar vários\ndomínios com `domain_names` (array). Mais detalhes em\n[Instalação do Aplicativo](/guides/instalacao).\n:::\n\n## 2. Publicar o `.well-known` e validar o domínio\n\n### 2.1 Publicar o arquivo `.well-known` (obrigatório em todos os modelos)\n\nEm **todos** os modelos de integração, cada domínio onde o botão Apple Pay\nserá exibido precisa servir, na raiz do site, o arquivo de validação:\n\n```\nhttps://subdominio.dominio.com.br/.well-known/apple-developer-merchantid-domain-association\n```\n\nO arquivo, o passo a passo de publicação e o comando para verificar se ele\nestá acessível estão em\n[Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio).\n\n::: info\nO conteúdo do `.well-known` **não** é o Apple Token. O Apple Token é o\ncartão tokenizado, gerado por transação. O `.well-known` é um arquivo\nestático de validação de domínio, vinculado ao `merchantIdentifier` — o\nmesmo arquivo é usado em todos os domínios da sua implementação.\n:::\n\n### 2.2 Cadastrar o domínio junto à Apple\n\n::: warning\nEste passo muda conforme o modelo de integração.\n:::\n\n**Modelo integrado (loja integrada / integrador):** você não precisa\ncadastrar o domínio pelo painel da Apple. O registro é feito por API,\npela Appmax, sob o `merchantIdentifier` da Appmax. Basta que o domínio\ntenha sido informado na instalação (passo 1) e que o arquivo `.well-known`\n(passo 2.1) já esteja publicado — a Apple confere o arquivo ao validar o\ndomínio.\n\nSe o domínio do lojista mudar: o novo domínio é tratado como um domínio\nnovo e precisa ser registrado novamente. Não é necessário criar um novo\nmerchant.\n\n**Fluxo direto:** o cadastro do domínio é feito por você, diretamente no\npainel de desenvolvedor da Apple, na sua própria conta. A Apple valida o\narquivo `.well-known` publicado no passo 2.1 no momento do cadastro.\n\n## 3. Configuração e inicialização do script no front-end\n\n::: tip\nEsta seção resume o essencial. Para o passo a passo completo — seletores\ndo botão, ordem de carregamento em SPA, contrato de DOM e troubleshooting\n— veja [Implementando o botão Apple Pay com o Appmax JS](/api-reference/payments/apple-pay-appmax-js).\n:::\n\n::: warning\nO `externalId` esperado aqui é o mesmo `external_id` que você retornou com\nHTTP 200 na etapa de [Instalação do Aplicativo](/guides/instalacao).\n:::\n\nO `appmax.min.js` faz três coisas:\n\n- Estiliza o botão com o design oficial da Apple (opcional).\n- Inicializa o botão para abrir a PaymentSheet com os dados do carrinho.\n- Dispara os callbacks de sucesso, erro, atualização e autorização.\n\n### 3.1 Inicializar com onSuccess, onError, externalId, onUpdate e onAuthorize\n\n```html\n\n```\n\n::: warning\nAtenção à ordem e aos nomes dos callbacks. O callback que recebe o token é\no `onAuthorize` (não `onAutorize`). A ordem em `init` é: `onSuccess`,\n`onError`, `externalId`, `onUpdate`, `onAuthorize`.\n:::\n\n### 3.2 Mantendo o onUpdate atualizado (JS puro)\n\nO `onUpdate` deve retornar os dados atuais do checkout para alimentar a\nPaymentSheet (valor, frete, desconto, parcelas, itens):\n\n```js\nfunction getCheckoutData() {\n const products = Array.from(document.querySelectorAll('.product-item')).map(item => ({\n name: item.querySelector('.product-name').textContent,\n price: parseFloat(item.querySelector('.product-price').value),\n quantity: parseInt(item.querySelector('.product-quantity').value, 10)\n }));\n const freight = parseFloat(document.getElementById('freight').value || 0);\n const discount = parseFloat(document.getElementById('discount').value || 0);\n const totalItems = products.reduce((sum, p) => sum + p.price * p.quantity, 0);\n return {\n orderId: sessionStorage.getItem('order_id') || '',\n total: totalItems + freight - discount,\n freight: freight,\n discount: discount,\n installments: parseInt(document.getElementById('installments').value, 10) || 1,\n products: products\n };\n}\n```\n\n::: info\nSobre o `orderId` no `onUpdate`: o campo aqui serve à montagem da\nPaymentSheet. O `order_id` obrigatório é o do request de pagamento\n(`POST /v1/payments/apple-pay`) — ele não precisa necessariamente ser\nsetado no `onUpdate`, mas precisa ser o `order_id` de uma Order já\nexistente na Appmax (veja o passo 4).\n:::\n\n## 4. Processar o pagamento\n\nO pagamento Apple Pay exige três elementos: `customer_id`, `order_id` e o\n`appleToken`. A ordem é: criar customer → criar order → efetivar o pagamento.\n\n```js\nasync function processarPagamento(appleToken) {\n // 1. Criar customer — POST /v1/customers (veja /api-reference/customers/criar-atualizar)\n // 2. Criar order — POST /v1/orders (veja /api-reference/orders/criar-pedido)\n // 3. Efetivar pagamento — POST /v1/payments/apple-pay\n const paymentPayload = {\n order_id, // Order já existente na Appmax\n customer_id,\n payment_data: {\n apple_pay: {\n installments: \"3\", // 1 a 12\n holder_document_number: \"22233344450\", // obrigatório\n soft_descriptor: \"EXEMPLOLOJA\", // opcional, máx. 13 caracteres\n // Do appleToken.paymentData:\n payment_data: {\n version: \"EC_v1\",\n data: \"exemplo\",\n signature: \"signature\",\n header: {\n ephemeralPublicKey: \"MFk...==\",\n transactionId: \"trx....wvu\"\n }\n },\n // Do appleToken.paymentMethod:\n payment_method: {\n displayName: \"Visa •••• 3714\",\n network: \"Visa\",\n type: \"credit\"\n },\n // Do appleToken.transactionIdentifier:\n transaction_identifier: \"trx....wvu\"\n }\n }\n };\n const resp = await fetch('https://api.appmax.com.br/v1/payments/apple-pay', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json', Authorization: `Bearer SEU_TOKEN` },\n body: JSON.stringify(paymentPayload)\n });\n if (!resp.ok) throw new Error('Falha no pagamento');\n return resp.json();\n}\n```\n\nMapeamento do Apple Token para o payload:\n\n| Campo do `appleToken` | Vai em |\n| --- | --- |\n| `paymentData` | `payment_data.apple_pay.payment_data` |\n| `paymentMethod` | `payment_data.apple_pay.payment_method` |\n| `transactionIdentifier` | `payment_data.apple_pay.transaction_identifier` |\n\n::: info\nCampos obrigatórios: `order_id`, `installments` (1–12) e\n`holder_document_number`. `soft_descriptor` é opcional (máx. 13 caracteres).\n:::\n\n## Validação em tempo real (Merchant Session)\n\nA validação do domínio junto à Apple não é única — a Apple revalida o\ndomínio/merchant a cada transação, no momento em que a PaymentSheet é\naberta (a Merchant Session é obtida em tempo real). É um processo rápido e\ntransparente para o usuário; o Appmax JS cuida disso automaticamente. Veja\n[`POST /v1/apple-pay/merchant-session`](/api-reference/payments/apple-pay-merchant-session).\n\n## Testes e Sandbox\n\n::: warning\nNão é possível testar o Apple Pay em `localhost`. O Apple Pay exige um\ndomínio público, com HTTPS válido e devidamente registrado/configurado. A\nApple não valida domínios não públicos.\n:::\n\n::: warning Não existe merchant session de sandbox\nA validação de domínio/merchant é sempre feita contra a infraestrutura de\n**produção** da Apple, mesmo em ambiente de sandbox — não existe uma\nsegunda instância só para teste. Trate sandbox e produção como\nassimétricos nesse ponto específico: o script de sandbox aponta para o\nmesmo endpoint de validação que o de produção.\n:::\n\nCartões de teste da Apple: a referência oficial é\n[developer.apple.com/apple-pay/sandbox-testing](https://developer.apple.com/apple-pay/sandbox-testing)\n— que exige uma Sandbox Apple Account própria.\n\n::: warning Modelo integrado\nComo o pagamento roda sob a conta Apple da Appmax, não é possível usar\ncartões de teste da Apple da sua própria conta (não conseguimos provisionar\ncredenciais de teste de terceiros na nossa conta Apple, por segurança).\nNesse caso, a forma prática de testar é usar um cartão real e\ncancelar/estornar as ordens pelo admin.\n:::\n\n## Ambientes\n\n| | Sandbox | Produção |\n| --- | --- | --- |\n| Script JS | `https://scripts.sandboxappmax.com.br/appmax.min.js` | `https://scripts.appmax.com.br/appmax.min.js` |\n| API | `https://api.sandboxappmax.com.br` | `https://api.appmax.com.br` |\n\n## Perguntas frequentes (FAQ)\n\n**O `appleToken` é usado para quê?**\n\nÉ o cartão tokenizado pela Apple. Ele precisa ser enviado ao\n`POST /v1/payments/apple-pay` (nos campos `payment_data`, `payment_method`,\n`transaction_identifier`). Sem ele, o pagamento não é processado. É de uso\núnico por transação.\n\n**Preciso hospedar o arquivo `.well-known` em cada domínio?**\n\nSim, em **todos** os modelos de integração — isso não muda entre o modelo\nintegrado e o fluxo direto. O que muda entre os modelos é apenas quem\ncadastra o domínio junto à Apple (a Appmax, por API, no modelo integrado;\nvocê mesmo, pelo painel da Apple, no fluxo direto). Veja\n[Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio).\n\n**O `order_id` do `onUpdate` precisa ser de uma Order real da Appmax?**\n\nO `order_id` obrigatório é o do request de pagamento e precisa ser de uma\nOrder existente (criada via `POST /v1/orders`). Ele não precisa vir do\n`onUpdate`, mas precisa estar no payload do pagamento.\n\n**Se o domínio do lojista mudar, preciso de um novo merchant?**\n\nNão. O novo domínio é registrado novamente na instalação existente.\n\n**Existe um token/arquivo por lojista, ou um geral?**\n\nO Apple Token é sempre por transação. O conteúdo do arquivo de validação de\ndomínio é o mesmo para todos os domínios vinculados ao `merchantIdentifier`\ngerido pela Appmax — não é gerado por lojista. Ainda assim, cada domínio\nprecisa hospedar sua própria cópia desse mesmo arquivo (veja\n[Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio)). O que\né por lojista são as credenciais (`client_id`/`client_secret`) e o\n`external_id`.\n\n**A validação do domínio demora?**\n\nO registro do domínio é rápido (chamada síncrona). A validação da Merchant\nSession ocorre em tempo real, a cada transação — também rápida.\n\n**Consigo testar pelo sandbox da Appmax?**\n\nÉ preciso um domínio público registrado e configurado. No modelo integrado,\no caminho prático é cartão real + estorno (veja Testes e Sandbox).\n\n## Conclusão — checklist\n\n1. Autorizar a instalação com `domain_name`.\n2. Publicar o arquivo `.well-known` em cada domínio (obrigatório em todos os modelos) e cadastrar o domínio junto à Apple — Appmax por API (modelo integrado) ou você mesmo (fluxo direto). Veja [Configuração de domínios para Apple Pay](/api-reference/payments/apple-pay-dominio).\n3. Incluir e inicializar o Appmax JS com `onSuccess`, `onError`, `externalId`, `onUpdate`, `onAuthorize`.\n4. Criar customer → criar order → processar o `appleToken` via `POST /v1/payments/apple-pay`." } }, { "name": "Tokenização de cartão de crédito", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"payment_data\": {\n \"credit_card\": {\n \"number\": \"4444222222222222\",\n \"cvv\": \"123\",\n \"expiration_month\": \"12\",\n \"expiration_year\": \"28\",\n \"holder_name\": \"John Doe\"\n }\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/tokenize", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "tokenize" ] }, "description": "Substitui os dados reais do cartão (número, CVV, validade) por um token\núnico e seguro, permitindo realizar transações sem expor as informações\noriginais.\n\n::: danger Tokenização server-side exige PCI-DSS\nQuando você tokeniza pelo seu backend, o seu servidor toca o número de\ncartão e o CVV em claro. Isso **só é permitido** se sua arquitetura\nestá em escopo PCI-DSS. Se você não tem certeza, use o caminho via CDN\n— o script Appmax JS isola os dados sensíveis do seu servidor.\n:::\n\nExistem dois caminhos de autenticação distintos para este endpoint:\nvia CDN (header `external-id`) ou via backend (header `Authorization:\nBearer`). Veja [`external-id`](/guides/external-id) para o contexto." } }, { "name": "Cálculo de parcelas", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"installments\": 10,\n \"total_value\": 10000,\n \"settings\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payments/installments", "host": [ "{{base_url}}" ], "path": [ "v1", "payments", "installments" ] }, "description": "Retorna o valor total com os juros aplicados em cada modalidade de\nparcelamento. A integração deve realizar a divisão para obter o valor\nde cada parcela.\n\n::: info\nA quantidade e os valores das parcelas podem ser personalizados de 1 a\n12 parcelas. Os valores são configuráveis individualmente para cada\nmerchant.\n:::\n\n**Modalidades**\n- **PP** (Simples por parcela): a taxa de juros é aplicada diretamente sobre o valor de cada parcela.\n- **AM** (Financiamento): a taxa de juros é calculada mensalmente sobre o saldo devedor total." } }, { "name": "Apple Pay merchant session", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"store_url\": \"checkout.minhaloja.com.br\",\n \"external_id\": \"37bb0791-ee0b-457d-860c-186e32978bcd\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/apple-pay/merchant-session", "host": [ "{{base_url}}" ], "path": [ "v1", "apple-pay", "merchant-session" ] }, "description": "Obtém a Merchant Session assinada pela Apple para iniciar o fluxo Apple\nPay no navegador. O retorno é repassado a\n`session.completeMerchantValidation(...)` da `ApplePaySession`.\n\n::: warning Header `external-id` é obrigatório\nDiferente do que uma versão anterior desta página chegou a afirmar,\neste endpoint **exige** o header `external-id` — além do campo\n`external_id` no body. Envie os dois com o mesmo valor. Sem o header,\na requisição falha com parâmetro ausente.\n:::" } } ] }, { "name": "Reembolsos", "item": [ { "name": "Criar um estorno", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 1,\n \"type\": \"total\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/refund-request", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "refund-request" ] }, "description": "Cria uma solicitação de estorno (total ou parcial) para um pedido.\n\nPara **boleto**, é necessário informar os dados bancários do cliente na\nAppmax para que o valor seja ressarcido." } } ] }, { "name": "Assinaturas", "item": [ { "name": "Listar assinaturas", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions?email=cliente@exemplo.com", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions" ], "query": [ { "key": "email", "value": "cliente@exemplo.com", "description": "E-mail do cliente.", "disabled": false }, { "key": "status", "value": "ACTIVE", "description": "Filtra pelo status da assinatura. Aceita apenas `ACTIVE`, `PAUSED` e\n`CANCELLED`. Sem filtro, a listagem devolve todos os status, incluindo\n`OVERDUE`, `SUSPENDED` e `FINISHED` — veja `status` no item da listagem.", "disabled": true }, { "key": "page", "value": "1", "description": "Página da listagem.", "disabled": true } ] }, "description": "Lista as assinaturas de um cliente, identificado pelo **e-mail**, com\npaginação e filtro por status. Retorna 10 itens por página.\n\n::: warning Formato de data na listagem\nNesta rota `next_charge_at` e `charges[].charged_at` vêm no formato\n`dd/mm/aaaa`. No detalhe da assinatura, `next_charge_at` vem como\n`aaaa-mm-dd hh:mm:ss`.\n:::" } }, { "name": "Criar assinatura", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"order_id\": 12345,\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"max_cycles\": 12,\n \"products\": [\n {\n \"product_id\": 55,\n \"quantity\": 1\n }\n ],\n \"freight_value\": 19.9,\n \"discount\": 10\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions" ] }, "description": "Cria uma assinatura a partir de um pedido existente. O pedido informado\nem `order_id` é transformado em uma cobrança recorrente.\n\n::: warning Pré-requisitos do pedido\n- Deve existir e pertencer à mesma loja das credenciais.\n- Forma de pagamento deve ser **cartão de crédito** ou **PIX**.\n- Status deve ser **aprovado** ou **integrado** (ou seja, já liberado pelo antifraude).\n:::\n\nUm mesmo pedido pode originar mais de uma assinatura.\n\n::: tip Pedidos originados de um checkout Shopify\nQuando o pedido tem carrinho Shopify vinculado, `products` é **obrigatório** e\ncada item precisa de `shopify_product_id` **e** `shopify_variant_id` (o preço é\nlido da variante na Shopify, não do payload).\n\n- Com `interval` informado, a cadência enviada vale para todos os itens.\n- Sem `interval`, a cadência vem do plano de assinatura da variante e todos os\n itens precisam ter a mesma frequência.\n:::" } }, { "name": "Consultar assinatura", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}" ] }, "description": "Retorna os detalhes completos da assinatura, incluindo produtos, ciclos e\no histórico de cobranças." } }, { "name": "Pausar assinatura", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"paused_until\": \"2026-09-01\",\n \"reason\": \"Cliente solicitou pausa temporária\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/pause", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "pause" ] }, "description": "Pausa temporariamente a assinatura. Opcionalmente informe uma data até a\nqual ela permanece pausada e um motivo. Retorna o detalhe atualizado com\n`status: PAUSED`." } }, { "name": "Reativar assinatura", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/activate", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "activate" ] }, "description": "Reativa uma assinatura pausada, retomando as cobranças recorrentes. Não\nrequer corpo. Retorna o detalhe atualizado com `status: ACTIVE`." } }, { "name": "Cancelar assinatura", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"reason\": \"Cliente não deseja mais o produto\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/cancel", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "cancel" ] }, "description": "Cancela a assinatura de forma definitiva — nenhuma nova cobrança será\ngerada. Opcionalmente registre um motivo. Retorna o detalhe atualizado\ncom `status: CANCELLED` e `canceled_at` preenchido." } }, { "name": "Alterar o dia de cobrança", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"charge_day\": 15\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/charge-day", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "charge-day" ] }, "description": "Altera o dia fixo de cobrança da assinatura. A mudança vale para todos os\nciclos futuros e a próxima data de cobrança (`next_charge_at`) é\nrecalculada." } }, { "name": "Alterar a periodicidade", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"interval\": \"month\",\n \"interval_count\": 2\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/frequency", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "frequency" ] }, "description": "Altera a periodicidade (`interval` + `interval_count`) da assinatura e\nrecalcula `next_charge_at`. Retorna o detalhe atualizado da assinatura.\n\nA periodicidade enviada precisa ser oferecida pelo produto da assinatura.\nPara assinaturas de produtos Shopify, isso significa existir uma variante de\nassinatura naquela cadência; caso contrário a troca é recusada com `422`.\n\n::: warning Quando a troca é recusada\n- assinatura não está ativa ou está pausada;\n- a periodicidade enviada é igual à atual;\n- já existe uma cobrança em processamento (`409`);\n- a próxima cobrança está dentro da janela do agendador (`409`).\n:::" } }, { "name": "Pular um ciclo", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/cycles/{{cycle_index}}/skip", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "cycles", "{{cycle_index}}", "skip" ] }, "description": "Marca um ciclo futuro para ser pulado: a assinatura segue ativa, mas\naquele ciclo não gera cobrança nem pedido — a cobrança salta para o\npróximo ciclo não pulado.\n\n`cycleIndex` é o número do ciclo (1 = primeiro ciclo de recorrência).\nSó é possível pular ciclos ainda **não processados** — use\n`completed_cycles` do detalhe da assinatura como referência.\n\nPara desfazer, chame\n[desfazer o skip](/api-reference/subscriptions/desfazer-skip-ciclo)." } }, { "name": "Desfazer o skip de um ciclo", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/cycles/{{cycle_index}}/unskip", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "cycles", "{{cycle_index}}", "unskip" ] }, "description": "Remove a marcação de \"pulado\" de um ciclo futuro, devolvendo-o à fila de\ncobrança. O ciclo precisa estar marcado como pulado e ainda não ter sido\nprocessado." } }, { "name": "Atualizar o endereço de entrega", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"address\": {\n \"postcode\": \"01010-000\",\n \"street\": \"Rua São Bento\",\n \"number\": \"111\",\n \"complement\": \"Bloco 7\",\n \"district\": \"Centro\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/address", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "address" ] }, "description": "Atualiza o endereço de entrega associado à assinatura (dados do cliente\nvinculado). Aplica-se aos próximos ciclos de cobrança.\n\nO `postcode` é gravado apenas com dígitos (a pontuação enviada é removida)\ne o `state` é gravado em maiúsculas — a resposta devolve os valores já\nnormalizados.\n\n::: warning\nA alteração é feita no **cadastro do cliente**, então vale para todas as\nassinaturas e pedidos futuros dele, não só para esta assinatura.\n:::" } }, { "name": "Atualizar a tag da assinatura", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"tag\": \"Clube do Whey\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/tag", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "tag" ] }, "description": "Define o apelido da assinatura — um rótulo livre de até 255 caracteres que\nvocê escolhe para identificar a assinatura nos seus relatórios.\n\nEnvie `tag` vazia (`\"\"` ou `null`) para remover o apelido. Sem apelido\ndefinido, todas as respostas da API devolvem o padrão `#assinatura{id}`.\n\n::: tip\nA tag não aparece no painel Appmax nem no portal do assinante — ela existe\napenas nas respostas desta API.\n:::" } }, { "name": "Listar produtos disponíveis", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/available-products?", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "available-products" ], "query": [ { "key": "q", "value": "camiseta", "description": "Termo de busca por nome ou SKU do produto. Para assinaturas Shopify,\nsem este parâmetro a resposta vem vazia.", "disabled": true } ] }, "description": "Lista os produtos que ainda não estão na assinatura e podem ser\nadicionados a ela, já filtrados pela periodicidade da assinatura.\n\nO formato de cada item depende da origem da assinatura:\n\n- **Assinaturas de produtos Shopify** — um item por produto, com a lista\n de `variants` compatíveis com a cadência da assinatura. `q` é\n obrigatório na prática: sem termo de busca a resposta vem vazia.\n- **Assinaturas de produtos internos da Appmax** — lista simples de\n produtos ativos da loja (`product_id`, `name`, `price`, `sku`), até 30\n itens. Sem `q`, retorna os primeiros produtos em ordem alfabética." } }, { "name": "Adicionar produtos", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"products\": [\n {\n \"product_id\": 55,\n \"quantity\": 1\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/products", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "products" ] }, "description": "Adiciona um ou mais produtos a uma assinatura existente. Retorna o detalhe\natualizado da assinatura.\n\nFunciona para os dois tipos de assinatura, e a forma de identificar o\nproduto muda conforme o tipo — sempre use os identificadores devolvidos por\n[produtos disponíveis](/api-reference/subscriptions/produtos-disponiveis):\n\n- **Produtos internos da Appmax** → `product_id` (+ `quantity`). Nome,\n preço e SKU vêm do cadastro do produto; se enviados, são ignorados.\n- **Produtos da Shopify** → `shopify_product_id` **e**\n `shopify_variant_id` (+ `quantity`). O preço é lido da variante.\n\n::: warning A assinatura precisa estar \"parada\"\nAlterar produtos só é permitido enquanto a assinatura está ativa, não\npausada e sem cobrança em andamento. Veja os erros `409` e `422` abaixo.\n:::\n\n::: warning Assinaturas sem produtos\nA gestão de produtos exige uma assinatura com produtos definidos: criada\ncom `products` no [criar assinatura](/api-reference/subscriptions/criar-assinatura)\nou originada de um checkout Shopify. Assinaturas criadas sem `products`\n(que herdam o valor do pedido) respondem `404` aqui.\n:::" } }, { "name": "Alterar a quantidade de um produto", "request": { "method": "PATCH", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"quantity\": 3\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/products/{{variant_id}}/quantity", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "products", "{{variant_id}}", "quantity" ] }, "description": "Altera a quantidade de um produto já presente na assinatura. Vale para os\ndois tipos de assinatura — o produto é identificado na URL pelo `variantId`,\nque é o `product_id` (produtos internos da Appmax) ou o `variant_id`\n(produtos da Shopify) mostrado no detalhe da assinatura. Retorna o detalhe\natualizado.\n\n::: warning A assinatura precisa estar \"parada\"\nAlterar produtos só é permitido enquanto a assinatura está ativa, não\npausada e sem cobrança em andamento. Veja os erros `409` e `422` abaixo.\n:::" } }, { "name": "Remover um produto", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/subscriptions/{{subscription_id}}/products/{{variant_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "subscriptions", "{{subscription_id}}", "products", "{{variant_id}}" ] }, "description": "Remove um produto da assinatura. Vale para os dois tipos de assinatura — o\nproduto é identificado na URL pelo `variantId`, que é o `product_id`\n(produtos internos da Appmax) ou o `variant_id` (produtos da Shopify)\nmostrado no detalhe da assinatura. Retorna o detalhe atualizado, sem o\nproduto removido.\n\nA assinatura precisa manter pelo menos um produto — para encerrá-la por\ncompleto use [cancelar assinatura](/api-reference/subscriptions/cancelar-assinatura).\n\n::: warning\nA rota é `DELETE /v1/subscriptions/{id}/products/{variantId}` — sem o\nsufixo `/quantity`. Alterar produtos só é permitido enquanto a assinatura\nestá ativa, não pausada e sem cobrança em andamento.\n:::" } } ] }, { "name": "Produtos", "item": [ { "name": "Listar produtos", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products?", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ], "query": [ { "key": "page", "value": "1", "description": "Página da listagem.", "disabled": true }, { "key": "name", "value": "camiseta", "description": "Filtra produtos cujo nome contém o termo informado.", "disabled": true }, { "key": "status", "value": "active", "description": "Sem valor ou `active`: apenas ativos. `inactive`: apenas inativos.\n`all`: todos.", "disabled": true }, { "key": "sort_by", "value": "price", "description": "Campo de ordenação.", "disabled": true }, { "key": "sort_dir", "value": "asc", "description": "Direção da ordenação.", "disabled": true } ] }, "description": "Lista os produtos do merchant com paginação, filtro por nome/status e\nordenação. Retorna **20 itens por página**. Cada produto pertence a uma\n*company*, resolvida automaticamente a partir das credenciais." } }, { "name": "Criar um produto", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Camiseta Preta\",\n \"price\": 199.9,\n \"sku\": \"SKU-1\",\n \"external_id\": \"EXT-123\",\n \"description\": \"Camiseta 100% algodão\",\n \"image\": \"/uploads/a.png\",\n \"inventory\": 5,\n \"cost\": 50\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products", "host": [ "{{base_url}}" ], "path": [ "v1", "products" ] }, "description": "Cria um novo produto para o merchant. Os campos `name` e `price` são\nobrigatórios. O produto é criado ativo (`is_active: true`).\n\n::: tip Unicidade\n`sku` e `external_id` devem ser únicos por company. Se já existir um\nproduto com o mesmo valor, a API retorna `422`.\n:::" } }, { "name": "Consultar um produto", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/{{product_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "{{product_id}}" ] }, "description": "Retorna um produto específico do merchant pelo identificador (`id`).\nProdutos de outra company são tratados como inexistentes (`404`)." } }, { "name": "Atualizar um produto", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Camiseta Preta Slim\",\n \"price\": 219.9\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/products/{{product_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "{{product_id}}" ] }, "description": "Atualiza os dados de um produto existente. Envie apenas os campos que\ndeseja alterar; todos são opcionais e seguem as mesmas regras da criação." } }, { "name": "Excluir um produto", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/products/{{product_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "products", "{{product_id}}" ] }, "description": "Exclui um produto do merchant. A exclusão é feita por **soft delete**: o\nproduto é marcado como inativo (`is_active: false`) e continua consultável\ncom o filtro de status `inactive` ou `all`.\n\n::: warning Bloqueio\nA exclusão é bloqueada (`409`) quando o produto está vinculado a uma\nassinatura.\n:::" } } ] }, { "name": "Links de pagamento", "item": [ { "name": "Criar um link de pagamento", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Teste Name\",\n \"value\": 1551,\n \"description\": \"Description payment link\",\n \"product_type\": \"physical\",\n \"document\": \"19100000000\",\n \"payments\": [\n \"creditcard\",\n \"boleto\",\n \"pix\"\n ],\n \"max_installments\": 12,\n \"fee_transfer_from_installment\": 0,\n \"allow_multiple_sales\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/payment-link", "host": [ "{{base_url}}" ], "path": [ "v1", "payment-link" ] }, "description": "Cria um novo link de pagamento. A resposta traz o `checkout_url` — a URL\nhospedada pela Appmax que você compartilha com o comprador para que ele\nfinalize o pagamento.\n\nA requisição deve conter um token Bearer do **merchant**, obtido no\nfluxo de autenticação. Veja\n[Autenticação](/guides/autenticacao).\n\n::: warning\nO campo `value` é informado em **centavos** e o mínimo aceito é `500`\n(R$ 5,00).\n:::\n\nO campo `fee_transfer_from_installment` define a partir de qual parcela\no custo do parcelamento é repassado ao comprador. Com o valor `0`\n(default), o custo é absorvido pelo merchant em todas as parcelas.\n\nO campo `document` é opcional. Quando informado, deve conter um CPF ou\nCNPJ válido e o merchant deve possuir vínculo com a empresa do\ndocumento informado.\n\n::: warning Comportamento padrão do documento\nQuando já existe um link de pagamento criado e vinculado a uma empresa,\na última empresa utilizada na criação de um link passa a ser o padrão.\nPortanto, ao criar um novo link **sem informar o campo `document`**, o\nsistema continuará criando o link vinculado à última empresa utilizada,\nmesmo que uma nova empresa tenha sido cadastrada posteriormente. Para\ngarantir que o link seja vinculado a uma empresa específica, informe o\n`document` correspondente no payload.\n:::" } }, { "name": "Consultar os dados de um link de pagamento", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/payment-link/{{payment_link_id}}/orders", "host": [ "{{base_url}}" ], "path": [ "v1", "payment-link", "{{payment_link_id}}", "orders" ] }, "description": "Retorna os pedidos gerados por um determinado link de pagamento, com o\nstatus de cada um. Use para acompanhar as conversões do link criado em\n[`POST /v1/payment-link`](/api-reference/payment-links/criar-link-pagamento).\n\nA resposta é paginada: `meta` traz os totais da consulta e `links` traz\nas URLs de navegação entre as páginas." } } ] }, { "name": "Split", "item": [ { "name": "Consultar saldos", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/balances", "host": [ "{{base_url}}" ], "path": [ "v1", "balances" ] }, "description": "Retorna os saldos financeiros da empresa autenticada, separados por tipo.\n\n**Autenticação:** header `secret` (API Gateway).\n\n| type | descrição |\n|------|-----------|\n| `available` | Saldo disponível para saque |\n| `to_release` | Saldo a liberar |" } }, { "name": "Criar um recebedor", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"triage\": {\n \"revenue\": 10000,\n \"storeUrl\": \"https://exemplo-loja.com.br\"\n },\n \"account\": {\n \"email\": \"usuario@exemplo.com\",\n \"name\": \"Nome do Usuário\",\n \"cpf\": \"00000000000\",\n \"phone\": \"11900000000\",\n \"dateOfBirth\": \"1990-01-01\"\n },\n \"company\": {\n \"companyName\": \"Empresa Exemplo LTDA\",\n \"companyDocumentNumber\": \"00000000000000\",\n \"companyPostcode\": \"00000000\",\n \"companyAddress\": \"Rua Exemplo\",\n \"companyAddressNumber\": \"100\",\n \"companyAddressState\": \"SP\",\n \"companyAddressNeighborhood\": \"Bairro Exemplo\",\n \"companyCity\": \"São Paulo\",\n \"companyAddressComplement\": \"Complemento\"\n },\n \"bankAccount\": {\n \"bank\": 104,\n \"agency\": \"1234-0\",\n \"account\": \"12345-2\",\n \"bankAccountType\": \"CC\"\n },\n \"config\": {\n \"sendAccountAccess\": true,\n \"enableAutomaticWithdraw\": false\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/recipient", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient" ] }, "description": "Cadastra um recebedor para receber valores de [split de\npagamentos](/guides/split-pagamentos).\n\nO cadastro é só a primeira etapa. Para completar o fluxo, o recebedor\ntambém precisa concluir o\n[facematch (KYC)](/api-reference/split/facematch-link) — enquanto o KYC\nnão é aprovado, ele não participa de splits. Os três status possíveis do\nonboarding são:\n\n| Status | Significado |\n| --- | --- |\n| `Awaiting face match completion` | Aguardando o recebedor concluir a etapa de facematch (KYC). |\n| `Onboarding on verification` | Recebemos todos os dados do formulário + facematch e estamos analisando as informações. |\n| `Onboarding completed` | Cadastro completo e aprovado. |\n\nReferência completa em\n[Status do split de pagamentos](/guides/split-status#status-do-recebedor-recipient).\n\nA conta bancária (`bankAccount`) pode ser enviada já no cadastro. Os\ncódigos de banco (COMPE) homologados e os tipos de conta aceitos estão\nem [Bancos homologados](/guides/bancos-homologados).\n\n::: warning\nUma vez criado, o recebedor **não pode ser editado nem excluído via\nAPI**. Revise os dados antes de enviar — correções são feitas pelo\nsuporte da Appmax caso a caso.\n:::\n\n::: tip\nUm CNPJ só pode ser cadastrado uma vez. Tentar recriar retorna `422`\ncom a mensagem `\"O valor indicado para o campo company.company\ndocument number já se encontra utilizado.\"`.\n:::" } }, { "name": "Criar um recebedor flexível", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"triage\": {\n \"revenue\": 10000,\n \"storeUrl\": \"https://exemplo-loja.com.br\"\n },\n \"account\": {\n \"name\": \"Fulano de Tal\",\n \"cpf\": \"11122233344\"\n },\n \"company\": {\n \"companyName\": \"Empresa de Testes LTDA\",\n \"companyDocumentNumber\": \"00000000000191\",\n \"companyPostcode\": \"00000000\",\n \"companyAddress\": \"Rua dos Testes\",\n \"companyAddressNumber\": \"123\",\n \"companyAddressState\": \"SP\",\n \"companyAddressComplement\": \"Bloco A\",\n \"companyAddressNeighborhood\": \"Bairro Fictício\",\n \"companyCity\": \"Cidade Exemplo\"\n },\n \"bankAccount\": {\n \"bank\": 104,\n \"agency\": \"0001\",\n \"account\": \"12345-6\",\n \"bankAccountType\": \"CC\"\n },\n \"pixKey\": \"chave-pix-exemplo\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/recipient/flexible", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "flexible" ] }, "description": "Cadastra um recebedor de forma flexível para receber valores de\n[split de pagamentos](/guides/split-pagamentos). Esta rota permite o\nenvio de conjuntos parciais de dados da conta (`account`).\n\nO cadastro é só a primeira etapa. Para completar o fluxo, o recebedor\ntambém precisa concluir o\n[facematch (KYC)](/api-reference/split/facematch-link) — enquanto o KYC\nnão é aprovado, ele não participa de splits. Os três status possíveis do\nonboarding são:\n\n| Status | Significado |\n| --- | --- |\n| `Awaiting face match completion` | Aguardando o recebedor concluir a etapa de facematch (KYC). |\n| `Onboarding on verification` | Recebemos todos os dados do formulário + facematch e estamos analisando as informações. |\n| `Onboarding completed` | Cadastro completo e aprovado. |\n\nReferência completa em\n[Status do split de pagamentos](/guides/split-status#status-do-recebedor-recipient).\n\nA conta bancária (`bankAccount`) pode ser enviada já no cadastro. Os\ncódigos de banco (COMPE) homologados e os tipos de conta aceitos estão\nem [Bancos homologados](/guides/bancos-homologados).\n\n::: warning\nUma vez criado, o recebedor **não pode ser editado nem excluído via\nAPI**. Revise os dados antes de enviar — correções são feitas pelo\nsuporte da Appmax caso a caso.\n:::\n\n::: tip\nUm CNPJ só pode ser cadastrado uma vez. Tentar recriar retorna `422`\ncom a mensagem `\"O valor indicado para o campo company.company\ndocument number já se encontra utilizado.\"`.\n:::" } }, { "name": "Criar link de facematch (KYC)", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"phone\": \"11999999999\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/facematch-link", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "facematch-link" ] }, "description": "Gera o link de facematch (KYC) para um recebedor recém-criado e envia\num SMS com esse link para o telefone informado.\n\n::: warning\nSMS **não são enviados em homologação**. Teste o disparo do facematch\nem produção.\n:::\n\n::: info\nO telefone enviado neste endpoint **não precisa ser o mesmo** do\n`account.phone` usado na criação do recebedor.\n:::" } }, { "name": "Consultar status do recebedor", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/status", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "status" ] }, "description": "Retorna o status atual do onboarding do recebedor. Use para descobrir\nse o recebedor está pronto para receber splits (`Onboarding completed`).\n\nPara a referência completa dos status, veja\n[Status do split de pagamentos](/guides/split-status)." } }, { "name": "Criar split de pedido", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"split\": [\n {\n \"amount\": 1000,\n \"recipient_hash\": \"d9bd0dae-3274-5e5a-939f-f50d867eb652\"\n },\n {\n \"amount\": 500,\n \"recipient_hash\": \"d9bd0dae-3274-5e5a-939f-f50d867eb653\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/orders/{{order_id}}/split-order", "host": [ "{{base_url}}" ], "path": [ "v1", "orders", "{{order_id}}", "split-order" ] }, "description": "Divide o valor líquido de um pedido entre um ou mais recebedores. Os\nvalores são informados em **centavos** e cada linha referencia um\n`recipient_hash` previamente aprovado (`Onboarding completed`).\n\n::: warning\nNão é permitido criar ou alterar split em pedidos com status\n`aprovado`. Pedidos com split também não aceitam estorno parcial — só\nestorno total.\n:::\n\n::: tip Valores e taxas\nO split é limitado ao `partner_total` — valor do pedido menos as taxas\nda Appmax. A taxa é descontada automaticamente do marketplace; **não\nenvie taxa no payload**. Se a soma ultrapassar o `partner_total`, a\ndivisão é proporcional e o último recebedor recebe apenas o residual,\n**sem retorno de erro**.\n:::" } }, { "name": "Consultar saldos do recebedor", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/balances", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "balances" ] }, "description": "Retorna os saldos financeiros do recebedor. Pode haver dois tipos:\n- `available` — saldo disponível para saque imediato.\n- `to_release` — saldo ainda em compensação (pode ser antecipado)." } }, { "name": "Simular antecipação de saque", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/withdraw-request/anticipation/simulate?value=10000", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "withdraw-request", "anticipation", "simulate" ], "query": [ { "key": "value", "value": "10000", "description": "Valor do saque a simular em **centavos**.", "disabled": false } ] }, "description": "Simula a antecipação de um saque e retorna valor bruto, valor líquido,\ntaxa aplicada e percentual da taxa.\n\n::: info\n**Nenhuma solicitação de saque é criada** por este endpoint. Ele é\npuramente informativo, para cálculo antes da confirmação real.\n:::" } }, { "name": "Solicitar antecipação de saque", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": 1000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/withdraw-request/anticipation", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "withdraw-request", "anticipation" ] }, "description": "Cria uma solicitação real de antecipação usando saldo do tipo\n`to_release`. Ao contrário da simulação, este endpoint efetivamente\nmovimenta o saldo." } }, { "name": "Solicitar saque com saldo disponível", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"value\": 1000\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/v1/recipient/{{recipient_hash}}/withdraw-request/available", "host": [ "{{base_url}}" ], "path": [ "v1", "recipient", "{{recipient_hash}}", "withdraw-request", "available" ] }, "description": "Cria uma solicitação de saque usando o saldo **available**. Sem taxa\nde antecipação — o saldo já está liberado.\n\n::: tip\nSe o recebedor tem `to_release` mas não `available`, este endpoint\nretorna `Insufficient balance`. Nesse caso, use\n[antecipação](/api-reference/split/antecipacao).\n:::" } }, { "name": "Consultar solicitação de saque", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/v1/withdraw-request/{{withdraw_request_id}}", "host": [ "{{base_url}}" ], "path": [ "v1", "withdraw-request", "{{withdraw_request_id}}" ] }, "description": "Retorna os detalhes de uma solicitação de saque específica pelo seu\nidentificador (`withdrawRequestId`), incluindo status atual, valores\ne a conta bancária vinculada.\n\nCobre tanto solicitações criadas via\n[saldo disponível](/api-reference/split/saque-disponivel) quanto via\n[antecipação](/api-reference/split/antecipacao)." } } ] } ], "variable": [ { "key": "base_url", "value": "https://api.sandboxappmax.com.br" }, { "key": "auth_url", "value": "https://auth.sandboxappmax.com.br/oauth2/token" }, { "key": "client_id", "value": "" }, { "key": "client_secret", "value": "" }, { "key": "access_token", "value": "" }, { "key": "cycle_index", "value": "" }, { "key": "order_id", "value": "" }, { "key": "payment_link_id", "value": "" }, { "key": "product_id", "value": "" }, { "key": "recipient_hash", "value": "" }, { "key": "subscription_id", "value": "" }, { "key": "variant_id", "value": "" }, { "key": "withdraw_request_id", "value": "" } ] }