Datos generales

URL base, formato JSON, encabezados HTTP y estructura de las respuestas de error.

Esta página reúne la información común que necesitas antes de consumir los endpoints de KubiBAI Web Services.

URL base

Utiliza una de estas URL como prefijo para todos los endpoints:

Entorno	URL base
Producción	`https://kws.kubibai.net/api`
Tests	`https://wstests.kubibai.com/api`

Formato de peticiones y respuestas

Las peticiones y respuestas utilizan JSON, salvo que la documentación de un endpoint indique expresamente otro formato.
Las respuestas satisfactorias utilizan un código de estado HTTP 2xx.
Las respuestas erróneas utilizan un código de estado HTTP 4xx o 5xx e incluyen información adicional sobre el error.

Encabezados HTTP

Las peticiones JSON deben incluir los siguientes encabezados:

Encabezado	Valor	Uso
`Content-Type`	`application/json`	Indica que el cuerpo de la petición contiene JSON.
`Accept`	`application/json`	Solicita que la respuesta se devuelva en JSON.
`X-Qbikode-ClientApiKey`	`{CLIENT_API_KEY}`	Identifica a la empresa cliente. La clave se obtiene desde el panel de gestión de KubiBAI Web Services.
`X-Qbikode-UserApiKey`	`{USER_API_KEY}`	Solo se requiere en los endpoints que necesitan identificar a un usuario. La clave se obtiene desde la edición del perfil en el panel de gestión.

Ejemplo de encabezados para una petición autenticada como empresa cliente, por ejemplo, para emitir una factura:

Content-Type: application/json
Accept: application/json
X-Qbikode-ClientApiKey: {CLIENT_API_KEY}

Ejemplo de encabezados para una petición autenticada como intermediario, por ejemplo, para dar de alta empresas:

Content-Type: application/json
Accept: application/json
X-Qbikode-UserApiKey: {USER_API_KEY}

Sustituye los valores entre llaves por las API keys correspondientes.

Respuestas de error

Las respuestas de error siempre utilizan un código de estado HTTP 4xx o 5xx. En la implementación actual, el cuerpo contiene el objeto de error bajo data.error:

Campo	Tipo	Descripción
`data.error`	`object`	Objeto con información relativa al error.
`data.error.code`	`string`	Código de error que puedes facilitar al solicitar asistencia técnica.
`data.error.message`	`string`	Descripción del error.
`data.error.http_code`	`integer`	Código HTTP del error. Coincide con el código de estado de la respuesta.
`data.error.errors`	`object \| array \| null`	Colección de errores ocurridos. En errores de validación suele estar indexada por el nombre del campo.
`data.error.details`	`object \| null`	Detalles adicionales sobre el error, cuando estén disponibles.

Ejemplo de una respuesta de validación:

{
  "data": {
    "error": {
      "code": "E-WRONGARGS",
      "message": "The given data was invalid.",
      "http_code": 422,
      "errors": {
        "invoice_number": [
          "The invoice number field is required."
        ]
      },
      "details": null
    }
  }
}