Introducción

UpConta pone a su disposición su API REST, con la cual es posible integrar UpConta con aplicaciones de terceros. Para esto proporcionamos dos ambientes:

Pruebas

• API: https://api-test.upconta.com (opens new window)
• APP: https://app-test.upconta.com (opens new window)

Producción

• API: https://api.upconta.com (opens new window)
• APP: https://app.upconta.com (opens new window)

Autenticación

La autenticación sirve para identificar a la empresa y a la aplicación que quiera acceder al sistema. Estos accesos deben ser proporcionados por el equipo de UpConta. Cuando el usuario se autentifique el sistema generará un token con el cual se proporcionará el acceso a la creación, lectura, actualización y eliminación de datos.

El token debe ser proporcionado mediante la cabecera HTTP Authorization o mediante la query string token.

# ejemplo con header
$ curl -H "Authorization: {token}" https://<subdomain>.upconta.com/auth

# ejemplo con query string
$ curl https://<subdomain>.upconta.com/auth?token={token}

Generanción de token

Después de que el sistema valide a la aplicación se generará un token que conceda el acceso a los distintos módulos.

POST https://api-test.upconta.com/v3/auth/user

Campos de petición

Nombre	Descripción
ruc	La identificación de la empresa
username	El nombre de la aplicación
password	La contraseña de acceso

Ejemplo de cuerpo de petición

{
  "ruc": "empresa",
  "username": "usuario",
  "password": "foo-bar"
}

Ejemplo de respuesta

{
  "name": "Nombre de empresa",
  "user": "Nombre de usuario",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc318JIUzI1NiJ9.eyJ1c2VyIjoiNWEyYWM1MmNiYmJjZTIxMmY4OPU1MmExIiwiYnVzaW5lc3cMiCha3LYuGchAY2JiYmNlMjEyZjg4NTUyOWMiLCJsb2cpbkRhdGUiOiIxNTM2NTk2MzQ5MDk0IiwiZXhwaXJhdGlvbkRhdGUiOiIxNTM3MDczOTkwMDk2In0.FfOQHMBdTuRP2BdXYP0_EYGj-DzsI7IOU51Z2yOj1k8"
}

De ahora en adelante todas las peticiones deben hacerse enviando el

token de acceso.

Comprobando token

Verifica si el token es válido y retorna la información del mismo.

GET https://api-test.upconta.com/v3/auth/user

Ejemplo de respuesta

{
  "ruc": "1716738033001",
  "business": "EMPRESA DE PRUEBAS",
  "user": "Usuario desarrollador",
  "modules": [
    {
      "key": "administrative",
      "label": "Administrativo",
      "icon": "receipt",
      "submodules": [
        {
          "label": "Comprobantes",
          "items": [
            {
              "key": "proformas",
              "label": "Proformas"
            },
            {
              "key": "sales-notes",
              "label": "Notas de venta / Recibos"
            }
          ]
        }
      ],
      "operationDate": "2017-12-08T16:58:04.000Z"
    }
  ],
  "businessModules": [
    {
      "key": "administrative",
      "operationDate": "2017-12-08T16:58:04.000Z",
      "activationDate": "2021-09-13T18:43:25.676Z"
    }
  ],
  "createdAt": "2017-12-08T16:58:04.000Z",
  "sessionStartDate": "2021-12-02T15:32:35.933Z",
  "sessionEndDate": "2021-12-08T23:59:59.999Z"
}

Campos de respuesta

Nombre	Descripción
ruc	El RUC de la empresa
business	El nombre de la empresa
configs	Las configuraciones de la empresa
configs.useTestEnviroment	true si se está usando el entorno de pruebas
configs.modules	Los módulos a los que la empresa tiene acceso
user	El nombre del usuario
sessionStartDate	La fecha de inicio de sesión
sessionEndDate	La fecha de fin de sesión

Consultas al api

Las consultas al API pueden tener operaciones como límites, paginación, búsqueda por campos específicos, entre otras cosas. Estas consultas se las realiza tomando las convenciones de mongoose-smart-query (opens new window)

