Saltar a contenido

API

OptaCheck proporciona una API REST para interactuar con el Escritorio de OptaCheck. Esta API permite a los desarrolladores crear aplicaciones personalizadas, integraciones y automatizaciones que interactúan con los datos del Escritorio. Para usar la API, es necesario tener conocimientos básicos de programación y familiaridad con el concepto de API RESTful.

La URL base del API es:

https://api.optacheck.com

Y luego se debe agregar la versión del API y el ID del Escritorio:

https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/

Actualmente, la API soporta las siguientes operaciones: - Autenticación: Permite a los usuarios autenticarse y obtener un token de acceso. - Tareas: Permite crear, leer, actualizar y eliminar tareas. - Clientes: Permite crear, leer, actualizar y eliminar clientes.

Requisitos previos

Para poder usar la API es necesario que el Escritorio tenga habilitado su uso.
Ponte en contacto con el soporte de OptaCheck para habilitar el uso del API en tu Escritorio. También es necesario conocer el ID del Escritorio, ponte en contacto con el soporte de OptaCheck para obtener este dato.

Autenticación del Escritorio

Esta autenticación se realiza mediante un token de acceso que se debe enviar en cada solicitud al API.
Este token también se conoce como API Key.
Para obtener el API Key debes de contactar a soporte de OptaCheck.

Autenticación del usuario

La autenticación del usuario se realiza mediante un token de acceso que se debe enviar en cada solicitud al API. Para obtener el token de acceso del usuario, debes de hacer una solicitud al API de autenticación con las credenciales del usuario.

Get your token

La API de autenticación se encuentra en la siguiente URL: https://api.optacheck.com/api-token-auth/

En el body de la solicitud debes enviar las credenciales del usuario en formato JSON:

{
  "username": "<tu-email-registrado>",
  "password": "<tu-contraseña>"
}

Si las credenciales son correctas, la API devolverá un token de acceso que debes de usar en cada solicitud.

{
  "token": "<tu-token-de-acceso>"
}

Uso del API

Para usar el API, debes enviar solicitudes HTTP a las URLs correspondientes. Cada solicitud debe incluir el token de acceso del usuario en el header de la solicitud. El header debe tener el siguiente formato:

Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>
Content-Type: application/json

Ejemplo, con datos ficticios, de como lucen las cabeceras de una solicitud a la API:

API header

Operaciones disponibles

Tareas

Las tareas son una de las principales entidades del Escritorio de OptaCheck. Puedes crear, leer, actualizar y eliminar tareas a través del API.

Los principales campos que tiene una tarea son:

  • status: Estado de la tarea.
  • title: Título de la tarea. Un máximo de 100 caracteres.
  • description (opcional): Una descripción de la tarea. Un maximo de 255 carácteres.
  • forms (opcional): Listado de IDs de formularios que la tarea utilizara.
  • project (opcional): ID de un proyecto.
  • client (opcional): ID de un cliente.
  • user_email: Email del usuario al que queremos asignar la tarea.
  • data (opcional): Información de las preguntas que aparecen en la tarea.

Leer una tarea

Para leer una tarea, debes enviar una solicitud GET a la siguiente URL:

GET https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/

HTTP Request Example:

GET /v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>

CURL Example:

curl -X GET \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>'

La respuesta de la solicitud será un objeto JSON que contiene los datos de la tarea solicitada.

{
    "id": "<id-de-la-tarea>",
    "status": "assigned",
    "title": "<titulo-de-la-tarea>",
    "description": "<descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "<id-del-proyecto>",
    "client": "<id-del-cliente>",
    "user": "<id-del-usuario-asignado>",
    "by_user": "<id-del-usuario-que-creo-la-tarea>",
    "date_edited": "2025-06-20T00:21:19.126137Z",
    "date_created": "2025-06-20T00:21:19.126147Z",
    "data": {
      "fields": [
        {
          "id": "<id-del-campo>",
          "value": "<valor-del-campo>",
          "title": "<etiqueta-del-campo>"
        },
        {
          "id": "<id-del-campo-2>",
          "value": "<valor-del-campo-2>",
          "title": "<etiqueta-del-campo-2>"
        }
      ]
    },
    "status_history": [
        {
            "status": "assigned",
            "date_status": "2025-06-20T00:21:19.213486Z",
            "status_name": "Asignada"
        }
    ]
}

