Clientes e grupos

Cadastrar

curl https://api.minstrel.com.br/v1/customers \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cliente-1234",
    "name": "Empresa Exemplo Ltda",
    "email": "financeiro@exemplo.com.br",
    "document": "12.ABC.345/01DE-35",
    "groupIds": ["cgr_01M4..."],
    "address": {
      "line1": "Avenida Paulista",
      "streetNumber": "1000",
      "district": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "postalCode": "01310-100"
    }
  }'

• externalId torna o cadastro idempotente: reenviar o mesmo cliente devolve o registro existente em vez de duplicar.
• CPF e CNPJ tem o digito verificador conferido. Documento errado so aparece tarde e caro - na nota fiscal ou na recusa do antifraude. O CNPJ alfanumerico (emitido desde julho de 2026) e aceito; documentType e deduzido pelo tamanho quando omitido.
• O numero do endereco se chama streetNumber. A chave number e recusada em qualquer corpo de requisicao pela guarda PCI, por ser o nome classico do campo de numero do cartao.

Grupos

Grupos segmentam a base ("Clientes B2B", "Parceiros", "Alto risco") e entram nas regras de fluxo como customer.groups, pelo id - renomear um grupo nao quebra a regra.

# criar
curl https://api.minstrel.com.br/v1/customer-groups \
  -d '{ "name": "Clientes B2B", "color": "#1a6cff" }'

# incluir clientes (ate 500 por chamada; quem ja e membro e ignorado)
curl https://api.minstrel.com.br/v1/customer-groups/cgr_01M4.../members \
  -d '{ "customerIds": ["cus_01HQ...", "cus_01HR..."] }'

Retire com POST /v1/customer-groups/:id/members/remove. Excluir um grupo e definitivo: os clientes saem dele e regras que o citam deixam de casar.

Cartoes

O Minstrel guarda apenas o token do cofre e dados de exibicao (bandeira, BIN, ultimos 4 digitos, validade). O cartao e tokenizado no checkout ou pelo SDK e vinculado ao cliente. No checkout transparente, o portador salva o cartao na propria compra, com saveCard: true e o consentimento dele. Pela API:

curl https://api.minstrel.com.br/v1/customers/cus_01HQ.../payment-methods \
  -d '{ "card": { "token": "tok_...", "connectorAccountId": "ca_...", "brand": "visa", "bin": "411111", "last4": "4242", "expMonth": 12, "expYear": 2029 } }'

connectorAccountId e a conta onde o token foi gerado. O token de uma adquirente so vale nela, entao as cobrancas desse cartao vao sempre para essa conta, e recusa ou falha seguem para a retentativa, nunca para outra adquirente. Se a conta for desativada ou removida, o cartao deixa de poder ser cobrado e a aba Cartoes avisa. Para conferir o cartao antes de salva-lo, veja Validar ao salvar.

Um card.token avulso em POST /v1/payments cobra uma vez e nao entra na carteira do cliente: guardar o cartao para cobrar depois exige o consentimento do portador, e o caminho e este endpoint. Por isso uma assinatura so aceita cartao salvo no proprio cliente.

O primeiro cartao vira o padrao. Um cartao que cobra assinatura em andamento nao pode ser removido: troque o cartao da assinatura antes. Cartoes invalidados pelo emissor continuam listados, com o motivo, para a equipe saber por que pedir um novo.

GET /v1/customers/:id traz tambem os indicadores do cliente: MRR, valor acumulado (capturado menos estornado, mais baixas manuais), faturas em aberto e vencidas e o ultimo pagamento.

Validar ao salvar

Antes de entrar na carteira, o cartao pode ser conferido por Zero Auth: o adquirente confirma que ele esta ativo sem cobrar nada, sem reservar limite e sem avisar o portador (o mesmo teste do no Validacao de cartao do fluxo). Cartao morto nao vira cartao salvo para falhar so na primeira cobranca.

POST /v1/customers/:id/payment-methods aceita verify:

curl https://api.minstrel.com.br/v1/customers/cus_01HQ.../payment-methods \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify": true,
    "card": { "token": "tok_...", "connectorAccountId": "ca_...", "brand": "visa", "bin": "411111", "last4": "4242", "expMonth": 12, "expYear": 2029 }
  }'

Resposta (resumida): o meio de pagamento ganha verification.

{
  "object": "payment_method",
  "id": "pm_01HQ...",
  "customerId": "cus_01HQ...",
  "type": "card",
  "brand": "visa",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2029,
  "isDefault": true,
  "verification": { "status": "valid", "verifiedAt": "2026-10-17T14:02:11.000Z" }
}

verification.status e valid, invalid ou unavailable, e verification.verifiedAt diz quando foi a validacao. A validacao emite o evento payment_method.verified.

O que acontece em cada resultado depende de como a validacao foi pedida:

A regra por tras: quando voce pede verify: true, a validacao e requisito, entao nao ser possivel valida-la e erro. Quando e so o padrao da conta, ela e um cuidado a mais e nao pode impedir o cadastro por um problema que nao e do cartao.

Ligue Validar ao salvar cartao em Plugins, na conta, em Recursos (ver Conectores). Ela depende de Validacao de cartao (Zero Auth) estar ligada na mesma conta. O Zero Auth conta nos programas de retentativa das bandeiras e pode ter custo no adquirente: valide quando o cartao entra, e no fluxo reaproveite o resultado com reuseWithinDays.