Pular para conteúdo
Postman

Clientes

Endpoints para criação e gerenciamento de clientes na plataforma.

GET /clients

Retorna uma lista paginada de clientes do parceiro autenticado.

Parâmetros da Query

Nome Tipo Obrigatório Descrição
page integer não Número da página (padrão: 0)
size integer não Itens por página (padrão: 20)
sort string não Ordenação (ex: name,asc)
index string não Filtro de busca por texto

Cabeçalhos

Header Valor
Authorization Bearer {token}
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X GET "https://api-portal.mediquo.com.br/clients?page=0&size=20" \
  -H "Authorization: Bearer {seu_token}" \
  -H "Accept: application/hal+json"

Respostas

Código Descrição
200 Lista paginada de clientes
401 Token inválido ou expirado
403 Sem permissão

Para detalhes sobre a estrutura de paginação, consulte Referência → Paginação.

GET /clients/{id}

Retorna os dados de um cliente específico.

Parâmetros do Path

Nome Tipo Obrigatório Descrição
id integer sim ID do cliente

Cabeçalhos

Header Valor
Authorization Bearer {token}
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X GET https://api-portal.mediquo.com.br/clients/1 \
  -H "Authorization: Bearer {seu_token}" \
  -H "Accept: application/hal+json"

Respostas

Código Descrição
200 Dados do cliente
401 Token inválido ou expirado
403 Sem permissão
404 Cliente não encontrado

POST /clients

Cria um novo cliente vinculado ao parceiro autenticado.

Corpo da Requisição

Campo Tipo Obrigatório Descrição
partnerId integer sim ID do parceiro
name string sim Nome do cliente
email string sim E-mail do cliente
personType string sim FISICA ou JURIDICA
documentNumber string sim CPF ou CNPJ (somente números)
active boolean sim true para criar ativo
phoneNumber string não Telefone do cliente
maxLicenses integer não Limite máximo de licenças
userRoot object não Dados do usuário administrador do cliente

Objeto userRoot

Campo Tipo Obrigatório Descrição
fullName string sim Nome completo
email string sim E-mail de acesso
password string sim Senha de acesso

O userRoot cria o usuário administrador que acessa o portal web do cliente.

Cabeçalhos

Header Valor
Authorization Bearer {token}
Content-Type application/json
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X POST https://api-portal.mediquo.com.br/clients \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": 1,
    "name": "Empresa Exemplo LTDA",
    "email": "contato@empresa.com",
    "personType": "JURIDICA",
    "documentNumber": "12345678000199",
    "active": true,
    "phoneNumber": "11999999999",
    "userRoot": {
      "fullName": "Administrador",
      "email": "admin@empresa.com",
      "password": "senha_segura_123"
    }
  }'

Resposta de Sucesso: 200 OK

JSON
{
  "id": 1,
  "partnerId": 1,
  "name": "Empresa Exemplo LTDA",
  "email": "contato@empresa.com",
  "personType": "JURIDICA",
  "documentNumber": "12345678000199",
  "active": true,
  "phoneNumber": "11999999999",
  "mediquoApiId": "api-id-gerado",
  "mediquoApiKey": "api-key-gerada",
  "mediquoApiSecret": "api-secret-gerado",
  "currentStatus": "ACTIVATED",
  "createdAt": "2025-01-27T10:00:00.000Z",
  "updatedAt": "2025-01-27T10:00:00.000Z"
}

Respostas de Erro

Código Descrição
400 Campos obrigatórios ausentes ou inválidos
401 Token inválido ou expirado
403 Sem permissão
409 Já existe um cliente com esse documento
422 Dados inválidos

PUT /clients/{id}

Atualiza os dados de um cliente.

Parâmetros do Path

Nome Tipo Obrigatório Descrição
id integer sim ID do cliente

Corpo da Requisição

Campo Tipo Obrigatório Descrição
name string sim Nome do cliente
personType string sim FISICA ou JURIDICA
email string não E-mail do cliente
phoneNumber string não Telefone do cliente
documentNumber string não CPF ou CNPJ
active boolean não Status do cliente
maxLicenses integer não Limite máximo de licenças

Cabeçalhos

Header Valor
Authorization Bearer {token}
Content-Type application/json
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X PUT https://api-portal.mediquo.com.br/clients/1 \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa Exemplo Atualizada LTDA",
    "personType": "JURIDICA",
    "email": "novo@empresa.com"
  }'

