MSOLUTIONS Manual de integração
Área administrativa

Manual de Integração - MSolutions Multas API

Versão 0.1.0 | Homologação | 22/08/2026

1. Objetivo

A MSolutions Multas API recebe veículos do sistema Frota Segura, registra a solicitação, coloca cada placa em uma fila e consulta multas RENAINF no DespaDoc. O processamento é assíncrono: o recebimento da solicitação e a conclusão da pesquisa acontecem em momentos diferentes.

Endereço público da API: https://multasapi.msolutions.dev.br/

Todas as rotas descritas neste manual devem ser acrescentadas a esse endereço-base. Exemplo: https://multasapi.msolutions.dev.br/api/v1/consultas.

2. Autenticação

Todas as rotas iniciadas por /api/v1 exigem o cabeçalho:

X-API-Key: CHAVE_FORNECIDA_PELA_MSOLUTIONS

Envie somente o valor da chave, sem Bearer, aspas ou colchetes. Os endpoints /status e /status/pronto são públicos. Chaves devem ser transmitidas separadamente deste manual e armazenadas como segredo.

3. Fluxo de integração

  1. O consumidor envia um veículo ou até 500 veículos da mesma empresa em POST /api/v1/consultas.
  2. A API cadastra ou atualiza cada veículo, cria um lote e responde imediatamente com HTTP 202 e um lote_id.
  3. Cada placa aguarda na fila. O robô inicia novas pesquisas somente entre 08:00 e 19:00, no fuso America/Sao_Paulo.
  4. O robô consulta todas as multas dos últimos 180 dias, abre os detalhes e grava somente multas ainda inexistentes.
  5. O consumidor acompanha o lote em GET /api/v1/consultas/{lote_id}.
  6. Após a conclusão, o consumidor lê as multas do veículo ou busca todas as multas pendentes de retorno.
  7. Depois de processar cada multa, o consumidor confirma o recebimento em POST /api/v1/multas/{multa_id}/marcar-enviada.

4. Identidade do veículo

O contrato preserva exatamente:

  • company_id: UUID da empresa no Frota Segura.
  • vehicle_id: UUID do veículo no Frota Segura.
  • plate: placa atual, normalizada sem espaços ou hífen.

A identidade única é company_id + vehicle_id. A placa não identifica isoladamente um veículo e pode aparecer no histórico de empresas ou veículos diferentes.

5. Solicitar consulta de um veículo

POST /api/v1/consultas
Content-Type: application/json
X-API-Key: CHAVE_FORNECIDA_PELA_MSOLUTIONS

{
  "company_id": "11111111-1111-4111-8111-111111111111",
  "vehicle_id": "22222222-2222-4222-8222-222222222222",
  "plate": "CPA0C46"
}

Resposta HTTP 202:

{
  "lote_id": "a15ae39e-3c35-4bc1-a82b-94c906fdd751",
  "status": "recebido",
  "quantidade": 1
}

6. Solicitar consulta em lote

{
  "company_id": "11111111-1111-4111-8111-111111111111",
  "vehicles": [
    {
      "vehicle_id": "22222222-2222-4222-8222-222222222222",
      "plate": "CPA0C46"
    },
    {
      "vehicle_id": "33333333-3333-4333-8333-333333333333",
      "plate": "ABC1D23"
    }
  ]
}

Regras: mínimo de 1 e máximo de 500 veículos; todos pertencem ao company_id do envelope; vehicle_id não pode se repetir no mesmo lote; não misture o formato unitário com vehicles.

7. Acompanhar um lote

GET /api/v1/consultas/{lote_id}
X-API-Key: CHAVE_FORNECIDA_PELA_MSOLUTIONS

Estados do lote: recebido, processando, concluido, concluido_parcialmente e erro.

Estados individuais: aguardando, aguardando_horario_operacional, processando, concluida, sem_multas, nova_tentativa, erro e bloqueada.

O consumidor deve consultar com intervalo recomendado de 15 a 30 segundos e parar quando o lote atingir um estado final.

8. Recuperar multas

Para listar multas de um veículo, obtenha primeiro o campo interno id em GET /api/v1/veiculos e consulte:

GET /api/v1/veiculos/{id_interno_do_veiculo}/multas

Para integração incremental, prefira:

GET /api/v1/multas/pendentes?limit=500

Esse endpoint retorna somente multas com retorno_enviado=false.

Exemplo abreviado:

[
  {
    "multa_id": "9db3a23d-23ec-4a67-9c2e-623165f8fb84",
    "veiculo_id": "id-interno-do-veiculo",
    "numero_auto_infracao": "E436010296",
    "placa_retornada_portal": "CPA0246",
    "codigo_orgao_autuador": "264770",
    "orgao_autuador": "GUARULHOS",
    "codigo_infracao": "6050",
    "descricao_infracao": "AVANCAR SINAL VERMELHO DO SEMAFORO",
    "data_infracao": "2026-06-19",
    "hora_infracao": "13:14:00",
    "valor_infracao_centavos": 29347,
    "exigivel": false,
    "retorno_enviado": false,
    "enviado_em": null
  }
]

A placa retornada pelo portal pode divergir da placa consultada por conversão entre o padrão antigo e o padrão Mercosul. Isso não deve ser tratado isoladamente como erro.

9. Confirmar recebimento

POST /api/v1/multas/{multa_id}/marcar-enviada
X-API-Key: CHAVE_FORNECIDA_PELA_MSOLUTIONS

A operação é idempotente. Ela define retorno_enviado=true e grava enviado_em. Repetir a chamada não cria duplicidade.

10. Principais campos de multa