Filtro de campos

Para filtrar los campos se utiliza la query string fields con los campos que se desea retornar en la consulta. Para buscar multiples campos se debe especificar estos campos separados por un espacio.

GET https://api-test.upconta.com/v3/administrative/clients?fields=name email

Si se desea obtener todos los campos se puede proporcionar la query string $getAllFields:

GET https://api-test.upconta.com/v3/administrative/clients?$getAllFields=true

Límites

Se utiliza la query string limit. El valor por defecto es 20.

GET https://api-test.upconta.com/v3/administrative/clients?limit=10

Paginación

Se utiliza la query string page. El valor por defecto es 1.

GET https://api-test.upconta.com/v3/administrative/clients?page=3

Por lo general el límite y la paginación van de la mano.

GET https://api-test.upconta.com/v3/administrative/clients?limit=5&page=3

Orden de datos

Se utiliza la query string sort. Por defecto se ordena desde el registro mas reciente hasta el mas antiguo.

• Es necesario mandar una propiedad existente en el modelo del recurso que se desea buscar.
• Por defecto se ordena de menor a mayor. Para ordenar de mayor a menor se pone el signo menos (-) antes de la propiedad del modelo.

Ejemplo

Ordenar por nombre:

GET https://api-test.upconta.com/v3/administrative/clients?sort=name

Ordenar por nombre de mayor a menor:

GET https://api-test.upconta.com/v3/administrative/clients?sort=-name

Se puede ordenar por multiples campos, para esto se debe especificar estos campos y separarlos por un espacio:

GET https://api-test.upconta.com/v3/administrative/clients?sort=name -age

Búsqueda

Se utiliza la query string q, esta realizará una búsqueda en los campos que hayan sido configurados como buscables en el modelo.

GET https://api-test.upconta.com/v3/administrative/clients?q=michael

Para realizar búsquedas exactas es necesario proporcionar el campo por query string y el valor que se quiere buscar. Por ejemplo se quiere buscar el cliente cuyo correo sea atencion@upconta.com:

GET https://api-test.upconta.com/v3/administrative/clients?email=atencion@upconta.com

Para buscar si una palabra esta incluida en un texto. Por ejemplo si se quiere buscar la palabra gmail.com en el campo email:

GET https://api-test.upconta.com/v3/administrative/clients?email={$includes}gmail.com

get-options

La mayoria de las rutas tienen una subruta llamada /get-options, la cual retorna las posibles opciones que puede tomar un campo para que pueda ser guardado en la base de datos. Ejmplo:

GET https://api-test.upconta.com/v3/administrative/clients/get-options

{
  "TiposDePersona": [
    {
      "id": "01",
      "description": "Persona natural"
    },
    {
      "id": "02",
      "description": "Sociedad"
    }
  ],
  "TiposDeIdentificacion": [
    {
      "id": "04",
      "description": "RUC"
    },
    {
      "id": "05",
      "description": "Cédula"
    },
    {
      "id": "06",
      "description": "Pasaporte"
    },
    {
      "id": "08",
      "description": "Identificación del exterior"
    },
    {
      "id": "09",
      "description": "Placa"
    }
  ]
}

Los id son los valores que pueden tomarse en ciertos campos del cliente.

movements

Los _movements en un historial de movimientos que se guarda por cada registro que es creado, editado, eliminado entre otros.

Modelo

interface Movement {
  /**
   * Tipo de movimiento para el registro.
   */
  type: string;
  /**
   * Fecha de creación del movimiento.
   */
  date?: Date;
  /**
   * Usuario por el cual fue creado el movimiento.
   */
  user?: Types.ObjectId;
  /**
   * Se identifica el tipo de movimiento y se agrega el nombre del usuario
   */
  nota?: string;
}

Ejemplo de movimiento

"_movements": [
	{
		"type": "created",
		"user": "608adf6a375dfd83381ba163",
		"nota": "Creado por desarrollador",
		"date": "2024-04-19T11:22:24.313Z"
  }
]