---
title: Datos generales
description: 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` |

:::note
Las facturas enviadas al entorno de tests se remiten a su vez a los servidores
de pruebas de TicketBAI.
:::

## 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:

```http
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:

```http
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:

```json
{
  "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
    }
  }
}
```