> For the complete documentation index, see [llms.txt](https://developer.miaid.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.miaid.me/api-reference/readme.md). # Especificación de API Bienvenido a nuestra API. Aca podras acceder a la documentación de todos los servicios expuestos por MIA. ### Introducción a PServices La API expuesta por MIA sigue una arquitectura RPC-like (Remote Procedure Call). A diferencia de las APIs REST orientadas a recursos, PServices se centra en la ejecución de servicios que encapsulan reglas de negocio complejas, abstrayendo la gestión de entidades para el cliente consumidor. #### Conceptos Clave * Método Único: Se utiliza exclusivamente el método `POST`. * Endpoint Único: Un solo punto de entrada que deriva internamente las peticiones. * Aislamiento de Errores: La API retorna siempre un código `HTTP 200`. Los errores de negocio se gestionan dentro del cuerpo de la respuesta, separando la capa de transporte de la lógica de aplicación. Cualquier otro código de retorno HTTP, debe ser interpretado a nivel protocolo HTTP. ### Especificación Técnica #### Entornos y URL Base Todas las solicitudes de servicio deben dirigirse a una única URL, dependiendo del ambiente en el que se esté trabajando: | **Ambiente** | **URL Base** | | ------------------ | ------------------------------- | | Dev / Homologación | `https://services-dev.miaid.me` | | Producción | `https://services.miaid.me` | *** #### Encabezados (Headers) Es obligatorio incluir los siguientes headers en cada petición: * `Content-Type`: `application/json` * `x-origin-id`: Identificador de la aplicación de origen. * `x-api-key`: Clave de acceso autorizada. *** #### Estructura del Request (Cuerpo) El cuerpo de la petición debe ser un objeto JSON con la siguiente estructura: ``` { "service": "nombre_del_servicio", "params": { "parametro_1": "valor", "parametro_n": 123 } } ``` * `service` (string): Nombre identificador del servicio a procesar. * `params` (JSON): Objeto que contiene los argumentos necesarios. Los pares nombre/valor específicos se detallan en la documentación de cada servicio. *** #### Estructura del Response (Cuerpo) La respuesta es un objeto JSON estandarizado que permite un manejo de errores predecible. #### 1. El objeto `status` Contiene la metadata del resultado de la ejecución: | **Atributo** | **Tipo** | **Descripción** | | ------------ | -------- | --------------------------------------------------------------------- | | `code` | `int` | `1` para éxito, `0` para error. | | `errcode` | `int` | Código numérico del error detectado. | | `errmsg` | `string` | Descripción textual del error o mensaje informativo. | | `origin` | `int` | Identificador del módulo emisor del error. | | `action` | `string` | Indica el curso de acción a seguir (ver tabla abajo). | | `id` | `int` | ID de la entidad principal creada (solo en operaciones de inserción). | **📝 Diccionario de Acciones/Gravedad del error (`action`)** Cuando el `code` es `0`, el atributo `action` determina cómo debe reaccionar la aplicación cliente: * `E` (Error): Error irrecuperable en la ejecución del servicio. * `W` (Warning): Aviso informativo/advertencia. * `X` (Interpretable): El cliente debe ejecutar una lógica específica basada en el `errcode`. * `F` (Fatal): Error crítico en la infraestructura o ejecución. #### 2. El objeto `result` * Tipo: `JSON Array` * Descripción: Contiene el resultado de la consulta o proceso. Cada elemento del array es un objeto con pares nombre/valor definidos en la documentación específica de cada servicio. *** #### Errores comunes Si la solicitud no cumples con los requisitos básicos, esta retornará un error. Los siguientes son comunes a todos los servicios: | **Gravedad (action)** | **Código (code)** | **Mensaje (errmsg)** | **Descripción** | | --------------------- | ----------------- | ----------------------------------- | ------------------------------------------------------------------------------- | | E | `10040` | Dispositivo no autorizado | El valor de `x-api-key` es inválido o no existe. | | E | `55001` | Servicio inválido | El atributo `service` es incorrecto, no se reconoce o no fue enviado. | | E | `55002` | Params inválido | Se ha omitido el atributo `params` en el cuerpo de la petición. | | E | `55003` | Parámetro requerido/inválido \[xxx] | El parámetro específico `xxx` dentro del objeto `params` falta o es incorrecto. | | E | `55999` | Ha ocurrido un error inesperado | Error genérico no manejado por el sistema. | ### Próximos Pasos Ahora que conoces la estructura base, puedes explorar los servicios en el menú lateral para conocer los parámetros específicos de cada operación. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.miaid.me/api-reference/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.