Clientes

O recurso Clientes (/customers) mantém o cadastro de clientes do tenant — pessoas físicas (individual) ou jurídicas (company). Assim como produtos, clientes têm campos universais e extensões por país (br_data, us_data).

Permissão exigida: customers (ações create, read, update, delete).

Conceitos e campos-chave

Na API de Integrações, tax_id é obrigatório ao criar um cliente. Diferente de outros contextos internos do bitERP, onde ele é opcional.

tax_id — CPF/CNPJ e EIN/SSN

O tax_id é normalizado antes de ser gravado e comparado: tudo que não é letra ou dígito é removido e o valor é convertido para maiúsculas. Ou seja, 12.345.678/0001-95 e 12345678000195 representam o mesmo cliente. A API não valida dígitos verificadores de CPF/CNPJ nem o formato de EIN/SSN — ela apenas normaliza e garante unicidade por tenant. Envie o tax_id_type que se aplica ao documento; ele é gravado como veio.

Endereço e geografia

Você pode informar cidade e estado por texto (city, state) — que a API resolve para o catálogo interno — ou diretamente pelos IDs do catálogo (city_id, state_id, obtidos via Dados de referência). Um ID inexistente ou um country_code não resolvível retorna 422 Unprocessable Entity. Na resposta, cidade, estado e país vêm resolvidos como objetos (city: { id, name }, state: { id, state_code, name }, country: { id, iso2, iso3, name }).

Criar um cliente

curl -X POST https://api.biterp.ai/customers \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "tax_id": "12.345.678/0001-95",
    "tax_id_type": "CNPJ",
    "legal_name": "Comercial Exemplo LTDA",
    "trade_name": "Exemplo Store",
    "emails": ["contato@exemplo.com.br"],
    "phones": ["+55 11 4002-8922"],
    "address_line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country_code": "BR",
    "br_data": {
      "ie": "123.456.789.012",
      "ie_exempt": false,
      "tax_regime": "simples_nacional"
    }
  }'

Buscar clientes

Além da listagem paginada (GET /customers, com filtros e paginação):

# Localizar por documento (pontuação é ignorada)
curl "https://api.biterp.ai/customers/tax-id/12345678000195" \
  -H "Authorization: Bearer sk_abc123_secretXYZ"

Campos filtráveis em GET /customers: legal_name, trade_name, tax_id, type, city, state, country_code, is_active, reference_code, tags, created_at, updated_at. Ordenação por id, legal_name, trade_name, reference_code, created_at, updated_at.

Remover

DELETE /customers/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints

Veja também