Skip to main content
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étodoEndpointDescrição
GET/customersListar clientes
POST/customersCriar 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

ParametroTipoDescricao
searchstringBusca por nome, documento ou e-mail
typestringindividual (PF) ou company (PJ)
integration_codestringFiltra pelo codigo de integracao do seu sistema
pageintegerNumero da pagina (padrao: 1)
per_pageintegerItens 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

CampoTipoObrigatórioDescrição
namestringSimNome completo (PF) ou razão social (PJ)
typestringSimindividual para PF, company para PJ
cnpj_cpfstringNãoCPF (PF, 11 dígitos) ou CNPJ (PJ, 14 dígitos), apenas dígitos
emailstringNãoE-mail de contato (único por CGD)
telstringNãoTelefone principal com DDD
last_namestringNãoSobrenome (PF)
trade_namestringPJ obrigatórioNome fantasia da empresa
responsiblestringPJ obrigatórioNome do responsável

​
Diferença entre tipos

CampoPF (individual)PJ (company)
cnpj_cpfCPF (11 dígitos)CNPJ (14 dígitos)
nameNome completoRazã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:
  1. Crie o cliente via POST /customers
  2. Salve o integration_code retornado na resposta no seu sistema
  3. Use esse código para buscar o cliente em chamadas futuras (GET /customers/by-code/{code})
  4. Ao criar orçamentos ou pedidos, referencie o cliente pelo integration_code