Automação de cobrança do cliente

PUT /api/{userId}/establishment/{establishmentId}/clients/{clientId}/charge-automations

Configura/atualiza automações relacionadas à cobrança do cliente (vínculos “operacionais” como tabelas de preço e serviços que alimentam o fluxo de cobrança).

As tabelas de preço utilizadas neste endpoint são cadastradas e gerenciadas na tela Tabelas de Preço (Site Admin).

Parâmetros de rota

Nome	Tipo	Descrição
userId	number	Identificador do usuário
establishmentId	number	Identificador do estabelecimento
clientId	string	Identificador do cliente

Corpo (JSON)

Campo	Tipo	Obrigatório	Descrição
establishmentId	number	sim	Estabelecimento
typePrices	array<string>	não	Lista de nomes das tabelas de preço (coluna typePrice de jump_prices). Cada item deve ser uma string, nunca um ID numérico. Consulte o aviso abaixo.
services	array<number>	não	Lista de IDs de serviço (inteiros).
userId	number	não	Usuário responsável.
clientTypeId	number	não	Tipo do cliente (quando o backend usa para regras específicas).

:::warning typePrices é array de strings, não de IDs Cada item de typePrices é o nome da tabela de preço (coluna typePrice em jump_prices). Enviar números inteiros não funciona: o backend procura a tabela de preço pelo nome via Price::view($establishmentId, $typePrice) e itens que não casem com um nome existente são silenciosamente ignorados (não geram erro, mas também não criam vínculo).

Essa mesma convenção é aplicada pelas validações dos endpoints correlatos:

• PUT /clients/{clientId}/type-prices-link — typePricesLink.* é nullable|string|max:255 (UpdateClientTypePricesLinkRequest).
• PUT /clients/{clientId}/restrictions — restrictionTypePrice é nullable|string (UpdateClientRestrictionsRequest).

Errado vs. Correto

❌ Errado — passando IDs numéricos (nada é vinculado):

{
  "establishmentId": 7724,
  "typePrices": [101, 102, 103]
}

✅ Correto — passando os nomes das tabelas de preço:

{
  "establishmentId": 7724,
  "typePrices": ["Rotativo", "Mensalista", "Diária"]
}

Dica: os nomes válidos são exatamente os cadastrados na tela Tabelas de Preço (Site Admin). Consulte-a para obter os nomes disponíveis antes de chamar este endpoint. :::

Requisição

• Método: PUT
• Path: /api/\{userId\}/establishment/\{establishmentId\}/clients/\{clientId\}/charge-automations
• Headers: Authorization, Accept: application/json, Content-Type: application/json

Formato da resposta (JSON)

• Sucesso (HTTP 200): { "response": "success", "data": <payload> }
• Erro de validação (HTTP 422): retorna os erros por campo
• Erro (HTTP 400): { "response": "error", "data": { "msg": "...", "code": "..." } }

Exemplo de resposta (JSON)

Valores ilustrativos; a forma dos campos segue o retorno real.

{
  "response": "success",
  "data": {
    "clientId": "772420260215093421",
    "establishmentId": 7724,
    "typePrices": ["Rotativo", "Mensalista"],
    "services": [501, 502, 503],
    "status": 1
  }
}

:::info Origem dos valores para exibir typePrices e services Para mostrar (renderizar na tela, em listas, dropdowns, etc.) quais tabelas de preço e serviços estão vinculados ao cliente, use exatamente o que vem no retorno do próprio endpoint — tanto da resposta deste PUT, quanto dos endpoints que retornam o cliente (ex.: Visualização do cliente).

Não há endpoint separado para buscar "os valores vinculados" nem é necessário cruzar IDs ou consultar outra tabela: os campos typePrices e services do próprio payload de resposta já são a fonte de verdade para exibição.

O formato também é simétrico entre leitura e escrita: os valores retornados nesses campos podem ser reenviados sem transformação como body de um próximo PUT /clients/{clientId}/charge-automations.

Campo	Tipo retornado	Origem interna
typePrices	array<string> — nomes das tabelas de preço.	ClientTypePrice::list() → coluna typePrice de jump_client_type_prices.
services	array<number> — IDs dos serviços.	ClientService::list() → coluna serviceId de jump_client_services.

Exemplo prático:

// 1. Busca o estado atual do cliente
const { data } = await api.get(`/clients/${clientId}?establishmentId=${establishmentId}`);

// 2. Exibe na UI exatamente o que veio
renderTypePrices(data.typePrices); // ex.: ["Rotativo", "Mensalista"]
renderServices(data.services);     // ex.: [501, 502, 503]

// 3. Após ajustes do usuário, envia de volta no mesmo formato
await api.put(`/clients/${clientId}/charge-automations`, {
  establishmentId,
  typePrices: data.typePrices, // array de strings
  services: data.services,     // array de números
});

:::

Nuâncias

• Se typePrices vier no payload, o backend trata como sincronização: remove todos os vínculos existentes em jump_client_type_prices e recria com base na lista enviada. Enviar "typePrices": [] limpa todas as tabelas vinculadas ao cliente.
• Cada item de typePrices é validado individualmente por nome (Price::view); nomes inexistentes para o establishmentId são ignorados sem erro. Os nomes válidos correspondem aos cadastrados em Tabelas de Preço (Site Admin).
• O mesmo comportamento de sincronização se aplica a services (usando IDs inteiros).
• Simetria leitura/escrita: os valores de typePrices e services retornados pelos endpoints de leitura (GET /clients/{clientId}) podem ser repassados sem transformação no corpo deste endpoint.