API atual/Referência completa/Campo e alçadas dos representantes

Check-ins de visita

Registra a visita de um representante a um cliente, com GPS, observação e foto, e lista os check-ins de um representante.

O check-in é o registro de que o representante esteve em um lugar: coordenadas, hora, uma observação e, opcionalmente, uma foto. Cada check-in pertence a uma rota do próprio representante. O app envia o check-in da rua; estas rotas existem para o painel registrar ou conferir.

Registrar um check-in

POST/api/v1/admin/trade-reps/checkinsAdmin

Registra um check-in de visita

Corpo da requisição

route_idintegerobrigatório

Rota da visita. Precisa existir e pertencer ao rep_id.

rep_idintegerobrigatório

Representante que visitou.

latitudenumberobrigatório

Latitude em graus decimais. Latitude e longitude ambas 0 são recusadas.

longitudenumberobrigatório

Longitude em graus decimais.

customer_iduuid

Cliente visitado. Pode ficar vazio (check-in sem cliente, por exemplo em trânsito).

notesstring

Observação livre.

photo_urlstring

Foto da visita: URL pública ou data:image/...;base64,....

client_checkin_idstring

Id gerado pelo app para este check-in. Reenviar o mesmo id devolve o registro já gravado em vez de criar outro.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/checkins" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"route_id": 2, "rep_id": 2, "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75", "latitude": -23.624, "longitude": -46.6995, "notes": "Foto da loja e checklist de merchandising", "client_checkin_id": "app-2026-10-11-0001"}'

201Check-in registrado

json

{
  "id": 21,
  "route_id": 2,
  "rep_id": 2,
  "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
  "latitude": -23.624,
  "longitude": -46.6995,
  "notes": "Foto da loja e checklist de merchandising",
  "client_checkin_id": "app-2026-10-11-0001",
  "checked_at": "2026-10-11T22:15:00Z"
}

Campos da resposta

idinteger

Id do check-in.

route_idinteger

Rota.

rep_idinteger

Representante.

customer_iduuid

Cliente visitado. Ausente se não houve.

latitudenumber

Latitude.

longitudenumber

Longitude.

notesstring

Observação.

photo_urlstring

Foto, quando enviada.

client_checkin_idstring

Id do app, quando enviado.

checked_atstring

Quando o check-in foi registrado (RFC 3339).

Listar os check-ins de um representante

GET/api/v1/admin/trade-reps/{id}/checkinsAdmin

Lista os check-ins de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

route_idinteger

Só os check-ins desta rota. Vazio ou 0 lista todos.

200Check-ins

json

{
  "checkins": [
    {
      "id": 9,
      "route_id": 2,
      "rep_id": 2,
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja e checklist de merchandising",
      "checked_at": "2026-07-14T21:10:48Z"
    }
  ],
  "total": 1
}

A lista não tem paginação e vem do mais recente para o mais antigo.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	Falta `route_id` ou `rep_id`.	`{"error":"create checkin failed","detail":"route_id and manager_id are required"}`
400	Latitude e longitude zeradas.	`{"error":"create checkin failed","detail":"latitude and longitude are required"}`
400	A rota não existe.	`{"error":"create checkin failed","detail":"route not found"}`
400	A rota é de outro representante.	`{"error":"create checkin failed","detail":"route does not belong to this representative"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`

Veja também

Check-ins de visita

Registra a visita de um representante a um cliente, com GPS, observação e foto, e lista os check-ins de um representante.

Registrar um check-in

POST/api/v1/admin/trade-reps/checkinsAdmin

Registra um check-in de visita

Corpo da requisição

route_idintegerobrigatório

Rota da visita. Precisa existir e pertencer ao rep_id.

rep_idintegerobrigatório

Representante que visitou.

latitudenumberobrigatório

Latitude em graus decimais. Latitude e longitude ambas 0 são recusadas.

longitudenumberobrigatório

Longitude em graus decimais.

customer_iduuid

Cliente visitado. Pode ficar vazio (check-in sem cliente, por exemplo em trânsito).

notesstring

Observação livre.

photo_urlstring

Foto da visita: URL pública ou data:image/...;base64,....

client_checkin_idstring

Id gerado pelo app para este check-in. Reenviar o mesmo id devolve o registro já gravado em vez de criar outro.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/checkins" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"route_id": 2, "rep_id": 2, "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75", "latitude": -23.624, "longitude": -46.6995, "notes": "Foto da loja e checklist de merchandising", "client_checkin_id": "app-2026-10-11-0001"}'

201Check-in registrado

json

{
  "id": 21,
  "route_id": 2,
  "rep_id": 2,
  "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
  "latitude": -23.624,
  "longitude": -46.6995,
  "notes": "Foto da loja e checklist de merchandising",
  "client_checkin_id": "app-2026-10-11-0001",
  "checked_at": "2026-10-11T22:15:00Z"
}

Campos da resposta

idinteger

Id do check-in.

route_idinteger

Rota.

rep_idinteger

Representante.

customer_iduuid

Cliente visitado. Ausente se não houve.

latitudenumber

Latitude.

longitudenumber

Longitude.

notesstring

Observação.

photo_urlstring

Foto, quando enviada.

client_checkin_idstring

Id do app, quando enviado.

checked_atstring

Quando o check-in foi registrado (RFC 3339).

Listar os check-ins de um representante

GET/api/v1/admin/trade-reps/{id}/checkinsAdmin

Lista os check-ins de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

route_idinteger

Só os check-ins desta rota. Vazio ou 0 lista todos.

200Check-ins

json

{
  "checkins": [
    {
      "id": 9,
      "route_id": 2,
      "rep_id": 2,
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja e checklist de merchandising",
      "checked_at": "2026-07-14T21:10:48Z"
    }
  ],
  "total": 1
}

A lista não tem paginação e vem do mais recente para o mais antigo.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	Falta `route_id` ou `rep_id`.	`{"error":"create checkin failed","detail":"route_id and manager_id are required"}`
400	Latitude e longitude zeradas.	`{"error":"create checkin failed","detail":"latitude and longitude are required"}`
400	A rota não existe.	`{"error":"create checkin failed","detail":"route not found"}`
400	A rota é de outro representante.	`{"error":"create checkin failed","detail":"route does not belong to this representative"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`