API legada/Referência completa/Equipe de campo

Check-ins de visita

Registra com GPS a visita de um representante a um cliente de uma rota e lista o histórico de visitas do representante.

O representante chega no cliente, abre o app e toca em "check-in": o celular envia a rota, o representante e a posição GPS. A plataforma grava a visita com a hora do servidor. Mais tarde, o gestor lista os check-ins para conferir quais visitas aconteceram.

O check-in só é aceito para uma rota que existe e que pertence ao representante. A rota é criada antes, pelas rotas routes ou ec_routes da API 1.0.

POST/api/v1.0/checkinsAdmin

Venddor 1.0: registrar um check-in de visita

Grava a visita. Responde 201 quando grava.

Corpo da requisição

route_idstringobrigatório

Id da rota (inteiro, como texto: "2"). A rota precisa existir.

manager_idstringobrigatório

Id do representante (inteiro, como texto: "2"). A rota precisa ser dele; senão a resposta é route does not belong to this representative.

latitudenumberobrigatório

Latitude em graus decimais, por exemplo -23.5614. 0 junto com longitude 0 é recusado.

longitudenumberobrigatório

Longitude em graus decimais, por exemplo -46.6559.

notesstring

Observação livre da visita.

GET/api/v1.0/checkins/{manager_id}Admin

Venddor 1.0: listar os check-ins de um representante

Devolve até 500 check-ins do representante, do mais novo para o mais antigo. Não há paginação.

Parâmetros de caminho

manager_idstringobrigatório

Id do representante (inteiro). Um valor que não é número volta 500 Query failed.

Parâmetros de consulta

route_idstring

Só os check-ins desta rota (inteiro).

POST/api/checkinsAdmin

Registrar um check-in, forma sem versão

Igual a POST /api/v1.0/checkins e com o mesmo corpo, mas veja o aviso acima sobre route_id.

Corpo da requisição

route_idstringobrigatório

Id da rota, como texto.

manager_idstringobrigatório

Id do representante, como texto.

latitudenumberobrigatório

Latitude.

longitudenumberobrigatório

Longitude.

notesstring

Observação livre.

GET/api/checkins/{manager_id}Admin

Listar os check-ins de um representante, forma sem versão

Igual a GET /api/v1.0/checkins/{manager_id}. Na resposta, customer_id sai como número decimal em string, e o filtro route_id sofre o problema descrito no aviso.

Parâmetros de caminho

manager_idstringobrigatório

Id do representante (inteiro).

Parâmetros de consulta

route_idstring

Só os check-ins desta rota. Evite nesta forma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/checkins" \
  -u "$ADMIN_EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"route_id":"2","manager_id":"2","latitude":-23.5614,"longitude":-46.6559,"notes":"Visita de reposição"}'

curl "$BASE_URL/api/v1.0/checkins/2?route_id=2" -u "$ADMIN_EMAIL:$API_KEY"

Resposta

201Check-in gravado

json

{ "success": true, "checkin_id": 14 }

200Lista de check-ins

json

{
  "success": true,
  "routes": [
    {
      "checkin_id": "9",
      "route_id": "2",
      "manager_id": "2",
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja + checklist de merchandising",
      "timestamp": 1784063448
    }
  ],
  "checkins": [
    {
      "checkin_id": "9",
      "route_id": "2",
      "manager_id": "2",
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja + checklist de merchandising",
      "timestamp": 1784063448
    }
  ]
}

Campos da resposta

successboolean

true quando a operação deu certo.

checkin_idinteger

(Gravação) Id do check-in criado. É número; na lista ele aparece como texto.

checkinsarray

(Lista) Os check-ins. A chave routes traz a mesma lista: o nome é um resto da API antiga. Leia checkins.

checkins[].checkin_idstring

Id do check-in.

checkins[].route_idstring

Id da rota.

checkins[].manager_idstring

Id do representante.

checkins[].customer_idstring

Cliente visitado (UUID em /api/v1.0, decimal em /api). Vazio quando o check-in foi gravado sem cliente, que é o caso do POST desta página.

checkins[].latitudenumber

Latitude.

checkins[].longitudenumber

Longitude.

checkins[].notesstring

Observação.

checkins[].timestampinteger

