Bem-vindo à documentação do Módulo de Clientes. Este módulo é responsável por concentrar, gerenciar e estruturar as informações de clientes, blocos operacionais, localizações geográficas e veículos associados à plataforma.

Esta documentação está dividida em 4 seções principais:

Fundamentos — Entenda as regras de negócio e os conceitos-chave.
Fluxo de Trabalho (Workflow) — Compreenda a ordem correta das integrações e o fluxo de dados.
Referência de Endpoints — Veja as especificações técnicas de cada rota (Headers, Payloads e Schemas).
Erros e Resolução de Problemas — Saiba como tratar as respostas da API e solucionar problemas.

Fundamentos

Antes de iniciar o desenvolvimento de suas integrações, familiarize-se com os principais conceitos de negócio que compõem o ecossistema de Gestão de Clientes.

Cliente

O cliente representa a entidade jurídica (empresa) cadastrada e habilitada na plataforma. Um cliente é o nó central de todas as operações e pode possuir usuários, blocos operacionais e veículos associados.

Estrutura de Clientes (Hierarquia)

Os clientes podem ser organizados de forma hierárquica (relação pai e filho):

Cliente Pai (isParent: true): É o registro principal na hierarquia da plataforma.
Cliente Filho: Vincula-se a um cliente pai através do campo parentId.

Cliente Pai (isParent: true) → Cliente Filho (parentId)

Bloco

Representa uma estrutura ou filial física vinculada a um cliente. Cada bloco possui identificadores únicos (blockCode, tag) e obrigatoriamente aponta para um endereço físico estruturado.

Cliente → possui → Bloco → localizado em → Endereço

Localização

As informações geográficas na plataforma seguem uma hierarquia rígida de dependência. Esse design garante consistência cadastral e evita erros manuais de digitação:

País (countryId) → Estado (stateId) → Cidade (cityId)

Para qualquer associação de endereço, a plataforma exige o identificador exclusivo da cidade (cityId), que por sua vez resolve suas dependências de estado e país de forma automatizada.

Entidade Geográfica	Identificador em API	Descrição
País	`countryId`	Código numérico identificador do país.
Estado	`stateId`	Código numérico identificador do estado/província.
Cidade	`cityId`	Código numérico identificador do município.

Veículos

Os veículos representam a frota ativa associada a um cliente específico para fins de logística e operacionalização. A vinculação é feita unicamente através do registro da placa do veículo. Um cliente pode possuir múltiplos veículos sob sua gestão.

Relação Geral entre os Recursos

A árvore estrutural completa abaixo demonstra graficamente como as entidades do Módulo de Clientes se relacionam e se aninham:

Cliente → [ Veículos ] (vínculo direto via placa)

Cliente → [ Bloco ] (estrutura operacional) → Endereço → Cidade (cityId) → Estado (stateId) → País (countryId)

Fluxo de Trabalho (Workflow)

Esta seção descreve os caminhos de integração recomendados para garantir que sua aplicação utilize as APIs de forma otimizada e livre de inconsistências cadastrais.

Pré-requisitos de Integração

Consumir as credenciais de autenticação válidas (Bearer Token ou similar dependendo do ambiente).
Garantir acesso de rede liberado às rotas expostas.
Compreender os mapeamentos de dados detalhados na etapa de Fundamentos.

Fluxo 1: Resolução Hierárquica de Localização

Para realizar operações de cadastro ou atualização de endereços, você não deve enviar nomes em texto simples. Em vez disso, resolva a árvore de geolocalização passo a passo conforme o fluxo a seguir:

Consultar Países → obter countryId → Consultar Estados → obter stateId → Consultar Cidades → obter cityId

Obter o País: Chame a API de países para identificar o ID do país de operação.
Filtrar o Estado: Utilize o ID retornado anteriormente para listar os estados correspondentes.
Filtrar a Cidade: Com o ID do estado, busque as cidades disponíveis e salve o cityId retornado. Ele será necessário nos fluxos de criação de blocos e endereços.

Fluxo 2: Consulta de Blocos Cadastrados

