> ## 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.

# Cadastrar uma loja

> Crie uma loja vinculada ao seu parceiro ou a uma das suas revendas.

`POST /partner/v2/{partnerId}/merchants` cria a loja já pronta para uso: domínio padrão, formas de pagamento, áreas de entrega e assinatura em `TRIAL` por 10 dias, no plano padrão (`standard`) do parceiro.

> [!NOTE]
>
> O `partnerId` define a quem a loja pertence:
>
> * **ID do parceiro**: a loja é atendida diretamente pelo parceiro.
> * **ID de uma revenda**: a loja nasce na revenda (`resaleId`), abaixo do parceiro dela.
>
> Um token de parceiro aceita o próprio ID e o de qualquer revenda dele. Um token de revenda aceita só o ID da revenda. Qualquer outro ID retorna `403`. O ID do parceiro aparece em `partnerId` nas respostas de [Listar lojas](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md).

> [!WARNING]
>
> A loja recebe o plano marcado como `standard` do parceiro. Confira em [Listar planos](/docs/guides/partner/plans/utilizando-a-api/listar-planos.md) se existe um plano padrão disponível antes de cadastrar.

## Corpo

**name** `string` *required*

Nome fantasia.

**corporateName** `string` *required*

Razão social.

**identifier** `string` *required*

CNPJ ou CPF da loja, com ou sem formatação. Precisa ser válido.

**email** `string` *required*

E-mail da loja.

**personResponsible** `object` *required*

Responsável pela loja.

**propriedades**

**name** `string` *required*

Nome.

**email** `string` *required*

E-mail.

**phone.number** `string` *required*

Telefone.

**identifier** `string`

CPF do responsável.

**address** `object` *required*

Endereço da loja. Todos os campos são obrigatórios.

**propriedades**

**postalCode** `string` *required*

CEP.

**street** `string` *required*

Rua.

**number** `string` *required*

Número.

**district** `string` *required*

Bairro.

**city** `string` *required*

Cidade.

**state** `string` *required*

UF.

## Requisição

```bash cURL theme={null}
curl --request POST 'https://api.deliveryvip.com.br/partner/v2/{partnerId}/merchants' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Cantina da Maria",
    "corporateName": "Cantina da Maria LTDA",
    "identifier": "11222333000144",
    "email": "contato@cantinadamaria.com.br",
    "personResponsible": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com.br",
      "phone": { "number": "11999998888" },
      "identifier": "12345678909"
    },
    "address": {
      "postalCode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }'
```

```js Node.js theme={null}
const response = await fetch(`https://api.deliveryvip.com.br/partner/v2/${partnerId}/merchants`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Cantina da Maria',
    corporateName: 'Cantina da Maria LTDA',
    identifier: '11222333000144',
    email: 'contato@cantinadamaria.com.br',
    personResponsible: {
      name: 'Maria Silva',
      email: 'maria@exemplo.com.br',
      phone: { number: '11999998888' },
    },
    address: {
      postalCode: '01310-100',
      street: 'Avenida Paulista',
      number: '1000',
      district: 'Bela Vista',
      city: 'São Paulo',
      state: 'SP',
    },
  }),
})
const merchant = await response.json()
```

```python Python theme={null}
response = requests.post(
    f"https://api.deliveryvip.com.br/partner/v2/{partner_id}/merchants",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "Cantina da Maria",
        "corporateName": "Cantina da Maria LTDA",
        "identifier": "11222333000144",
        "email": "contato@cantinadamaria.com.br",
        "personResponsible": {
            "name": "Maria Silva",
            "email": "maria@exemplo.com.br",
            "phone": {"number": "11999998888"},
        },
        "address": {
            "postalCode": "01310-100",
            "street": "Avenida Paulista",
            "number": "1000",
            "district": "Bela Vista",
            "city": "São Paulo",
            "state": "SP",
        },
    },
)
merchant = response.json()
```

## Respostas

| Status | Quando |
| - | - |
| `201 Created` | Loja criada. O corpo é a loja completa, no formato de [Obter detalhes](/docs/guides/partner/merchant/utilizando-a-api/obter-detalhes-do-merchant.md). |
| `403 Forbidden` | `partnerId` fora do alcance do token. |
| `422 Unprocessable Content` | Dados inválidos. O `title` traz os erros por campo, com os nomes internos em snake\_case. |

```json Resposta (201, resumida) theme={null}
{
  "id": "466caa37-ab0b-4f9d-b583-896681627367",
  "name": "Cantina da Maria",
  "identifier": "11.222.333/0001-44",
  "subscription": {
    "status": "TRIAL",
    "trialExpiresAt": "2025-10-10T17:35:03-03:00",
    "planId": "aa67c98c-d81f-5a9c-b0bc-26caa0051aea"
  },
  "partnerId": "32eeaefa-6a31-487f-9402-fd9a41683830"
}
```

## Próximos passos

> [card] [Adicionar membros](/docs/guides/partner/merchant/utilizando-a-api/membros-do-merchant.md)
>
> Dê acesso ao painel para o lojista.

> [card] [Ativar a assinatura](/docs/guides/partner/merchant/utilizando-a-api/gerenciar-assinatura-dos-merchants.md)
>
> Saia do teste com contrato e plano.


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