Documentação Oficial

API MePagg

Interface REST para integrar o MePagg ao seu sistema. Autenticação via chave de API, respostas em JSON e suporte a todas as operações de gestão de clientes.

Base URL https://app.mepagg.com
Formato JSON
Autenticação API Key
Versão v1

Início Rápido

Em 3 passos você já está integrado:

  • 1. No painel, acesse Integração → Chave de API e clique em Gerar chave de API.
  • 2. Inclua a chave no header de todas as requisições: X-API-KEY: SUA_CHAVE.
  • 3. Faça sua primeira chamada conforme os exemplos abaixo.
Guarde sua chave com segurança. Ela dá acesso completo à sua conta. Se suspeitar de vazamento, gere uma nova chave imediatamente — a anterior é invalidada.
GET
/api/v1/customers/
Listar clientes com paginação e filtros
POST
/api/v1/customers/
Criar novo cliente
GET
/api/v1/customers/{id}/
Consultar cliente por reference_id
PUT
/api/v1/customers/{id}/
Atualização completa do cliente
PATCH
/api/v1/customers/{id}/
Atualização parcial de campos
DEL
/api/v1/customers/{id}/
Remoção lógica do cliente

Autenticação

Todas as requisições precisam de autenticação. Envie sua chave de API em um dos dois formatos abaixo — ambos são aceitos em qualquer endpoint.

X-API-KEY Recomendado

Header customizado — mais simples e direto.

X-API-KEY: sua_chave_aqui

Authorization Bearer

Padrão OAuth2 — ideal para bibliotecas HTTP que já usam este header.

Authorization: Bearer sua_chave_aqui
Nunca exponha sua chave de API em código client-side (JavaScript no browser, apps mobile). Use sempre no servidor.

Endpoints — Clientes

CRUD completo de clientes da sua conta. O identificador único de cada cliente é o reference_id retornado na criação.

GET /api/v1/customers/ Listar clientes

Retorna os clientes da conta autenticada com suporte a busca, filtros e paginação.

Parâmetros de query
ParâmetroTipoPadrãoDescrição
qstringBusca por nome, e-mail ou CPF/CNPJ
is_blockedbooleanFiltrar por bloqueados (true / false)
is_defaulterbooleanFiltrar por inadimplentes (true / false)
limitinteger100Itens por página (máx. 200)
offsetinteger0Deslocamento para paginação
cURL
Python
JavaScript
PHP
curl -X GET "https://app.mepagg.com/api/v1/customers/?limit=50&offset=0&q=joao" \
  -H "X-API-KEY: SUA_CHAVE"
import requests

url = "https://app.mepagg.com/api/v1/customers/"
headers = {"X-API-KEY": "SUA_CHAVE"}
params = {"limit": 50, "offset": 0, "q": "joao"}

response = requests.get(url, headers=headers, params=params)
print(response.json())
const params = new URLSearchParams({ limit: 50, offset: 0, q: "joao" });

const res = await fetch(`https://app.mepagg.com/api/v1/customers/?${params}`, {
  headers: { "X-API-KEY": "SUA_CHAVE" }
});

const data = await res.json();
console.log(data);
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/?limit=50&q=joao",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ["X-API-KEY: SUA_CHAVE"],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta 200 OK
{
  "success": true,
  "total": 142,
  "count": 50,
  "offset": 0,
  "limit": 50,
  "results": [
    {
      "reference_id": "xK9mP2qR",
      "name": "João Almeida",
      "email_primary": "joao@empresa.com.br",
      "document": "12345678901",
      "is_blocked": false,
      "is_defaulter": false
    }
  ]
}
POST /api/v1/customers/ Criar cliente

Cria um novo cliente vinculado à sua conta. Campos name e email_primary são obrigatórios.

cURL
Python
JavaScript
PHP
curl -X POST "https://app.mepagg.com/api/v1/customers/" \
  -H "X-API-KEY: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Almeida",
    "email_primary": "joao@empresa.com.br",
    "document": "123.456.789-00",
    "phone": "31987654321",
    "state": "MG",
    "city": "Belo Horizonte",
    "street": "Av. Afonso Pena",
    "number": "1500",
    "neighborhood": "Centro",
    "zipcode": "30130004"
  }'
