Personas

Usa la API de Personas para crear, listar, consultar, reemplazar y eliminar contactos.

Acceso públicoCopiar enlace

Las solicitudes a Personas no requieren iniciar sesión. Los registros se comparten con la página de Personas de la consola y cualquier visitante puede modificarlos.

Personas pertenece a la versión 0.0.1 de la API pública, cuya numeración se aplica a toda la API. Sus operaciones se agrupan en la referencia de API de Personas. Consulta la política de versiones para conocer los cambios de versión.

Elige la versión de la APICopiar enlace

Usa la ruta canónica /persons. La cabecera opcional API-Version de la solicitud selecciona su comportamiento: omítela o envía API-Version: latest para seguir la última versión compatible, actualmente 0.0.1. Envía API-Version: 0.0.1 para fijar esta versión. Seguir la última versión puede seleccionar una más reciente en el futuro; una versión explícita sigue solicitando exactamente esa versión.

Las selecciones aceptadas devuelven la versión resuelta en la cabecera API-Version de respuesta, actualmente 0.0.1. Las respuestas también incluyen API-Version en Vary. Envía un solo valor de versión; consulta la guía del contrato para conocer las respuestas a cabeceras inválidas y el comportamiento CORS del navegador.

Actualmente solo se implementa 0.0.1. Las versiones no compatibles devuelven 400 Bad Request antes de una escritura, sin recurrir a otra versión. Los ejemplos de abajo fijan 0.0.1, salvo el de listar, que omite la cabecera de forma intencional para seguir la última versión.

Campos y validaciónCopiar enlace

Las solicitudes de creación y reemplazo requieren exactamente cuatro campos editables. Los campos desconocidos, incluido id, se rechazan. Los espacios al principio y al final se recortan antes de validar. Se permiten correos y teléfonos duplicados.

Concatena country_code y phone_number para obtener el número internacional. +1 más 2025550123 produce +12025550123. El valor combinado debe cumplir ^\+[1-9][0-9]{1,14}$, con un máximo de 15 dígitos sin contar +. Varios países pueden compartir un prefijo. La validación revisa solo la sintaxis; no demuestra que un número esté asignado, sea accesible o esté registrado en SMS o WhatsApp.

Ejecuta las cinco operacionesCopiar enlace

Usa una terminal con curl y jq. El origen de la API se muestra abajo. Para una API local, configura API_ORIGIN=http://127.0.0.1:18884 antes de ejecutar los bloques. Mantén la misma terminal para conservar PERSON_ID.

CrearCopiar enlace

API_ORIGIN="${API_ORIGIN:-https://api.centrixiso.com}"
PERSON_JSON=$(curl --fail-with-body --silent --show-error \
  -X POST "$API_ORIGIN/persons" \
  -H 'API-Version: 0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"Alex Morgan","email":"alex.morgan@example.com","phone_number":"2025550123","country_code":"+1"}')
PERSON_ID=$(printf '%s' "$PERSON_JSON" | jq -er '.id')
printf '%s\n' "$PERSON_JSON" | jq .

Espera 201 Created, la persona en JSON y Location: /persons/{id}. El servidor genera el ID; será distinto del mostrado en esta respuesta ilustrativa.

{
  "id": "8b7f8b7d-3ac0-4ce2-b85f-578f3113022d",
  "full_name": "Alex Morgan",
  "email": "alex.morgan@example.com",
  "phone_number": "2025550123",
  "country_code": "+1"
}

ListarCopiar enlace

curl --fail-with-body --silent --show-error \
  "$API_ORIGIN/persons?limit=25&offset=0" | jq .

Espera 200 OK y un objeto con items, limit, offset y has_more. Los elementos se ordenan por ID ascendente. El límite predeterminado es 25 y se permiten valores de 1–100. El desplazamiento comienza en 0 y debe ser un entero no negativo. La paginación inválida devuelve 400.

Esta solicitud omite API-Version, por lo que usa la última versión del servidor. Añade -H 'API-Version: 0.0.1' para fijarla como en los demás ejemplos.

Cuando has_more sea true, suma limit a offset para solicitar la siguiente página. Resta limit para retroceder sin bajar de cero. No se devuelve un total. Otros visitantes pueden modificar los datos compartidos, por lo que las páginas pueden desplazarse entre solicitudes.

ConsultarCopiar enlace

curl --fail-with-body --silent --show-error \
  -H 'API-Version: 0.0.1' \
  "$API_ORIGIN/persons/$PERSON_ID" | jq .

Espera 200 OK con la persona creada. Las respuestas usan Cache-Control: no-store.

ReemplazarCopiar enlace

curl --fail-with-body --silent --show-error \
  -X PUT "$API_ORIGIN/persons/$PERSON_ID" \
  -H 'API-Version: 0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"Updated Alex Morgan","email":"updated.alex.morgan@example.com","phone_number":"02025550123","country_code":"+1"}' | jq .

