Grupos

Grupos servem para classificar contatos (clientes ou fornecedores) por afinidade e, no contexto de cobranças, para emitir cobranças em massa (billing_issue_type=bulk) endereçadas a todos os contatos do grupo.

Antes de ler, veja as regras gerais em conventions.md — paginação, autenticação, erros, rate limit e isolamento entre contas seguem o padrão da API.

Modelo

Campo	Tipo	Observações
`id`	integer	Gerado pelo Sacador
`contact_type`	string	`"customers"` (clientes) ou `"suppliers"` (fornecedores). Não confunda com o `contact_type` de contatos, que é singular (`customer`/`supplier`)
`description`	string	Nome do grupo. Obrigatório, até 255 caracteres, único por conta (case-insensitive)
`created_at`, `updated_at`	ISO-8601

Endpoints

GET`/v1/groups`

Lista os grupos da conta autenticada, ordenados por contact_type ascendente e depois description ascendente.

Query params:

Param	Tipo	Comportamento
`contact_type`	string	Se presente, filtra exatamente por `"customers"` ou `"suppliers"`
`s`	string	Busca por substring em `description` (LIKE `%s%`)
`page`, `per_page`	int	Padrão de paginação

Exemplo cURL:

curl -X GET 'https://api.sacador.com.br/v1/groups?contact_type=customers&page=1&per_page=25' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Resposta 200 OK:

{
  "groups": [
    {
      "id": 12,
      "contact_type": "customers",
      "description": "Clientes Premium",
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-04-15T14:32:11.000Z"
    }
  ]
}

Headers X-Total-Count, X-Page, X-Per-Page, X-Total-Pages conforme conventions.md.

GET`/v1/groups/:id`

Retorna um grupo específico.

Exemplo cURL:

curl -X GET 'https://api.sacador.com.br/v1/groups/12' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Resposta 200 OK: corpo idêntico ao item da listagem.

Erros: 404 Not Found se o grupo não existir ou pertencer a outra conta.

POST`/v1/groups`

Cria um grupo.

Body:

{
  "group": {
    "contact_type": "customers",
    "description": "Clientes Premium"
  }
}

Campos aceitos:

Campo	Obrigatório	Regras
`contact_type`	sim	`"customers"` ou `"suppliers"`
`description`	sim	1..255 caracteres, único dentro da conta (case-insensitive)

Qualquer campo não listado (incluindo account_id) é silenciosamente ignorado.

Exemplo cURL:

curl -X POST 'https://api.sacador.com.br/v1/groups' \
  -H 'Authorization: Bearer sct_seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "group": {
      "contact_type": "customers",
      "description": "Clientes Premium"
    }
  }'

Resposta 201 Created: corpo idêntico a um item de GET/v1/groups (todos os campos do Modelo).

Erros 422 Unprocessable Content: - contact_type inválido - description em branco, > 255, ou já existente na conta

PATCH`/v1/groups/:id` (ou `PUT`)

Atualiza um grupo. Aceita os mesmos campos do POST. Campos omitidos no body são preservados.

Exemplo cURL:

curl -X PATCH 'https://api.sacador.com.br/v1/groups/12' \
  -H 'Authorization: Bearer sct_seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "group": {
      "description": "Clientes Premium VIP"
    }
  }'

Resposta 200 OK: corpo idêntico a um item de GET/v1/groups.

Erros: - 404 — grupo de outra conta ou inexistente - 422 — mesmas regras do POST

DELETE`/v1/groups/:id`

Apaga um grupo.

Exemplo cURL:

curl -X DELETE 'https://api.sacador.com.br/v1/groups/12' \
  -H 'Authorization: Bearer sct_seu_token_aqui'

Resposta 204 No Content: corpo vazio.

Erros: - 404 — grupo de outra conta ou inexistente - 422 Unprocessable Content — o grupo possui cobranças associadas. A exclusão é bloqueada (dependent: :restrict_with_error). Para apagar, primeiro reassocie ou cancele as cobranças. Contatos que apontavam para o grupo têm seu group_id setado para null automaticamente, então essa não é uma razão para 422.

{
  "status": 422,
  "errors": ["Não é possível excluir o registro pois existem cobranças dependentes"]
}