import requests

payload = {
  "name": "João Almeida",
  "email_primary": "joao@empresa.com.br",
  "document": "12345678900",
  "phone": "31987654321",
  "state": "MG",
  "city": "Belo Horizonte",
}

response = requests.post(
  "https://app.mepagg.com/api/v1/customers/",
  headers={"X-API-KEY": "SUA_CHAVE"},
  json=payload
)
print(response.json())
const res = await fetch("https://app.mepagg.com/api/v1/customers/", {
  method: "POST",
  headers: {
    "X-API-KEY": "SUA_CHAVE",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "João Almeida",
    email_primary: "joao@empresa.com.br",
    document: "12345678900",
    phone: "31987654321",
    state: "MG",
    city: "Belo Horizonte"
  })
});

const data = await res.json();
console.log(data.customer.reference_id);
$payload = json_encode([
  "name"          => "João Almeida",
  "email_primary" => "joao@empresa.com.br",
  "document"      => "12345678900",
  "phone"         => "31987654321",
]);

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => $payload,
  CURLOPT_HTTPHEADER     => [
    "X-API-KEY: SUA_CHAVE",
    "Content-Type: application/json",
  ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta 201 Created
{
  "success": true,
  "message": "Cliente criado com sucesso.",
  "customer": {
    "reference_id": "xK9mP2qR",
    "name": "João Almeida",
    "email_primary": "joao@empresa.com.br",
    "document": "12345678900",
    "phone_ddd": "31",
    "phone_number": "987654321",
    "phone": "31987654321",
    "state": "MG",
    "city": "Belo Horizonte",
    "is_blocked": false,
    "is_defaulter": false,
    "created_at": "2026-04-02T14:32:00.123456-03:00",
    "updated_at": "2026-04-02T14:32:00.123456-03:00"
  }
}
GET /api/v1/customers/{reference_id}/ Consultar cliente

Retorna os dados completos de um cliente pelo reference_id.

cURL
Python
JavaScript
PHP
curl -X GET "https://app.mepagg.com/api/v1/customers/xK9mP2qR/" \
  -H "X-API-KEY: SUA_CHAVE"
import requests

r = requests.get(
  "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  headers={"X-API-KEY": "SUA_CHAVE"}
)
cliente = r.json()["customer"]
const res = await fetch(
  "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  { headers: { "X-API-KEY": "SUA_CHAVE" } }
);
const { customer } = await res.json();
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ["X-API-KEY: SUA_CHAVE"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Resposta 200 OK
{
  "success": true,
  "customer": { /* objeto completo do cliente */ }
}
PUT /api/v1/customers/{reference_id}/ Atualização completa

Substitui todos os dados do cliente. Os campos name e email_primary são obrigatórios. Campos não enviados são limpos.

cURL
Python
JavaScript
PHP
curl -X PUT "https://app.mepagg.com/api/v1/customers/xK9mP2qR/" \
  -H "X-API-KEY: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Almeida Atualizado",
    "email_primary": "joao.novo@empresa.com.br",
    "phone": "31999990000",
    "state": "MG",
    "city": "Mariana"
  }'
import requests

requests.put(
  "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  headers={"X-API-KEY": "SUA_CHAVE"},
  json={
    "name": "João Almeida Atualizado",
    "email_primary": "joao.novo@empresa.com.br",
    "phone": "31999990000",
  }
)
await fetch("https://app.mepagg.com/api/v1/customers/xK9mP2qR/", {
  method: "PUT",
  headers: { "X-API-KEY": "SUA_CHAVE", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "João Almeida Atualizado",
    email_primary: "joao.novo@empresa.com.br",
    phone: "31999990000"
  })
});
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => "PUT",
  CURLOPT_POSTFIELDS     => json_encode([
    "name"          => "João Atualizado",
    "email_primary" => "joao.novo@empresa.com.br",
  ]),
  CURLOPT_HTTPHEADER     => ["X-API-KEY: SUA_CHAVE", "Content-Type: application/json"],
]);
curl_exec($ch); curl_close($ch);
Resposta 200 OK
{
  "success": true,
  "message": "Cliente atualizado com sucesso.",
  "customer": { /* objeto completo atualizado */ }
}
PATCH /api/v1/customers/{reference_id}/ Atualização parcial