Momento do check-in, Unix timestamp em segundos (hora do servidor).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, ou `route_id`/`manager_id` enviados como número	`{"message":"Invalid JSON","status":400}`
400	`route_id` ou `manager_id` vazio	`{"success":false,"message":"Required fields: route_id, manager_id, latitude, longitude"}`
400	Latitude e longitude zeradas	`{"success":false,"message":"latitude and longitude are required"}`
400	A rota não existe	`{"success":false,"message":"route not found"}` (em `/api`, também `Route not found`)
400	A rota é de outro representante	`{"success":false,"message":"route does not belong to this representative"}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	`manager_id` do caminho não é número, ou falha ao consultar	`{"message":"Query failed","status":500}`

Veja também

Check-ins de visita

Registra com GPS a visita de um representante a um cliente de uma rota e lista o histórico de visitas do representante.

O check-in só é aceito para uma rota que existe e que pertence ao representante. A rota é criada antes, pelas rotas routes ou ec_routes da API 1.0.

POST/api/v1.0/checkinsAdmin

Venddor 1.0: registrar um check-in de visita

Grava a visita. Responde 201 quando grava.

Corpo da requisição

route_idstringobrigatório

Id da rota (inteiro, como texto: "2"). A rota precisa existir.

manager_idstringobrigatório

Id do representante (inteiro, como texto: "2"). A rota precisa ser dele; senão a resposta é route does not belong to this representative.

latitudenumberobrigatório

Latitude em graus decimais, por exemplo -23.5614. 0 junto com longitude 0 é recusado.

longitudenumberobrigatório

Longitude em graus decimais, por exemplo -46.6559.

notesstring

Observação livre da visita.

GET/api/v1.0/checkins/{manager_id}Admin

Venddor 1.0: listar os check-ins de um representante

Devolve até 500 check-ins do representante, do mais novo para o mais antigo. Não há paginação.

Parâmetros de caminho

manager_idstringobrigatório

Id do representante (inteiro). Um valor que não é número volta 500 Query failed.

Parâmetros de consulta

route_idstring

Só os check-ins desta rota (inteiro).

POST/api/checkinsAdmin

Registrar um check-in, forma sem versão

Igual a POST /api/v1.0/checkins e com o mesmo corpo, mas veja o aviso acima sobre route_id.

Corpo da requisição

route_idstringobrigatório

Id da rota, como texto.

manager_idstringobrigatório

Id do representante, como texto.

latitudenumberobrigatório

Latitude.

longitudenumberobrigatório

Longitude.

notesstring

Observação livre.

GET/api/checkins/{manager_id}Admin

Listar os check-ins de um representante, forma sem versão

Igual a GET /api/v1.0/checkins/{manager_id}. Na resposta, customer_id sai como número decimal em string, e o filtro route_id sofre o problema descrito no aviso.

Parâmetros de caminho

manager_idstringobrigatório

Id do representante (inteiro).

Parâmetros de consulta

route_idstring

Só os check-ins desta rota. Evite nesta forma.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/checkins" \
  -u "$ADMIN_EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"route_id":"2","manager_id":"2","latitude":-23.5614,"longitude":-46.6559,"notes":"Visita de reposição"}'

curl "$BASE_URL/api/v1.0/checkins/2?route_id=2" -u "$ADMIN_EMAIL:$API_KEY"

Resposta

201Check-in gravado

json

{ "success": true, "checkin_id": 14 }

200Lista de check-ins

json

{
  "success": true,
  "routes": [
    {
      "checkin_id": "9",
      "route_id": "2",
      "manager_id": "2",
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja + checklist de merchandising",
      "timestamp": 1784063448
    }
  ],
  "checkins": [
    {
      "checkin_id": "9",
      "route_id": "2",
      "manager_id": "2",
      "customer_id": "8a20f4fa-442b-46bc-a2b3-360e365f4b75",
      "latitude": -23.624,
      "longitude": -46.6995,
      "notes": "Foto da loja + checklist de merchandising",
      "timestamp": 1784063448
    }
  ]
}

Campos da resposta

successboolean

true quando a operação deu certo.

checkin_idinteger

(Gravação) Id do check-in criado. É número; na lista ele aparece como texto.

checkinsarray

(Lista) Os check-ins. A chave routes traz a mesma lista: o nome é um resto da API antiga. Leia checkins.

checkins[].checkin_idstring

Id do check-in.

checkins[].route_idstring

Id da rota.

checkins[].manager_idstring

Id do representante.

checkins[].customer_idstring

Cliente visitado (UUID em /api/v1.0, decimal em /api). Vazio quando o check-in foi gravado sem cliente, que é o caso do POST desta página.

checkins[].latitudenumber

Latitude.

checkins[].longitudenumber

Longitude.

checkins[].notesstring

Observação.

checkins[].timestampinteger

Momento do check-in, Unix timestamp em segundos (hora do servidor).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, ou `route_id`/`manager_id` enviados como número	`{"message":"Invalid JSON","status":400}`
400	`route_id` ou `manager_id` vazio	`{"success":false,"message":"Required fields: route_id, manager_id, latitude, longitude"}`
400	Latitude e longitude zeradas	`{"success":false,"message":"latitude and longitude are required"}`
400	A rota não existe	`{"success":false,"message":"route not found"}` (em `/api`, também `Route not found`)
400	A rota é de outro representante	`{"success":false,"message":"route does not belong to this representative"}`
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	`manager_id` do caminho não é número, ou falha ao consultar	`{"message":"Query failed","status":500}`