API

API é a tela do painel da Appmax onde você obtém as credenciais do merchant (client_id e client_secret) da sua própria loja, sem precisar percorrer o fluxo de instalação de aplicativo.

Você escolhe (ou cria) a loja, copia as credenciais e faz uma única chamada em /oauth2/token para começar a usar a API transacional.

Para quem é esta página

Para quem vai integrar a própria loja à API da Appmax. Se você desenvolve um aplicativo que será instalado por outros merchants, o caminho continua sendo o fluxo de instalação.

O que muda em relação ao fluxo de instalação

O fluxo tradicional existe para o cenário multi-merchant: um aplicativo de terceiro precisa de autorização de cada loja que o instala. Para integrar a sua própria loja, essa negociação não é necessária.

	Fluxo de instalação	API
Credenciais do app	necessárias	não se aplica
`POST /app/authorize`	necessário	não se aplica
Tela de autorização com hash	necessária	não se aplica
`POST /app/client/generate`	necessário	não se aplica
URL de validação (health check)	necessária	não se aplica
Chamadas até ter o token do merchant	5	1

Antes de começar

Acesso ao painel da Appmax com perfil de produtor.
O item API visível no menu lateral, logo abaixo de Aplicativos. Se não aparecer, fale com o suporte: o acesso é liberado por permissão.

Ambiente	Painel
Sandbox	`https://breakingcode.sandboxappmax.com.br`
Produção	`https://admin.appmax.com.br`

Passo a passo

Abrir a tela API

No menu lateral do painel, clique em API, logo abaixo de Aplicativos.

A tela é organizada em abas: Credenciais, Webhooks, Documentação e Guia para IA. O Guia para IA mostra como usar um assistente de código (Claude, ChatGPT, Cursor, Copilot…) na integração: o contexto para colar na conversa — que já orienta o assistente a usar os webhooks do painel, e não os da Appstore —, o .env com o Client ID da loja, prompts prontos e a conexão com o MCP da documentação.

Criar ou selecionar a loja

Na aba Credenciais, clique em Gerar credenciais. O formulário abre numa janela sobre o painel, sem sair da tela. Escolha uma das duas opções:

Criar nova loja — informe o nome e o domínio da loja. O nome também aparece na fatura do cartão de crédito dos seus clientes. Se a sua conta tiver mais de uma empresa, selecione qual delas será a dona da loja.
Usar loja existente — selecione uma das lojas que você já tem na Appmax.

É a única decisão que você precisa tomar nesta tela. A criação da loja, os vínculos e a geração do par de credenciais acontecem em seguida, sem nenhum passo manual.

Copiar as credenciais do merchant

A loja passa a aparecer em Credenciais do merchant, com um card por loja. Ao lado do título fica o total de lojas ativas; com mais de uma loja, aparece também uma busca pelo nome. Ao lado da lista, o bloco Como funciona resume o caminho até a primeira chamada.

O card de cada loja traz as credenciais dela:

Client ID — sempre visível.
Client Secret — exibido uma única vez, no momento em que é gerado. Depois disso o campo fica mascarado. Copie e guarde em local seguro.
External ID — identificador desta instalação na loja, usado nas tokenizações via JS.

Perder o secret exige gerar um novo

O client_secret não é guardado para consulta posterior nem enviado por e-mail. Se você perder, use Gerar novo secret no card da loja: o client_id continua o mesmo, mas um secret novo é emitido e o anterior deixa de valer na hora. Toda aplicação que usa o secret antigo para de funcionar até você substituí-lo.

Cadastrar a URL de webhook

As credenciais permitem chamar a API. Para receber os eventos da Appmax (pedido aprovado, cliente criado, reembolso e outros), cadastre uma URL de webhook.

Na mesma tela API, abra a aba Webhooks e preencha:

a loja que você acabou de configurar;
a URL do seu endpoint (HTTPS, público);
os eventos que você quer receber, agrupados em Pedidos, Pagamentos, Clientes e Assinaturas.

O webhook cadastrado aparece na lista logo abaixo, onde você pode testar o envio ou excluir.

Logs e regras avançadas

A aba cobre o cadastro simples. Histórico de entregas, reenvio de evento e regras condicionais continuam na tela completa de webhooks do painel.

O formato das entregas, a lista de eventos e as regras de retentativa estão em Webhooks do painel.

Autenticar e transacionar

Com o par em mãos, troque-o por um access_token:

bash

curl --location 'https://auth.appmax.com.br/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=SEU_CLIENT_ID_MERCHANT' \
  --data-urlencode 'client_secret=SEU_CLIENT_SECRET_MERCHANT'

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "customer/create order/create payments/credit-card ..."
}

Use o access_token como Bearer nas chamadas transacionais:

bash

curl --location 'https://api.appmax.com.br/v1/customers' \
  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "firstname": "Maria", "lastname": "Silva", "email": "[email protected]" }'

O token vale 1 hora e não há refresh token: quando expirar, repita a chamada acima. Os escopos do token são os concedidos ao aplicativo — veja Autenticação e autorização.

O mesmo exemplo em outras linguagens

A aba Documentação traz este fluxo pronto em cURL, Node.js, PHP e Python, com botão para copiar.

Aba Documentação

A aba Documentação reúne, dentro do painel, o que você precisa para a primeira integração:

