Adiciona detalhamento sobre webhooks

docs.json

@@ -134,6 +134,7 @@
               {
                 "group": "Webhooks",
                 "pages": [
+                  "pages/v2/referencia/webhooks/sobre",
                   "pages/v2/referencia/webhooks/endpoint/get",
                   "pages/v2/referencia/webhooks/endpoint/post",
                   "pages/v2/referencia/webhooks/endpoint/put",
@@ -261,6 +262,7 @@
               {
                 "group": "Webhooks",
                 "pages": [
+                  "pages/v2/entregas/webhooks/sobre",
                   "pages/v2/entregas/webhooks/endpoint/get",
                   "pages/v2/entregas/webhooks/endpoint/post",
                   "pages/v2/entregas/webhooks/endpoint/put",
@@ -342,6 +344,7 @@
               {
                 "group": "Webhooks",
                 "pages": [
+                  "pages/v1/referencia/webhooks/sobre",
                   "pages/v1/referencia/webhooks/endpoint/get",
                   "pages/v1/referencia/webhooks/endpoint/post",
                   "pages/v1/referencia/webhooks/endpoint/put",
@@ -497,6 +500,7 @@
               {
                 "group": "Webhooks",
                 "pages": [
+                  "pages/v1/entregas/webhooks/sobre",
                   "pages/v1/entregas/webhooks/endpoint/get",
                   "pages/v1/entregas/webhooks/endpoint/post",
                   "pages/v1/entregas/webhooks/endpoint/put",

pages/v1/entregas/webhooks/sobre.mdx

@@ -0,0 +1,239 @@
+---
+title: 'Sobre'
+description: 'Entenda o funcionamento, payloads e campos dos Webhooks da plataforma Machine.'
+icon: 'book-open'
+---
+
+Um webhook é uma forma de recebimento de informações quando ocorre um dado evento. Neste caso, quando uma solicitação sofrer uma alteração do seu estado, a Machine irá acionar uma URL informada pela central com determinadas informações sobre a solicitação que sofreu a mudança.
+
+O nosso webhook do tipo status envia eventos nos seguintes momentos: quando uma solicitação muda de status, quando o condutor sinaliza que chegou ao local e quando uma parada é confirmada. As informações enviadas vão variar conforme o estado da solicitação. Por exemplo, enquanto a solicitação não foi aceita, nenhum dado associado ao aceite será enviado, entretanto, quando ela for aceita, as informações associadas ao aceite serão enviadas.
+
+O nosso webhook do tipo posição envia a posição dos condutores que estão com solicitações aceitas (`A`), em andamento (`E`) ou em espera (`S`).
+
+> ⚠️ **Atenção**: Os antigos formatos dos Webhooks de Status e Posição serão deprecados. A central deve cadastrar novamente os webhooks para utilizar os novos formatos.
+
+---
+
+# (Novo) Webhook de Posição
+
+O **Webhook de Posição** realiza o envio da posição de condutores, a cada 15s, que estão com solicitações em espera (`S`), em andamento (`E`) ou aceitas (`A`).
+
+## Exemplo do Payload
+
+```json
+{
+ "datetime": "2025-08-29T13:20:05Z",
+ "event_id": "550e8400-e29b-41d4-a716-446655440000",
+ "company_id": 8,
+ "request_id": 12345,
+ "driver_id": 8101,
+ "latitude": -22.906847,
+ "longitude": -43.172896,
+ "links": {
+   "request": "https://api.taximachine.com.br/api/v1/request/12345",
+   "driver": "https://api.taximachine.com.br/api/integracao/condutor?id=8101",
+   "enterprise": "https://api.taximachine.com.br/api/integracao/empresa?empresa_id=987"
+ }
+}
+```
+
+## Campos
+
+| Campo | Formato | Requerido | Descrição |
+| :--- | :--- | :--- | :--- |
+| `datetime` | ISO-8601 | SIM | Data e hora do evento gerado pela Machine. |
+| `event_id` | UUID | SIM | Identificação única do evento (idempotência). |
+| `company_id` | INT | SIM | Identificador da central. |
+| `request_id` | INT | SIM | Identificador da solicitação. |
+| `driver_id` | INT | SIM | Identificador do condutor na plataforma Machine. |
+| `latitude` | DECIMAL | SIM | Latitude do condutor. |
+| `longitude` | DECIMAL | SIM | Longitude do condutor. |
+| `links` | Object | SIM | URLs relacionadas ao evento. Inclui sempre `request` e `driver`. |
+
+### Links no Payload
+
+- `links.request` -> acesso aos detalhes da solicitação.
+- `links.driver` -> referência ao condutor.
+- `links.enterprise` -> (opcional) referência à empresa vinculada.
+
+---
+
+# (Novo) Webhook de Status
+
+O **Webhook de Status** é acionado sempre que uma solicitação passa por uma **mudança de estado** (ex.: aceita, em andamento, finalizada, cancelada), quando o condutor indica chegada ao local ou quando uma parada é confirmada.
+
+## Exemplo do Payload
+
+```json
+{
+ "datetime": "2025-08-29T13:20:05Z",
+ "event_id": "550e8400-e29b-41d4-a716-446655440000",
+ "company_id": 8,
+ "request_id": 12345,
+ "status_code": "A",
+ "status_label": "ACEITA",
+ "stop_id": 567,
+ "links": {
+   "request": "https://api.taximachine.com.br/api/v1/request/12345",
+   "driver": "https://api.taximachine.com.br/api/integracao/condutor?id=321",
+   "enterprise": "https://api.taximachine.com.br/api/integracao/empresa?empresa_id=987"
+ }
+}
+```
+
+## Exemplo de apresentação do `status_label`
+
+#### Enum de Status
+
+| Código (`status_code`) | Label (`status_label`) | Descrição |
+| :--- | :--- | :--- |
+| `AP` | `ARRIVED_AT_LOCATION` | Condutor chegou ao local |
+| `ER` | `STOP_FINISHED` | Parada finalizada |
+| `L` | `WAITING_RELEASE` | Aguardando liberação |
+| `R` | `WAITING_PAYMENT` | Aguardando pagamento |
+| `D` | `DISTRIBUTING` | Distribuindo |
+| `G` | `WAITING_ACCEPTANCE` | Aguardando aceite |
+| `P` | `PENDING` | Pendente |
+| `S` | `ON_HOLD` | Solicitação em espera |
+| `N` | `NOT_SERVED` | Solicitação não atendida ou buscando condutor |
+| `A` | `ACCEPTED` | Solicitação aceita |
+| `E` | `IN_PROGRESS` | Solicitação em andamento |
+| `C` | `CANCELLED` | Solicitação cancelada |
+| `F` | `FINISHED` | Solicitação finalizada |
+| `U` | `GROUPED` | Solicitação agrupada em andamento |
+
+#### Como usar
+
+- `status_code`: valor curto do status
+- `status_label`: valor descritivo do status
+- **Extensibilidade**: se a Machine adicionar novos status no futuro, basta incluir novos pares para `codes/label`
+
+## Campos
+
+| Campo | Formato | Requerido | Descrição |
+| :--- | :--- | :--- | :--- |
+| `datetime` | ISO-8601 | SIM | Data e hora do evento gerado pela Machine. |
+| `event_id` | UUID | SIM | Identificação única do evento (idempotência). |
+| `company_id` | INT | SIM | Identificador da central |
+| `request_id` | INT | SIM | Identificador da solicitação |
+| `status_code` | VARCHAR(2) | SIM | Código do status |
+| `status_label` | ENUM | SIM | Status descritivo |
+| `stop_id` | INT | NÃO | Identificador da parada (preenchido apenas no status `STOP_FINISHED`) |
+| `links` | Object | SIM | URLs relacionadas ao evento. Inclui sempre `request` e pode incluir `enterprise` e `driver` (se aplicável) |
+
+### Links no Payload
+
+- `links.request` -> acesso aos detalhes da solicitação
+- `links.enterprise` -> (opcional) referência à empresa
+- `links.driver` -> (opcional) referência ao condutor
+
+---
+
+# Webhook de Mensagens
+
+O **Webhook de Mensagens** é acionado sempre que ocorre o recebimento de mensagens relacionadas a uma central. Ele possibilita à central receber as mensagens enviadas pelo **condutor** e **empresa**, garantindo histórico e rastreabilidade da comunicação.
+
+## Exemplo do Payload
+
+```json
+{
+ "company_id": 8,
+ "content": "me aguarde",
+ "datetime": "2025-08-29T14:01:36Z",
+ "event_id": "0198f622-400f-7137-a03d-142dd9c2298a",
+ "message_id": 24148,
+ "sender_id": 8101,
+ "sequence": 1,
+ "type_code": "DRIVER",
+ "type_label": "P",
+ "links": {
+   "sender": "https://api.taximachine.com.br/api/integracao/condutor?id=8101"
+ }
+}
+```
+
+## Campos
+
+| Campo | Formato | Requerido | Descrição |
+| :--- | :--- | :--- | :--- |
+| `datetime` | ISO-8601 | SIM | Data e hora do evento gerado pela Machine. |
+| `event_id` | UUID | SIM | Identificação única do evento (idempotência). |
+| `company_id` | INT | SIM | Identificador da central |
+| `message_id` | INT | SIM | Identificador da mensagem |
+| `sender_id` | INT | SIM | Identificador do remetente (condutor, empresa) |
+| `sequence` | INT | SIM | Número sequencial da mensagem no contexto da solicitação |
+| `type_code` | ENUM | SIM | Origem da mensagem ( `DRIVER`, `ENTERPRISE`) |
+| `type_label` | String | SIM | Indicação adicional do tipo de mensagem (pode variar por contexto) |
+| `content` | String | SIM | Conteúdo textual da mensagem |
+| `links` | Object | SIM | URLs relacionadas ao evento. Inclui, por exemplo, a referência ao remetente ( `sender`) |
+
+### Enum `type_label`
+
+| Code | Label | Descrição |
+| :--- | :--- | :--- |
+| `P` | `DRIVER` | Chat do tipo condutor |
+| `E` | `ENTERPRISE` | Chat do tipo empresa |
+
+---
+
+# (DEPRECADO) Webhook de Posição
+
+O webhook de posição realiza o envio de posição de condutores, a cada 15s, que estão com solicitações em espera (S), em andamento (E) ou aceitas (A). Caso a central configuração e de corrida sejam a mesma, a central receberá o evento do webhook apenas uma vez.
+
+| Campo | Formato | Descrição |
+| :--- | :--- | :--- |
+| `id_mch` | String (Obrigatório) | Identificação da corrida no Sistema Machine |
+| `condutor_id` | String | Identificação do condutor |
+| `lat_cond` | String (Obrigatório) | Latitude do condutor |
+| `lng_cond` | String (Obrigatório) | Longitude do condutor |
+
+---
+
+# (DEPRECADO) Webhook de Mudança de Status
+
+Um webhook é uma forma de recebimento de informações quando ocorre um dado evento. Neste caso, quando uma corrida sofrer uma alteração do seu estado, quando uma parada for confirmada ou quando o condutor indicar que chegou ao local, a Machine irá acionar uma URL informada pela central com determinadas informações. Este é um mecanismo prático para receber dados da Machine. Caso a central configuração e de corrida sejam a mesma, a central receberá o evento do webhook apenas uma vez.
+
+| Campo | Formato | Descrição |
+| :--- | :--- | :--- |
+| `id_mch` | String (Obrigatório) | Identificação da solicitação no Sistema Machine |
+| `id_externo` | String | Identificação da solicitação pela central |
+| `status_solicitacao` | String (Obrigatório) | Status da solicitação. |
+| `data_hora_solicitacao` | Datetime (Obrigatório) | Data e hora de abertura da solicitação |
+| `chave_trajeto` | String (Obrigatório) | Chave para acesso a consulta aos trajetos |
+| `usuario` | String | Nome do usuário de abertura da solicitação |
+| `condutor` | | (Bloco opcional) - usado apenas quando o condutor atender a solicitação |
+| `id` | Integer (Obrigatório) | Identificação do condutor na plataforma machine |
+| `nome` | String (Obrigatório) | Nome do condutor |
+| `vtr` | String (Obrigatório) | Número da viatura no cadastro do condutor |
+| `telefone` | String (Obrigatório) | Telefone do cadastro do condutor |
+| `cpf` | String (Obrigatório) | CPF do condutor |
+| `modelo` | String (Obrigatório) | Modelo do veículo |
+| `placa` | String (Obrigatório) | Placa do veículo |
+| `empresa` | | (Bloco opcional) - usado para solicitação em eTicket ou Voucher |
+| `nome` | String (Obrigatório) | Nome da empresa |
+| `centro_custo` | String | Nome do centro de custo |
+| `serie_voucher` | String (Obrigatório) | Série do voucher |
+| `numero_voucher` | String (Obrigatório) | Número do voucher |
+| `status_ticket` | String (Obrigatório) | Status de autorização do eTicket. |
+| `numero_autorizacao` | Number (Obrigatório) | Número de autorização |
+| `data_hora_autorizacao` | Datetime (Obrigatório) | Data e hora da autorização |
+| `tipo_finalizacao` | String (Obrigatório) | Tipo de finalização do eTicket |
+| `andamento` | | (Bloco opcional) - usado para andamento da solicitação |
+
+---
+
+# Assinatura de validação do Webhook
+
+A assinatura de validação do webhook tem como objetivo garantir a integridade e a autenticação da mensagem.
+
+Os campos de assinatura, contidos no HEADER, seguem o padrão HMAC-SHA-512.
+
+O campo `Signature-V2` é composto pelos elementos enviados no webhook, a função de hash SHA-512 e a chave da API.
+
+É importante observar que o campo `Signature` está atualmente obsoleto, sendo substituído pelo `Signature-V2`; no entanto, ele é construído com base nos dados recebidos no webhook, a função de hash SHA-512 e a chave privada previamente informada.
+
+```http
+Content-Type: application/json
+Signature-V2: 17d3170aa2271f8ce1151f730cfea1660359f073e99bc96c2320a49a23bf0700225017c3135693eb7bd1ba9aa06ada60924fdf38f2856bd3ef3aca169f89988a
+@deprecated Signature: 17d3170aa2271f8ce1151f730cfea1660359f073e99bc96c2320a49a23bf0700225017c3135693eb7bd1ba9aa06ada60924fdf38f2856bd3ef3aca169f89988a
+```