Desenvolvedores: API e importação

Leve os dados para outros sistemas (ERP, administradora, BI) pela API de integração, e traga pontos, rondas e tarefas de outros sistemas por CSV.

API de integração (leitura)

Uma API REST somente leitura, em JSON, com os dados da empresa.

• Endereço base: https://vistoria.trng.capital/api/integration/v1
• Autenticação: cada requisição envia o cabeçalho X-API-Key: psk_…
• As chaves (começam com psk_) são criadas e revogadas pelo síndico em Painel › Integrações. A chave aparece uma única vez; guarde-a num cofre de senhas.
• Disponível nos planos Profissional e Completo, com a assinatura ativa.
• Limite: 600 requisições por minuto por chave (acima disso, 429).
• Listas por data vêm em páginas de 500 itens: repita a chamada com cursor=next_cursor até next_cursor ser null.

curl -H "X-API-Key: psk_…" \
  "https://vistoria.trng.capital/api/integration/v1/entries?since=2026-10-01T00:00:00Z&until=2026-11-01T00:00:00Z"

Endpoints

since e until são datas ISO 8601 (com fuso; sem fuso = UTC). location_id filtra por local. Datas nas respostas estão em UTC.

{
  "entries": [
    {"id": "6f1c…", "recorded_at": "2026-10-05T22:04:11Z", "received_at": "2026-10-05T22:04:13Z",
     "username": "joao", "entry_type": "rfid", "area_name": "Portaria",
     "checkpoint_id": "a41e…", "location_id": "0b9d…", "identifier": "04:A1:B2:C3:D4:E5:F6",
     "latitude": -23.561414, "longitude": -46.655881, "session_key": "…",
     "comments": "", "has_photo": true, "clock_anomaly": false, "time_zone": "America/Sao_Paulo"}
  ],
  "next_cursor": "eyJ0IjogIjIwMjYt…"
}

Exportar o livro de ocorrências

Todas as ocorrências da empresa, com autor, local, gravidade, status e resolução — ideal para levar à administradora ou a um sistema de chamados.

curl -H "X-API-Key: psk_…" "https://vistoria.trng.capital/api/integration/v1/occurrences?since=2026-10-01T00:00:00Z"

{
  "occurrences": [
    {"id": "c2d7…", "category": "iluminacao", "severity": "media",
     "description": "Lâmpada queimada no hall do bloco A", "status": "resolvida",
     "author": {"id": "…", "display_name": "João", "role": "worker"},
     "location": {"id": "0b9d…", "name": "Torre A"},
     "recorded_at": "2026-10-05T22:26:00Z", "has_photo": true, "photo_received": true,
     "resolved_at": "2026-10-06T09:10:00Z", "resolution_note": "Trocada pela manutenção"}
  ],
  "next_cursor": null
}

Uma ocorrência nunca é editada nem apagada depois de registrada: só a resolução é acrescentada. O que a API devolve é o histórico real.

Para baixar tudo, siga o next_cursor:

cursor=""
while :; do
  page=$(curl -s -H "X-API-Key: $KEY" "https://vistoria.trng.capital/api/integration/v1/occurrences?cursor=$cursor")
  echo "$page" | jq -c '.occurrences[]' >> ocorrencias.jsonl
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Importação por CSV

Pontos, rondas e tarefas podem ser importados pelo painel (Painel › Importar) ou pela API do aplicativo. Até 2000 linhas e 1024 KB por arquivo.

• Tudo ou nada: todas as linhas são verificadas antes; se houver qualquer erro, nada é gravado e a lista de erros diz a linha, a coluna e o problema.
• CSV em UTF-8, separado por vírgula ou ponto e vírgula, com cabeçalho. Os nomes das colunas aceitam português ou inglês, com ou sem acento; colunas desconhecidas são recusadas (para não perder dados por engano).
• Datas: DD/MM/AAAA ou AAAA-MM-DD, no fuso da empresa. Horas: HH:MM.
• Dias da semana: seg, ter, qua, qui, sex, sab, dom (ou mon…sun, ou 0 = segunda … 6 = domingo).
• Listas dentro de uma célula (paradas, horários, dias) são separadas por |.
• Locais, pontos e pessoas são procurados pelo nome (ou e-mail) só dentro da sua empresa e dos locais que você pode ver.

Pontos

Rondas

Tarefas

Exemplo: tarefas únicas e programadas

titulo;descricao;responsavel;inicio;prazo;hora_prazo;repetir;a_cada;dias_semana;dia_mes;mes;hora;local;ponto
Trocar lâmpada do hall;Bloco A;joao@exemplo.com.br;05/10/2026;05/10/2026;18:00;;;;;;;;
Revisar hidrantes;;joao@exemplo.com.br;;;;semanal;1;seg;;;07:00;;
Bomba d'água;Conferir pressão;joao@exemplo.com.br;;;;semanal;1;qui;;;22:00;Torre A;Casa de bombas
Dedetização;;maria@exemplo.com.br;;;;anual;1;;15;3;09:00;;

Importar pela API do aplicativo

Síndicos e supervisores podem enviar o mesmo CSV com o token de acesso do aplicativo. commit=0 só verifica; commit=1 importa quando não há erros (com erros, responde 422 e nada é gravado).

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: text/csv" \
  --data-binary @pontos.csv "https://vistoria.trng.capital/api/v1/import/checkpoints?commit=0"

{"kind": "checkpoints", "rows": 2, "valid": false,
 "errors": [{"row": 2, "column": "identifier", "code": "duplicate_identifier",
             "message": "Já existe um ponto com este identificador."}]}

Erros

Erros vêm com um código estável (para o seu sistema tratar) e uma mensagem. 401: chave ou token inválido; 402: assinatura inativa; 403: plano sem API ou sem permissão; 429: limite de requisições.

{"detail": {"code": "plan_feature_unavailable", "message": "…"}}

Dúvidas: suporte@trng.capital.