PT EN

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"
}

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}'

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"
}

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"

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#