Convenções da API

A API do Vipter segue as convenções da API da Stripe sempre que existe um equivalente: nomes de campos, formato de erro, paginação por cursor, idempotência e versão por data. Quem já integrou a Stripe reconhece tudo. Esta página reúne o que vale para todos os endpoints; cada endpoint está na referência.

Endereço baseCopiar link da seção

https://api.vipter.com/v1

O mesmo serviço responde em https://app.vipter.com/api/v1, com os mesmos caminhos. Use api.vipter.com nas integrações novas; o outro endereço existe para ambientes onde só o domínio do painel está liberado na rede.

Toda chamada é HTTPS. Uma URL fora de /v1 ou um caminho que não existe recebe 404 resource_missing, no mesmo formato dos outros erros.

VersãoCopiar link da seção

A API tem versões por data. A versão atual é 2026-11-01, a única que existe hoje.

Cada chave de API nasce presa à versão atual do dia em que foi criada, e as requisições com ela usam essa versão sem precisar dizer nada. Para pedir outra versão numa chamada, envie o cabeçalho:

Vipter-Version: 2026-11-01

Uma versão desconhecida recebe 400 invalid_api_version, com a lista das versões aceitas na mensagem. Toda resposta autenticada traz o cabeçalho Vipter-Version com a versão usada.

Dentro de uma versão, a API só muda de forma compatível: campos novos podem aparecer em qualquer objeto a qualquer momento, e valores novos podem aparecer em campos de texto como status e payment_method. Escreva o seu código para ignorar campos que não conhece. Uma mudança incompatível, como renomear ou remover um campo, vira uma versão nova, e as chaves existentes continuam na versão antiga.

Formato da requisiçãoCopiar link da seção

Parâmetros de consulta vão na query string. Corpos de requisição, nos endpoints que aceitam corpo, podem ir em JSON ou em formulário:

O formato de formulário usa a notação de colchetes da Stripe: a[b]=1 vira um objeto, a[0]=x&a[1]=y ou a[]=x&a[]=y viram uma lista. Um curl copiado da documentação da Stripe funciona como está. Em formulário todo valor chega como texto; a API converte números e booleanos onde os espera.

A query string aceita a mesma notação de colchetes. Um corpo com outro Content-Type, ou um JSON que não é um objeto, recebe 400 parameter_invalid.

Formato da respostaCopiar link da seção

Toda resposta é JSON em UTF-8, com Cache-Control: no-store. Uma consulta de um objeto devolve o objeto; uma listagem devolve um objeto list (veja Paginação); um erro devolve um objeto error (veja Erros).

Cabeçalhos presentes em toda resposta:

Tipos de dadoCopiar link da seção

Os campos metadata, client_reference_id e checkout_session dos pedidos e das assinaturas vêm preenchidos quando a venda nasceu de uma sessão de checkout criada pela API; nas outras vendas, vêm {} ou null.

ErrosCopiar link da seção

Um erro é uma resposta com código HTTP 4xx ou 5xx e este corpo:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid query parameter 'limit': Number must be less than or equal to 100",
    "param": "limit",
    "doc_url": "https://docs.vipter.com/pt-br/developers/api-conventions#erros"
  }
}

Tipos de erroCopiar link da seção

CódigosCopiar link da seção

Um objeto que existe mas pertence a outra loja é um 404, igual a um ID inexistente. Os códigos próprios de um endpoint, como offer_unavailable ou portal_disabled, estão na referência, junto do endpoint.

IdempotênciaCopiar link da seção

Repetir uma requisição por causa de um timeout de rede não pode cobrar duas vezes. Para isso, todo POST e DELETE aceita o cabeçalho Idempotency-Key, com um valor único que você gera, como um UUID v4:

curl -X POST https://api.vipter.com/v1/… \
  -H "Authorization: Bearer vk_live_…" \
  -H "Idempotency-Key: 5f0b2c8e-3a1d-4e7f-9b6c-2d4a8e1f0c3b" \
  …

