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 el Catálogo de Servicios en el menú lateral para conocer los parámetros específicos de cada operación.