Convenciones de la API

La API de Vipter sigue las convenciones de la API de Stripe siempre que existe un equivalente: nombres de campos, formato de error, paginación por cursor, idempotencia y versión por fecha. Quien ya integró Stripe reconoce todo. Esta página reúne lo que vale para todos los endpoints; cada endpoint está en la referencia.

Dirección baseCopiar enlace de la sección

https://api.vipter.com/v1

El mismo servicio responde en https://app.vipter.com/api/v1, con las mismas rutas. Usa api.vipter.com en las integraciones nuevas; la otra dirección existe para redes donde solo el dominio del panel está permitido.

Toda llamada es HTTPS. Una URL fuera de /v1 o una ruta que no existe recibe 404 resource_missing, en el mismo formato que los demás errores.

VersiónCopiar enlace de la sección

La API tiene versiones por fecha. La versión actual es 2026-11-01, la única que existe hoy.

Cada clave de API nace fijada a la versión actual del día en que fue creada, y las solicitudes con ella usan esa versión sin necesidad de indicar nada. Para pedir otra versión en una llamada, envía el encabezado:

Vipter-Version: 2026-11-01

Una versión desconocida recibe 400 invalid_api_version, con la lista de versiones aceptadas en el mensaje. Toda respuesta autenticada trae el encabezado Vipter-Version con la versión usada.

Dentro de una versión, la API solo cambia de forma compatible: pueden aparecer campos nuevos en cualquier objeto en cualquier momento, y valores nuevos en campos de texto como status y payment_method. Escribe tu código para ignorar los campos que no conoce. Un cambio incompatible, como renombrar o quitar un campo, se convierte en una versión nueva, y las claves existentes siguen en la versión anterior.

Formato de la solicitudCopiar enlace de la sección

Los parámetros de consulta van en la query string. Los cuerpos de solicitud, en los endpoints que aceptan cuerpo, pueden ir en JSON o en formulario:

El formato de formulario usa la notación de corchetes de Stripe: a[b]=1 se convierte en un objeto, a[0]=x&a[1]=y o a[]=x&a[]=y se convierten en una lista. Un curl copiado de la documentación de Stripe funciona tal cual. En formulario todo valor llega como texto; la API convierte números y booleanos donde los espera.

La query string acepta la misma notación de corchetes. Un cuerpo con otro Content-Type, o un JSON que no es un objeto, recibe 400 parameter_invalid.

Formato de la respuestaCopiar enlace de la sección

Toda respuesta es JSON en UTF-8, con Cache-Control: no-store. Consultar un objeto devuelve el objeto; un listado devuelve un objeto list (consulta Paginación); un error devuelve un objeto error (consulta Errores).

Encabezados presentes en toda respuesta:

Tipos de datoCopiar enlace de la sección

Los campos metadata, client_reference_id y checkout_session de los pedidos y las suscripciones vienen completados cuando la venta nació de una sesión de checkout creada por la API; en las demás ventas, vienen {} o null.

ErroresCopiar enlace de la sección

Un error es una respuesta con código HTTP 4xx o 5xx y este cuerpo:

{
  "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 errorCopiar enlace de la sección

CódigosCopiar enlace de la sección

Un objeto que existe pero pertenece a otra tienda es un 404, igual que un ID inexistente. Los códigos propios de un endpoint, como offer_unavailable o portal_disabled, están en la referencia, junto al endpoint.

IdempotenciaCopiar enlace de la sección

Repetir una solicitud por un timeout de red no puede cobrar dos veces. Para eso, todo POST y DELETE acepta el encabezado Idempotency-Key, con un valor único que tú generas, como un UUID v4:

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

Las reglas, las mismas de Stripe:

• La clave vale por 24 horas dentro de la tienda. Hasta 255 caracteres.
• La misma clave con el mismo método, ruta y cuerpo devuelve la respuesta guardada de la primera vez, con el mismo código HTTP, sin ejecutar nada de nuevo. La respuesta repetida trae Idempotent-Replayed: true y Original-Request-Id con el Request-Id de la primera.
• La misma clave con un cuerpo distinto recibe 400 idempotency_key_reused.
• Mientras la primera solicitud todavía se ejecuta, una segunda con la misma clave recibe 409 idempotency_key_in_use. Espera un momento y repite con la misma clave.
• Las respuestas 4xx también se guardan y se repiten. Las 5xx no: puedes reintentar con la misma clave.

Los endpoints GET son idempotentes por naturaleza e ignoran el encabezado. En los POST de hoy (sesiones de checkout, clientes, sesiones del portal) la clave es opcional y recomendada; en los endpoints de cobro que vienen después, será obligatoria.

PaginaciónCopiar enlace de la sección

Todo listado devuelve un 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 }
  ]
}

Los elementos vienen del más nuevo al más antiguo. Parámetros, los mismos de Stripe:

No envíes los dos cursores en la misma llamada (400 parameter_invalid). Un cursor que no existe en la tienda recibe 404 resource_missing, con param indicando cuál. Los filtros del endpoint, como customer o status, siguen valiendo con el cursor.

Para recorrer todo, repite mientras has_more sea true, pasando el id del último elemento en 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_…"

Las ofertas vienen en orden alfabético por nombre, y no por fecha, porque son un catálogo pequeño. Los cursores funcionan de la misma manera.

Límites de solicitudesCopiar enlace de la sección

Cada clave de API puede hacer 100 solicitudes cada 2 segundos, lo que da 50 por segundo con margen para ráfagas. Toda respuesta dice dónde estás:

Pasado el límite, la respuesta es 429 rate_limit con Retry-After en segundos. Espera ese tiempo y repite. En una integración que recorre muchos datos, usa limit=100 y una pequeña pausa entre páginas en vez de paralelizar llamadas.

Las solicitudes sin clave válida tienen un límite aparte, por dirección IP: 10 por minuto.

Request-IdCopiar enlace de la sección

Toda respuesta, incluidos los errores y los 429, trae un Request-Id único:

Request-Id: req_8c2f4e6a1b3d5f7e9a0c

Registra ese valor en tus logs junto con la llamada. Al hablar con el soporte de Vipter sobre una solicitud, indica el Request-Id: con él, el soporte localiza la llamada exacta, con el estado, la duración y el error. El mismo valor aparece en los registros de solicitudes del panel, que se guardan por 30 días.

Diferencias respecto a StripeCopiar enlace de la sección

La API no es un clon: el objetivo es que una integración con Stripe se adapte por mapeo, no que el SDK de Stripe funcione apuntando a Vipter. Lo que cambia:

Qué hacer despuésCopiar enlace de la sección

• Consulta cada endpoint y cada objeto en la referencia de la API.
• Crea y protege las claves en Autenticación y claves de API.