Documentação Completa da API

Guia consolidado para configurar, integrar e testar a API de Pagamentos Multi-Gateway (Mercado Pago, EFI Bank/Gerencianet, Asaas, Stripe e Pagar.me), unindo o conteúdo do HTML, Markdown e da documentação interativa.

Configuração Inicial

A primeira etapa é configurar o sistema e credenciais na interface administrativa.

1. Acesse o painel em: https://seu-dominio/api/configuracao.php
2. Preencha as credenciais de cada gateway (Tokens, Client IDs, chaves PIX, etc.).
3. Ative ou desative cada gateway conforme o uso, além de opções como cartão de crédito e PIX.
4. Defina juros, parcelamentos e taxa de Multicheckout.
5. Escolha o ambiente: Produção ou Sandbox.
6. Gerencie a Chave de API única de acesso, caso queira segurança completa nos endpoints.

Webhooks & Atualização Automática

Para que os pedidos mudem automaticamente de pendente para pago ou cancelado, você deve configurar as URLs de Webhook nos painéis dos gateways.

1. Acesse configuracao.php e localize as configurações de cada gateway.
2. Siga os links e eventos necessários para a comunicação bidirecional de recebimentos.
3. Configure essa URL (geralmente apontando para os webhook.php de suas subpastas) no gateway correspondente:

• Asaas: Configurações > Integrações > Webhooks, eventos de cobrança. (URL: /gateways/asaas/config/webhook.php)
• EFI Bank: URLs de PIX e Boletos via API/painel da EFI. (URL: /gateways/gerencianet/config/webhook.php)
• Mercado Pago: em Sua Aplicação > Notificações Webhooks/IPN, eventos de payment. (URL: /gateways/mercadopago/webhook.php)
• Stripe: em Developers > Webhooks, configure a URL para eventos de payment_intent.succeeded e charge.updated. (URL: /gateways/stripe/webhook.php)
• Pagar.me: em Configurações > Webhooks, configure os eventos de order.paid e charge.paid. (URL: /gateways/pagarme/webhook.php)

Estrutura de Arquivos

• pagamento.php – Página de checkout global que exibe o pedido e opções de múltiplos pagamentos.
• index.php – Gerador de Links de Pagamento.
• configuracao.php – Painel administrativo interativo.
• gerar_pagamento.php – Endpoint JSON para criação de pedidos via API externa.
• consultar_status.php – Endpoint JSON/HTML para consulta de status.
• config.php – Centralizador de credenciais do sistema.
• gateways/ – Implementações e regras divididas por pastas (Mercado Pago, EFI, Asaas, Stripe, Pagar.me).

Endpoints Principais

{
  "success": true,
  "pedido_id": "42",
  "payment_url": "https://seu-dominio/api/pagamento?id=42"
}

Parâmetros da Requisição

Endpoint: gerar_pagamento.php

Endpoint: consultar_status.php

Segurança & Gerenciamento de Chaves

Como funciona o sistema de chaves

Fluxo de ativação:

1. Minhas Chaves → Criar chave → Escolher Sandbox (ativa imediato) ou Produção (fica pendente)
2. Se Produção: Gerenciar Chaves (Admin) → aba Chaves → Aprovar → definir permissões e limites
3. Configurações → Card "Chave de API Ativa" → Selecionar a chave no dropdown → Aplicar
4. A chave passa a ser exigida em todas as requisições JSON à API

Como enviar a chave nas requisições:

• Header HTTP (recomendado): X-API-KEY: sua_chave_aqui
• Query String (alternativo): ?api_key=sua_chave_aqui

Respostas de Erro de Autenticação (HTTP 401):

Coleção do Postman

Para facilitar os seus testes, preparamos uma coleção oficial do Postman com todos os endpoints pré-configurados (Headers, Body e Variáveis).

Exemplos de Integração em Múltiplas Linguagens

<?php
$url = "https://seu-dominio/api/gerar_pagamento.php";
$params = [
    "valor"   => "150.00",
    "nome"    => "João Silva",
    "email"   => "joao@email.com",
    "cpf"     => "123.456.789-00", // Necessário pro Asaas/Pagar.me PIX
    "format"  => "json",
];

$ch = curl_init($url . "?" . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: SUA_CHAVE_MESTRA" // Opcional / Depende da sua configuração
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if (!empty($data["success"])) {
    echo "URL de Checkout Unificado: " . $data["payment_url"];
} else {
    echo "Erro ocorrido: " . ($data["error"] ?? "Erro não fatal");
}
?>

import requests

url = "https://seu-dominio/api/gerar_pagamento.php"
params = {
    "valor": "99.90",
    "nome": "Maria Souza",
    "format": "json"
}
headers = {
    "X-API-Key": "SUA_CHAVE_MESTRA"
}

try:
    response = requests.get(url, params=params, headers=headers)
    data = response.json()

    if data.get("success"):
        print("Pedido Criado Internamente:", data["pedido_id"])
        print("Link Base:", data["payment_url"])
    else:
        print("Erro Local:", data.get("error"))
except Exception as e:
    print(f"Erro Request: {e}")

const axios = require('axios');

async function gerarPagamento() {
  try {
    const res = await axios.post('https://seu-dominio/api/gerar_pagamento.php', null, {
      params: { 
          valor: '50.00', 
          format: 'json' 
      },
      headers: { 
          'X-API-Key': 'SUA_CHAVE_MESTRA' 
      }
    });

    console.log('Central de Pagamento Ativa em:', res.data.payment_url);
  } catch (error) {
    console.error('Falha de sistema', error.response?.data || error.message);
  }
}

gerarPagamento();

curl -X GET \
  -H "X-API-Key: SUA_CHAVE_MESTRA" \
  "https://seu-dominio/api/gerar_pagamento.php?valor=10.00&format=json"

Consulta Direta de Status e Sincronização

Use o endpoint consultar_status.php para saber se o usuário de fato concluiu a verificação nos checkouts externos e se Webhooks já sincronizaram e alteraram as linhas do Banco de Dados para seu fechamento de caixa.

Exemplo completo de retorno com o agrupamento de multi-compras (multicheckout_id):

{
  "success": true,
  "type": "multicheckout",
  "summary": {
    "total_items": 2,
    "paid_items": 1,
    "total_value": "250.00",
    "status_geral": "parcialmente_pago"
  },
  "items": [
    { "id": 1, "status": "paid", "valor": "100.00" },
    { "id": 2, "status": "pendente", "valor": "150.00" }
  ]
}

Testar API ao Vivo

{
    "method": "GET",
    "params": {
        "format": "json",
        "valor": "100.00",
        "nome": "Cliente Teste",
        "email": "teste@email.com"
    }
}

{
    "message": "Clique em 'Testar Requisição' para ver a resposta da API"
}

Testes Locais da Produção API

Via Barra do Navegador: Acesso Direto para Checkout

1. Acesse por janela anônima para testar a captura:

   https://seu-dominio/api/gerar_pagamento.php?valor=50.00&nome=TesteLocal

2. Siga o curso lógico. O script criará o pedido_id, preencherá as tabelas nativas de logs, e pulará você a página unificada pagamento?id={gerado}.
3. Confirme em Painel Pedidos visivelmente a geração limpa.

Simulação Profunda com Aplicativo/REST

1. Use a aplicação robusta do Postman e adicione a Query Form JSON:

   curl -X GET "https://seu-dominio/api/gerar_pagamento?valor=75.50&format=json"

2. A guarde retornar um status Code 200 OK com a key "payment_url" populada.