Lista las empresas del tenant con sus series del ambiente de la clave

GET

/v1/companies

curl https://api.boletura.com/v1/companies \
  --header 'Authorization: Bearer bol_test_TU_CLAVE'

import http.client

conn = http.client.HTTPSConnection("api.boletura.com")

headers = {
  "Authorization": "Bearer bol_test_TU_CLAVE"
}

conn.request(
    "GET",
    "/v1/companies",
    headers=headers,
)

response = conn.getresponse()
print(response.read().decode())

conn.close()

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.boletura.com/v1/companies");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "bol_test_TU_CLAVE");

using var response = await client.SendAsync(request);

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(java.net.URI.create("https://api.boletura.com/v1/companies"))
  .header("Authorization", "Bearer bol_test_TU_CLAVE")
  .method("GET", HttpRequest.BodyPublishers.noBody())
  .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Permite resolver company_id y las series sin entrar al back office. Lista todas las empresas del tenant, aunque la clave tenga una por defecto, ordenadas por creación. No devuelve certificados, credenciales ni otros secretos.

Requiere el scope companies:read.

Autorización

api_key

Parámetros

Parámetros de la consulta

limit

integer format: int32

Tamaño de la página, de 1 a 200; por defecto 50. Fuera de ese rango responde 422 limit_invalid, y un valor que no es un número, 400 bad_request.

cursor

string

El next_cursor de la página anterior. Es opaco y vale solo para el orden con el que se generó: otro responde 400 invalid_cursor.

Respuestas

200

Solicitud correcta.

application/json

Una página de empresas.

object

data

obligatorio

Empresas de la página.

Array<object>

Empresa emisora del tenant.

object

obligatorio

UUID de la empresa: es el company_id de la emisión.

string format: uuid

ruc

obligatorio

RUC de la empresa.

string

legal_name

obligatorio

Razón social.

string

trade_name

obligatorio

Nombre comercial; nulo si no tiene.

null | string

status

obligatorio

Estado de la empresa.

Valores admitidos: draft ready suspended

environments_ready

obligatorio

Habilitación por ambiente.

object

test

obligatorio

Verdadero salvo si la empresa está suspendida.

boolean

live

obligatorio

Verdadero solo cuando la empresa está ready y la cuenta está activada para live.

boolean

series

obligatorio

Series activas en el ambiente de la clave, ordenadas por tipo y código. Vacía si no tiene.

Array<object>

Serie activa de la empresa en el ambiente de la clave.

object

obligatorio

UUID de la serie.

string format: uuid

establishment_id

obligatorio

UUID del establecimiento de la serie.

string format: uuid

environment

obligatorio

Ambiente de la serie.

Valores admitidos: test live

document_type

obligatorio

Tipo de comprobante que emite.

Valores admitidos: factura boleta nota_credito nota_debito

code

obligatorio

Código de la serie, como B001: es el series de la emisión.

string

is_default

obligatorio

Si es la serie por defecto de su tipo en ese establecimiento y ambiente.

boolean

next_cursor

obligatorio

Cursor de la página siguiente, para pasarlo en cursor; nulo en la última página.

null | string

Ejemplos

Una empresa con dos series

{
  "data": [
    {
      "id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6b",
      "ruc": "20100066603",
      "legal_name": "Empresa de Ejemplo S.A.C.",
      "trade_name": "Ejemplo",
      "status": "draft",
      "environments_ready": {
        "test": true,
        "live": false
      },
      "series": [
        {
          "id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6d",
          "establishment_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6c",
          "environment": "test",
          "document_type": "boleta",
          "code": "B001",
          "is_default": true
        },
        {
          "id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6e",
          "establishment_id": "0192f0b1-2d4c-7a1e-8b3f-1c2d3e4f5a6c",
          "environment": "test",
          "document_type": "factura",
          "code": "F001",
          "is_default": true
        }
      ]
    }
  ],
  "next_cursor": null
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

400

Solicitud mal formada. Códigos: invalid_cursor y bad_request, cuando un parámetro no tiene el formato de su tipo, como limit=abc. No se reintenta sin corregirla.

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

invalid_cursor

{
  "error": {
    "type": "bad_request",
    "code": "invalid_cursor",
    "message": "El cursor no es válido.",
    "param": "cursor",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

401

Sin una API key válida. Códigos: unauthorized, invalid_api_key, revoked_api_key, expired_api_key.

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

invalid_api_key

{
  "error": {
    "type": "unauthorized",
    "code": "invalid_api_key",
    "message": "La API key no es válida.",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

403

La clave no puede operar. Códigos: forbidden (no tiene el scope), tenant_suspended, plan_without_api (el plan de la cuenta no incluye la API), account_not_activated (emisión en live de una cuenta que Boletura todavía no activó).

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

forbidden

{
  "error": {
    "type": "forbidden",
    "code": "forbidden",
    "message": "La API key no tiene el scope companies:read que exige este endpoint.",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

422

limit_invalid: limit está fuera del rango de 1 a 200.

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

limit_invalid

{
  "error": {
    "type": "validation_error",
    "code": "limit_invalid",
    "message": "El límite debe estar entre 1 y 200.",
    "param": "limit",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

429

rate_limited: se superó el límite de 600 solicitudes por minuto por clave o 1200 por IP. Se reintenta después de Retry-After.

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

rate_limited

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limited",
    "message": "Demasiadas solicitudes. Reintente después de los segundos que indica Retry-After.",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.

Retry-After

integer

Segundos que conviene esperar antes de reintentar.

503

Falla transitoria, como database_unavailable o storage_unavailable. Se reintenta con una espera creciente.

application/json

Formato único de los errores de la API.

object

error

obligatorio

El error principal.

object

type

obligatorio

Familia del error, como validation_error, conflict o unavailable.

string

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador. Puede cambiar: no se programa contra él.

string

param

Ruta del campo en el JSON, con índices entre corchetes, como items[2].unit_price. Solo cuando el error apunta a un campo.

null | string

request_id

obligatorio

Identificador de la solicitud, el mismo de X-Request-Id. Inclúyelo al escribir a soporte.

string

document_id

Documento con el que choca la solicitud. Solo en external_id_conflict y document_already_replaced.

null | string format: uuid

errors

Todos los problemas. Solo aparece cuando hay varios.

Array<object> | null

Uno de los problemas de la solicitud.

object

code

obligatorio

Código estable, para programar contra él.

string

message

obligatorio

Mensaje en español, apto para mostrar a un operador.

string

param

Ruta del campo en el JSON, si el error apunta a uno.

null | string

Ejemplos

database_unavailable

{
  "error": {
    "type": "unavailable",
    "code": "database_unavailable",
    "message": "La base de datos no está disponible. Reintente en unos segundos.",
    "request_id": "req_0192f1a27c3e7d4b9a8f2b6c1d0e4f5a"
  }
}

Cabeceras

X-Request-Id

string

El del cliente si tiene de 1 a 128 caracteres [A-Za-z0-9._-]; si no, uno generado. Es el request_id de los errores.

RateLimit-Limit

integer

Solicitudes admitidas en la ventana de un minuto, de la clave o de la IP.

RateLimit-Remaining

integer

Solicitudes que quedan en la ventana.

RateLimit-Reset

integer

Segundos hasta la ventana siguiente.