Referência¶

Valores de referência utilizados em toda a API.

Códigos de Status HTTP¶

Código	Status	Descrição
200	OK	Requisição bem-sucedida
201	Created	Recurso criado com sucesso
204	No Content	Requisição bem-sucedida sem conteúdo de retorno
400	Bad Request	Requisição inválida. Verifique os parâmetros
401	Unauthorized	Token inválido ou expirado
403	Forbidden	Sem permissão para acessar este recurso
404	Not Found	Recurso não encontrado
409	Conflict	Conflito. Registro já existe
422	Unprocessable Entity	Dados inválidos. Verifique as validações
429	Too Many Requests	Limite de requisições excedido
500	Internal Server Error	Erro interno do servidor

Enumerações¶

Status da Licença¶

Valor	Descrição
`CREATED`	Licença criada, aguardando ativação pelo usuário
`ACTIVATED`	Licença ativa e em uso
`SUSPENDED`	Licença suspensa temporariamente
`DEACTIVATED`	Licença desativada

Tipo de Pessoa¶

Valor	Documento
`FISICA`	CPF (11 dígitos)
`JURIDICA`	CNPJ (14 dígitos)

Gênero¶

Valor	Descrição
`MALE`	Masculino
`FEMALE`	Feminino

Motivos de Suspensão de Cliente¶

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

Motivos de Desativação de Cliente¶

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

Eventos de Webhook¶

Valor	Descrição
`LICENCE_CREATED_SUCCESS`	Licença criada e processada com sucesso
`LICENCE_CREATED_FAILED`	Falha na criação ou processamento da licença

Status de Entrega do Webhook¶

Valor	Descrição
`SUCCESS`	Webhook entregue com sucesso (código 2xx)
`FAILED`	Falha na entrega

Roles de Usuário¶

Valor	Descrição
`ROLE_PARTNER`	Parceiro: acesso completo aos recursos do parceiro
`ROLE_CLIENT`	Cliente: acesso aos recursos do cliente
`ROLE_BRANCH`	Filial: acesso aos recursos da filial

Paginação¶

Todos os endpoints que retornam listas utilizam paginação.

Parâmetros de Requisição¶

Parâmetro	Tipo	Descrição	Padrão
`page`	integer	Número da página (começa em 0)	0
`size`	integer	Quantidade de itens por página	20
`sort`	string	Campo e direção de ordenação (ex: `createdAt,desc`)	—

Estrutura da Resposta¶

JSON

{
  "totalPages": 10,
  "totalElements": 100,
  "numberOfElements": 10,
  "number": 0,
  "size": 10,
  "first": true,
  "last": false,
  "empty": false,
  "content": [...]
}

Campos da Resposta¶

Campo	Tipo	Descrição
`totalPages`	integer	Total de páginas disponíveis
`totalElements`	integer	Total de elementos na base
`numberOfElements`	integer	Número de elementos na página atual
`number`	integer	Número da página atual (começa em 0)
`size`	integer	Tamanho da página
`first`	boolean	Indica se é a primeira página
`last`	boolean	Indica se é a última página
`empty`	boolean	Indica se a página está vazia
`content`	array	Lista de itens da página atual

Formatos¶

Datas e Horários¶

Todas as datas seguem o formato ISO 8601:

Text Only

YYYY-MM-DDTHH:mm:ss.sssZ

Exemplo: 2025-01-27T18:07:13.353Z

Telefone¶

Campo	Formato	Exemplo
`phoneNumberCode`	Código do país	`+55`
`phoneNumber`	DDD + Número (sem formatação)	`11999999999`

Documentos¶

Tipo	Formato	Exemplo
CPF	11 dígitos (sem formatação)	`12345678901`
CNPJ	14 dígitos (sem formatação)	`12345678000199`

Limites da API¶

Rate Limiting¶

Endpoint	Limite
`POST /auth/login`	10 requisições/minuto por IP
Demais endpoints	100 requisições/minuto por token

Ao exceder o limite, a API retorna 429 Too Many Requests. Aguarde antes de fazer novas requisições.

Limites de Payload¶

Tipo	Limite
Tamanho máximo do body	1 MB
Tamanho máximo de string	255 caracteres
Tamanho máximo de observações	1000 caracteres

Headers Padrão¶

Requisição¶

Header	Valor	Obrigatório
`Authorization`	`Bearer {token}`	Sim (exceto login)
`Content-Type`	`application/json`	Sim (POST/PUT)
`Accept`	`application/hal+json`	Recomendado

Resposta¶

Header	Descrição
`Content-Type`	`application/hal+json;charset=UTF-8`
`X-Request-Id`	Identificador único da requisição