Início rápido — os quatro passos até a primeira chamada (configurar o .env, gerar o access token, fazer a primeira requisição e cadastrar um webhook) e o exemplo de código em cURL, Node.js, PHP e Python. Os exemplos leem as credenciais das variáveis de ambiente APPMAX_AUTH_URL, APPMAX_API_URL, APPMAX_CLIENT_ID e APPMAX_CLIENT_SECRET, então nada sensível fica no código.

Ambientes — a URL base da API e a URL de autenticação de cada ambiente, e quando usar cada um.

Ambiente	URL base da API	URL de autenticação
Sandbox	`https://api.sandboxappmax.com.br`	`https://auth.sandboxappmax.com.br/oauth2/token`
Produção	`https://api.appmax.com.br`	`https://auth.appmax.com.br/oauth2/token`

Referência da API — atalhos para as páginas de Autenticação, Pedidos, Pagamentos, Clientes, Produtos, Assinaturas, Link de pagamentos, Webhooks e Boas práticas, abertas em nova aba. O de Pagamentos leva à visão geral de cartão de crédito, Pix, boleto, Apple Pay e parcelamento.
Arquivos para download:
- Coleção Postman — todos os endpoints da API organizados por recurso (Autenticação, Clientes, Pedidos, Pagamentos, Reembolsos, Assinaturas, Produtos, Links de pagamento e Split), já apontando para o Sandbox.
- Especificação OpenAPI — para gerar SDKs ou dar contexto a um assistente de IA.
- Guia de integração em PDF — o passo a passo completo para a própria loja: credenciais, ambientes, autenticação, primeira integração, webhooks do painel e erros.

Usando a coleção Postman

Importe o arquivo no Postman (Import).
Nas variáveis da coleção, preencha client_id e client_secret com as credenciais da loja. Use o Current value, para o secret não ser sincronizado com a nuvem do Postman.
Rode Autenticação → Gerar access token: o token é salvo em access_token e usado por todos os outros requests.

Para Produção, troque base_url por https://api.appmax.com.br e auth_url por https://auth.appmax.com.br/oauth2/token.

Integre com ajuda de IA — o botão Usar IA na integração abre a aba Guia para IA, com o contexto para colar no assistente, o .env pronto e os prompts para gerar e revisar o código.

Nunca cole o Client Secret no chat da IA

O assistente escreve o código lendo variáveis de ambiente. O Client Secret vai direto no .env, fora da conversa e fora do Git.

Gerenciar as credenciais de uma loja

No card de cada loja existem duas ações, e a diferença entre elas importa:

	Gerar novo secret	Revogar
`client_id`	continua o mesmo	deixa de existir
`client_secret` anterior	deixa de valer na hora	deixa de valer na hora
Integração ativa	volta a funcionar ao trocar o secret	só volta com credenciais novas
Quando usar	perdeu o secret, ou quer trocá-lo por rotina	o secret vazou, ou a integração daquela loja foi desligada

Revogar

Revogar apaga o client no provedor de identidade da Appmax. A partir daí, qualquer chamada em /oauth2/token com aquele par responde erro de autenticação.

A revogação não tem volta

Não existe "desrevogar": o client deixa de existir. Para a loja voltar a acessar a API é preciso gerar credenciais novas, e nesse caso o client_id também é novo — diferente do que acontece em Gerar novo secret, que o preserva. Toda aplicação daquela loja precisa ser atualizada com o par novo.

A loja revogada continua na lista, marcada como tal, oferecendo Gerar novas credenciais. Ao confirmar, a Appmax emite um par novo — client_id e client_secret — e o card volta a mostrar as credenciais. Como na geração, o client_secret aparece uma única vez: copie-o antes de sair da tela e atualize a sua integração com o par novo.

Revogar não desativa a loja

A revogação encosta somente nas credenciais de API. A loja continua ativa na Appmax, vendendo pelo checkout e recebendo pedidos normalmente — o que ela perde é o acesso programático.

Depois disso

Referência da API — clientes, pedidos e pagamentos.
Exemplo de integração completa — do cliente ao pagamento aprovado.
Webhooks do painel — formato das entregas e lista de eventos.
Ambientes sandbox e produção — teste no sandbox antes de transacionar de verdade.

Perguntas frequentes

Cada loja tem credenciais próprias? Sim. O par é por loja. Se você opera várias lojas, gere as credenciais de cada uma e guarde separadamente.

Perdi o client_secret. Preciso criar outra loja? Não. Use Gerar novo secret no card da loja: o client_id é preservado e um secret novo é emitido. Lembre que o anterior deixa de funcionar imediatamente.

Revoguei sem querer. Como volto atrás? Não é possível reverter: o client deixa de existir no provedor de identidade. Gere credenciais novas para a mesma loja — o par será novo, inclusive o client_id, e as aplicações precisam ser atualizadas.

Revogar desativa a minha loja? Não. A loja segue ativa e vendendo; encerra-se apenas o acesso à API daquele par.

Preciso de credenciais de aplicativo (app credentials)? Não neste caminho. Elas existem para quem instala um aplicativo em lojas de terceiros. Aqui você usa apenas as credenciais do merchant.

A Appmax envia as credenciais por e-mail? Não. Nenhuma credencial é enviada por e-mail, chat ou qualquer canal manual — elas só aparecem nesta tela.

API ​

O que muda em relação ao fluxo de instalação ​

Antes de começar ​

Passo a passo ​

Aba Documentação ​

Gerenciar as credenciais de uma loja ​

Revogar ​

Depois disso ​

Perguntas frequentes ​

API