Pular para o conteúdo
PTEN

Clientes

Sincronize a sua base de dados de organizações e potenciais clientes.

Visão geral

O objeto Cliente contém o cadastro mestre comercial das pessoas ou organizações que você fatura. Sincronizar clientes pela API é a base para manter o Cord perfeitamente alinhado ao seu ERP ou CRM (como Salesforce ou HubSpot).

Criar um cliente

Crie um novo cliente enviando um POST /api/v1/clientes. O único campo estritamente obrigatório é o nome da empresa (empresa); o restante é opcional e depende do seu negócio e do seu país. rfc é a identificação fiscal mexicana (Registro Federal de Contribuyentes) — só se aplica se o seu cliente for faturado no México. Se o seu negócio ou o seu cliente estiver em outro país, simplesmente omita o campo; o Cord não exige um rfc para criar nem para faturar um cliente fora do México.

Requisição:

curl -X POST "https://cordhq.app/api/v1/clientes" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "empresa": "Stark Industries",
       "contacto": "Tony Stark",
       "email": "tony@stark.com",
       "rfc": "STA120412XYZ",
       "terminos": "net30",
       "limite": 500000,
       "nivel": "oro",
       "descuento_pct": 15
     }'

Resposta bem-sucedida:

{
  "data": {
    "id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b"
  }
}

Regras de negócio automatizadas

Quando você cria clientes pela API, o Cord aplica restrições lógicas em tempo real:

  • As condições de pagamento (terminos) devem ser válidas: contado ou net7, net15, net30, net45, net60, net90 (N dias de crédito). Se você enviar algo inválido, o valor padrão passa a ser contado.
  • O nível de parceria (nivel) está restrito a estandar, plata, oro ou distribuidor.
  • O RFC (se você o enviar) é normalizado para maiúsculas automaticamente.
  • O desconto (descuento_pct) é limitado matematicamente entre 0 e 100.

Listar clientes

Recupere o catálogo completo usando a Paginação.

curl -X GET "https://cordhq.app/api/v1/clientes?limit=100" \
     -H "Authorization: Bearer sk_live_tU..."
{
  "data": [
    {
      "id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
      "empresa": "Stark Industries",
      "contacto": "Tony Stark",
      "email": "tony@stark.com",
      "telefono": "",
      "rfc": "STA120412XYZ",
      "terminos": "Net 30",
      "terminosCode": "net30",
      "limite": 500000,
      "nivel": "oro",
      "descuentoPct": 15,
      "countryCode": "",
      "direccionLine1": "",
      "ciudad": "",
      "region": "",
      "language": "en",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "nCotizaciones": 4,
      "cerrado": 32000
    }
  ],
  "meta": { "limit": 100, "offset": 0, "total": 1, "next_cursor": null }
}

Ao criar um cliente, POST /api/v1/clientes também aceita os dados de endereço e os dados fiscais do destinatário: country_code (ISO 3166-1 alfa-2), direccion_line1 e direccion_line2 (até 200 caracteres), ciudad e region (até 100) e, para o México, regimen_fiscal, uso_cfdi e cp_fiscal. Na leitura, eles vêm como countryCode, direccionLine1, direccionLine2, ciudad, region, regimenFiscal, usoCfdi e cpFiscal. Ao atualizar com PATCH, só o country_code desse grupo pode ser alterado; o endereço e os dados fiscais são editados na ficha do cliente no app.

Ao criar, você também pode enviar buyer_reference: a referência do comprador que as faturas eletrônicas europeias dele levam por padrão (na Alemanha, o Leitweg-ID de uma administração pública). Uma fatura pode levar a sua própria; veja a API de Faturas.

Identificação fiscal validada

O Cord valida rfc com o dígito verificador do país do cliente ou, se você não enviar country_code, do país da sua conta: RFC no México, NIF/NIE/CIF na Espanha, EIN nos Estados Unidos, CNPJ ou CPF no Brasil, NIT na Colômbia, CUIT na Argentina, RUT no Chile, RUC no Peru, SIREN, SIRET ou TVA na França, USt-IdNr. ou Steuernummer na Alemanha, VAT ou UTR no Reino Unido e Business Number no Canadá. Uma identificação que não passa responde 422 com code: "invalid_tax_id" e um motivo que nomeia o dado local. Ao atualizar, ela só é validada se você mudar a identificação ou o país: um dado antigo não impede que você corrija o telefone ou o e-mail.

Idioma dos documentos

language é o idioma em que o cliente recebe seus orçamentos, faturas, PDFs, e-mails e links: es, en, pt, fr ou de; null significa o da sua organização. Ele é enviado ao criar e ao atualizar. No PATCH, omiti-lo o mantém, e enviar null ou uma string vazia volta ao da sua organização. Qualquer outro valor responde 400 com code: "invalid_request" e field: "language". Alterá-lo não reescreve o que já foi enviado: cada orçamento e cada fatura guarda o idioma com que foi enviado ou emitido.

Buscar clientes

q busca em empresa, contato, e-mail e RFC. email busca o e-mail exato, sem diferenciar maiúsculas e minúsculas; é a forma de evitar duplicados antes de criar um cliente a partir de outra ferramenta.

curl -X GET "https://cordhq.app/api/v1/clientes?email=tony@stark.com" \
     -H "Authorization: Bearer sk_live_tU..."

Obter um cliente

GET /api/v1/clientes/{id} devolve o mesmo objeto da listagem. Um id de outra organização responde 404.

Atualizar um cliente

PATCH /api/v1/clientes/{id} altera apenas os campos que você enviar: empresa, contacto, email, telefono, rfc, terminos, country_code e language. O restante é mantido. O limite de crédito, o nível e o desconto não podem ser alterados por este endpoint, mesmo que você os envie. Exige uma chave com permissão de escrita.

curl -X PATCH "https://cordhq.app/api/v1/clientes/8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{ "email": "procurement@stark.com" }'
{ "data": { "ok": true } }

Cada alteração emite o evento client.updated.