{ "openapi": "3.1.0", "info": { "title": "Plusdiario API comercial", "version": "2.0.0", "description": "Operaciones nuevas en ARS. Requiere migración instalada y permisos v2. La API v1 se conserva." }, "servers": [ { "url": "https://www.plusdiario.com.ar/api/v2" } ], "paths": { "/contactos.php": { "get": { "operationId": "contactos_get", "summary": "GET contactos", "description": "Contacto sin consulta ni venta implícita. Permiso: contactos:read.", "tags": [ "contactos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "contactos_post", "summary": "POST contactos", "description": "Contacto sin consulta ni venta implícita. Permiso: contactos:write.", "tags": [ "contactos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "apellido": { "type": "string", "description": "apellido." }, "telefono": { "type": "string", "description": "Teléfono como texto, de 7 a 15 dígitos; se permiten signos de formato. No enviar como número JSON." }, "email": { "type": "string", "description": "Correo electrónico válido." }, "dni": { "type": "string", "description": "DNI de 7 u 8 dígitos." }, "cuit": { "type": "string", "description": "CUIT de 11 dígitos." }, "direccion": { "type": "string", "description": "direccion." }, "ciudad": { "type": "string", "description": "ciudad." }, "provincia": { "type": "string", "description": "provincia." }, "pais": { "type": "string", "description": "pais." }, "cp": { "type": "string", "description": "cp." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "estado_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "responsable_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "source": { "type": "string", "description": "Origen del registro. Ejemplo: web_form, ecommerce o sistema_gestion." }, "source_detail": { "type": "string", "description": "source detail." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto con UTMs u otros datos auxiliares, hasta 16 KB. No enviar secretos." }, "ad_account_id": { "type": "string", "description": "ad account id." }, "ad_id": { "type": "string", "description": "ad id." }, "campaign_id": { "type": "string", "description": "campaign id." }, "adgroup_id": { "type": "string", "description": "adgroup id." }, "ad_name": { "type": "string", "description": "ad name." }, "adset_name": { "type": "string", "description": "adset name." }, "campaign_name": { "type": "string", "description": "campaign name." } } }, "example": { "nombre": "Ana Ejemplo", "telefono": "1112345678", "external_id": "cliente-123" } } } } }, "patch": { "operationId": "contactos_patch", "summary": "PATCH contactos", "description": "Contacto sin consulta ni venta implícita. Permiso: contactos:write.", "tags": [ "contactos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "apellido": { "type": "string", "description": "apellido." }, "telefono": { "type": "string", "description": "Teléfono como texto, de 7 a 15 dígitos; se permiten signos de formato. No enviar como número JSON." }, "email": { "type": "string", "description": "Correo electrónico válido." }, "dni": { "type": "string", "description": "DNI de 7 u 8 dígitos." }, "cuit": { "type": "string", "description": "CUIT de 11 dígitos." }, "direccion": { "type": "string", "description": "direccion." }, "ciudad": { "type": "string", "description": "ciudad." }, "provincia": { "type": "string", "description": "provincia." }, "pais": { "type": "string", "description": "pais." }, "cp": { "type": "string", "description": "cp." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "estado_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "responsable_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "source": { "type": "string", "description": "Origen del registro. Ejemplo: web_form, ecommerce o sistema_gestion." }, "source_detail": { "type": "string", "description": "source detail." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto con UTMs u otros datos auxiliares, hasta 16 KB. No enviar secretos." }, "ad_account_id": { "type": "string", "description": "ad account id." }, "ad_id": { "type": "string", "description": "ad id." }, "campaign_id": { "type": "string", "description": "campaign id." }, "adgroup_id": { "type": "string", "description": "adgroup id." }, "ad_name": { "type": "string", "description": "ad name." }, "adset_name": { "type": "string", "description": "adset name." }, "campaign_name": { "type": "string", "description": "campaign name." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } }, "/leads.php": { "get": { "operationId": "leads_get", "summary": "GET leads", "description": "Consulta comercial vinculada al CRM. El estado de venta requiere permiso ventas:write. Permiso: leads:read.", "tags": [ "leads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "leads_post", "summary": "POST leads", "description": "Consulta comercial vinculada al CRM. El estado de venta requiere permiso ventas:write. Permiso: leads:write.", "tags": [ "leads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "apellido": { "type": "string", "description": "apellido." }, "telefono": { "type": "string", "description": "Teléfono como texto, de 7 a 15 dígitos; se permiten signos de formato. No enviar como número JSON." }, "email": { "type": "string", "description": "Correo electrónico válido." }, "dni": { "type": "string", "description": "DNI de 7 u 8 dígitos." }, "cuit": { "type": "string", "description": "CUIT de 11 dígitos." }, "direccion": { "type": "string", "description": "direccion." }, "ciudad": { "type": "string", "description": "ciudad." }, "provincia": { "type": "string", "description": "provincia." }, "pais": { "type": "string", "description": "pais." }, "cp": { "type": "string", "description": "cp." }, "mensaje": { "type": "string", "description": "Texto de la consulta; obligatorio al crear un lead." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "estado_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "responsable_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "source": { "type": "string", "description": "Origen del registro. Ejemplo: web_form, ecommerce o sistema_gestion." }, "source_detail": { "type": "string", "description": "source detail." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto con UTMs u otros datos auxiliares, hasta 16 KB. No enviar secretos." }, "ad_account_id": { "type": "string", "description": "ad account id." }, "ad_id": { "type": "string", "description": "ad id." }, "campaign_id": { "type": "string", "description": "campaign id." }, "adgroup_id": { "type": "string", "description": "adgroup id." }, "ad_name": { "type": "string", "description": "ad name." }, "adset_name": { "type": "string", "description": "adset name." }, "campaign_name": { "type": "string", "description": "campaign name." } } }, "example": { "nombre": "Ana Ejemplo", "telefono": "1112345678", "mensaje": "Quiero información", "source": "web_form", "external_id": "lead-123" } } } } }, "patch": { "operationId": "leads_patch", "summary": "PATCH leads", "description": "Consulta comercial vinculada al CRM. El estado de venta requiere permiso ventas:write. Permiso: leads:write.", "tags": [ "leads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "apellido": { "type": "string", "description": "apellido." }, "telefono": { "type": "string", "description": "Teléfono como texto, de 7 a 15 dígitos; se permiten signos de formato. No enviar como número JSON." }, "email": { "type": "string", "description": "Correo electrónico válido." }, "dni": { "type": "string", "description": "DNI de 7 u 8 dígitos." }, "cuit": { "type": "string", "description": "CUIT de 11 dígitos." }, "direccion": { "type": "string", "description": "direccion." }, "ciudad": { "type": "string", "description": "ciudad." }, "provincia": { "type": "string", "description": "provincia." }, "pais": { "type": "string", "description": "pais." }, "cp": { "type": "string", "description": "cp." }, "mensaje": { "type": "string", "description": "Texto de la consulta; obligatorio al crear un lead." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "estado_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "responsable_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "source": { "type": "string", "description": "Origen del registro. Ejemplo: web_form, ecommerce o sistema_gestion." }, "source_detail": { "type": "string", "description": "source detail." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Objeto con UTMs u otros datos auxiliares, hasta 16 KB. No enviar secretos." }, "ad_account_id": { "type": "string", "description": "ad account id." }, "ad_id": { "type": "string", "description": "ad id." }, "campaign_id": { "type": "string", "description": "campaign id." }, "adgroup_id": { "type": "string", "description": "adgroup id." }, "ad_name": { "type": "string", "description": "ad name." }, "adset_name": { "type": "string", "description": "adset name." }, "campaign_name": { "type": "string", "description": "campaign name." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } }, "/productos.php": { "get": { "operationId": "productos_get", "summary": "GET productos", "description": "Catálogo compartido con inventario. El stock se modifica exclusivamente en stock.php. Permiso: productos:read.", "tags": [ "productos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "productos_post", "summary": "POST productos", "description": "Catálogo compartido con inventario. El stock se modifica exclusivamente en stock.php. Permiso: productos:write.", "tags": [ "productos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "codigo": { "type": "string", "description": "codigo." }, "marca": { "type": "string", "description": "marca." }, "familia": { "type": "string", "description": "familia." }, "linea": { "type": "string", "description": "linea." }, "descripcion": { "type": "string", "description": "descripcion." }, "unidad": { "type": "string", "description": "unidad." }, "codigo_ml": { "type": "string", "description": "codigo ml." }, "catalog_product_id": { "type": "string", "description": "catalog product id." }, "foto_url": { "type": "string", "description": "La validación de ficha existente admite imágenes HTTPS de mlstatic.com. No se descargan imágenes arbitrarias." }, "costo": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_venta": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_mayorista": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_3_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_6_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_9_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_12_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "controlar_stock": { "type": "boolean", "description": "controlar stock." }, "visible_chat": { "type": "boolean", "description": "visible chat." }, "stock_minimo": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "proveedor_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "tipo": { "type": "string", "description": "Tipo de producto simple/compuesto/insumo, o clase fiscal A/B/C según el recurso.", "enum": [ "simple", "compuesto", "insumo" ] }, "componentes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." } }, "required": [ "inventario_id", "cantidad" ] }, "maxItems": 100, "description": "Composición de un producto compuesto: inventario_id y cantidad por componente. Se rechazan ciclos y referencias ajenas.", "minItems": 1 }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." } } }, "example": { "codigo": "SKU-123", "nombre": "Producto de ejemplo", "precio_venta": "100.00", "controlar_stock": true } } } } }, "patch": { "operationId": "productos_patch", "summary": "PATCH productos", "description": "Catálogo compartido con inventario. El stock se modifica exclusivamente en stock.php. Permiso: productos:write.", "tags": [ "productos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "codigo": { "type": "string", "description": "codigo." }, "marca": { "type": "string", "description": "marca." }, "familia": { "type": "string", "description": "familia." }, "linea": { "type": "string", "description": "linea." }, "descripcion": { "type": "string", "description": "descripcion." }, "unidad": { "type": "string", "description": "unidad." }, "codigo_ml": { "type": "string", "description": "codigo ml." }, "catalog_product_id": { "type": "string", "description": "catalog product id." }, "foto_url": { "type": "string", "description": "La validación de ficha existente admite imágenes HTTPS de mlstatic.com. No se descargan imágenes arbitrarias." }, "costo": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_venta": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_mayorista": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_3_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_6_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_9_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "precio_12_cuotas": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "controlar_stock": { "type": "boolean", "description": "controlar stock." }, "visible_chat": { "type": "boolean", "description": "visible chat." }, "stock_minimo": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "proveedor_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "tipo": { "type": "string", "description": "Tipo de producto simple/compuesto/insumo, o clase fiscal A/B/C según el recurso.", "enum": [ "simple", "compuesto", "insumo" ] }, "componentes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." } }, "required": [ "inventario_id", "cantidad" ] }, "maxItems": 100, "description": "Composición de un producto compuesto: inventario_id y cantidad por componente. Se rechazan ciclos y referencias ajenas.", "minItems": 1 }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } }, "/stock.php": { "get": { "operationId": "stock_get", "summary": "GET stock", "description": "Entradas, salidas, ajustes y Kardex. Lectura por inventario_id. Para crear lote: codigo_lote y fecha_vencimiento opcional. Permiso: stock:read.", "tags": [ "stock" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "stock_post", "summary": "POST stock", "description": "Entradas, salidas, ajustes y Kardex. Lectura por inventario_id. Para crear lote: codigo_lote y fecha_vencimiento opcional. Permiso: stock:write.", "tags": [ "stock" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "action": { "type": "string", "description": "action.", "enum": [ "entrada", "salida", "ajuste" ] }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "stock_esperado": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Stock leído previamente, obligatorio para ajustes; si cambió se responde 409." }, "motivo": { "type": "string", "description": "Explicación obligatoria del movimiento o devolución, hasta 500 caracteres." }, "lote_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "codigo_lote": { "type": "string", "description": "codigo lote." }, "fecha_vencimiento": { "type": "string", "description": "fecha vencimiento." }, "venta_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "inventario_id": "10", "action": "entrada", "cantidad": "10.00", "motivo": "Recepción de mercadería", "external_id": "recepcion-123" } } } } } }, "/presupuestos.php": { "get": { "operationId": "presupuestos_get", "summary": "GET presupuestos", "description": "Presupuestos al contado en ARS, editables antes de convertirlos. Financiación histórica se conserva en su circuito actual. Permiso: presupuestos:read.", "tags": [ "presupuestos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "presupuestos_post", "summary": "POST presupuestos", "description": "Presupuestos al contado en ARS, editables antes de convertirlos. Financiación histórica se conserva en su circuito actual. Permiso: presupuestos:write.", "tags": [ "presupuestos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cliente_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "articulo": { "type": "string", "maxLength": 100 }, "descripcion": { "type": "string", "maxLength": 12000 }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "precio_unitario": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$" } }, "required": [ "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "observaciones": { "type": "string", "description": "observaciones." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "convertir_pedido", "convertir_venta" ] }, "afectar_stock": { "type": "boolean", "description": "Booleano obligatorio para venta operativa o su conversión; requiere stock:write cuando es true." }, "pagos": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "monto", "metodo_pago" ] }, "maxItems": 20, "description": "Pagos realmente recibidos. Lista obligatoria en venta operativa; [] deja el saldo pendiente. Cada pago usa monto, metodo_pago y sucursal_id opcional." }, "sucursal_id": { "type": "string", "description": "sucursal id." } } }, "example": { "cliente_id": "123", "items": [ { "inventario_id": "10", "cantidad": "2.00" } ], "observaciones": "Presupuesto de ejemplo" } } } } }, "patch": { "operationId": "presupuestos_patch", "summary": "PATCH presupuestos", "description": "Presupuestos al contado en ARS, editables antes de convertirlos. Financiación histórica se conserva en su circuito actual. Permiso: presupuestos:write.", "tags": [ "presupuestos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cliente_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "articulo": { "type": "string", "maxLength": 100 }, "descripcion": { "type": "string", "maxLength": 12000 }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "precio_unitario": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$" } }, "required": [ "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "observaciones": { "type": "string", "description": "observaciones." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "convertir_pedido", "convertir_venta" ] }, "afectar_stock": { "type": "boolean", "description": "Booleano obligatorio para venta operativa o su conversión; requiere stock:write cuando es true." }, "pagos": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "monto", "metodo_pago" ] }, "maxItems": 20, "description": "Pagos realmente recibidos. Lista obligatoria en venta operativa; [] deja el saldo pendiente. Cada pago usa monto, metodo_pago y sucursal_id opcional." }, "sucursal_id": { "type": "string", "description": "sucursal id." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } }, "/pedidos.php": { "get": { "operationId": "pedidos_get", "summary": "GET pedidos", "description": "Preparación y entrega con venta, stock y cobro explícitos. Una entrega sin pagos conserva saldo pendiente. Permiso: pedidos:read.", "tags": [ "pedidos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "pedidos_post", "summary": "POST pedidos", "description": "Preparación y entrega con venta, stock y cobro explícitos. Una entrega sin pagos conserva saldo pendiente. Permiso: pedidos:write.", "tags": [ "pedidos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cliente_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "presupuesto_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "articulo": { "type": "string", "maxLength": 100 }, "descripcion": { "type": "string", "maxLength": 12000 }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "precio_unitario": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$" } }, "required": [ "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "direccion_entrega": { "type": "string", "description": "direccion entrega." }, "ciudad_entrega": { "type": "string", "description": "ciudad entrega." }, "notas": { "type": "string", "description": "notas." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "confirmar", "preparar", "despachar", "entregar", "cancelar", "confirmar_venta" ] }, "afectar_stock": { "type": "boolean", "description": "Booleano obligatorio para venta operativa o su conversión; requiere stock:write cuando es true." }, "pagos": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "monto", "metodo_pago" ] }, "maxItems": 20, "description": "Pagos realmente recibidos. Lista obligatoria en venta operativa; [] deja el saldo pendiente. Cada pago usa monto, metodo_pago y sucursal_id opcional." }, "sucursal_id": { "type": "string", "description": "sucursal id." } } }, "example": { "cliente_id": "123", "items": [ { "inventario_id": "10", "cantidad": "2.00" } ], "direccion_entrega": "Dirección de ejemplo", "ciudad_entrega": "Ciudad" } } } } }, "patch": { "operationId": "pedidos_patch", "summary": "PATCH pedidos", "description": "Preparación y entrega con venta, stock y cobro explícitos. Una entrega sin pagos conserva saldo pendiente. Permiso: pedidos:write.", "tags": [ "pedidos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cliente_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "presupuesto_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "articulo": { "type": "string", "maxLength": 100 }, "descripcion": { "type": "string", "maxLength": 12000 }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "precio_unitario": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$" } }, "required": [ "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "direccion_entrega": { "type": "string", "description": "direccion entrega." }, "ciudad_entrega": { "type": "string", "description": "ciudad entrega." }, "notas": { "type": "string", "description": "notas." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "confirmar", "preparar", "despachar", "entregar", "cancelar", "confirmar_venta" ] }, "afectar_stock": { "type": "boolean", "description": "Booleano obligatorio para venta operativa o su conversión; requiere stock:write cuando es true." }, "pagos": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "monto", "metodo_pago" ] }, "maxItems": 20, "description": "Pagos realmente recibidos. Lista obligatoria en venta operativa; [] deja el saldo pendiente. Cada pago usa monto, metodo_pago y sucursal_id opcional." }, "sucursal_id": { "type": "string", "description": "sucursal id." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } }, "/ventas.php": { "get": { "operationId": "ventas_get", "summary": "GET ventas", "description": "Modo externa importa la venta sin efectos adicionales. Modo operativa exige afectar_stock y pagos (incluido []). Registra scoring 20. Permiso: ventas:read.", "tags": [ "ventas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "ventas_post", "summary": "POST ventas", "description": "Modo externa importa la venta sin efectos adicionales. Modo operativa exige afectar_stock y pagos (incluido []). Registra scoring 20. Permiso: ventas:write.", "tags": [ "ventas" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "modo": { "type": "string", "description": "externa u operativa. No hay un modo predeterminado.", "enum": [ "externa", "operativa" ] }, "cliente_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "presupuesto_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "pedido_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "inventario_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "articulo": { "type": "string", "maxLength": 100 }, "descripcion": { "type": "string", "maxLength": 12000 }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." }, "precio_unitario": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$" } }, "required": [ "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "afectar_stock": { "type": "boolean", "description": "Booleano obligatorio para venta operativa o su conversión; requiere stock:write cuando es true." }, "pagos": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "monto", "metodo_pago" ] }, "maxItems": 20, "description": "Pagos realmente recibidos. Lista obligatoria en venta operativa; [] deja el saldo pendiente. Cada pago usa monto, metodo_pago y sucursal_id opcional." }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "fecha": { "type": "string", "description": "fecha." }, "observaciones": { "type": "string", "description": "observaciones." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "modo": "operativa", "cliente_id": "123", "items": [ { "inventario_id": "10", "cantidad": "2.00" } ], "afectar_stock": true, "pagos": [], "sucursal_id": "1", "external_id": "venta-123" } } } } } }, "/cobros.php": { "get": { "operationId": "cobros_get", "summary": "GET cobros", "description": "Registrar un ingreso real y su recibo interno. Lectura por venta_id. No ejecuta transferencias ni pasarelas. Permiso: cobros:read.", "tags": [ "cobros" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "cobros_post", "summary": "POST cobros", "description": "Registrar un ingreso real y su recibo interno. Lectura por venta_id. No ejecuta transferencias ni pasarelas. Permiso: cobros:write.", "tags": [ "cobros" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "venta_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "monto": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Decimal con punto, sin separador de miles. Enviar como texto para conservar precisión." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "venta_id": "456", "monto": "100.00", "metodo_pago": "transferencia", "sucursal_id": "1", "external_id": "pago-123" } } } } } }, "/devoluciones.php": { "get": { "operationId": "devoluciones_get", "summary": "GET devoluciones", "description": "Devoluciones de artículos con detalle trazable v2; reposición y reintegro explícitos. Las operaciones históricas sin ese detalle requieren revisión en su circuito original. Permiso: devoluciones:read.", "tags": [ "devoluciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "devoluciones_post", "summary": "POST devoluciones", "description": "Devoluciones de artículos con detalle trazable v2; reposición y reintegro explícitos. Las operaciones históricas sin ese detalle requieren revisión en su circuito original. Permiso: devoluciones:write.", "tags": [ "devoluciones" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "venta_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "sale_item_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "cantidad": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Cantidad positiva con hasta 2 decimales. En un ajuste representa el nuevo stock absoluto y admite cero." } }, "required": [ "sale_item_id", "cantidad" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "motivo": { "type": "string", "description": "Explicación obligatoria del movimiento o devolución, hasta 500 caracteres." }, "reponer_stock": { "type": "boolean", "description": "Booleano obligatorio en devoluciones. true repone los productos/componentes y lotes descontados originalmente." }, "reintegro": { "type": "string", "pattern": "^\\d{1,7}(?:\\.\\d{1,2})?$", "description": "Importe efectivamente reintegrado. Obligatorio incluso cuando es 0.00; mayor a cero requiere cobros:write y metodo_pago." }, "metodo_pago": { "type": "string", "description": "efectivo, transferencia, tarjeta, mercadopago, cheque u otro.", "enum": [ "efectivo", "transferencia", "tarjeta", "mercadopago", "cheque", "otro" ] }, "sucursal_id": { "type": "string", "description": "sucursal id." }, "moneda": { "type": "string", "description": "ARS para operaciones nuevas. Los históricos se consultan en su moneda original.", "enum": [ "ARS" ] }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "venta_id": "456", "items": [ { "sale_item_id": "789", "cantidad": "1.00" } ], "motivo": "Devolución acordada", "reponer_stock": true, "reintegro": "0.00", "external_id": "devolucion-123" } } } } } }, "/comprobantes.php": { "get": { "operationId": "comprobantes_get", "summary": "GET comprobantes", "description": "Facturas A/B/C y notas de crédito asociadas, asíncronas. Consultar por venta_id, id de comprobante o job_id. Una alícuota explícita por comprobante A/B (10.5, 21 o 27). Permiso: comprobantes:read.", "tags": [ "comprobantes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "comprobantes_post", "summary": "POST comprobantes", "description": "Facturas A/B/C y notas de crédito asociadas, asíncronas. Consultar por venta_id, id de comprobante o job_id. Una alícuota explícita por comprobante A/B (10.5, 21 o 27). Permiso: comprobantes:write.", "tags": [ "comprobantes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "action": { "type": "string", "description": "action.", "enum": [ "factura", "nota_credito", "reintentar" ] }, "venta_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "devolucion_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "tipo": { "type": "string", "description": "Tipo de producto simple/compuesto/insumo, o clase fiscal A/B/C según el recurso.", "enum": [ "A", "B", "C" ] }, "concepto_arca": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "1 productos, 2 servicios, 3 ambos. Servicios requieren fecha_desde, fecha_hasta y fecha_vto_pago." }, "concepto": { "type": "string", "description": "concepto." }, "doc_tipo": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "80 CUIT, 96 DNI, 99 consumidor final." }, "doc_nro": { "type": "string", "description": "Documento fiscal como texto; 0 para tipo 99." }, "nombre": { "type": "string", "description": "Nombre. Obligatorio al crear un contacto, lead o producto." }, "condicion_iva": { "type": "string", "description": "Condición fiscal del receptor: responsable inscripto, monotributista, exento o consumidor final." }, "iva_alicuota": { "type": "string", "description": "Alícuota explícita para A/B: 10.5, 21 o 27. La nota de crédito conserva la de la factura original." }, "fecha_desde": { "type": "string", "description": "fecha desde." }, "fecha_hasta": { "type": "string", "description": "fecha hasta." }, "fecha_vto_pago": { "type": "string", "description": "fecha vto pago." }, "job_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "action": "factura", "venta_id": "456", "tipo": "C", "condicion_iva": "Consumidor Final", "concepto_arca": 1, "external_id": "factura-123" } } } } } }, "/catalogos.php": { "get": { "operationId": "catalogos_get", "summary": "GET catalogos", "description": "Referencias de la empresa: estados, responsables autorizados, sucursales, medios de pago, monedas y permisos efectivos. Permiso: catalogos:read.", "tags": [ "catalogos" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } } }, "/lotes.php": { "get": { "operationId": "lotes_get", "summary": "GET lotes", "description": "Importaciones de 1 a 100 operaciones homogéneas. Cada elemento se confirma por separado. Consultar id/job_id y reintentar solo fallidos. Permiso: lotes:read.", "tags": [ "lotes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "lotes_post", "summary": "POST lotes", "description": "Importaciones de 1 a 100 operaciones homogéneas. Cada elemento se confirma por separado. Consultar id/job_id y reintentar solo fallidos. Permiso: lotes:write.", "tags": [ "lotes" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "recurso": { "type": "string", "description": "recurso." }, "metodo": { "type": "string", "description": "metodo." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "object" }, "data": { "type": "object" } }, "required": [ "data" ] }, "maxItems": 100, "description": "Artículos. Se calcula el total en el servidor; precio_unitario omitido usa el catálogo. Sin inventario_id, articulo y precio_unitario son obligatorios.", "minItems": 1 }, "action": { "type": "string", "description": "action.", "enum": [ "reintentar" ] }, "job_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "recurso": "contactos", "metodo": "POST", "items": [ { "data": { "nombre": "Ana Ejemplo", "telefono": "1112345678" } } ], "external_id": "importacion-123" } } } } } }, "/webhooks.php": { "get": { "operationId": "webhooks_get", "summary": "GET webhooks", "description": "Suscripciones por integración con firma HMAC. Su administración requiere rango 90 o superior. GET action=entregas&id=WEBHOOK_ID lista entregas; delivery_id consulta una entrega. Permiso: webhooks:read.", "tags": [ "webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } } }, "post": { "operationId": "webhooks_post", "summary": "POST webhooks", "description": "Suscripciones por integración con firma HMAC. Su administración requiere rango 90 o superior. GET action=entregas&id=WEBHOOK_ID lista entregas; delivery_id consulta una entrega. Permiso: webhooks:write.", "tags": [ "webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Destino HTTPS público con puerto 443. No admite credenciales, destinos internos ni redirecciones." }, "topics": { "type": "array", "items": { "type": "string", "enum": [ "contactos.created", "contactos.updated", "productos.created", "productos.updated", "stock.created", "stock.updated", "presupuestos.created", "presupuestos.updated", "pedidos.created", "pedidos.updated", "ventas.created", "ventas.updated", "cobros.created", "cobros.updated", "comprobantes.created", "comprobantes.updated", "devoluciones.created", "devoluciones.updated", "leads.created", "leads.updated" ] }, "minItems": 1, "description": "Lista de eventos exactos; exige permiso de lectura de los recursos correspondientes." }, "enabled": { "type": "boolean", "description": "enabled." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "reenviar" ] }, "delivery_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } } }, "example": { "url": "https://integracion.example.com/webhooks/plusdiario", "topics": [ "ventas.created", "stock.created" ], "enabled": true } } } } }, "patch": { "operationId": "webhooks_patch", "summary": "PATCH webhooks", "description": "Suscripciones por integración con firma HMAC. Su administración requiere rango 90 o superior. GET action=entregas&id=WEBHOOK_ID lista entregas; delivery_id consulta una entrega. Permiso: webhooks:write.", "tags": [ "webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador del recurso. Obligatorio para PATCH y transiciones." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor next_after de la página anterior." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cantidad por página: 1 a 100; predeterminado 50." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "estado", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "inventario_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "venta_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "delivery_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro o selector aplicable al recurso; ver su descripción." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 190, "pattern": "^[A-Za-z0-9_.:-]+$" }, "description": "Una clave estable por operación lógica. Reutilizarla con otro contenido devuelve 409." } ], "responses": { "200": { "description": "Consulta, actualización o repetición correcta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "201": { "description": "Registro creado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "202": { "description": "Trabajo aceptado; consultar su estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "400": { "description": "JSON inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "401": { "description": "Token inválido o revocado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "403": { "description": "Faltan permisos, módulo o usuario operativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "404": { "description": "Registro no encontrado o fuera de su visibilidad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "405": { "description": "Método no permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "409": { "description": "Conflicto de identidad, versión, stock o estado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "413": { "description": "Solicitud mayor a 2 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "415": { "description": "Se requiere application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "422": { "description": "Datos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "429": { "description": "Límite por minuto; respetar Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "500": { "description": "Fallo interno; consultar el resultado antes de reintentar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } }, "503": { "description": "Migración v2 pendiente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "Destino HTTPS público con puerto 443. No admite credenciales, destinos internos ni redirecciones." }, "topics": { "type": "array", "items": { "type": "string", "enum": [ "contactos.created", "contactos.updated", "productos.created", "productos.updated", "stock.created", "stock.updated", "presupuestos.created", "presupuestos.updated", "pedidos.created", "pedidos.updated", "ventas.created", "ventas.updated", "cobros.created", "cobros.updated", "comprobantes.created", "comprobantes.updated", "devoluciones.created", "devoluciones.updated", "leads.created", "leads.updated" ] }, "minItems": 1, "description": "Lista de eventos exactos; exige permiso de lectura de los recursos correspondientes." }, "enabled": { "type": "boolean", "description": "enabled." }, "version": { "type": "string", "description": "Valor devuelto al consultar el registro. Obligatorio al editar y al ejecutar transiciones de documentos; evita sobrescribir cambios concurrentes." }, "action": { "type": "string", "description": "action.", "enum": [ "reenviar" ] }, "delivery_id": { "oneOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ], "description": "Identificador obtenido desde esta API o catalogos.php." }, "external_id": { "type": "string", "maxLength": 190, "description": "Referencia estable del sistema externo. Única por empresa, token y recurso; repetirla devuelve el registro vinculado. Hasta 190 caracteres." } }, "required": [ "version" ] }, "example": { "version": "VERSION_DEVUELTA_POR_GET" } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Response": { "type": "object", "required": [ "status", "data", "error", "meta" ], "properties": { "status": { "type": "string", "enum": [ "ok", "error" ] }, "data": { "type": [ "object", "array", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": [ "object", "array" ] } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "2" }, "replayed": { "type": "boolean" } } } } } } } }