Saltar al contenido principal
API docs by Redocly

API de Palenca (1.0)

En esta página enlistamos todos los métodos disponibles en la API de Palenca, así como la referencia completa de los parámetros que acepta cada uno.

La API de Palenca está diseñada con el estándar REST en mente. Los endpoints de la API están agrupados por recursos, tienen URLs predecibles, las respuestas tienen formato JSON y usamos códigos HTTP de respuesta, autenticación y verbos estándar.

Tenemos 2 entornos: Sandbox y Producción.

Sandbox: https://sandbox.palenca.com/v1

Producción: https://api.palenca.com/v1

Antes de integrarte, te recomendamos familiarizarte con las Entidades que manejamos en Palenca (Usuarios, Cuentas, Logins)

Users

Create User

Registra un nuevo usuario en Palenca. Un usuario representa a un trabajador formal o de la gig economy.

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
widget_id
required
string <uuid>

requerido: Id del Widget al que estará asociado el usuario

external_id
string

opcional: Identificador único externo del cliente (proporcionado por tu propia aplicación)

Responses

Request samples

Content type
application/json
{
  • "widget_id": "2b0956a2-58e7-4e97-804d-2852d40f05d7",
  • "external_id": "1234567890"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "error": { }
}

Retrieve User

Regresa el usuario correspondiente al id especificado.

path Parameters
required
User Id (string) or User Id (string)

ID del usuario a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete User

Elimina el usuario correspondiente al id especificado.

path Parameters
user_id
required
string <uuid>

ID del usuario a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}

Retrieve User Accounts

Recupera las cuentas de usuario ligadas al user_id.

path Parameters
required
User Id (string) or User Id (string)

User ID to obtain

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Users

Regresa una lista paginada con los usuarios creados entre un rango de fechas.

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
start_date
required
string

requerido: Fecha de inicio de la búsqueda en formato YYYY-MM-DD

end_date
required
string

requerido: Fecha de fin de la búsqueda en formato YYYY-MM-DD

object
Default: {"items_per_page":100,"page":1}

opcional: Opciones de paginación

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    }
}

Create User And Account

Registra en una sola petición un usuario junto con su correspondiente cuenta. Un usuario representa a un trabajador formal o de la gig economy y una cuenta representa una cuenta del trabajador en una plataforma específica. Actualmente disponible para IMSS e ISSSTE. Si quieres utilizar este endpoint para crear cuentas de la gig economy contáctanos a soporte@palenca.com

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
widget_id
string <uuid>

opcional: Id del Widget al que estará asociado el usuario

external_id
string

opcional: Identificador único externo del cliente (proporcionado por tu propia aplicación)

country
required
any
Value: "mx"

requerido: País

platform
required
any
Enum: "imss" "issste"

requerido: Plataforma con la cual se quiere hacer la conexión.

identifier
required
string

requerido: Identificador del usuario (CURP).

Responses

Request samples

Content type
application/json
{
  • "widget_id": "2b0956a2-58e7-4e97-804d-2852d40f05d7",
  • "external_id": "1234567890",
  • "country": "mx",
  • "platform": "imss",
  • "identifier": "XXXX000806HTSRNNA3"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Accounts

Retrieve User Accounts

Recupera las cuentas de usuario ligadas al user_id.

path Parameters
required
User Id (string) or User Id (string)

User ID to obtain

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Create Account

Registra una nueva cuenta correspondiente a un usuario. Una cuenta representa una cuenta del trabajador en una plataforma específica. Actualmente disponible para IMSS e ISSSTE. Si quieres utilizar este endpoint para crear cuentas de la gig economy contáctanos a soporte@palenca.com

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
country
required
any
Value: "mx"

requerido: País

platform
required
any
Enum: "imss" "issste"

requerido: Plataforma con la cual se quiere hacer la conexión.

identifier
required
string

requerido: Identificador del usuario (CURP)

user_id
required
string <uuid>

requerido: Id del usuario al que estará asociada la cuenta

Responses

Request samples

Content type
application/json
{
  • "user_id": "ee15970e-034e-4bd0-8e43-61383cc4c7d1",
  • "country": "mx",
  • "platform": "imss",
  • "identifier": "XXXX000806HTSRNNA3"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Retrieve Account

Regresa la cuenta correspondiente al id especificado.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete Account

Elimina la cuenta correspondiente al id especificado.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}

Data & Insights

Retrieve Account Profile

Regresa los datos de perfil del trabajador, correspondientes a la cuenta especificada mediante el id.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quiere obtener los datos de perfil

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Retrieve Account Employment

Regresa los datos de empleo del trabajador formal (IMSS, ISSSTE, CDT), correspondientes a la cuenta especificada mediante el id.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quiere obtener los datos de empleo

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Retrieve Account Earnings

Regresa una lista paginada con los datos de ganancias del trabajador de la gig economy (Uber, Rappi, Didi, etc.), correspondientes a la cuenta especificada mediante el id.

⚠ start_date debe ser una fecha más reciente que end_date.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quieren obtener las ganancias

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
start_date
required
string

requerido: Fecha más reciente de la búsqueda en formato YYYY-MM-DD

end_date
required
string

requerido: Fecha más antigua de la búsqueda en formato YYYY-MM-DD

object
Default: {"items_per_page":100,"page":1}

opcional: Opciones de paginación

Responses

Request samples

Content type
application/json
{
  • "start_date": "2022-12-31",
  • "end_date": "2022-01-01",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    },
  • "account_id": "e28f45c2-b137-407c-9aed-adaac2765b36"
}

