Referência rápida - DeliveryVip Developers

Host: https://od.deliveryvip.com.br

Você chama: API OD da DeliveryVip

Método	Endpoint	Descrição
`POST`	`/oauth/token`	Token OAuth2 (client credentials, scope `od.all`) com o `client_id` do app e o `client_secret` da loja. Fica na raiz do host, fora do `/v1`.
`GET`	`/v1/versions/orderingApp`	Versões das specs suportadas e métodos de eventos disponíveis. Público.
`GET`	`/v1/versions/merchant`	Versão do endpoint Merchant. Público.
`PUT`	`/v1/merchantOnboarding?merchantId={id}`	Registrar/substituir a configuração da loja: `ordersWebhookURL` e `getMerchantURL` (`baseURL`, `apiKey`).
`POST`	`/v1/merchantUpdate`	Corpo vazio: reimportar a loja. `merchantStatus`: abrir/fechar a loja, sem reimportar.
`GET`	`/v1/merchantStatus?merchantId={id}`	Resultado do último processamento: `lastRead`, `status` (`SUCCESS`/`PROCESSING`/`FAIL`) e `moreInfo`.
`GET`	`/v1/events:polling`	Eventos pendentes (últimas 24 h, máx. 100 por chamada, mais antigos primeiro). Filtros `eventType` e `orderType` repetidos na query.
`POST`	`/v1/events/acknowledgment`	Confirmar eventos processados (`202`, idempotente).
`GET`	`/v1/orders/{orderId}`	Detalhes de um pedido.
`POST`	`/v1/orders/{orderId}/{ação}`	Transicionar o status: `confirm`, `preparing`, `readyForPickup`, `pickedUp`, `dispatch`, `delivered`, `requestCancellation`, `acceptCancellation`, `denyCancellation`, `tracking`.

A DeliveryVip chama: seu sistema

Método	URL	Descrição
`POST`	`ordersWebhookURL` da loja	Um evento por requisição, assinado em `X-App-Signature`.
`GET`	`getMerchantURL.baseURL` da loja	Snapshot da loja no formato da spec Merchant. Chamada exatamente nesta URL, com a `apiKey` no header `X-API-KEY`.

Versões das specs

Spec	Versão
Order	`1.3.0`
Merchant	`1.0.0`

Métodos de eventos: WEBHOOK e POLLING.

Credenciais

Credencial	Escopo
`client_id`	Do app: o mesmo para todas as lojas.
`client_secret`	Da loja: um por loja instalada, no formato `ods_<hint>_<random>`. Define qual loja o token enxerga.
Assinatura do webhook	`X-App-Signature` é HMAC-SHA256 hex do corpo bruto com o `client_secret` da loja.
`X-App-Id` do webhook	Fixo da plataforma: `019efa90-dcd1-7846-983d-6bab871b2f6b`.

Limites e janelas

Item	Valor
Datas	UTC (RFC 3339, sufixo `Z`), conforme a spec OD, no polling e no webhook.
Polling	100 eventos por chamada; se vierem 100, confirme e consulte de novo imediatamente
Janela de eventos	24 horas
Token OAuth	Expira em 24 horas; o token vigente é reutilizado até expirar
Webhook	Responder 2xx em até 5 s (3 s para conectar)
Retentativas do webhook	Só para `408`, `429`, timeout e erro de conexão: 3 tentativas no total. `5xx` não é retentado.
Suspensão do webhook	Por loja, após 10 falhas consecutivas (retentativas contam). Reativação: reenviar o onboarding, o formulário do painel ou o botão “Reativar envio de webhooks”.
Importação do catálogo	Assíncrona; avisos em sequência agrupados em 10 s

Códigos de resposta comuns

Código	Quando ocorre
`200`	`requestCancellation`, `acceptCancellation`, `denyCancellation`; `merchantStatus`.
`201` / `204`	`merchantOnboarding`: criação / atualização da configuração (com credencial por loja, espere `204`).
`202`	Transições de status, `tracking` e acknowledgment.
`204`	`events:polling` sem eventos pendentes; `merchantUpdate` aceito.
`400`	`merchantOnboarding` / `merchantStatus` sem `merchantId`, ou URL inválida no onboarding.
`401`	Token ausente, inválido ou expirado.
`403`	Token sem o scope `od.all`; ou valor inválido em filtro do polling.
`404`	Pedido inexistente ou ainda aguardando pagamento; `merchantStatus` de loja desconhecida, fora do alcance do token, ou sem processamento registrado.
`422`	Transição que o estado do pedido não aceita; `merchantUpdate` com corpo inválido ou loja sem `getMerchantURL`; `merchantOnboarding` sem a extensão Open Delivery (`open_delivery_extension_not_declared`).