# Importar clientes

Passe o cadastro de clientes para a API como clientes, imóveis e contas de serviço, pela ordem que a API exige, com chaves de idempotência que tornam segura uma segunda execução.


## O que vai construir

Um script que converte cada linha do cadastro actual em três registos ligados entre si: o cliente (quem paga), o imóvel (o local onde a água é fornecida) e a conta de serviço (o registo a que se associam contadores, facturas e pagamentos). Criar um cliente não cria imóvel nem conta, por isso uma importação que pare na primeira chamada deixa clientes que ninguém consegue facturar. Cada pedido leva um cabeçalho `Idempotency-Key` construído a partir do identificador da própria linha, o que permite repetir a importação inteira depois de uma falha sem criar duplicados.

## Pré-requisitos

- Uma sandbox. Já contém clientes de exemplo, por isso as listagens devolvem mais registos do que os importados aqui.
- Uma chave de API de teste em `$API_KEY` com `business:customers:create`, `business:properties:create` e `business:accounts:create`. Junte `business:customers:read` e `business:accounts:read` para as verificações. Para um processo de importação, a opção mais segura é uma chave restrita (prefixo `sk_rtest_`) com exactamente estes scopes.
- Um identificador estável para cada linha de origem. Este guia usa `ROW-0042`.

## 1. Criar o cliente

São obrigatórios `display_name`, `customer_type` (`individual` ou `business`) e `category` (`residential`, `commercial`, `industrial`, `institutional` ou `government`). Os campos `tax_number`, `email` e `phone` são opcionais e a API retira-lhes os espaços antes de os guardar. O corpo é lido de forma estrita: um campo desconhecido, como `name`, é recusado com `400`.

```bash
curl -sS -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-customer" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Ana Macuácua","customer_type":"individual","category":"residential","phone":"+258841234567"}'
```

```json
{
  "id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Ana Macuácua",
  "phone": "+258841234567",
  "status": "active",
  "created_at": "2026-11-19T09:14:03Z",
  "updated_at": "2026-11-19T09:14:03Z"
}
```

✓ Checkpoint: o código de estado é `201`, `status` vale `active` e o `id` começa por `cus_`. Guarde esse `id` para os dois passos seguintes.

## 2. Registar o imóvel

São obrigatórios `customer_id` e `address_line`. `latitude` e `longitude` enviam-se juntas ou não se enviam. Se indicar `service_area_id`, tem de ser uma das áreas de serviço da própria empresa; outro valor devolve `400` com `error_code: "validation.invalid_choice"`.

```bash
curl -sS -X POST "$BUSINESS_API/properties" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-property" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7","address_line":"Rua da Resistência, 1147","locality":"Malhangalene","district":"KaMpfumo","province":"Maputo Cidade","premise_type":"residential","latitude":-25.9553,"longitude":32.5892}'
```

✓ Checkpoint: `201` com um `id` que começa por `prp_`, o mesmo `customer_id` e `status: "active"`. A API regista esta primeira titularidade como uma transferência para o cliente, pelo que o histórico do imóvel começa no dia da importação.

## 3. Abrir a conta de serviço

```bash
curl -sS -X POST "$BUSINESS_API/accounts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: import-ROW-0042-account" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7","property_id":"prp_2pN4wA3cHs7QkV1yMd5TnJ8eXb2"}'
```

```json
{
  "id": "act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
  "property_id": "prp_2pN4wA3cHs7QkV1yMd5TnJ8eXb2",
  "account_number": "CTA-000318",
  "billing_entity_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "status": "active",
  "opened_at": "2026-11-19T09:14:05Z"
}
```

✓ Checkpoint: `201` com `status: "active"` e um `account_number` da série sem falhas da empresa. É este número que os moradores escrevem para associar a conta na app. Um imóvel de outro cliente devolve `409`; um cliente ou imóvel inexistente devolve `404`.

## 4. Repetir sem riscos

Se repetir uma chamada com a mesma chave e o mesmo corpo, a API devolve a resposta guardada com o cabeçalho `Idempotent-Replayed: true`. A mesma chave com outro corpo devolve `409` com `error_code: "request.idempotency_conflict"`. As chaves ficam guardadas 24 horas; uma importação retomada mais tarde deve procurar primeiro o cliente:

```bash
curl -sS "$BUSINESS_API/customers?q=Macu%C3%A1cua&category=residential&limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data` traz os resultados e `has_more` indica se existe outra página.

## Testar

Na linha de comandos, `gotactl customers get cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7 --json id,display_name,status` mostra o cliente e `gotactl accounts list --customer-id cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7 --json id,account_number,status` mostra a conta. No painel, o cliente aparece em **Clientes** e o imóvel, com a respectiva conta, em **Imóveis e contas**.

## Próximos passos

- [Registar as primeiras leituras das novas contas](/docs/guides/record-readings)
- [Emitir uma factura manual ou uma nota de crédito numa conta](/docs/guides/issue-invoices)
- [Dar ao processo de importação uma chave restrita só com estes scopes](/docs/getting-started/restricted-keys)
- [Como funcionam as repetições e os conflitos de Idempotency-Key](/docs/getting-started/idempotency)

