# Appmax API

> Documentação da Appmax API: integre pagamentos (cartão, Pix, boleto, Apple Pay), pedidos, clientes, assinaturas e split de pagamentos. Inclui o fluxo de instalação de aplicativos na AppStore da Appmax, autenticação OAuth2 e webhooks.

## Guias

- [Introdução](https://docs.appmax.com.br/index.md)
- [Por onde começar](https://docs.appmax.com.br/guides/por-onde-comecar.md): Guia de orientação para integradores que estão chegando na Appmax pela primeira vez.
- [Quickstart](https://docs.appmax.com.br/quickstart.md): Guia rápido para criar seu aplicativo, autenticar e processar seu primeiro pagamento na Appmax.
- [Conceitos de negócio](https://docs.appmax.com.br/guides/conceitos.md): Entenda os conceitos fundamentais da API e da Loja de Aplicativos da Appmax.
- [Ambientes e sandbox](https://docs.appmax.com.br/guides/ambientes.md): Entenda a diferença entre os ambientes de sandbox e produção da Appmax.
- [Status de pedidos](https://docs.appmax.com.br/guides/status-pedidos.md): Todos os status de pedidos na Appmax e seus significados.
- [Criar aplicativo](https://docs.appmax.com.br/guides/criar-aplicativo.md): Como criar um aplicativo público ou privado na Loja de Aplicativos da Appmax — decisão de tipo, requisitos e etapas do formulário.
- [Identificadores e URLs do app](https://docs.appmax.com.br/guides/identificadores-do-app.md): Referência dos dois IDs do aplicativo (UUID e Numerical ID) e das URLs configuradas no painel — onde cada um é usado no fluxo de instalação e na operação.
- [Validar URL de instalação](https://docs.appmax.com.br/guides/validar-url.md): Ferramenta interativa que dispara um health check sintético contra a URL de validação do seu aplicativo e checa cada requisito do contrato — HTTP 200, JSON, external_id UUID e alias.
- [Implementar a URL de validação](https://docs.appmax.com.br/guides/implementar-url-validacao.md): Como implementar no seu servidor o endpoint que recebe o health check da Appmax — contrato exato, exemplos prontos em Go, Node.js e PHP, e troubleshooting das falhas mais comuns.
- [Publicação em produção](https://docs.appmax.com.br/guides/publicacao-producao.md): Checklist de go-live e passos para migrar sua integração de sandbox para produção.
- [Fluxo de instalação](https://docs.appmax.com.br/guides/instalacao.md): Fluxo completo para obter o token, autorizar a instalação e gerar as credenciais do merchant.
- [Callback de instalação](https://docs.appmax.com.br/guides/callback-instalacao.md): Como o parâmetro url_callback em /app/authorize recebe o token de autorização e como esse token é trocado pelas credenciais do merchant — padrão ideal para integrações baseadas em microserviços.
- [Reaproveitamento de loja](https://docs.appmax.com.br/guides/reaproveitar-loja.md): Na tela de autorização o lojista pode vincular a instalação a uma loja que já existe, em vez de criar uma nova. O que muda na prática, por que "loja" e "site" são a mesma entidade e como tratar a reinstalação na mesma loja.
- [Automação de credenciais](https://docs.appmax.com.br/guides/automatizar-criacao-credenciais.md): Tutorial prático para montar um serviço que recebe o callback da instalação e gera automaticamente as credenciais do merchant, habilitando onboarding self-service.
- [Autenticação e autorização](https://docs.appmax.com.br/guides/autenticacao.md): Entenda o modelo de autenticação da API da Appmax, os dois tipos de credenciais e por que não utilizamos refresh tokens.
- [Identificador de instalação (external-id)](https://docs.appmax.com.br/guides/external-id.md): Identificador da instalação do aplicativo em uma loja. Como é gerado, onde é usado, quando muda e como diagnosticar os erros mais comuns.
- [Appmax JS](https://docs.appmax.com.br/guides/appmax-js.md): Como implementar o script de segurança da Appmax para coleta de IP e tokenização de cartão.
- [Webhooks](https://docs.appmax.com.br/guides/webhooks.md): Eventos de webhook da Appmax e como receber notificações em tempo real.
- [Rate limit](https://docs.appmax.com.br/guides/rate-limit.md): Entenda os limites de requisições da API da Appmax e como lidar com throttling.
- [Cálculo de parcelas](https://docs.appmax.com.br/guides/calculo-parcelas.md): Entenda as modalidades de cálculo de parcelas e como consultar os valores na API.
- [Visão geral](https://docs.appmax.com.br/guides/recuperacao-vendas-ia.md): Como criar um carrinho abandonado para acionar a recuperação de vendas com inteligência artificial da Appmax.
- [Integração completa](https://docs.appmax.com.br/guides/exemplo-integracao.md): Passo a passo completo com código para integrar pagamentos via API da Appmax no ambiente sandbox.
- [Pagamento parcelado](https://docs.appmax.com.br/guides/exemplo-parcelamento.md): Como consultar parcelas, calcular juros e processar um pagamento parcelado com cartão de crédito.
- [Checkout com múltiplos produtos](https://docs.appmax.com.br/guides/exemplo-checkout-completo.md): Como criar um pedido com vários produtos, frete, desconto e processar o pagamento.
- [Visão geral](https://docs.appmax.com.br/guides/split-pagamentos.md): Visão geral do fluxo de split de pagamentos na Appmax — onboarding de recebedores com KYC, divisão de valores em pedidos e solicitação de saques.
- [Status](https://docs.appmax.com.br/guides/split-status.md): Referência consolidada dos status de recebedor (recipient) e de solicitações de saque (withdraw request) do split de pagamentos Appmax, com regras de transição e elegibilidade.
- [Bancos homologados](https://docs.appmax.com.br/guides/bancos-homologados.md): Relação completa de bancos e instituições financeiras homologadas para cadastro de conta bancária de recebedores no split de pagamentos Appmax, com códigos COMPE e tipos de conta aceitos.
- [Perguntas frequentes](https://docs.appmax.com.br/guides/split-perguntas-frequentes.md): Respostas rápidas às dúvidas mais comuns sobre o fluxo de split de pagamentos na Appmax.
- [Integração com IA](https://docs.appmax.com.br/guides/ia.md): Acelere sua integração com a API da Appmax usando Claude, Cursor, Windsurf ou qualquer cliente MCP compatível.
- [Referência de ferramentas MCP](https://docs.appmax.com.br/guides/ia-ferramentas.md): Glossário completo das 13 ferramentas do servidor MCP da Appmax com exemplos de uso.
- [FAQ](https://docs.appmax.com.br/guides/faq.md): Perguntas frequentes sobre a integração com a API da Appmax.

## API Reference

- [Introdução à API](https://docs.appmax.com.br/api-reference/introduction.md): Visão geral da API da Appmax, URLs base e formato de autenticação.
- [Criar ou atualizar](https://docs.appmax.com.br/api-reference/customers/criar-atualizar.md): POST /v1/customers - Crie ou atualize um cliente na Appmax.
- [Listar produtos](https://docs.appmax.com.br/api-reference/products/listar-produtos.md): GET /v1/products - Liste os produtos do merchant com filtros, ordenação e paginação.
- [Consultar produto](https://docs.appmax.com.br/api-reference/products/consultar-produto.md): GET /v1/products/{id} - Consulte um produto do merchant pelo identificador.
- [Criar produto](https://docs.appmax.com.br/api-reference/products/criar-produto.md): POST /v1/products - Crie um novo produto no catálogo do merchant.
- [Atualizar produto](https://docs.appmax.com.br/api-reference/products/atualizar-produto.md): PUT /v1/products/{id} - Atualize os dados de um produto existente.
- [Excluir produto](https://docs.appmax.com.br/api-reference/products/excluir-produto.md): DELETE /v1/products/{id} - Exclua (soft delete) um produto do merchant.
- [Criar pedido](https://docs.appmax.com.br/api-reference/orders/criar-pedido.md): POST /v1/orders - Crie um novo pedido vinculado a um cliente na Appmax.
- [Consultar pedido](https://docs.appmax.com.br/api-reference/orders/consultar-pedido.md): GET /v1/orders/{order_id} - Consulte os detalhes de um pedido previamente criado.
- [Cálculo do valor](https://docs.appmax.com.br/api-reference/orders/calculo-valor.md): Entenda as regras de calculo do valor total de um pedido na Appmax.
- [Upsell](https://docs.appmax.com.br/api-reference/orders/upsell.md): POST /v1/orders/upsell - Crie um upsell vinculado a um pedido existente.
- [Código de rastreio](https://docs.appmax.com.br/api-reference/orders/codigo-rastreio.md): POST /v1/orders/shipping-tracking-code - Cadastre um código de rastreio no pedido.
- [Visão geral](https://docs.appmax.com.br/api-reference/payments/visao-geral.md): Métodos de pagamento disponíveis na API da Appmax e pré-requisitos para criar um pagamento.
- [Cartão de crédito](https://docs.appmax.com.br/api-reference/payments/cartao-credito.md): Fluxo completo do cartão de crédito - primeiro a tokenização (POST /v1/payments/tokenize), depois o pagamento (POST /v1/payments/credit-card).
- [Pix](https://docs.appmax.com.br/api-reference/payments/pix.md): POST /v1/payments/pix - Gere QR Code e código EMV para pagamento via Pix.
- [Boleto](https://docs.appmax.com.br/api-reference/payments/boleto.md): POST /v1/payments/boleto - Gere um boleto bancário vinculado a um pedido existente.
- [Pagamento com Apple Pay](https://docs.appmax.com.br/api-reference/payments/apple-pay.md): POST /v1/payments/apple-pay - Processe pagamentos via Apple Pay na Appmax.
- [Configuração de domínios (.well-known)](https://docs.appmax.com.br/api-reference/payments/apple-pay-dominio.md): Como publicar o arquivo .well-known/apple-developer-merchantid-domain-association exigido pela Apple para habilitar o Apple Pay em um domínio.
- [Implementando o botão (Appmax JS)](https://docs.appmax.com.br/api-reference/payments/apple-pay-appmax-js.md): Passo a passo de como o appmax.min.js renderiza e ativa o botão Apple Pay — seletores de DOM, ordem de carregamento e os callbacks do fluxo, com foco em SPA (React, Vue).
- [Parcelas](https://docs.appmax.com.br/api-reference/payments/parcelas.md): POST /v1/payments/installments - Consulte os valores de parcelas com as taxas configuradas na Appmax.
- [Listar assinaturas](https://docs.appmax.com.br/api-reference/subscriptions/listar-assinaturas.md): GET /v1/subscriptions - Liste as assinaturas de um cliente por e-mail, com filtro por status e paginação.
- [Criar assinatura](https://docs.appmax.com.br/api-reference/subscriptions/criar-assinatura.md): POST /v1/subscriptions - Transforme um pedido aprovado em uma cobrança recorrente.
- [Consultar assinatura](https://docs.appmax.com.br/api-reference/subscriptions/consultar-assinatura.md): GET /v1/subscriptions/{id} - Consulte os detalhes completos de uma assinatura, incluindo produtos e cobranças.
- [Pausar assinatura](https://docs.appmax.com.br/api-reference/subscriptions/pausar-assinatura.md): PATCH /v1/subscriptions/{id}/pause - Pause temporariamente uma assinatura ativa.
- [Reativar assinatura](https://docs.appmax.com.br/api-reference/subscriptions/reativar-assinatura.md): PATCH /v1/subscriptions/{id}/activate - Reative uma assinatura pausada, retomando as cobranças.
- [Cancelar assinatura](https://docs.appmax.com.br/api-reference/subscriptions/cancelar-assinatura.md): PATCH /v1/subscriptions/{id}/cancel - Cancele definitivamente uma assinatura.
- [Alterar dia de cobrança](https://docs.appmax.com.br/api-reference/subscriptions/alterar-dia-cobranca.md): PATCH /v1/subscriptions/{id}/charge-day - Altere o dia fixo de cobrança da assinatura.
- [Alterar periodicidade](https://docs.appmax.com.br/api-reference/subscriptions/alterar-periodicidade.md): PATCH /v1/subscriptions/{id}/frequency - Troque a periodicidade da assinatura e recalcule a próxima cobrança.
- [Pular ciclo](https://docs.appmax.com.br/api-reference/subscriptions/pular-ciclo.md): PATCH /v1/subscriptions/{id}/cycles/{cycleIndex}/skip - Pule um ciclo futuro sem cancelar a assinatura.
- [Desfazer skip de ciclo](https://docs.appmax.com.br/api-reference/subscriptions/desfazer-skip-ciclo.md): PATCH /v1/subscriptions/{id}/cycles/{cycleIndex}/unskip - Devolva um ciclo pulado à fila de cobrança.
- [Atualizar endereço](https://docs.appmax.com.br/api-reference/subscriptions/atualizar-endereco.md): PATCH /v1/subscriptions/{id}/address - Atualize o endereço de entrega vinculado à assinatura.
- [Atualizar tag](https://docs.appmax.com.br/api-reference/subscriptions/atualizar-tag.md): PATCH /v1/subscriptions/{id}/tag - Defina um apelido para identificar a assinatura nas respostas da API.
- [Produtos disponíveis](https://docs.appmax.com.br/api-reference/subscriptions/produtos-disponiveis.md): GET /v1/subscriptions/{id}/available-products - Liste os produtos que podem ser adicionados à assinatura.
- [Adicionar produtos](https://docs.appmax.com.br/api-reference/subscriptions/adicionar-produtos.md): POST /v1/subscriptions/{id}/products - Adicione um ou mais produtos a uma assinatura existente.
- [Alterar quantidade de produto](https://docs.appmax.com.br/api-reference/subscriptions/alterar-quantidade-produto.md): PATCH /v1/subscriptions/{id}/products/{variantId}/quantity - Altere a quantidade de um produto já presente na assinatura.
- [Remover produto](https://docs.appmax.com.br/api-reference/subscriptions/remover-produto.md): DELETE /v1/subscriptions/{id}/products/{variantId} - Remova um produto de uma assinatura.
- [Criar estorno](https://docs.appmax.com.br/api-reference/refunds/criar-estorno.md): POST /v1/orders/refund-request - Solicite estornos totais ou parciais de pedidos.
- [Criar link de pagamento](https://docs.appmax.com.br/api-reference/payment-links/criar-link-pagamento.md): POST /v1/payment-link - Crie um link de pagamento hospedado pela Appmax e receba a URL de checkout.
- [Consultar link de pagamento](https://docs.appmax.com.br/api-reference/payment-links/consultar-link-pagamento.md): GET /v1/payment-link/{payment_link_id}/orders - Consulte os pedidos e o status de um link de pagamento.
- [Criar recebedor](https://docs.appmax.com.br/api-reference/split/criar-recebedor.md): POST /v1/recipient - Cadastra um recebedor (recipient) para receber valores de split de pagamentos via fast onboarding.
- [Criar link de facematch (KYC)](https://docs.appmax.com.br/api-reference/split/facematch-link.md): POST /v1/recipient/{recipient_hash}/facematch-link - Gera o link de verificação facial e envia por SMS para o recebedor.
- [Consultar status do recebedor](https://docs.appmax.com.br/api-reference/split/consultar-recebedor.md): GET /v1/recipient/{recipient_hash}/status - Retorna o status atualizado do onboarding do recebedor.
- [Criar split de pedido](https://docs.appmax.com.br/api-reference/split/criar-split-pedido.md): POST /v1/orders/{orderId}/split-order - Divide o valor líquido de um pedido entre marketplace e recebedores.
- [Consultar saldos](https://docs.appmax.com.br/api-reference/split/saldos.md): GET /v1/recipient/{recipient_hash}/balances - Retorna saldos financeiros disponíveis e a liberar de um recebedor.
- [Simular antecipação](https://docs.appmax.com.br/api-reference/split/simular-antecipacao.md): GET /v1/recipient/{recipient_hash}/withdraw-request/anticipation/simulate - Simula uma antecipação de saque sem criar solicitação.
- [Solicitar antecipação](https://docs.appmax.com.br/api-reference/split/antecipacao.md): POST /v1/recipient/{recipient_hash}/withdraw-request/anticipation - Cria uma solicitação real de antecipação usando saldo a liberar.
- [Saque com saldo disponível](https://docs.appmax.com.br/api-reference/split/saque-disponivel.md): POST /v1/recipient/{recipient_hash}/withdraw-request/available - Cria uma solicitação de saque usando saldo disponível do recebedor.
- [Consultar solicitação de saque](https://docs.appmax.com.br/api-reference/split/consultar-solicitacao-saque.md): GET /v1/withdraw-request/{withdrawRequestId} - Consulta os detalhes de uma solicitação de saque específica.

## Optional

- [MCP & llms.txt](https://docs.appmax.com.br/llms.md): Toda a documentação da Appmax API em formato texto plano, otimizada para consumo por LLMs e agentes de IA.