Contrato de API
Consulta operaciones, elige una versión de la API y trabaja con solicitudes y respuestas.
Consulta la referencia de API
El portal tiene dos áreas principales. Documentación contiene guías como Personas. Referencia de API describe el método HTTP y la ruta de cada operación, los parámetros, los campos y la validación de las solicitudes, las respuestas correctas y de error, los tipos de contenido y las cabeceras. Usa esa área para implementar una solicitud o interpretar su respuesta.
Descarga el contrato OpenAPI de Personas o el contrato OpenAPI de Comercios y Direcciones. Cada operación muestra una tabla de cabeceras y estados de respuesta generada a partir de su contrato.
Versiones de la API
La versión actual de toda la API pública es 0.0.1 y se registra en info.version de OpenAPI. Todos los recursos de ese contrato comparten esta versión; Personas no tiene una numeración independiente. El campo openapi identifica el formato de la especificación, actualmente 3.1.0.
La política de numeración usa mayor.menor.parche:
| Parte | Cambio |
|---|---|
| Parche | Correcciones compatibles; aumenta el último número. |
| Menor | Nuevas funciones compatibles; aumenta el número central y reinicia el parche en cero. |
| Mayor | Cambios incompatibles del contrato público; aumenta el primer número y reinicia los números menor y de parche en cero. |
Esta política de numeración sigue el versionado semántico. Revisa el contrato publicado al cambiar de versión.
Las rutas de los recursos no incluyen la versión: Personas está en /persons. Selecciona una versión con la cabecera opcional API-Version de la solicitud:
| Cabecera de solicitud | Comportamiento |
|---|---|
Omitida, o API-Version: latest | Sigue la última versión compatible del servidor, actualmente 0.0.1. La versión elegida puede avanzar cuando se publique otra versión. |
API-Version: 0.0.1 | Fija explícitamente la solicitud a la versión 0.0.1. |
| Valor vacío, no compatible, mal formado, combinado o repetido | Devuelve 400 Bad Request antes de ejecutar la operación, sin recurrir a otra versión. |
Se recortan los espacios al principio y al final; los valores distinguen mayúsculas de minúsculas. Envía un solo valor una sola vez. Las solicitudes con versión inválida devuelven application/problem+json con el detalle API-Version must be latest or 0.0.1 and must appear only once.
Una selección aceptada devuelve API-Version: 0.0.1, incluso en respuestas de validación, registro inexistente o indisponibilidad de la base de datos. Una versión inválida no incluye una cabecera API-Version de respuesta resuelta. Las respuestas de negocio incluyen API-Version en Vary, junto con valores existentes como Origin. CORS permite la cabecera de solicitud y expone la cabecera de respuesta resuelta al navegador.
La versión compatible actual es 0.0.1.
Personas
Abre Referencia de API → Núcleo → Personas. El objeto Persona muestra el esquema de respuesta y un ejemplo, seguido de las operaciones de crear, actualizar, consultar, listar y eliminar. Actualizar usa PUT para reemplazar los cuatro campos editables; no es una actualización parcial. Sigue la guía de Personas para ejecutar la secuencia completa de solicitudes.
Ejemplos de solicitudes y pruebas en vivo
Busca Ejemplos de solicitud en una operación y elige cURL, JavaScript, Python, Java, Go, C# o Rust. Copia el ejemplo para ejecutarlo en tu propio entorno. En las operaciones de Personas, Enviar en el explorador ejecuta una solicitud HTTP desde el navegador. Consulta la guía de Personas para configurar Python o Java.
Revisa el estado y el cuerpo de la respuesta, incluidos los errores application/problem+json. DELETE devuelve una respuesta 204 vacía. Los fragmentos muestran solicitudes HTTP para ejecutarlas en tu propio entorno.