Clientes

O endpoint de clientes permite criar, consultar e atualizar cadastros de pessoas físicas (PF) e jurídicas (PJ) no CGD. Ao criar um cliente, o CGD retorna automaticamente um integration_code — use esse código para referenciar o cliente em chamadas futuras (orçamentos, pedidos etc.).

Endpoints

Método	Endpoint	Descrição
`GET`	`/customers`	Listar clientes
`POST`	`/customers`	Criar cliente
`GET`	`/customers/{id}`	Buscar cliente por ID
`GET`	`/customers/by-code/{integration_code}`	Buscar cliente pelo integration_code
`PUT`	`/customers/{id}`	Atualizar cliente

Listar clientes

curl -X GET "https://gds.fretatech.com.br/api/partner/v1/customers?type=company&search=exemplo" \
  -H "Authorization: Bearer SEU_TOKEN"

Parametros de filtro

Parametro	Tipo	Descricao
`search`	string	Busca por nome, documento ou e-mail
`type`	string	`individual` (PF) ou `company` (PJ)
`integration_code`	string	Filtra pelo codigo de integracao do seu sistema
`page`	integer	Numero da pagina (padrao: 1)
`per_page`	integer	Itens por pagina (padrao: 15, maximo: 100)

Resposta

{
  "data": [
    {
      "id": "01jk2m3n4p5q6r7s8t9u0vwxyz",
      "name": "Empresa Exemplo Ltda",
      "type": "company",
      "document": "12345678000195",
      "email": "contato@exemplo.com.br",
      "phone": "11999990000",
      "integration_code": "ERP-CLIENTE-001",
      "created_at": "2026-01-10T09:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42
  }
}

Criar cliente

curl -X POST https://gds.fretatech.com.br/api/partner/v1/customers \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "type": "individual",
    "cnpj_cpf": "12345678901",
    "email": "joao.silva@email.com",
    "tel": "11988887777"
  }'

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo (PF) ou razão social (PJ)
`type`	string	Sim	`individual` para PF, `company` para PJ
`cnpj_cpf`	string	Não	CPF (PF, 11 dígitos) ou CNPJ (PJ, 14 dígitos), apenas dígitos
`email`	string	Não	E-mail de contato (único por CGD)
`tel`	string	Não	Telefone principal com DDD
`last_name`	string	Não	Sobrenome (PF)
`trade_name`	string	PJ obrigatório	Nome fantasia da empresa
`responsible`	string	PJ obrigatório	Nome do responsável

Diferença entre tipos

Campo	PF (`individual`)	PJ (`company`)
`cnpj_cpf`	CPF (11 dígitos)	CNPJ (14 dígitos)
`name`	Nome completo	Razão social
`trade_name`	—	Obrigatório
`responsible`	—	Obrigatório

Resposta

{
  "success": true,
  "data": {
    "id": 42,
    "name": "João Silva",
    "type": "individual",
    "cnpj_cpf": "12345678901",
    "email": "joao.silva@email.com",
    "tel": "11988887777",
    "integration_code": "42",
    "created_at": "2026-03-06T14:00:00.000000Z"
  }
}

O campo integration_code é gerado automaticamente pelo CGD no momento da criação e corresponde ao ID interno do cliente. Salve esse valor no seu sistema para referenciar este cliente em orçamentos, pedidos e consultas futuras.

Buscar cliente por ID

curl -X GET https://gds.fretatech.com.br/api/partner/v1/customers/01jk2m3n4p5q6r7s8t9u0vwxyz \
  -H "Authorization: Bearer SEU_TOKEN"

Atualizar cliente

Apenas os campos enviados serao atualizados (PATCH semantics via PUT):

curl -X PUT https://gds.fretatech.com.br/api/partner/v1/customers/01jk2m3n4p5q6r7s8t9u0vwxyz \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "novo.email@exemplo.com.br",
    "phone": "11977776666"
  }'

Buscar por integration_code

Use este endpoint para encontrar um cliente pelo integration_code que você salvou no seu sistema:

curl -X GET https://gds.fretatech.com.br/api/partner/v1/customers/by-code/42 \
  -H "Authorization: Bearer SEU_TOKEN"

Você também pode usar o filtro integration_code na listagem:

curl -X GET "https://gds.fretatech.com.br/api/partner/v1/customers?integration_code=42" \
  -H "Authorization: Bearer SEU_TOKEN"

O campo integration_code

O integration_code é atribuído automaticamente pelo CGD no momento da criação do cliente. Seu valor é o ID interno do cliente no CGD. Fluxo recomendado:

Crie o cliente via POST /customers
Salve o integration_code retornado na resposta no seu sistema
Use esse código para buscar o cliente em chamadas futuras (GET /customers/by-code/{code})
Ao criar orçamentos ou pedidos, referencie o cliente pelo integration_code

Início

Referência

Endpoints

Listar clientes

Parametros de filtro

Resposta

Criar cliente

Campos da requisição

Diferença entre tipos

Resposta

Buscar cliente por ID

Atualizar cliente

Buscar por integration_code

O campo integration_code

​Endpoints

​Listar clientes

​Parametros de filtro

​Resposta

​Criar cliente

​Campos da requisição

​Diferença entre tipos

​Resposta

​Buscar cliente por ID

​Atualizar cliente

​Buscar por integration_code

​O campo integration_code

Endpoints

Listar clientes

Parametros de filtro

Resposta

Criar cliente

Campos da requisição

Diferença entre tipos

Resposta

Buscar cliente por ID

Atualizar cliente

Buscar por integration_code

O campo integration_code