Guía de Integración de Tokens API

Esta guía describe el flujo por API key: generar, cancelar y reactivar la integración de un usuario. Se prefiere SSO con JWT por su menor complejidad.

Integración preferida: SSO JWT

Se prefiere SSO con JWT: la empresa firma un token y redirige al usuario. No requiere invocar POST /integrations/token. Consulte la Guía de Integración SSO JWT.

Requisitos Previos

Antes de comenzar, necesitas tener una clave API aprobada. Para obtenerla, contacta con nuestro equipo proporcionando: nombre de la aplicación, descripción de la integración y dominios/IPs permitidos.

Endpoints

Producción – Generar URL de integración:

POST https://api.nuevometodo.com/integrations/token

Producción – Cancelar integración de usuario:

POST https://api.nuevometodo.com/integrations/cancelIntegration

Producción – Reactivar integración de usuario:

POST https://api.nuevometodo.com/integrations/reactivateIntegration

Autenticación

Todas las solicitudes requieren autenticación mediante tu clave API. Puedes enviarla usando cualquiera de estos métodos:

Bearer Token (Recomendado): En el header Authorization
Query Parameter: Como ?api_key=TU_CLAVE_API
Body Property: En el JSON del body como api_key

Flujo para generar la URL

Secuencia de POST /integrations/token: la API devuelve la url al cliente y el cliente redirige el navegador del usuario. El flujo termina en ese redirect.

Parámetros del Request Body – Generar URL de Integración

✅ Campos Requeridos

⚠️ Importante: Debes proporcionar uno de estos campos (no ambos):

Campo	Tipo	Descripción
`email`	string	Email válido del usuario (requerido si no se proporciona external_id)
`external_id`	string	Identificador externo único del usuario (requerido si no se proporciona email)

🔵 Campos Opcionales

⚠️ Importante: Todos los campos opcionales deben ir dentro del objeto data. Puedes omitir data completamente, enviarlo vacío data: {}, o incluir uno o más campos opcionales dentro de data.

Campos dentro de data:

Campo	Tipo	Descripción
`full_name`	string	Nombre completo del usuario
`first_name`	string	Nombre del usuario
`last_name`	string	Apellido del usuario
`dni`	string	Documento Nacional de Identidad
`date_of_birth`	string	Fecha de nacimiento en formato ISO 8601 con zona horaria UTC: YYYY-MM-DDTHH:mm:ss.sssZ (ej: "1995-07-21T00:00:00.000Z").Nota: En JSON las fechas se envían como string, no como objeto Date.
`country`	string	Nombre completo del país (ej: "Argentina", "Estados Unidos")
`gender`	string	Género (ej: "M", "F", "O")
`dial_code`	string	Código de marcado internacional (ej: "+54")
`phone_number`	string	Número de teléfono sin código de país

Ejemplo de Request Body – Generar URL de Integración

Ejemplo mínimo usando email (sin data):

{
  "email": "usuario@ejemplo.com"
}

Ejemplo mínimo usando external_id (sin data):

{
  "external_id": "USR-12345-ABC"
}

Ejemplo con email y data vacío:

{
  "email": "usuario@ejemplo.com",
  "data": {}
}

Ejemplo con email y un solo campo en data:

{
  "email": "usuario@ejemplo.com",
  "data": {
    "full_name": "Juan Pérez"
  }
}

Ejemplo completo con email y todos los campos opcionales en data:

{
  "email": "usuario@ejemplo.com",
  "data": {
    "full_name": "Juan Pérez",
    "first_name": "Juan",
    "last_name": "Pérez",
    "dni": "12345678",
    "date_of_birth": "1995-07-21T00:00:00.000Z",
    "country": "Argentina",
    "gender": "M",
    "dial_code": "+54",
    "phone_number": "1123456789"
  }
}

Ejemplo completo con external_id y todos los campos opcionales en data:

{
  "external_id": "USR-12345-ABC",
  "data": {
    "full_name": "Juan Pérez",
    "first_name": "Juan",
    "last_name": "Pérez",
    "dni": "12345678",
    "date_of_birth": "1995-07-21T00:00:00.000Z",
    "country": "Argentina",
    "gender": "M",
    "dial_code": "+54",
    "phone_number": "1123456789"
  }
}

Respuestas del Servidor – Generar URL

✅ Éxito (HTTP 200)

Cuando la solicitud se procesa correctamente, recibirás una respuesta con la URL de integración generada.

{
  "url": "https://nuevometodo.com/auth/connecting?token=abc123xyz789"
}

❌ Error de Autenticación (HTTP 401)

