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
}

Recuperar Usuario de la Cuenta

Devuelve el usuario asociado con la cuenta.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta a buscar.

header Parameters
x-api-key
string

Clave privada única por organización. Permite realizar solicitudes en entornos de Sandbox y Producción.

Responses

Response samples

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

Logins

List Logins

Regresa una lista paginada con los logins 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": {
    }
}

Profile

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": {
    }
}

Employment Mexico

Retrieve Account Employment

Regresa los datos de empleo del trabajador formal (IMSS, ISSSTE), 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": {
    }
}

Employment Brazil

Retrieve Account Employment History

Regresa los datos del historial de empleo del trabajador que pertenece a la cuenta especificada en el account_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
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Gig earnings

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
Example
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    },
  • "account_id": "e28f45c2-b137-407c-9aed-adaac2765b36"
}

CDT earnings

Retrieve payment history of a Carteira de Trabalho account

Regresa una lista paginada del historial de pagos de un trabajador dentro de la cuenta de la Carteira de Trabalho (CDT) especificada en el account_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": {
    }
}

Employment insights

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
}

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": { }
}

Gig insights

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": {
    }
}

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": {
    }
}

Actualizar un widget

Actualizar un widget.

Request Body schema: application/json
name
string

Nombre del widget

countries
Array of strings

Países a mostrar en el widget

platforms
Array of strings

Plataformas a mostrar en el widget

require_gov_id
boolean

Agrega un paso extra para solicitar el Government ID (CURP, CPF, etc.) al usuario

hide_logo
boolean

Oculta el logo en el widget

hide_whatsapp
boolean

Oculta el icono de Whatsapp en el widget

hide_consent
boolean

Oculta la pantalla de bienvenida en el widget

font_family
string

Fuente para modificar el texto en el widget, debe existir en Google Fonts

primary_color
string

Color primario para modificar el widget en formato hexadecimal (#FFFFFF)

border_radius
string

Define el radio del borde para botones y campos del formulario (round, rounded, square)

custom_privacy_url
string

URL de los términos y condiciones a mostrar en el widget

whatsapp_number
string

Número de Whatsapp para recibir mensajes de los usuarios

Responses

Request samples

Content type
application/json
{
  • "countries": [
    ],
  • "platforms": [
    ],
  • "require_gov_id": false
}

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": [
    ]
}

Crear un widget

Crea un nuevo widget.

Request Body schema: application/json
name
required
string

requerido: Nombre del widget

countries
required
Array of strings

requerido: Países a mostrar en el widget

platforms
required
Array of strings

requerido: Plataformas a mostrar en el widget

is_sandbox
required
boolean

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

require_gov_id
boolean

Agrega un paso extra para solicitar el Government ID (CURP, CPF, etc.) al usuario

Responses

Request samples

Content type
application/json
{
  • "name": "My sandbox widget",
  • "countries": [
    ],
  • "platforms": [
    ],
  • "is_sandbox": true,
  • "require_gov_id": false
}

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
}

Consents

Obtener Consentimientos por ID Gubernamental

Devuelve los consentimientos correspondientes al ID Gubernamental especificado.

path Parameters
gov_id
required
string

El ID Gubernamental para obtener los consentimientos.

header Parameters
x-api-key
string

Clave privada única por organización. Permite realizar solicitudes en entornos de Sandbox y Producción.

Responses

Response samples

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

Buscar Consentimientos

Permite buscar consentimientos en un rango de fechas especificado.

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
string <date>
end_date
string <date>
object

Responses

Request samples

Content type
application/json
{
  • "start_date": "2020-08-03",
  • "end_date": "2025-07-03",
  • "options": {
    }
}

Response samples

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