Cadastrar cliente em um grupo

POST

/groups/{groupId}/clients

Cadastra um cliente na empresa do usuário a partir do CPF ou CNPJ e o vincula ao grupo informado em groupId. taxId é obrigatório e aceita o número com ou sem máscara; birthDate é opcional e deve ser enviada quando o CPF for de menor de idade. Os dados cadastrais do cliente são buscados numa consulta cadastral externa. Se o CPF ou CNPJ já estiver cadastrado e ativo na empresa, devolve 400 com clientId e clientName do cadastro existente: para colocar um cliente que já existe num grupo, use a rota de adicionar cliente a um grupo. Se estiver cadastrado e removido, o cliente é reativado e vinculado ao grupo. O cliente é cadastrado antes de o grupo ser conferido: com grupo inexistente a resposta é 400, mas o cliente já foi criado. Devolve id, kind e taxId do cliente. Corpo fora do formato devolve 422. 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 de Caminho

Parâmetros Header

Parâmetros Bodyapplication/jsonNecessário

Examples

Respostas

🟢201

application/json

Cliente cadastrado e vinculado ao grupo

Bodyapplication/json

🟠400BadRequest

🟠401Unauthorized

🟠404NotFound

🟠429TooManyRequests

🔴500InternalError

🟠400Cadastro recusado

🟠422taxId inválido

Request Example

Shell

JavaScript

Java

Swift

curl --location '/groups/f1a2b3c4-0000-4000-8000-000000000901/clients' \
--header 'x-api-key: SUA_CHAVE_DE_API' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "taxId": "11222333000181"
}'

Response Example

201 - Sucesso

{
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "kind": "legal",
    "taxId": "11222333000181"
}

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

Página anterior

Listar clientes de um grupo

Próxima página

Consultar totais de clientes de um grupo