En el campo data se incluyen campos adicionales, aparte de los campos de los formularios indicados, este campo puede dejarse vacío si no se necesitan campos adicionales en la tarea.

Crear una tarea

Para crear una tarea, debes enviar una solicitud POST a la siguiente URL:

POST https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers.
La URL debe incluir el ID del Escritorio al que deseas agregar la tarea y el body de la solicitud debe contener los datos de la tarea en formato JSON.

HTTP Request Example:

POST /v1.0/workspaces/<id-del-escritorio>/assignments/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>
Content-Type: application/json

{
    "status": "assigned",
    "title": "<titulo-de-la-tarea>",
    "description": "<descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "id-del-proyecto",
    "client": "id-del-cliente",
    "user_email": "<email-del-usuario-asignado>"
}

CURL Example:

curl -X POST \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>' \
-H 'Content-Type: application/json' \
-d '{
    "status": "assigned",
    "title": "<titulo-de-la-tarea>",
    "description": "<descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "id-del-proyecto",
    "client": "id-del-cliente",
    "user_email": "<email-del-usuario-asignado>"
}'

La respuesta de la solicitud será un objeto JSON que contiene los datos de la tarea creada, incluyendo su ID y otros detalles. La respuesta tendrá un estado HTTP 201 Created.

{
    "id": "<id-de-la-tarea>",
    "status": "assigned",
    "title": "<titulo-de-la-tarea>",
    "description": "<descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "<id-del-proyecto>",
    "client": "<id-del-cliente>",
    "user": "<id-del-usuario-asignado>",
    "by_user": "<id-del-usuario-que-creo-la-tarea>",
    "date_edited": "2025-06-20T00:21:19.126137Z",
    "date_created": "2025-06-20T00:21:19.126147Z",
    "status_history": [
        {
            "status": "assigned",
            "date_status": "2025-06-20T00:21:19.213486Z",
            "status_name": "Asignada"
        }
    ]
}

Actualizar una tarea

Para actualizar una tarea, debes enviar una solicitud PUT a la siguiente URL:

PUT https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers. El body de la solicitud debe contener los datos actualizados de la tarea en formato JSON.

HTTP Request Example:

PUT /v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>
Content-Type: application/json

{
    "status": "in_progress",
    "title": "<nuevo-titulo-de-la-tarea>",
    "description": "<nueva-descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario-actualizado>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "<id-del-proyecto-actualizado>",
    "client": "<id-del-cliente-actualizado>",
    "user_email": "<email-del-usuario-asignado>"
}

CURL Example:

curl -X PUT \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>' \
-H 'Content-Type: application/json' \
-d '{
  "status": "active"
}'

La respuesta de la solicitud será un objeto JSON que contiene los datos actualizados de la tarea y con estado HTTP 200 OK.

{
    "id": "<id-de-la-tarea>",
    "status": "active",
    "title": "<nuevo-titulo-de-la-tarea>",
    "description": "<nueva-descripcion-de-la-tarea>",
    "forms": ["<id-del-formulario-actualizado>", "id-del-formulario-2", "<id-del-formulario-3>"],
    "project": "<id-del-proyecto-actualizado>",
    "client": "<id-del-cliente-actualizado>",
    "user": "<id-del-usuario-asignado>",
    "by_user": "<id-del-usuario-que-creo-la-tarea>",
    "date_edited": "2025-06-20T00:21:19.126137Z",
    "date_created": "2025-06-20T00:21:19.126147Z",
    "status_history": [
        {
            "status": "assigned",
            "date_status": "2025-06-20T00:21:19.213486Z",
            "status_name": "Asignada"
        },
        {
            "status": "in_progress",
            "date_status": "2025-06-20T00:22:19.213486Z",
            "status_name": "En progreso"
        }
    ]
}

