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

> ## Agent Instructions
> Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": "<eventId>"}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI.

# Onboarding de lojas

> Registre por loja o merchantId do seu sistema, a URL de webhook e o endpoint de catálogo no padrão Open Delivery.

O onboarding registra a configuração da integração Open Delivery **por loja**: qual é o identificador da loja no seu sistema, para onde enviar os webhooks de pedido e onde a DeliveryVip busca os dados da loja no padrão OD.

Use o token emitido com o `client_secret` **daquela loja**: é ele que determina qual loja está sendo configurada. Veja [Primeiros passos](/docs/guides/open-delivery/primeiros-passos.md).

> [!NOTE]
>
> **Também disponível pelo painel.** Esses mesmos dados podem ser preenchidos no painel de developers ([https://developer.deliveryvip.com.br/](https://developer.deliveryvip.com.br/)), no formulário **"Dados da integração da loja"**, sem chamar a API. O endpoint `merchantOnboarding` é útil para automatizar o cadastro quando você integra muitas lojas.

## Request

```
PUT https://od.deliveryvip.com.br/v1/merchantOnboarding?merchantId={merchantId}
```

O `merchantId` vai na **query string**; o restante no corpo, em camelCase, conforme a spec OD.

**merchantId** `string` *required*

O identificador da loja **no seu sistema**. A partir do onboarding, ele passa a ser o `merchantId` usado nos eventos e nas URLs da integração.

**ordersWebhookURL** `string`

URL que receberá os webhooks de pedido **desta loja**. Veja [Recebendo eventos](/docs/guides/open-delivery/recebendo-eventos.md).

**getMerchantURL** `object`

Onde a DeliveryVip busca os dados da loja no padrão OD Merchant.

**propriedades**

**baseURL** `string`

URL do **seu** endpoint OD Merchant. A DeliveryVip faz um `GET` exatamente nesta URL; veja [Catálogo](/docs/guides/open-delivery/catalogo.md).

**apiKey** `string`

Chave que a DeliveryVip envia no header `X-API-KEY` ao chamar o seu endpoint. Fica guardada criptografada.

```bash cURL theme={null}
curl --request PUT 'https://od.deliveryvip.com.br/v1/merchantOnboarding?merchantId=loja-centro-001' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ordersWebhookURL": "https://pdv.exemplo.com.br/webhooks/deliveryvip",
    "getMerchantURL": {
      "baseURL": "https://pdv.exemplo.com.br/opendelivery/merchant",
      "apiKey": "{sua api key}"
    }
  }'
```

```js Node.js theme={null}
const url = new URL('https://od.deliveryvip.com.br/v1/merchantOnboarding')
url.searchParams.set('merchantId', 'loja-centro-001')

const response = await fetch(url, {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ordersWebhookURL: 'https://pdv.exemplo.com.br/webhooks/deliveryvip',
    getMerchantURL: {
      baseURL: 'https://pdv.exemplo.com.br/opendelivery/merchant',
      apiKey: process.env.MERCHANT_API_KEY,
    },
  }),
})
console.log(response.status) // 201 ou 204
```

```python Python theme={null}
import os
import requests

response = requests.put(
    "https://od.deliveryvip.com.br/v1/merchantOnboarding",
    params={"merchantId": "loja-centro-001"},
    headers={"Authorization": f"Bearer {token}"},
    json={
        "ordersWebhookURL": "https://pdv.exemplo.com.br/webhooks/deliveryvip",
        "getMerchantURL": {
            "baseURL": "https://pdv.exemplo.com.br/opendelivery/merchant",
            "apiKey": os.environ["MERCHANT_API_KEY"],
        },
    },
)
print(response.status_code)  # 201 ou 204
```

Só o `merchantId` é obrigatório. Os campos do corpo que você não enviar ficam sem configuração: a loja fica sem webhook próprio ou sem endpoint de catálogo até você informá-los.

## Response

| Código | Quando |
| - | - |
| `201 Created` | A configuração da loja foi criada. |
| `204 No Content` | A configuração da loja foi atualizada. Como a configuração nasce na instalação do app (junto com o `client_secret` da loja), espere `204` já no primeiro envio. |
| `400 Bad Request` | `merchantId` ausente ou URL inválida. Nada é gravado. A mensagem vem em `title`. |
| `401 Unauthorized` | Token ausente, inválido ou expirado. |
| `422 Unprocessable Content` | O app não declara a extensão Open Delivery (`open_delivery_extension_not_declared`). |

> [!TIP]
>
> Trate `201` e `204` como sucesso. Depois do onboarding, chame o [`merchantUpdate`](/docs/guides/open-delivery/catalogo#re-sincronização-merchantupdate) para disparar a primeira importação do catálogo: o onboarding apenas registra a configuração.

## Reenviar o onboarding

O onboarding é um **upsert** que **substitui** a configuração da loja: cada envio regrava `merchantId`, `ordersWebhookURL` e `getMerchantURL` com o que veio no corpo. Envie sempre a configuração completa; um campo omitido no reenvio é apagado.

Ao reenviar:

* o `client_secret` da loja é **preservado**: você não precisa reconfigurar a credencial;
* o circuito de webhooks da loja é **religado**, se estiver suspenso. Reenviar o onboarding é uma das formas de reativar as entregas; veja [Recebendo eventos](/docs/guides/open-delivery/recebendo-eventos.md#reentrega-e-suspensão).

## O `merchantId` da integração

O `merchantId` informado no onboarding passa a ser **o** identificador da loja em toda a integração: é o valor que chega nos eventos (campo `merchantId` e header `X-App-MerchantId` dos webhooks) e o que você informa em [`merchantStatus`](/docs/guides/open-delivery/catalogo#acompanhando-o-processamento-merchantstatus). Se a loja não tiver um `merchantId` configurado, a integração usa o **id interno** da loja na DeliveryVip.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.