Webhooks

Os webhooks da Flowls permitem que sua equipe receba notificações automáticas sobre eventos importantes, como a criação ou atualização de pedidos e processos logísticos.

Como funciona

• Endpoint único: Todos os eventos são enviados para um único endpoint HTTP do tipo POST, fornecido por sua equipe.
• Headers: Recomendamos configurar uma api-key para garantir a segurança da comunicação. O header típico será:

  api-key: SUA_API_KEY
  Content-Type: application/json
• Body: O corpo da requisição conterá dois campos principais:
  • "type": indica o tipo de evento, podendo ser "ORDER" ou "PROCESS".
  • "data": um objeto com os dados completos do pedido ou processo.

Ativação e configuração

Para ativar e configurar os webhooks, entre em contato com a equipe de integrações da Flowls. Será necessário informar:

• A URL do endpoint que receberá os eventos;
• A api-key que será utilizada para autenticação;
• Os tipos de evento que deseja receber: criação, atualização ou ambos.

A equipe realizará a configuração conforme os dados fornecidos, garantindo o envio adequado das notificações.

Exemplos Simplificados do Body:

Process:

{
    "type": "PROCESS",
    "data": {
        "id": "67890",
        "alert_level": "warning",
        "reference_code": "PROC-002",
        "finished_at": null,
        "lead_time_datetime_reference": "2023-10-01T14:00:00Z",
        "extra_fields": {},
        "handlers": [],
        "foreign_trade_shipment": {
            "air_transport_shipment": {
                "id": 1122,
                "type": "LOOSE_CARGO",
                "hawb": "hawb_number",
                "airline": null,
                "awb": null,
                "destination_airport": null,
                "origin_airport": null
            }
        }
    }
}

Order:

{
    "type": "ORDER",
    "data": {
        "id": "12345",
        "alert_level": "normal",
        "reference_code": "ORD-001",
        "finished_at": null,
        "extra_fields": {},
        "handlers": [],
        "processes": [],
        "sales_order": {
            "id": 1234,
            "type": "DIRECT",
            "items": [
                {
                    "line_number": 1,
                    "line_reference": "1",
                    "product": {
                        "code": "PROD 1",
                        "id": 123456,
                        "description": "PRODUTO 1",
                        "mercosul_code": null,
                        "package_type": null
                    }
                }
            ],
            "order_confirmed_at": null,
            "order_received_at": null
        }
    }
}

Observação: O formato dos dados dentro do campo data segue o mesmo padrão de estrutura retornado pelo endpoint GET /orders/:id ou GET /processes/:id da REST API da Flowls. Assim, a integração do seu sistema com os webhooks é consistente com as respostas já utilizadas na API.

Testando Webhooks com o Postman

Para facilitar a configuração e os testes dos webhooks, disponibilizamos exemplos prontos na pasta webhooks dentro das collections do Postman. Nela, você encontrará requisições para testar tanto pedidos (orders) quanto processos (processes), em cenários de importação (IMPO) e exportação (EXPO).

Você pode acessar essas collections na seção Próximos Passos da documentação.

Configurando os Testes no Postman

1. Informe a URL do seu endpoint nos exemplos de webhook.
2. Ajuste os headers conforme necessário para o seu ambiente. Por exemplo:
   • Content-Type: application/json para indicar o tipo de conteúdo enviado.
   • api-key: SUA_API_KEY ou outros headers de autenticação, se sua aplicação exigir.
3. Envie a requisição e verifique se o payload foi recebido corretamente.