Clientes

O cliente final nasce inline em POST /v1/subscriptions e é reaproveitado pelo externalRef. O motor é a fonte desses dados: é daqui que saem o nome na fatura, o e-mail dos avisos, o CPF/CNPJ da nota fiscal e o cliente espelhado em cada gateway. Este recurso serve para consultar e corrigir — não existe POST /v1/customers.

Rota	O que faz
GET /v1/customers	Lista os clientes, paginados; filtra pelo seu externalRef
GET /v1/customers/{customerId}	Um cliente pelo id do motor
PATCH /v1/customers/{customerId}	Corrige nome, e-mail, documento, telefone ou endereço

O objeto Cliente

Campo	Tipo	Descrição
id	string (uuid)	Identificador do cliente no motor — é ele que vai em subscription.customer.id
externalRef	string	Identificador do cliente no seu sistema — imutável; é a chave de reaproveitamento e o que volta em webhooks
name	string	Nome do cliente final
email	string	E-mail — é para ele que vão avisos de fatura e a nota fiscal
document	string | null	CPF/CNPJ — null quando nunca informado
phone	string | null	Telefone com DDD, só dígitos (ex.: 5511999998888) — null quando nunca informado
address	object | null	Endereço completo — null quando nunca informado. Campos abaixo
createdAt	datetime	Quando o cliente foi criado no motor
updatedAt	datetime	Última alteração dos dados

O objeto address (quando presente, todos os campos vêm):

Campo	Tipo	Descrição
address.line	string	Logradouro com número (ex.: Rua das Videiras, 52)
address.zipCode	string	CEP, 8 dígitos
address.city	string	Cidade
address.state	string	UF (ex.: MG)

Listar clientes

GET /v1/customers

Paginação padrão (page, pageSize), do mais recente ao mais antigo. Um filtro a mais:

Parâmetro	Tipo	Descrição
externalRef	string	Devolve só o cliente com este id do seu sistema — casamento exato

É o jeito de achar o id do motor sem precisar guardá-lo na adesão:

curl "$MOTOR/customers?externalRef=cliente-4512" -H "$AUTH"

Resposta 200: { data: [Cliente…], pagination } — com o filtro, data tem zero ou um item.

Detalhar cliente

GET /v1/customers/{customerId}

Resposta 200: o objeto Cliente. Erros: 404 (engine.customer_not_found).

Editar cliente

PATCH /v1/customers/{customerId}

Altera só os campos enviados; null apaga. O externalRef não muda. Use isto para corrigir um dado — repetir POST /v1/subscriptions com o mesmo externalRef não atualiza o cliente, cria outra assinatura.

Corpo (ao menos um campo):

Campo	Tipo	Descrição
name	string	1–200 caracteres
email	string	E-mail válido
document	string | null	CPF/CNPJ, 11–18 caracteres — null apaga
phone	string | null	Telefone com DDD, só dígitos (ex.: 5511999998888) — null apaga
address	object | null	Endereço completo (line, zipCode, city, state — todos obrigatórios) — null apaga

curl -X PATCH $MOTOR/customers/0199c1b2-… -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana.sales@exemplo.com.br", "document": "12345678909" }'

Resposta 200 — o objeto Cliente já atualizado:

{
  "id": "0199c1b2-…",
  "externalRef": "cliente-4512",
  "name": "Ana Beatriz Sales",
  "email": "ana.sales@exemplo.com.br",
  "document": "12345678909",
  "phone": null,
  "address": null,
  "createdAt": "2026-08-29T18:20:11.000Z",
  "updatedAt": "2026-08-30T21:40:02.000Z"
}

O que acontece depois:

• A alteração vale para as próximas faturas, notas fiscais e avisos. Faturas já emitidas não mudam.
• O motor dispara customer.updated com o retrato atual do cliente.
• O cliente espelhado no gateway é atualizado de forma assíncrona, em cada conexão da conta. O que cada gateway aceita receber:

Gateway	O que é replicado
Vindi	nome, e-mail, CPF/CNPJ, telefone (trocado no lugar) e endereço
Asaas	nome, e-mail, CPF/CNPJ, telefone, endereço e CEP
pagar.me	nome, e-mail, CPF/CNPJ, telefone e endereço
Stripe	nome, e-mail, telefone e endereço
Malga	nome e telefone — a API da Malga não aceita trocar e-mail nem documento, e exige bairro e número no endereço
Mercado Pago	nada a replicar: não há cadastro de cliente lá, os dados viajam em cada cobrança — a próxima já sai com o novo
Efí	idem Mercado Pago

Campo que o gateway não aceita fica só no motor: a fatura, a nota fiscal e os avisos saem certos; o cadastro no gateway mantém o valor antigo.

Erros: 400 (corpo vazio, ou campo inválido) · 404.