Atualiza somente os campos enviados. Ideal para alterações pontuais sem precisar reenviar todos os dados.

cURL
Python
JavaScript
PHP
curl -X PATCH "https://app.mepagg.com/api/v1/customers/xK9mP2qR/" \
  -H "X-API-KEY: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"is_blocked": true, "blocked_reason": "Inadimplência"}'
requests.patch(
  "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  headers={"X-API-KEY": "SUA_CHAVE"},
  json={"is_blocked": True, "blocked_reason": "Inadimplência"}
)
await fetch("https://app.mepagg.com/api/v1/customers/xK9mP2qR/", {
  method: "PATCH",
  headers: { "X-API-KEY": "SUA_CHAVE", "Content-Type": "application/json" },
  body: JSON.stringify({ is_blocked: true, blocked_reason: "Inadimplência" })
});
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => "PATCH",
  CURLOPT_POSTFIELDS     => json_encode(["is_blocked" => true]),
  CURLOPT_HTTPHEADER     => ["X-API-KEY: SUA_CHAVE", "Content-Type: application/json"],
]);
curl_exec($ch); curl_close($ch);
DELETE /api/v1/customers/{reference_id}/ Remover cliente

Realiza remoção lógica do cliente — o registro não é apagado do banco, apenas marcado como removido e não aparece mais nas listagens.

cURL
Python
JavaScript
PHP
curl -X DELETE "https://app.mepagg.com/api/v1/customers/xK9mP2qR/" \
  -H "X-API-KEY: SUA_CHAVE"
requests.delete(
  "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  headers={"X-API-KEY": "SUA_CHAVE"}
)
await fetch("https://app.mepagg.com/api/v1/customers/xK9mP2qR/", {
  method: "DELETE",
  headers: { "X-API-KEY": "SUA_CHAVE" }
});
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL            => "https://app.mepagg.com/api/v1/customers/xK9mP2qR/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => "DELETE",
  CURLOPT_HTTPHEADER     => ["X-API-KEY: SUA_CHAVE"],
]);
curl_exec($ch); curl_close($ch);
Resposta 200 OK
{
  "success": true,
  "message": "Cliente removido com sucesso."
}

Campos do Cliente

Referência completa de todos os campos do objeto cliente.

CampoTipoObrig.Descrição
namestringsimNome completo do cliente
email_primarystringsimE-mail principal (único por conta)
email_secondarystringnãoE-mail secundário
documentstringnãoCPF ou CNPJ (apenas dígitos ou formatado)
phonestringnãoTelefone completo com DDD. Ex: "31987654321"
phone_dddstringnãoDDD separado. Use com phone_number
phone_numberstringnãoNúmero sem DDD. Use com phone_ddd
statestringnãoUF. Ex: "MG", "SP"
citystringnãoCidade
streetstringnãoLogradouro
numberstringnãoNúmero do endereço
no_numberbooleannãotrue se sem número
neighborhoodstringnãoBairro
complementstringnãoComplemento
zipcodestringnãoCEP. Ex: "30130004"
observationstringnãoObservações internas (suporta HTML)
is_blockedbooleannãoSe o cliente está bloqueado
blocked_reasonstringnãoMotivo do bloqueio
Os campos reference_id, is_defaulter, created_at e updated_at são somente leitura — gerados automaticamente pelo sistema.

Erros e Status HTTP

Todas as respostas de erro seguem o formato {"success": false, "message": "descrição do erro"}.

CódigoSignificadoCausa comum
200OKLeitura, atualização ou remoção com sucesso
201CreatedCliente criado com sucesso
400Bad RequestCampo obrigatório ausente, JSON inválido ou falha de validação
401UnauthorizedChave de API ausente ou inválida
404Not FoundCliente não encontrado ou não pertence à sua conta
405Method Not AllowedMétodo HTTP não suportado pelo endpoint
Exemplo de resposta de erro
{
  "success": false,
  "message": "Campos obrigatórios ausentes: name, email_primary."
}

MePagg API Docs · Atualizado em 02/04/2026 · app.mepagg.com