Identificação

  • multa_id: identificador interno da multa.
  • veiculo_id: identificador interno do veículo na MSolutions.
  • consulta_id: consulta que encontrou a multa.
  • id_consulta_portal: identificador da consulta no DespaDoc.
  • placa_retornada_portal: placa apresentada pelo portal.
  • numero_auto_infracao: número único do auto de infração.

Notificação

  • codigo_orgao_autuador, orgao_autuador, uf_orgao_autuador.
  • codigo_infracao, descricao_infracao.
  • uf_emplacamento, local_infracao, data_infracao, hora_infracao.
  • data_cadastramento_infracao, codigo_municipal_infracao, tipo_auto_infracao.
  • medicao_real, limite_permitido, medicao_considerada, unidade_medida.
  • valor_infracao_centavos: valor monetário inteiro em centavos.
  • exigivel: true, false ou null quando o portal não informar.
  • uf_jurisdicao_veiculo, codigo_municipal_emplacamento.
  • codigo_marca_modelo, marca_modelo_veiculo.
  • data_notificacao, data_emissao_penalidade.

Pagamento, suspensão e auditoria

  • uf_pagamento, data_pagamento, valor_pago_centavos, data_registro_pagamento.
  • tipo_suspensao_cancelamento, data_registro_suspensao_cancelamento, origem_suspensao_cancelamento, aceite_uf_jurisdicao.
  • data_realizacao_consulta_portal, hora_realizacao_consulta_portal.
  • dados_originais: retorno integral preservado para auditoria.
  • retorno_enviado, encontrado_em, enviado_em.

Campos não informados pelo DespaDoc são retornados como null. Datas usam AAAA-MM-DD, horários usam HH:MM:SS e datas/hora de auditoria usam ISO 8601.

11. Códigos HTTP

  • 200 OK: leitura ou confirmação concluída.
  • 201 Created: veículo cadastrado ou reativado.
  • 202 Accepted: lote aceito para processamento assíncrono.
  • 401 Unauthorized: X-API-Key ausente ou inválida.
  • 404 Not Found: lote, veículo, multa ou rota inexistente.
  • 409 Conflict: conflito ao cadastrar veículo.
  • 422 Unprocessable Entity: JSON, UUID, placa ou quantidade inválida.
  • 503 Service Unavailable: banco de dados ou Redis indisponível no teste de prontidão.

12. Segurança e operação

  • Use HTTPS fora do computador local.
  • Nunca envie a chave na URL ou no corpo JSON.
  • Não registre a chave em logs e não a versione em repositórios.
  • Configure timeout de conexão e leitura no consumidor.
  • Trate HTTP 202 como aceite, não como conclusão da consulta.
  • Requisições podem chegar 24 horas por dia; o robô inicia pesquisas apenas na janela operacional.
  • A API evita duplicidade de multas pelo conteúdo e pelo número do auto disponível.

13. Recursos entregues

  • Swagger: /docs
  • Esquema OpenAPI: /openapi.json
  • Collection Postman: MSolutions_Multas_API.postman_collection.json
  • Ambiente Postman: MSolutions_Multas_API_Local.postman_environment.json

14. Webhook de multas

A API possui estrutura persistente e fila separada para notificar cada multa nova. O destino homologado é https://political-infant-electro-rand.trycloudflare.com/api/integrations/webhooks/msolutions/infractions/.

Configurar o destino da empresa

PUT /api/v1/empresas/{company_id}/webhook
X-API-Key: CHAVE_FORNECIDA_PELA_MSOLUTIONS
Content-Type: application/json

{
  "url": "https://political-infant-electro-rand.trycloudflare.com/api/integrations/webhooks/msolutions/infractions/",
  "token": "TOKEN_CONFIGURADO",
  "ativo": true
}

O token não é devolvido pela API e não deve ser registrado em logs.

Contrato do evento

{
  "event_id": "uuid-do-evento",
  "infraction_id": "uuid-da-multa",
  "multa_id": "uuid-da-multa",
  "company_id": "uuid-da-empresa",
  "vehicle_id": "uuid-do-veiculo-no-frota-segura",
  "data_infracao": "2026-07-20",
  "plate": "ABC1D23",
  "agency": "264770 - GUARULHOS",
  "occurred_at": "2026-07-20T10:15:00-03:00",
  "notice_number": "A123456789",
  "code": "74550",
  "description": "Descrição da infração",
  "amount": "195.23",
  "location": "Av. Exemplo, km 10",
  "points": null,
  "notification_date": "2026-07-25",
  "identification_deadline": null,
  "defense_deadline": null,
  "payment_due_date": null
}

Cada requisição envia X-Webhook-Token: TOKEN_CONFIGURADO. Sem o token correto, o Frota Segura responde HTTP 401.

O campo multa_id identifica a multa na MSolutions; infraction_id permanece como alias de compatibilidade. Os campos company_id e vehicle_id preservam os identificadores recebidos do Frota Segura. data_infracao usa o formato AAAA-MM-DD; occurred_at mantém a data e hora com fuso horário.

Os eventos possuem estados aguardando_configuracao, pendente, enviando, nova_tentativa, enviado e falhou. Somente uma resposta HTTP entre 200 e 299 marca a multa como retorno_enviado=true. Falhas geram novas tentativas com intervalo progressivo e ficam registradas para auditoria.

Endpoints auxiliares:

  • GET /api/v1/empresas/{company_id}/webhook
  • GET /api/v1/webhooks/eventos
  • POST /api/v1/webhooks/eventos/{evento_id}/reenviar

O parâmetro legado callback_url do lote permanece reservado e não substitui o cadastro seguro por empresa nesta etapa.