Espera 200 OK con el mismo ID y los cuatro valores reemplazados. El cero inicial de phone_number se conserva como texto. La referencia llama Actualizar a esta operación. PUT requiere todos los campos editables, reemplaza el contacto completo y no crea registros inexistentes. Si hay reemplazos simultáneos, prevalece la última escritura. Actualiza la consola para ver estos valores allí.

EliminarCopiar enlace

curl --fail-with-body --silent --show-error --include \
  -X DELETE "$API_ORIGIN/persons/$PERSON_ID" \
  -H 'API-Version: 0.0.1'

Espera 204 No Content con el cuerpo vacío; no intentes interpretarlo como JSON. La eliminación es definitiva.

Datos inválidos y registros inexistentesCopiar enlace

Esta solicitud contiene un correo inválido y no crea ningún registro:

curl --silent --show-error --include \
  -X POST "$API_ORIGIN/persons" \
  -H 'API-Version: 0.0.1' \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"Alex Morgan","email":"invalid","phone_number":"2025550123","country_code":"+1"}'

Espera 400 Bad Request con Content-Type: application/problem+json:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "email must be a valid email address of at most 254 characters.",
  "instance": "/persons"
}

Consulta el ID eliminado arriba para observar la respuesta de un registro inexistente:

curl --silent --show-error --include \
  -H 'API-Version: 0.0.1' \
  "$API_ORIGIN/persons/$PERSON_ID"

Espera 404 Not Found con application/problem+json, status: 404 y detail: "Person was not found in this scope.". El campo instance contiene la ruta solicitada. Reemplazar y eliminar también devuelven 404 para un ID inexistente. Un UUID mal formado devuelve 400. Si la base de datos no está disponible, la API devuelve 503 con un detalle genérico; los fallos inesperados devuelven 500.

Usa el playground del navegadorCopiar enlace

Abre una operación en la referencia de Personas, introduce los campos de la solicitud en su playground y envíala. Copia el ID de la respuesta para consultar, reemplazar o eliminar.

Configura la cabecera API-Version de la solicitud con 0.0.1 cuando quieras fijar la misma versión explícita que este recorrido. Omitirla sigue la última versión, independientemente del lenguaje elegido para un ejemplo copiado.

Después de un fallo de transporte, consulta el registro o recarga la lista antes de repetir una escritura: el servidor pudo completarla aunque la respuesta no llegara al navegador. La consola pública permite consultar y editar los mismos registros sin iniciar sesión.

Ejecuta ejemplos en tu lenguajeCopiar enlace

Abre Referencia de API → Núcleo → Personas. El objeto Persona muestra el esquema y un ejemplo de respuesta. Selecciona una operación y busca Ejemplos de solicitud. Selecciona la pestaña visible de cURL, JavaScript, Python, Java, Go, C# o Rust para consultar el ejemplo de ese lenguaje. Cada ejemplo utiliza el método, la ruta, los parámetros, las cabeceras y el cuerpo de la operación. Sustituye los ID ilustrativos por uno devuelto al crear y confirma el origen de la API antes de ejecutarlo.

El playground del navegador envía una solicitud HTTP al pulsar Enviar. Elegir Python o Java cambia el código para copiar; el portal no ejecuta un intérprete de Python ni una JVM. Ejecuta los fragmentos copiados con las herramientas locales del lenguaje. Son ejemplos HTTP, no SDK de Centrix.

PythonCopiar enlace

Usa Python 3 y el paquete requests. Crea un entorno virtual con python -m venv .venv, actívalo según tu terminal e instala la dependencia con python -m pip install requests. Copia el ejemplo generado de Python en person-example.py y ejecuta python person-example.py. Revisa el estado HTTP y la respuesta antes de repetir una escritura.

JavaCopiar enlace

Los ejemplos usan java.net.http.HttpClient de la biblioteca estándar, disponible desde Java 11. Usa JDK 17 o posterior para todos los ejemplos generados, incluidos los cuerpos de solicitudes escritos con bloques de texto. Copia el ejemplo completo de la pestaña Java en PersonExample.java y ejecuta java PersonExample.java. El ejemplo incluye la clase PersonExample y su método main, listo para el lanzador de archivos fuente de Java.

Otros lenguajesCopiar enlace

Copia los comandos de cURL en una terminal. Los ejemplos de JavaScript usan fetch; un archivo .mjs puede ejecutarse con Node.js 18 o posterior. Los ejemplos de Go, C# y Rust requieren las herramientas locales del lenguaje y las dependencias HTTP indicadas por el fragmento. Integra las importaciones y las instrucciones copiadas en el programa o proyecto correspondiente antes de ejecutarlo.

La guía del contrato de API explica la selección de versión y el manejo de respuestas. El recorrido con curl de arriba incluye crear un ID, utilizarlo y eliminar el registro al terminar.