Uwata Developers

Listar e consultar clientes requer o scope clients:read. Criar clientes requer o scope clients:write. Todos os endpoints requerem o cabeçalho X-Company-Id.

Listar clientes

GET/api/v1/v1/clientsListar clientes da empresa

Devolve uma lista paginada de clientes da empresa. Podes pesquisar por nome ou NIF.

Query parameters

Nome	Tipo	Obrig.	Descrição
`page`	`number`	não	Número da página (começa em 1).ex: `1`
`pageSize`	`number`	não	Resultados por página (máx. 100).ex: `20`
`search`	`string`	não	Pesquisa por nome ou NIF.

GET /api/v1/v1/clients

curl "https://api.uwata.app/api/v1/v1/clients?page=1&pageSize=20" \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Company-Id: SEU_COMPANY_ID"

Resposta

{
  "data": [
    {
      "id": "cly5678efgh",
      "name": "Empresa ABC, Lda.",
      "nif": "5000123456",
      "email": "geral@empresaabc.ao",
      "phone": "+244923000000",
      "address": "Rua da Missão, 123, Luanda",
      "type": "COMPANY",
      "createdAt": "2024-01-15T09:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Detalhes de um cliente

GET/api/v1/v1/clients/{id}Detalhes de um cliente

Devolve os dados completos de um cliente específico.

Path parameters

Nome	Tipo	Obrig.	Descrição
`id`	`string`	sim	ID único do cliente.ex: `cly5678efgh`

Criar cliente

POST/api/v1/v1/clientsCriar novo cliente

Cria um novo cliente na empresa. O NIF é único por empresa — se já existir, recebes um erro 409 Conflict.

Body (JSON)

Nome	Tipo	Obrig.	Descrição
`name`	`string`	sim	Nome completo ou razão social.ex: `Empresa ABC, Lda.`
`nif`	`string`	não	Número de Identificação Fiscal angolano (9 dígitos).ex: `5000123456`
`email`	`string`	não	Endereço de email do cliente.
`phone`	`string`	não	Telemóvel angolano (+244 + 9 dígitos).ex: `+244923000000`
`address`	`string`	não	Morada completa.
`type`	`string`	não	Tipo de cliente: COMPANY ou INDIVIDUAL.ex: `COMPANY`

POST /api/v1/v1/clients

curl -X POST "https://api.uwata.app/api/v1/v1/clients" \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Company-Id: SEU_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa ABC, Lda.",
    "nif": "5000123456",
    "email": "geral@empresaabc.ao",
    "phone": "+244923000000",
    "address": "Rua da Missão, 123, Luanda",
    "type": "COMPANY"
  }'

Tipos de cliente

Valores do campo type

Nome	Tipo	Obrig.	Descrição
`COMPANY`	`type`	não	Empresa — pessoa colectiva com NIF de empresa.
`INDIVIDUAL`	`type`	não	Particular — pessoa singular.

Referência — Clientes