Integração Corporativa

Criar solicitação

Cria um chamado de guincho com cobrança vinculada ao seu contrato corporativo. Pode ser disparado pelo backend do parceiro (X-API-Key) ou diretamente pelo app autenticado do segurado.

POST/api/v1/service-requests

Cria uma nova solicitação de serviçoX-API-Key ou JWT

Comportamento corporativo

Quando autenticado por API Key (parceiro corporativo) ou JWT do segurado com corporateContext, a NetGuincho automaticamente:

Re-executa a checagem de elegibilidade (contrato + segurado + cota).
Define billing_type = "corporate" na solicitação.
Vincula o chamado ao seu contrato (insurer_customer_id) para fins de faturamento e relatório.
Bloqueia a criação se o segurado já tiver um chamado em aberto.

Parâmetros do body

Campo	Tipo	Descrição
`cpf`obrigatório	`string`	CPF do segurado. Apenas obrigatório quando autenticado por X-API-Key.
`location`obrigatório	`object`	Coordenadas GPS do veículo a ser atendido. Veja schema abaixo.
`address`opcional	`string`	Endereço textual de fallback caso a geocodificação reversa falhe.
`occurrenceType`obrigatório	`"flat_tire" \| "battery" \| "fuel" \| "tow" \| "other"`	Tipo da ocorrência para roteamento ao prestador adequado.
`vehicle`obrigatório	`object`	Dados do veículo (placa, modelo, cor). Necessário para o prestador identificar.
`notes`opcional	`string`	Observações livres (até 500 caracteres). Visíveis ao prestador.

Schemas aninhados

JSON

// location
{
  "lat": -23.5613,
  "lng": -46.6565
}

// vehicle
{
  "plate": "ABC1D23",
  "type": "passeio",
  "brand": "Volkswagen",
  "model": "Polo",
  "year": 2022,
  "color": "preto"
}

Exemplo de requisição

cURL

curl -X POST 'https://api.netguincho.com.br/api/v1/service-requests' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "cpf": "12345678900",
    "location": { "lat": -23.5613, "lng": -46.6565 },
    "address": "Av. Paulista, 1000 - São Paulo/SP",
    "occurrenceType": "battery",
    "vehicle": {
      "plate": "ABC1D23",
      "type": "passeio",
      "brand": "Volkswagen",
      "model": "Polo",
      "year": 2022,
      "color": "preto"
    },
    "notes": "Carro estacionado no subsolo, vaga 42"
  }'

Resposta de sucesso (201)

JSON

{
  "id": "f0a2b3c4-1234-4abc-9def-0123456789ab",
  "status": "pending",
  "billing_type": "corporate",
  "insurer_id": "9b3f...",
  "insurer_customer_id": "2a1c...",
  "requested_at": "2026-04-18T14:32:11.000Z",
  "tracking_url": "https://app.netguincho.com.br/chamado/f0a2..."
}

Estados do chamado

Status	Significado	Conta no limite?
pending	Aguardando validação automática.	Não
validated	Procurando prestador disponível.	Não
assigned	Prestador aceitou e está a caminho.	Sim
in_service	Atendimento em execução.	Sim
completed	Atendimento concluído com sucesso.	Sim
cancelled	Chamado cancelado pelo segurado, prestador ou sistema.	Depende*

Erros possíveis

JSON

// 409 Conflict — segurado já tem chamado aberto
{
  "statusCode": 409,
  "error_code": "OPEN_REQUEST_EXISTS",
  "message": "Existe um chamado em andamento para este segurado.",
  "open_request_id": "f0a2b3c4..."
}

// 422 Unprocessable Entity — payload inválido
{
  "statusCode": 422,
  "error_code": "VALIDATION_ERROR",
  "message": "location.lat deve ser um número entre -90 e 90"
}