Eliminar una tarea

Para eliminar una tarea, debes enviar una solicitud DELETE a la siguiente URL:

DELETE https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers.

HTTP Request Example:

DELETE /v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>

CURL Example:

curl -X DELETE \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/assignments/<id-de-la-tarea>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>'

Clientes

Los clientes son una de las principales entidades del Escritorio de OptaCheck. Puedes crear, leer, actualizar y eliminar clientes a través del API.

Los principales campos que tiene un cliente son:

  • name: Nombre del cliente.
  • description (opcional): Descripción del cliente.
  • internal_code (opcional): Código interno del cliente.
  • address (opcional): Dirección del cliente.
  • sales_goal (opcional): Meta de ventas del cliente.
  • contact_name (opcional): Nombre de la persona de contacto.
  • contact_phone (opcional): Teléfono de la persona de contacto.
  • contact_email (opcional): Correo electrónico de la persona de contacto.
  • latitude (opcional): Latitud de la ubicación del cliente.
  • longitude (opcional): Longitud de la ubicación del cliente.
  • invoice_tax_identifier (opcional): Identificador tributario para facturación.
  • invoice_name (opcional): Nombre utilizado para facturación.
  • projects (opcional): Listado de IDs de proyectos asociados al cliente.
  • teams (opcional): Listado de IDs de equipos asociados al cliente.
  • seller_email: Correo electrónico del vendedor asignado al cliente.

Leer un cliente

Para leer un cliente, debes enviar una solicitud GET a la siguiente URL:

GET https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/

HTTP Request Example:

GET /v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>

CURL Example:

curl -X GET \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>'

La respuesta de la solicitud será un objeto JSON que contiene los datos del cliente solicitado.