Retrieve Employment Insights

Regresa los insights de empleo del trabajador formal (IMSS, ISSSTE), correspondientes a la cuenta especificada mediante el id. Los insights de Palenca ofrecen una lista de variables precalculadas que ayudan a los equipos de riesgos y ciencia de datos a tomar decisiones con mayor grado de certeza. Es importante notar que este endpoint tiene una respuesta disinta dado que no contiene el campo de error ni el de data.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quieren obtener los insighs de empleo

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "account_id": "7dd8a8ba-dba6-43e6-b1b6-63a94e5fedbe",
  • "identifier": "SAVE840914JNZNLN09",
  • "platform": "imss",
  • "success": true,
  • "current_situation": {
    },
  • "seniority": {
    },
  • "stability": {
    },
  • "salary": {
    },
  • "warning": null
}

Retrieve Gig Insights

Regresa los insights de ganancias del trabajador de la gig economy (Uber, Rappi, Didi, etc.), correspondientes a la cuenta especificada mediante el id. Los insights de Palenca ofrecen una lista de variables precalculadas que ayudan a los equipos de riesgos y ciencia de datos a tomar decisiones con mayor grado de certeza.

⚠ In the Sandbox environment, the endpoint is /insights for Employment and also for Gig. /insights-gig is useless in Sandbox.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quieren obtener los insighs de ganancias (gig economy)

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Generar PDF de Tendencias de Empleo

Genera un archivo PDF detallando las tendencias de empleo para la cuenta especificada, asociada con IMSS e ISSSTE. Este endpoint es exclusivamente para la creación del PDF y el proceso toma aproximadamente 1 minuto.

Después de la generación, el PDF puede ser recuperado a través de la clave 'employment_files' dentro de la respuesta del endpoint de empleo. Esta clave contiene un arreglo de archivos relacionados con el historial de empleo, incluyendo el PDF generado recientemente. Para información detallada sobre cómo acceder al PDF generado y entender la estructura de respuesta, por favor consulte la documentación del endpoint de empleo.

⚠ Ese endpoint no es disponible en el ambiente de Sandbox.

path Parameters
account_id
required
string <uuid>

Requerido: El ID de la cuenta para la cual se generará el PDF de tendencias de empleo.

header Parameters
x-api-key
string

Llave privada única para cada organización, que permite realizar peticiones en los ambientes de Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": { }
}

Widgets

Retrieve Widget

Regresa el widget correspondiente al id especificado.

path Parameters
widget_id
required
string <uuid>

requerido: Id del widget a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Widgets

Regresa una lista con los widgets registrados.

query Parameters
is_sandbox
boolean
Default: false

opcional: Entorno al que corresponden los widgets a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": [
    ]
}

Webhooks

Create Webhook

Registra un nuevo webhook. Para más información puedes consultar nuestra guía

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
url
required
string

requerido: URL del webhook

name
required
string

requerido: Nombre a asignar al webhook

widget_id
required
string <uuid>

requerido: Widget ID al que estará asociado el webhook

is_sandbox
required
boolean

requerido: Entorno del webhook (sandbox o producción)

sign_request
boolean
Default: false

opcional: Parámetro para definir si las notificaciones al webhook estarán firmadas (hmac)

Responses

Request samples

Content type
application/json
{
  • "url": "https://domain.com/webhook",
  • "name": "My webhook",
  • "is_sandbox": true,
  • "sign_request": false,
  • "widget_id": "b679c2fb-a096-4c26-a902-245f9bce66d9"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Webhooks

Regresa una lista con los webhooks registrados.

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { },
  • "error": { }
}

Retrieve Webhook

Regresa el webhook correspondiente al id especificado.

path Parameters
webhook_id
required
string <uuid>

requerido: Id del webhook a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Update Webhook

Actualiza el webhook correspondiente al id especificado.

path Parameters
webhook_id
required
string <uuid>

requerido: Id del webhook a actualizar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
url
string

opcional: URL del webhook

name
string

opcional: Nombre a asignar al webhook

widget_id
string <uuid>

opcional: Widget ID al que estará asociado el webhook

is_sandbox
boolean

opcional: Entorno del webhook (sandbox o producción)

sign_request
boolean

opcional: Parámetro para definir si las notificaciones al webhook estarán firmadas (hmac)

is_active
boolean

opcional: Parámetro para activar o desactivar el webhook

Responses

Request samples

Content type
application/json
{
  • "url": "https://domain.com/webhook",
  • "name": "My webhook",
  • "is_sandbox": true,
  • "is_active": true,
  • "sign_request": false,
  • "widget_id": "b679c2fb-a096-4c26-a902-245f9bce66d9"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete Webhook

Elimina el webhook correspondiente al id especificado.

path Parameters
webhook_id
required
string <uuid>

requerido: Id del webhook a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}