REST API · OpenAPI 3.0 · HMAC Webhooks

Documentación API

Integre el cumplimiento fiscal de Bali en sus aplicaciones

12 Endpoints100 sol./minHMAC-SHA256OpenAPI 3.0

Obtener una clave API Ver documentación interactiva

Bearer Auth

Claves API en Configuración → API. vt_live_* para producción, vt_test_* para sandbox.

Límites de tasa

100 solicitudes/minuto por clave API. Headers: X-RateLimit-Limit, X-RateLimit-Remaining.

Webhooks firmados

Firma HMAC-SHA256 en cada payload. Reintento automático con backoff exponencial en caso de fallo.

OpenAPI 3.0

Especificación completa en /openapi.yaml. Use openapi-generator para crear SDKs en cualquier lenguaje.

Autenticación

Todas las solicitudes API requieren un Bearer token API key. Obtenga su clave desde Panel > Configuración > Claves API.

Base URL: https://villa-tax.operium.store/api/v1
Auth:     Authorization: Bearer vt_live_YOUR_API_KEY
Sandbox:  Bearer vt_test_YOUR_KEY (returns testMode: true)

Limitado a 100 solicitudes/minuto por clave API. Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Inicio rápido

JavaScriptnode.js

// Authenticate with Bearer token
const headers = {
  'Authorization': 'Bearer vt_live_YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// List your properties
const res = await fetch(
  'https://villa-tax.operium.store/api/v1/properties?organizationId=YOUR_ORG_ID',
  { headers }
).then(r => r.json());
// { data: [...], testMode: false, meta: { total: 5, page: 1, limit: 20 } }

// Create a booking + auto tax calculation
const booking = await fetch('https://villa-tax.operium.store/api/v1/bookings', {
  method: 'POST', headers,
  body: JSON.stringify({
    propertyId: 'prop-uuid',
    guestName: 'Alice Martin',
    checkIn: '2025-06-15',
    checkOut: '2025-06-22',
    grossAmountIdr: 14000000,
    platform: 'airbnb'
  })
}).then(r => r.json());
// { data: { id: '...', taxBreakdowns: [{ type:'PBJT', rate:0.10, ... }] }, testMode: false }

Endpoints

Abrir explorador interactivo→

GET/v1/organizationsList all organizations

GET/v1/organizations/{id}Get an organization

GET/v1/propertiesList properties

POST/v1/propertiesCreate a property

GET/v1/properties/{id}Get a property

GET/v1/bookingsList bookings

POST/v1/bookingsCreate a booking

GET/v1/bookings/{id}Get booking + tax breakdowns

GET/v1/tax-summaryTax summary by org & fiscal year

GET/v1/webhooks/endpointsList webhook endpoints

POST/v1/webhooks/endpointsRegister a webhook endpoint

DELETE/v1/webhooks/endpoints/{id}Delete a webhook endpoint

SDKs para Node.js y Python, Disponibles en Q3 2026

Webhooks

Configure sus webhooks desde Panel > Integraciones > Webhooks

booking.created

New booking received

booking.updated

Booking modified

tax.calculated

Tax calculation completed

report.generated

Fiscal report generated

HMAC-SHA256

Todos los payloads de webhook están firmados con HMAC-SHA256. Verifique el header X-VillaTax-Signature con el secreto de su endpoint.

Construido para desarrolladores que necesitan datos fiscales reales

Integración con Channel Manager

Envíe reservas desde su PMS o gestor de canales. Los cálculos fiscales se activan automáticamente. Construya su propia capa de reporting encima.

Software de gestión de propiedades

Integre el cumplimiento fiscal directamente en su software de gestión de propiedades. Sus clientes obtienen cumplimiento fiscal indonesio sin salir de su aplicación.

Informes fiscales automatizados

Obtenga resúmenes fiscales vía API para generar automáticamente informes mensuales de PBJT, PPh y PPN. Exporte a su sistema contable con JSON limpio.

FAQ

¿Listo para integrar VillaTax?

Obtener una clave API Contactar equipo Enterprise