O endpoint de blocos retorna uma listagem paginada para garantir alta performance. Ao consumir este fluxo, atente-se às seguintes boas práticas de paginação:

Consumir GET /blocks → Validação paginal

Se empty: true → Fim da lista / Sem Registros.

Se empty: false → Processar itens do array content → Chamar próxima página (page + 1).

Nota de Integração: Uma resposta sem registros (página vazia) não indica necessariamente uma falha de sistema. Sempre verifique as propriedades de paginação (empty e content) antes de assumir erros na requisição.

Fluxo 3: Fluxo de Cadastro Completo (Cliente + Veículo)

Ao registrar um novo cliente na plataforma, a operação pode ser realizada de forma atômica, enviando os dados do cliente, do usuário administrador associado e a frota de veículos inicial em uma única chamada.

Fornecer Dados do Cliente → Definir Usuário Responsável → Associar Placas de Veículos → Chamar POST /customer-register → Em caso de Sucesso → Retorna ID gerado [ customer_id ]

Referência de Endpoints

Blocos

Consultar Blocos Cadastrados

Retorna a listagem paginada de todos os blocos cadastrados e seus respectivos relacionamentos de cliente e endereço.

Endpoint: api/v2/blocks

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`page`	integer	Não	0	Número da página a ser recuperada.
`size`	integer	Não	30	Limite de registros por página.

Exemplo de Requisição:

GET api/v2/blocks?page=0&size=30 HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

Response:

Bloco Principal

Campo	Tipo	Descrição
`id`	integer	Identificador único do bloco na plataforma.
`blockCode`	string	Código interno atribuído ao bloco.
`tag`	string	Tag de identificação ou classificação visual do bloco.
`parentId`	integer	Identificador do cliente relacionado ao bloco.

Detalhes do Cliente (parent object)

Campo	Tipo	Descrição
`id`	integer	Identificador único do cliente.
`clientCode`	string	Código cadastral do cliente.
`sapId`	string	ID de integração com o sistema SAP corporativo.
`corporateName`	string	Razão Social do cliente.
`tradingName`	string	Nome fantasia da marca.
`taxIdentifier`	string	Identificador fiscal (CNPJ/CPF).
`isParent`	boolean	Flag indicando se é um cliente pai na hierarquia.
`clientType`	string	Tipo operacional/comercial do cliente.

Detalhes do Endereço do Bloco (address object)

Campo	Tipo	Descrição
`street`	string	Logradouro / Nome da rua.
`zipCode`	string	CEP (Código de Endereçamento Postal).
`number`	string	Número do imóvel.
`district`	string	Bairro.
`complement`	string	Complemento adicional do endereço.
`cityId`	integer	ID relacional da cidade cadastrada na plataforma.
`cityName`	string	Nome textual da cidade correspondente.
`stateName`	string	Nome do estado correspondente.
`countryName`	string	Nome do país correspondente.

Estrutura de Paginação (page metadata)

Campo	Tipo	Descrição
`totalElements`	integer	Total acumulado de registros no banco de dados.
`totalPages`	integer	Total de páginas disponíveis para consulta baseadas no size.
`size`	integer	Quantidade de registros solicitada por página.
`number`	integer	Índice da página atualmente retornada.
`first`	boolean	Sinaliza se a página atual é a primeira.
`last`	boolean	Sinaliza se a página atual é a última.
`empty`	boolean	Indica se a página atual não possui registros em `content`.

Localização

Consultar Países

Retorna todos os países cadastrados na plataforma.

Endpoint: api/countries

Método: GET

Resposta de Exemplo:

[
  {
    "id": 1,
    "name": "Brazil",
    "code": "BR",
    "currencyId": 1,
    "localeId": 1
  }
]

Detalhe dos Campos de Resposta

Campo	Tipo	Descrição
`id`	integer	Identificador único do país na plataforma.
`name`	string	Nome completo do país em inglês/localizado.
`code`	string	Código de duas letras padrão ISO (ex: BR, US).
`currencyId`	integer	Identificador relacional da moeda oficial.
`localeId`	integer	Identificador das configurações regionais de exibição.

