Consulta y Búsqueda de Contribuyentes de la Organización

Este endpoint permite la búsqueda, paginación y listado de los contribuyentes (taxpayers) asociados a una organización específica. Se pueden aplicar filtros por una cadena de consulta (q) para refinar el listado por identificación o nombre.

Detalles Técnicos

Endpoint y Método

• Método: GET
• Endpoint: /taxpayers

Parámetros de Consulta (Query Parameters)

• page (integer): El número de página a recuperar (ej. 1)
• limit (integer): El número máximo de elementos por página (ej. 10)
• q (string): Cadena de búsqueda opcional para filtrar por parte del ID o nombre del contribuyente (ej. 1726051285)

Headers Requeridos

• x-api-key: [Tu Clave] - Autenticación del servicio
• x-organization-id: [Tu ID de Organización] - Filtro fundamental para obtener solo tus clientes

Body/Payload

No Aplica. Es una consulta GET.

Código de Ejemplo

const axios = require('axios');

let config = {
  method: 'get',
  url: 'https://staging-api.taxo.ws/taxpayers?page=1&limit=10&q=1726051285',
  headers: { 
    'x-api-key': 'tu_api_key',
    'x-organization-id': 'tu_organization_id'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Respuesta de la solicitud

La respuesta es un listado paginado que contiene la información esencial de cada contribuyente, junto con metadatos de paginación:

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "8198fb21-b64b-43c1-8549-f8d94d62998e",
        "organizationId": "e9ab2bca-5189-44fb-9a84-9978494b39f3",
        "fullName": "SOTO ESPINOSA ANDREA ESTEFANIA",
        "identification": "1726051285001",
        "kind": "PNL",
        "contacts": [],
        "status": "ACTIVE"
      }
    ],
    "meta": {
      "totalItems": 1,
      "itemCount": 1,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

Campos de la Respuesta

• status (string): El estado general de la solicitud ("success")
• data.items (array): La lista de objetos de contribuyentes encontrados en la página actual
• data.items.id (string): ID interno del contribuyente
• data.items.identification (string): RUC o ID fiscal del contribuyente
• data.items.fullName (string): Nombre o razón social completa
• data.meta (object): Objeto de paginación
• data.meta.totalItems (integer): Cantidad total de contribuyentes que coinciden con la búsqueda
• data.meta.currentPage (integer): La página que ha sido devuelta

Código de Respuesta HTTP

200 OK: Código estándar para una consulta GET exitosa que retorna una lista de recursos.