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_KEYcombusiness:customers:create,business:properties:createebusiness:accounts:create. Juntebusiness:customers:readebusiness:accounts:readpara as verificações. Para um processo de importação, a opção mais segura é uma chave restrita (prefixosk_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.
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"}'
{
"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"
}
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".
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}'
3. Abrir a conta de serviço#
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"}'
{
"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"
}
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:
curl -sS "$BUSINESS_API/customers?q=Macu%C3%A1cua&category=residential&limit=5" \
-H "Authorization: Bearer $API_KEY"
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.