Consultar Estados de um País

Busca os estados que pertencem a um determinado país com opção de filtros textuais.

Endpoint: states/filters

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`countryId`	integer	Sim	ID relacional do país associado aos estados desejados.
`name`	string	Não	Filtro para buscar estados correspondentes ao nome enviado.

Resposta de Exemplo:

[
  {
    "id": 1,
    "name": "São Paulo",
    "countryId": 1
  }
]

Consultar Cidades de um Estado

Busca as cidades que pertencem a um determinado estado.

Endpoint: api/cities/filters

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`stateId`	integer	Sim	ID relacional do estado associado às cidades.
`name`	string	Não	Filtro para buscar cidades pelo nome ou parte do nome.

Resposta de Exemplo:

[
  {
    "id": 1,
    "name": "Campinas",
    "stateId": 1
  }
]

Cadastrar Cliente e Veículos

Realiza o registro unificado de um novo cliente corporativo, com seu respectivo gestor e frota de veículos.

Endpoint: customer-register

Método: POST

Headers: Content-Type: application/json

Exemplo de Payload de Envio (Request Body):

{
  "cnpj": "12345678000199",
  "user": {
    "name": "Example User",
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "vehicles": [
    "ABC1D23",
    "XYZ9A87"
  ],
  "manager": true
}

Detalhe dos Campos de Entrada (Request Schema)

Campo	Tipo	Obrigatório	Descrição
`cnpj`	string	Sim	Número do CNPJ contendo apenas números ou formatado.
`manager`	boolean	Sim	Indica se o usuário enviado no payload deve ser configurado como gestor da conta.
`vehicles`	array of strings	Não	Lista contendo as placas dos veículos associados a este cliente.

Objeto do Usuário (user object)

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo do usuário.
`email`	string	Sim	Endereço de correio eletrônico corporativo único do usuário.
`phone`	string	Sim	Telefone de contato estruturado em padrão internacional (DDI + DDD + Número).

Exemplo de Resposta (Status 200 OK):

{
  "customer_id": 123
}

Erros e Resolução de Problemas

Sempre que a sua aplicação interagir com as nossas APIs, verifique os códigos de status HTTP para determinar o sucesso ou a necessidade de correção das requisições.

Códigos de Status HTTP

Status HTTP	Causa Provável	Ação Recomendada
200 OK ou 201 Created	A transação foi efetuada e validada com sucesso.	Prossiga com o processamento dos dados retornados.
400 Bad Request	Envio de payloads inválidos, falta de parâmetros obrigatórios, ou formatação de dados incompatível.	Valide o contrato de dados. Verifique formatos de e-mail, numeração de CNPJ e a presença de campos mandatórios.
401 Unauthorized	O token de autenticação enviado é inválido, está expirado ou ausente no Header.	Renove o token de autenticação utilizando suas chaves de API válidas e certifique-se de anexá-lo corretamente.
403 Forbidden	O cliente autenticado não possui permissão para acessar o recurso específico ou filial solicitada.	Entre em contato com seu gestor de conta para garantir que seu perfil tenha as roles necessárias para esta operação.
500 Internal Server Error	Falha inesperada no processamento por parte do nosso servidor.	Salve os detalhes do erro e aguarde alguns minutos antes de efetuar uma nova tentativa de envio.

Dicas de Resolução de Problemas

Validando Placas de Veículos: Ao enviar registros no array vehicles do endpoint customer-register, garanta que as strings estejam formatadas sem espaços ou hífens, utilizando preferencialmente o padrão Mercosul (ABC1D23) ou antigo brasileiro (ABC1234).
Como Lidar com Registros Não Localizados em Filtros: Se consultas aos endpoints states/filters ou api/cities/filters retornarem um array vazio ([]), certifique-se de que o ID pai (countryId ou stateId) correspondente está correto. Filtros de texto por name são case-sensitive em alguns cenários — tente pesquisar utilizando caracteres comuns e omitindo acentuações caso não localize registros de imediato.