Guía de Integración de Tokens API

Esta guía te proporcionará toda la información necesaria para integrar tu aplicación con nuestro servicio de generación de tokens de integración, así como para cancelar la integración de un usuario previamente generado.

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:

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

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

✅ Campos Requeridos

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

CampoTipoDescripción
emailstringEmail válido del usuario (requerido si no se proporciona external_id)
external_idstringIdentificador 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:

CampoTipoDescripción
full_namestringNombre completo del usuario
first_namestringNombre del usuario
last_namestringApellido del usuario
dnistringDocumento Nacional de Identidad
date_of_birthstringFecha 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.
countrystringNombre completo del país (ej: "Argentina", "Estados Unidos")
genderstringGénero (ej: "M", "F", "O")
dial_codestringCódigo de marcado internacional (ej: "+54")
phone_numberstringNú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.

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

⚠️ 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).

Parámetros del Request Body – Cancelación

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

CampoTipoDescripción
emailstringEmail válido del usuario cuya integración quieres cancelar (requerido si no se proporciona external_id)
external_idstringIdentificador 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.

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

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.

Copyright © 2026, Nuevo Método