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.
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.
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.
Endpoints — Clientes
CRUD completo de clientes da sua conta. O identificador único de cada cliente é o reference_id retornado na criação.
Retorna os clientes da conta autenticada com suporte a busca, filtros e paginação.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| q | string | — | Busca por nome, e-mail ou CPF/CNPJ |
| is_blocked | boolean | — | Filtrar por bloqueados (true / false) |
| is_defaulter | boolean | — | Filtrar por inadimplentes (true / false) |
| limit | integer | 100 | Itens por página (máx. 200) |
| offset | integer | 0 | Deslocamento para paginação |
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);
{
"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
}
]
}
Cria um novo cliente vinculado à sua conta. Campos name e email_primary são obrigatórios.
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);
{
"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"
}
}
Retorna os dados completos de um cliente pelo reference_id.
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);
{
"success": true,
"customer": { /* objeto completo do cliente */ }
}
Substitui todos os dados do cliente. Os campos name e email_primary são obrigatórios. Campos não enviados são limpos.
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);
{
"success": true,
"message": "Cliente atualizado com sucesso.",
"customer": { /* objeto completo atualizado */ }
}
Atualiza somente os campos enviados. Ideal para alterações pontuais sem precisar reenviar todos os dados.
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);
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 -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);
{
"success": true,
"message": "Cliente removido com sucesso."
}
Campos do Cliente
Referência completa de todos os campos do objeto cliente.
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| name | string | sim | Nome completo do cliente |
| email_primary | string | sim | E-mail principal (único por conta) |
| email_secondary | string | não | E-mail secundário |
| document | string | não | CPF ou CNPJ (apenas dígitos ou formatado) |
| phone | string | não | Telefone completo com DDD. Ex: "31987654321" |
| phone_ddd | string | não | DDD separado. Use com phone_number |
| phone_number | string | não | Número sem DDD. Use com phone_ddd |
| state | string | não | UF. Ex: "MG", "SP" |
| city | string | não | Cidade |
| street | string | não | Logradouro |
| number | string | não | Número do endereço |
| no_number | boolean | não | true se sem número |
| neighborhood | string | não | Bairro |
| complement | string | não | Complemento |
| zipcode | string | não | CEP. Ex: "30130004" |
| observation | string | não | Observações internas (suporta HTML) |
| is_blocked | boolean | não | Se o cliente está bloqueado |
| blocked_reason | string | não | Motivo do bloqueio |
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ódigo | Significado | Causa comum |
|---|---|---|
| 200 | OK | Leitura, atualização ou remoção com sucesso |
| 201 | Created | Cliente criado com sucesso |
| 400 | Bad Request | Campo obrigatório ausente, JSON inválido ou falha de validação |
| 401 | Unauthorized | Chave de API ausente ou inválida |
| 404 | Not Found | Cliente não encontrado ou não pertence à sua conta |
| 405 | Method Not Allowed | Método HTTP não suportado pelo endpoint |
{
"success": false,
"message": "Campos obrigatórios ausentes: name, email_primary."
}
MePagg API Docs · Atualizado em 02/04/2026 · app.mepagg.com