Se devuelve cuando las credenciales de autenticación son inválidas o están ausentes: clave API desconocida, integración inactiva u origen no habilitado. No incluye el campo key.

{
  "statusCode": 401,
  "message": "No autorizado."
}

❌ Usuario con acceso cancelado (HTTP 401)

Mismo código de estado, causa distinta: las credenciales son válidas y el rechazo es por el usuario final. Se distingue por el campo key, que no cambia aunque cambie el mensaje.

{
  "statusCode": 401,
  "key": "integrations.user_access_canceled",
  "message": "El acceso de este usuario está cancelado. Las credenciales de la integración son válidas: lo que está deshabilitado es la sesión del usuario final indicado en este pedido. Reactivalo con POST /integrations/reactivateIntegration enviando el mismo identificador."
}

Secuencia de POST /integrations/token con el acceso cancelado: la API responde 401 integrations.user_access_canceled, sin url y sin redirect.

⚠️ Error de Validación (HTTP 400)

Se devuelve cuando faltan campos requeridos o los datos son inválidos.

{
  "statusCode": 400,
  "message": "Debe proporcionar 'email' o 'external_id'"
}

Ejemplos de Solicitudes HTTP – Generar URL

Método 1: Bearer Token (Recomendado)

Usa el header Authorization con Bearer token:

POST /integrations/token HTTP/1.1
Host: api.nuevometodo.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

{
  "email": "usuario@ejemplo.com",
  "data": {
    "full_name": "Juan Pérez",
    "first_name": "Juan",
    "last_name": "Pérez",
    "dni": "12345678",
    "phone_number": "1123456789"
  }
}

O usando external_id:

POST /integrations/token HTTP/1.1
Host: api.nuevometodo.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

{
  "external_id": "USR-12345-ABC",
  "data": {
    "full_name": "Juan Pérez"
  }
}

Método 2: Query Parameter

Pasa la clave API como parámetro en la URL:

POST /integrations/token?api_key=TU_CLAVE_API HTTP/1.1
Host: api.nuevometodo.com
Content-Type: application/json

{
  "email": "usuario@ejemplo.com",
  "data": {
    "full_name": "Juan Pérez",
    "date_of_birth": "1995-07-21T00:00:00.000Z",
    "country": "Argentina",
    "gender": "M"
  }
}

Método 3: Body Property

Incluye la clave API en el cuerpo del JSON:

POST /integrations/token HTTP/1.1
Host: api.nuevometodo.com
Content-Type: application/json

{
  "external_id": "USR-12345-ABC",
  "data": {
    "full_name": "Juan Pérez",
    "dial_code": "+54",
    "phone_number": "1123456789"
  },
  "api_key": "TU_CLAVE_API"
}

Ejemplos de Código – Generar URL

cURL

curl -X POST https://api.nuevometodo.com/integrations/token \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com"
  }'

O usando external_id:

curl -X POST https://api.nuevometodo.com/integrations/token \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "USR-12345-ABC"
  }'

JavaScript (Fetch API)

const response = await fetch(
  'https://api.nuevometodo.com/integrations/token',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer TU_CLAVE_API',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'usuario@ejemplo.com', // O external_id: 'USR-12345-ABC'
      data: {
        full_name: 'Juan Pérez', // Opcional
        first_name: 'Juan', // Opcional
        last_name: 'Pérez', // Opcional
        date_of_birth: new Date('1995-07-21').toISOString() // Convierte Date a string ISO 8601
      }
    })
  }
);

const data = await response.json();
console.log(data.url);

Nota: Si tienes un objeto Date, usa .toISOString() para convertirlo al formato requerido. Todos los campos opcionales deben ir dentro del objeto data.

Cancelar Integración de Usuario

Usa este endpoint para cancelar la integración de un usuario, es decir, para revocar su acceso vía token de integración. Internamente, esto deshabilita la sesión del usuario asociado (equivalente a una baja de acceso, no una eliminación física del paciente).

Secuencia de POST /integrations/cancelIntegration: la API responde 200 successful cancellation, sin url y sin redirect.

Parámetros del Request Body – Cancelación

⚠️ Importante: Debes proporcionar uno de estos campos (no ambos):

Campo	Tipo	Descripción
`email`	string	Email válido del usuario cuya integración quieres cancelar (requerido si no se proporciona external_id)
`external_id`	string	Identificador externo único del usuario cuya integración quieres cancelar (requerido si no se proporciona email)

Para la cancelación, no es necesario enviar el objeto data; solo se utiliza para identificar al usuario por email o external_id.

Ejemplos de Request Body – Cancelación

