Cadastrar grupos

POST

/groups/

Cadastra um grupo de clientes para a empresa autenticada. Opcionalmente, aceita uma lista de CPF/CNPJ (clientsTaxIds) para já criar e vincular os clientes ao grupo na mesma chamada: clientes ainda não cadastrados na empresa são criados automaticamente, sujeitos às mesmas validações de bureau do cadastro individual; clientes que já existem na empresa são apenas vinculados, sem serem recriados.

Não aceita CPF de menor de idade nesse fluxo em lote — se detectado, a operação retorna erro pedindo para cadastrar esse cliente separadamente, informando a data de nascimento.

O nome do grupo deve ser único por empresa; se já existir um grupo com o mesmo nome, a operação retorna erro.

Requer autenticação via Bearer JWT ou header x-api-key.

Requisição

Authorization

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

Parâmetros Header

Parâmetros Bodyapplication/jsonNecessário

Examples

Respostas

🟢201

application/json

Harvested 201

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠404NotFound

🟠429TooManyRequests

🔴500InternalError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/groups/' \
--header 'x-api-key: SUA_CHAVE_DE_API' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "string",
    "clientsTaxIds": [
        "string"
    ]
}'

Response Example

201 - Sucesso

{
    "id": "d6c06a8f-2df4-470d-9391-9fee5d139343",
    "name": "teste-documentação",
    "kind": "group",
    "items": []
}

Modificado em 2026-10-13 09:47:06