> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Coloque sua integração com o Fire no ar de ponta a ponta — receber eventos e injetar pedidos.

Este guia te leva pelos passos mínimos para ter uma integração funcionando com o Fire: receber eventos de pedido através de um Integration Flow e injetar pedidos via API REST.

## Pré-requisitos

* Credenciais de API do dashboard do Fire (veja [Autenticação](/pt/authentication))
* Um endpoint HTTPS acessível publicamente
* Acesso ao dashboard em **Settings → Integration Flows**

## Passo 1: Configurar um Integration Flow

No dashboard do Fire, vá em **Settings → Integration Flows → New flow**, e então:

* **Trigger:** escolha `order.completed`
* **Escopo:** account, vendor e opcionalmente lojas específicas
* **Nó HTTP:** adicione um e configure
  * Método: `POST`
  * URL: seu endpoint HTTPS
  * Headers: `Content-Type: application/json` (mais qualquer header de auth — Bearer token / API key)
  * Body: cole o template canônico de exemplo que o dashboard inclui (produz `{ event, data, _meta }`)
* **Ative** o flow

Para um walkthrough de 10 minutos com detalhe passo a passo, veja [Tratar eventos de pedido](/pt/guides/handle-order-events).

<Tip>
  Durante o desenvolvimento você pode usar uma ferramenta como [ngrok](https://ngrok.com) para expor um servidor local à internet. Cole a URL HTTPS do ngrok como URL do nó HTTP do flow.
</Tip>

## Passo 2: Identificadores de canal e serviço para pedidos

Se sua integração injeta pedidos, os objetos `channel` e `service` precisam de valores `uid` do Fire (e campos relacionados). Obtenha esses identificadores nos payloads de webhooks de publicação — por exemplo [`channel.updated`](/pt/webhook-reference/channel-updated) e eventos relacionados — ou na configuração de integração e canais que você gerencia no painel Fire (veja [Integrações de agregadores](/pt/configuration/backoffice-integrations)).

## Passo 3: Tratar o evento

Seu endpoint vai receber requisições `POST` do seu flow toda vez que um pedido for completado. O formato do body é o que o template do body do seu flow renderiza. Com o template canônico, isso é:

```json theme={null}
{
  "event": {
    "id": "0d6e8a1c-1e7a-4b4f-8a3a-74ab0e9a9b21",
    "type": "order.completed",
    "createdAt": "2026-05-06T01:22:59.902Z"
  },
  "data": {
    "orderId": "21ec1f6c-c301-4528-b999-7836c1d21c6c",
    "orderCode": "OC-br-001",
    "status": "COMPLETED",
    "paymentStatus": "SUCCEEDED",
    "store": { /* ... */ },
    "client": { /* ... */ },
    "payments": { /* ... */ },
    "orderLines": [ /* ... */ ],
    "fulfillment": { /* ... */ }
  },
  "_meta": { "executionId": "...", "flowId": "...", "attempt": "1" }
}
```

Um handler mínimo:

```js theme={null}
import express from "express";

const app = express();
const seen = new Map(); // troque por Redis/DB em produção

app.post("/fire/events", express.json(), async (req, res) => {
  const { event, data } = req.body ?? {};
  if (!event?.id) return res.status(400).end();

  // 1. Confirme rápido (o Fire dá timeout em 30s)
  res.status(200).end();

  // 2. Deduplique por event.id
  if (seen.has(event.id)) return;
  seen.set(event.id, Date.now());

  // 3. Despache por type
  switch (event.type) {
    case "order.completed":      return onOrderCompleted(data);
    case "order.cancelled":      return onOrderCancelled(data);
    case "order.invoiced": return onFiscalAuthorized(data);
    case "order.reversed":  return onFiscalCancelled(data);
  }
});

app.listen(8080);
```

Veja [`order.completed`](/pt/events/order-completed) para a referência campo a campo do payload.

## Passo 4: Injetar pedidos

Quando seu sistema receber um pedido (de um agregador ou qualquer outra fonte), injete-o no Fire.

```http theme={null}
POST /v1/orders
Authorization: Bearer <sua_api_key>
Content-Type: application/json

{
  "channelId": "channel_uber",
  "externalOrderId": "uber_order_xyz",
  "...": "veja a referência completa"
}
```

Quando o pedido alcançar `status=COMPLETED` e `paymentStatus=SUCCEEDED`, seu flow dispara e seu handler roda. Se o pedido for cancelado depois, você receberá `order.cancelled`.

Veja [Injetar pedido](/pt/api-reference/orders) para a referência completa do payload.

## Passo 5: Adicionar eventos fiscais (apenas Brasil)

Se você opera no Brasil e tem emissão fiscal habilitada para uma loja, adicione um segundo flow com trigger `order.invoiced` (e outro com `order.reversed`) — mesmo endpoint HTTPS, mesmo template — para receber o contexto do documento fiscal.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Tratar eventos de pedido" icon="bolt" href="/pt/guides/handle-order-events">
    Walkthrough detalhado com auth e idempotência.
  </Card>

  <Card title="Visão geral de eventos" icon="bell" href="/pt/events/overview">
    Envelope, headers, retentativas, dedup.
  </Card>

  <Card title="Referência order.completed" icon="receipt" href="/pt/events/order-completed">
    Esquema de payload completo com os blocos fiscais BR.
  </Card>

  <Card title="Referência da API" icon="code" href="/pt/api-reference/introduction">
    Injetar pedidos e chamar endpoints autenticados.
  </Card>
</CardGroup>