Saltar al contenido principal
Version: 1.0.0

Referencia API de Basilic

La API de Basilic te permite construir flujos reutilizables de cobro, tanto para checkouts hosteados como para instrucciones directas de transferencia bancaria.

Qué cubre cada sección​

  • Plantillas de Links de Pago definen la configuración reutilizable del checkout que administra tu equipo en Basilic.
  • Links Temporales crean una instancia única de checkout a partir de una plantilla, con monto, contexto de cliente y redirecciones opcionales.
  • Payment History te permite inspeccionar los pagos cobrados por cada link temporal una vez que el checkout empieza a recibir fondos.
  • VA Payments son instrucciones API-only de cuenta virtual para cobros directos en ARS dentro de Argentina, sin página hosteada de checkout.

Modelo general​

Cuándo usar cada flujo​

  • Usá Plantillas de Links de Pago + Links Temporales cuando Basilic deba hostear el checkout y capturar los datos del formulario del pagador.
  • Usá Payment History cuando necesites conciliación y visibilidad de estado para un checkout hosteado que ya está cobrando.
  • Usá VA Payments cuando tu producto necesite mostrar el CVU directamente y mantener el flujo de transferencia dentro de tu propia interfaz.

Autenticación​

Todas las solicitudes a la API requieren autenticación mediante una API key. Incluila en el header Authorization:

Authorization: Bearer wp_live_your_api_key_here

Podés generar API keys desde tu dashboard de Basilic en Configuración > API Keys.

La información de rate limit aparece en los headers de respuesta:

  • X-RateLimit-Limit: máximo de requests por minuto
  • X-RateLimit-Remaining: requests restantes en la ventana actual
  • X-RateLimit-Reset: timestamp en que se reinicia el rate limit

Idempotencia​

Para evitar operaciones duplicadas, incluí un header Idempotency-Key en los requests POST:

Idempotency-Key: unique-request-id-123
  • Las idempotency keys son válidas por 24 horas
  • Los requests repetidos con la misma key devuelven la respuesta original
  • Si enviás distintos bodies con la misma key, recibís un error 409 Conflict

Manejo de Errores​

La API usa códigos HTTP estándar y devuelve errores con un formato consistente:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensaje de error legible",
    "details": ["Detalles adicionales opcionales"]
  },
  "timestamp": "2025-01-01T00:00:00.000Z",
  "path": "/api/v1/temp-links"
}

Códigos de Error Comunes​

  • UNAUTHORIZED: API key inválida o ausente
  • RATE_LIMIT_EXCEEDED: Demasiados requests
  • VALIDATION_ERROR: Datos inválidos en el request
  • RESOURCE_NOT_FOUND: El recurso solicitado no existe
  • PAYMENT_LINK_NOT_FOUND: La plantilla de link de pago no existe
  • FORM_VALIDATION_ERROR: Los datos del formulario no coinciden con la plantilla
  • IDEMPOTENCY_CONFLICT: Se reutilizó la misma key con un body distinto
  • INTERNAL_SERVER_ERROR: Error inesperado del servidor

Webhooks (Próximamente)​

El soporte de webhooks se agregará en una futura actualización para notificar a tus sistemas eventos de pago en tiempo real.

Autenticación​

Autenticación por API key. Formato: wp_{environment}_{random_string}

Tipo de esquema de seguridad:

http

Esquema HTTP de autorización:

bearer

Formato bearer:

API Key

Licencia

Propietario