{
    "id": "<id-del-cliente>",
    "name": "<nombre-del-cliente>",
    "description": "<descripcion-del-cliente>",
    "internal_code": "<codigo-interno-del-cliente>",
    "address": "<direccion-del-cliente>",
    "sales_goal": "<meta-de-ventas>",
    "contact_name": "<nombre-del-contacto>",
    "contact_phone": "<telefono-del-contacto>",
    "contact_email": "<email-del-contacto>",
    "latitude": 0.0,
    "longitude": 0.0,
    "invoice_tax_identifier": "<identificador-tributario>",
    "invoice_name": "<nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}

Crear un cliente

Para crear un cliente, debes enviar una solicitud POST a la siguiente URL:

POST https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers. La URL debe incluir el ID del Escritorio al que deseas agregar el cliente y el body de la solicitud debe contener los datos del cliente en formato JSON.

HTTP Request Example:

POST /v1.0/workspaces/<id-del-escritorio>/clients/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>
Content-Type: application/json

{
    "name": "<nombre-del-cliente>",
    "description": "<descripcion-del-cliente>",
    "internal_code": "<codigo-interno-del-cliente>",
    "address": "<direccion-del-cliente>",
    "sales_goal": "<meta-de-ventas>",
    "contact_name": "<nombre-del-contacto>",
    "contact_phone": "<telefono-del-contacto>",
    "contact_email": "<email-del-contacto>",
    "latitude": "<latitud-del-cliente>",
    "longitude": "<longitud-del-cliente>",
    "invoice_tax_identifier": "<identificador-tributario>",
    "invoice_name": "<nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}

CURL Example:

curl -X POST \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>' \
-H 'Content-Type: application/json' \
-d '{
    "name": "<nombre-del-cliente>",
    "description": "<descripcion-del-cliente>",
    "internal_code": "<codigo-interno-del-cliente>",
    "address": "<direccion-del-cliente>",
    "sales_goal": "<meta-de-ventas>",
    "contact_name": "<nombre-del-contacto>",
    "contact_phone": "<telefono-del-contacto>",
    "contact_email": "<email-del-contacto>",
    "latitude": "<latitud-del-cliente>",
    "longitude": "<longitud-del-cliente>",
    "invoice_tax_identifier": "<identificador-tributario>",
    "invoice_name": "<nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}'

La respuesta de la solicitud será un objeto JSON que contiene los datos del cliente creado, incluyendo su ID y otros detalles. La respuesta tendrá un estado HTTP 201 Created.

{
    "id": "<id-del-cliente>",
    "name": "<nombre-del-cliente>",
    "description": "<descripcion-del-cliente>",
    "internal_code": "<codigo-interno-del-cliente>",
    "address": "<direccion-del-cliente>",
    "sales_goal": "<meta-de-ventas>",
    "contact_name": "<nombre-del-contacto>",
    "contact_phone": "<telefono-del-contacto>",
    "contact_email": "<email-del-contacto>",
    "latitude": "<latitud-del-cliente>",
    "longitude": "<longitud-del-cliente>",
    "invoice_tax_identifier": "<identificador-tributario>",
    "invoice_name": "<nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}

Actualizar un cliente

Para actualizar un cliente, debes enviar una solicitud PUT a la siguiente URL:

PUT https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers. El body de la solicitud debe contener los datos actualizados del cliente en formato JSON.

HTTP Request Example:

PUT /v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>
Content-Type: application/json

{
    "name": "<nuevo-nombre-del-cliente>",
    "description": "<nueva-descripcion-del-cliente>",
    "internal_code": "<nuevo-codigo-interno>",
    "address": "<nueva-direccion>",
    "sales_goal": "<nueva-meta-de-ventas>",
    "contact_name": "<nuevo-nombre-del-contacto>",
    "contact_phone": "<nuevo-telefono-del-contacto>",
    "contact_email": "<nuevo-email-del-contacto>",
    "latitude": 0.0,
    "longitude": 0.0,
    "invoice_tax_identifier": "<nuevo-identificador-tributario>",
    "invoice_name": "<nuevo-nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}

CURL Example:

curl -X PUT \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>' \
-H 'Content-Type: application/json' \
-d '{
    "name": "<nuevo-nombre-del-cliente>",
    "description": "<nueva-descripcion-del-cliente>",
    "internal_code": "<nuevo-codigo-interno>",
    "address": "<nueva-direccion>",
    "sales_goal": "<nueva-meta-de-ventas>",
    "contact_name": "<nuevo-nombre-del-contacto>",
    "contact_phone": "<nuevo-telefono-del-contacto>",
    "contact_email": "<nuevo-email-del-contacto>",
    "latitude": 0.0,
    "longitude": 0.0,
    "invoice_tax_identifier": "<nuevo-identificador-tributario>",
    "invoice_name": "<nuevo-nombre-de-facturacion>",
    "projects": ["<id-del-proyecto-1>", "<id-del-proyecto-2>"],
    "teams": ["<id-del-equipo-1>", "<id-del-equipo-2>"],
    "seller_email": "<email-del-vendedor>"
}'

La respuesta de la solicitud será un objeto JSON que contiene los datos actualizados del cliente y tendrá un estado HTTP 200 OK.

Eliminar un cliente

Para eliminar un cliente, debes enviar una solicitud DELETE a la siguiente URL:

DELETE https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/

Esta solicitud debe incluir el token de acceso del usuario y la API Key del Escritorio en los headers.

HTTP Request Example:

DELETE /v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ HTTP/1.1
Host: api.optacheck.com
Authorization: Token <tu-token-de-acceso>
x-api-key: <api-key-del-escritorio>

CURL Example:

curl -X DELETE \
https://api.optacheck.com/v1.0/workspaces/<id-del-escritorio>/clients/<id-del-cliente>/ \
-H 'Authorization: Token <tu-token-de-acceso>' \
-H 'x-api-key: <api-key-del-escritorio>'