Regras, as mesmas da Stripe:

• A chave vale por 24 horas dentro da loja. Até 255 caracteres.
• A mesma chave com o mesmo método, caminho e corpo devolve a resposta guardada da primeira vez, com o mesmo código HTTP, sem executar nada de novo. A resposta repetida traz Idempotent-Replayed: true e Original-Request-Id com o Request-Id da primeira.
• A mesma chave com um corpo diferente recebe 400 idempotency_key_reused.
• Enquanto a primeira requisição ainda está rodando, uma segunda com a mesma chave recebe 409 idempotency_key_in_use. Espere um instante e repita com a mesma chave.
• Respostas 4xx também são guardadas e repetidas. Respostas 5xx não: você pode repetir com a mesma chave.

Os endpoints GET são idempotentes por natureza e ignoram o cabeçalho. Nos POST de hoje (sessões de checkout, clientes, sessões do portal) a chave é opcional e recomendada; nos endpoints de cobrança que vêm em seguida, ela será obrigatória.

PaginaçãoCopiar link da seção

Toda listagem devolve um objeto list:

{
  "object": "list",
  "url": "https://api.vipter.com/v1/orders",
  "has_more": true,
  "data": [
    { "id": "ord_7b3e9f1c2a8d4e6f", "object": "order", "created": 1790790412 },
    { "id": "ord_5c1e8a2b9d4f4e7a", "object": "order", "created": 1790704011 }
  ]
}

Os itens vêm do mais novo para o mais antigo. Parâmetros, os mesmos da Stripe:

Não envie os dois cursores na mesma chamada (400 parameter_invalid). Um cursor que não existe na loja recebe 404 resource_missing, com param dizendo qual. Os filtros do endpoint, como customer ou status, continuam valendo com o cursor.

Para percorrer tudo, repita enquanto has_more for true, passando o id do último item em starting_after:

curl "https://api.vipter.com/v1/orders?limit=100" \
  -H "Authorization: Bearer vk_live_…"

# has_more: true, último id: ord_5c1e8a2b9d4f4e7a
curl "https://api.vipter.com/v1/orders?limit=100&starting_after=ord_5c1e8a2b9d4f4e7a" \
  -H "Authorization: Bearer vk_live_…"

Ofertas vêm em ordem alfabética de nome, e não por data, porque são um catálogo pequeno. Os cursores funcionam do mesmo jeito.

Limites de requisiçõesCopiar link da seção

Cada chave de API pode fazer 100 requisições a cada 2 segundos, o que dá 50 por segundo com espaço para rajadas. Toda resposta diz onde você está:

Passou do limite, a resposta é 429 rate_limit com Retry-After em segundos. Espere esse tempo e repita. Numa integração que varre muitos dados, use limit=100 e um pequeno intervalo entre páginas em vez de paralelizar chamadas.

Requisições sem chave válida têm um limite separado, por endereço IP: 10 por minuto.

Request-IdCopiar link da seção

Toda resposta, inclusive erros e 429, traz um Request-Id único:

Request-Id: req_8c2f4e6a1b3d5f7e9a0c

Registre esse valor nos seus logs junto com a chamada. Ao falar com o suporte do Vipter sobre uma requisição, informe o Request-Id: com ele o suporte localiza a chamada exata, com o status, a duração e o erro. O mesmo valor aparece nos logs de requisições do painel, que ficam guardados por 30 dias.

Diferenças em relação à StripeCopiar link da seção

A API não é um clone: o objetivo é que uma integração com a Stripe seja adaptada por mapeamento, não que o SDK da Stripe funcione apontando para o Vipter. O que muda:

O que fazer a seguirCopiar link da seção

• Veja cada endpoint e cada objeto na referência da API.
• Crie e proteja as chaves em Autenticação e chaves de API.