Ejemplo mínimo usando email:

{
  "email": "usuario@ejemplo.com"
}

Ejemplo mínimo usando external_id:

{
  "external_id": "USR-12345-ABC"
}

Respuestas del Servidor – Cancelación

✅ Éxito (HTTP 200)

Cuando la cancelación se procesa correctamente, recibirás un mensaje de confirmación.

{
  "message": "successful cancellation"
}

❌ Error de Autenticación (HTTP 401)

Se devuelve cuando las credenciales de autenticación son inválidas o están ausentes.

{
  "statusCode": 401,
  "message": "No autorizado."
}

⚠️ Usuario no encontrado (HTTP 404)

Se devuelve cuando no existe un usuario integrado con el email o external_id proporcionado.

{
  "statusCode": 404,
  "message": "User integration not found."
}

Reactivar Integración de Usuario

Usa este endpoint para reactivar la integración de un usuario previamente cancelado. Internamente, vuelve a habilitar su acceso vía token de integración, estableciendo is_session_allowed en true.

Secuencia de reactivación: POST /integrations/reactivateIntegration responde 200 sin url. POST /integrations/token devuelve la url al cliente, que redirige el navegador del usuario.

Parámetros del Request Body – Reactivación

⚠️ Importante: Debes proporcionar uno de estos campos (no ambos):

Puedes enviar email o external_id. Para la reactivación, no es necesario enviar data.

{
  "email": "usuario@ejemplo.com"
}

Respuestas del Servidor – Reactivación

✅ Éxito (HTTP 200)

{
  "message": "successful reactivation"
}

❌ Error de Autenticación (HTTP 401)

{
  "statusCode": 401,
  "message": "No autorizado."
}

⚠️ Usuario no encontrado (HTTP 404)

{
  "statusCode": 404,
  "message": "User integration not found."
}

⚠️ Usuario de otra integración (HTTP 403)

{
  "statusCode": 403,
  "message": "User does not belong to this integration."
}

Ejemplos de Solicitudes HTTP – Reactivación

POST /integrations/reactivateIntegration HTTP/1.1
Host: api.nuevometodo.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

{
  "email": "usuario@ejemplo.com"
}

Reactivación automática al pedir el token

⚠️ Esta opción se habilita por integración, a pedido.

Con ella, /integrations/token reactiva al usuario cancelado en lugar de responder 401, sin llamar a este endpoint. Mientras esté activa, las bajas dejan de tener efecto para tu integración.

Ejemplos de Solicitudes HTTP – Cancelación

Ejemplo usando Bearer token y email:

POST /integrations/cancelIntegration HTTP/1.1
Host: api.nuevometodo.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

{
  "email": "usuario@ejemplo.com"
}

Ejemplo usando Bearer token y external_id:

POST /integrations/cancelIntegration HTTP/1.1
Host: api.nuevometodo.com
Authorization: Bearer TU_CLAVE_API
Content-Type: application/json

{
  "external_id": "USR-12345-ABC"
}

Ejemplos de Código – Cancelación

cURL

curl -X POST https://api.nuevometodo.com/integrations/cancelIntegration \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com"
  }'

O usando external_id:

curl -X POST https://api.nuevometodo.com/integrations/cancelIntegration \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "USR-12345-ABC"
  }'

JavaScript (Fetch API)

const response = await fetch(
  'https://api.nuevometodo.com/integrations/cancelIntegration',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer TU_CLAVE_API',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      // Usa uno de los dos campos:
      email: 'usuario@ejemplo.com', // O bien:
      // external_id: 'USR-12345-ABC'
    })
  }
);

const data = await response.json();
console.log(data.message); // "successful cancellation"

💡 Notas Importantes

Debes proporcionar uno de estos campos (no ambos): email o external_id
Para la generación de URL, todos los campos opcionales deben ir dentro del objeto data
Puedes omitir data completamente, enviarlo vacío data: {}, o incluir uno o más campos opcionales dentro de data
No envíes email y external_id juntos en la misma solicitud
El campo date_of_birth debe ser en formato fecha ISO 8601 con zona horaria UTC: YYYY-MM-DDTHH:mm:ss.sssZ (ej: "1995-07-21T00:00:00.000Z"). En JSON las fechas siempre se envían como string, no como objeto Date.
El campo country debe ser el nombre completo del país (ej: "Argentina", "Estados Unidos", "México")
Si tienes problemas, verifica que tu clave API sea válida y esté activa

Si necesitas asistencia adicional o tienes preguntas sobre la integración, no dudes en contactar a nuestro equipo de soporte técnico.