Respostas

Código Descrição
200 Cliente atualizado. Retorna o objeto completo
400 Requisição inválida
401 Token inválido ou expirado
403 Sem permissão
404 Cliente não encontrado

Ciclo de Vida do Cliente

Um cliente pode transitar entre os estados abaixo. Escolha a operação adequada conforme a intenção:

Suspensão Desativação
Intenção Pausa temporária Encerramento definitivo
Licenças Pausadas (recuperáveis) Canceladas (não recuperáveis)
Reversibilidade Total Parcial (sem licenças)
Caso de uso Inadimplência, verificação Encerramento de contrato

PUT /clients/suspend/{id}

Suspende um cliente ativamente. Use para interrupções temporárias com expectativa de retorno.

Ao suspender:

  • Licenças ativas passam para status SUSPENDED e são pausadas no chat
  • Todos os usuários perdem acesso ao sistema
  • Todas as filiais e integrações são suspensas

Só é possível suspender um cliente com status ativo. Clientes desativados não podem ser suspensos.

Parâmetros do Path

Nome Tipo Obrigatório Descrição
id integer sim ID do cliente

Corpo da Requisição

Campo Tipo Obrigatório Descrição
reason string (enum) sim Motivo da suspensão
description string não Descrição complementar

Valores de reason:

Valor Descrição
NON_PAYMENT Inadimplência
CLIENT_REQUEST Solicitação do cliente
VERIFICATION Verificação interna
OPERATIONAL_IRREGULARITY Irregularidade operacional
OTHER Outro

Cabeçalhos

Header Valor
Authorization Bearer {token}
Content-Type application/json
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X PUT https://api-portal.mediquo.com.br/clients/suspend/1 \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "NON_PAYMENT",
    "description": "Fatura em aberto há 30 dias"
  }'

Respostas

Código Descrição
200 Cliente suspenso
401 Token inválido ou expirado
403 Sem permissão
404 Cliente não encontrado
422 Cliente já desativado. Não pode ser suspenso

PUT /clients/unsuspend/{id}

Reverte a suspensão de um cliente. Restaura completamente o estado anterior.

Ao desbloquear:

  • Licenças suspensas voltam para ACTIVATED e são despausadas no chat
  • Usuários recuperam acesso ao sistema
  • Filiais e integrações são reativadas
  • O motivo da suspensão é limpo

Parâmetros do Path

Nome Tipo Obrigatório Descrição
id integer sim ID do cliente

Cabeçalhos

Header Valor
Authorization Bearer {token}
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X PUT https://api-portal.mediquo.com.br/clients/unsuspend/1 \
  -H "Authorization: Bearer {seu_token}"

Respostas

Código Descrição
200 Suspensão revertida
401 Token inválido ou expirado
403 Sem permissão
404 Cliente não encontrado

PUT /clients/deactivate/{id}

Desativa um cliente de forma permanente. Use apenas para encerramento definitivo.

Ao desativar:

  • Todas as licenças são enviadas para cancelamento
  • Todos os usuários do cliente são desativados
  • Todas as filiais, integrações e pacientes são desativados

Ação irreversível para licenças

Licenças canceladas não são recuperadas na reativação. Precisam ser recriadas manualmente.

Parâmetros do Path

Nome Tipo Obrigatório Descrição
id integer sim ID do cliente

Corpo da Requisição

Campo Tipo Obrigatório Descrição
reason string (enum) sim Motivo da desativação
description string não Descrição complementar

Valores de reason:

Valor Descrição
CONTRACT_EXPIRATION Expiração de contrato
CONTRACT_TERMINATION Rescisão de contrato
MEDIQUO_DECISION Decisão MediQuo
CLIENT_ACTIVITY_END Encerramento de atividade do cliente
PORTFOLIO_MIGRATION Migração de portfólio
OTHERS Outro

Cabeçalhos

Header Valor
Authorization Bearer {token}
Content-Type application/json
Accept application/hal+json

Exemplo de Requisição

Bash
curl -X PUT https://api-portal.mediquo.com.br/clients/deactivate/1 \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CONTRACT_EXPIRATION",
    "description": "Contrato encerrado em 31/01/2025"
  }'

Respostas

Código Descrição
200 Cliente desativado
401 Token inválido ou expirado