{ "openapi": "3.0.3", "info": { "title": "API de CopilotGestoria", "version": "2026-09-05", "description": "API para integrar CopilotGestoria en tu web, tu app o tu ERP.\n\nAutenticación: `Authorization: Bearer cg_live_.`.\nCliente sobre el que operas: cabecera `X-CG-Client`.\nLas escrituras (POST, PUT y PATCH) exigen `Idempotency-Key`; en las de webhooks es opcional y los DELETE no la usan.\nLas fechas van siempre en AAAA-MM-DD: `05/09/2026` se rechaza con un 422.\n\nLas respuestas llevan siempre la cabecera `Request-Id`: guárdala, es lo que permite localizar la llamada exacta si algo falla.\n\n**Paginación:** por cursor, nunca por número de página. `limit` vale 25 por defecto y admite de 1 a 100 (fuera de ese rango, 400 `limite_no_valido`); la respuesta trae `has_more` y `next_cursor`, que se usa tal cual (un cursor manipulado responde 400 `cursor_no_valido`).\n\n**Qué plan incluye cada operación:** cada una lleva `x-scope` (el permiso que exige; `a|b` significa que basta con uno de los dos, y una lista, que hacen falta todos) y `x-plan` (el plan más barato que lo incluye). Los dos salen del código y de la tabla de planes, no de un texto escrito aparte, así que no pueden contradecir a lo que hace el servidor.", "contact": { "name": "Soporte", "email": "info@copilotgestoria.com" } }, "servers": [ { "url": "https://copilot.asesores.click/api/public/v1", "description": "Producción" }, { "url": "https://sandbox.copilotgestoria.com/api/public/v1", "description": "Sandbox (datos ficticios; claves cg_sbx_)" } ], "components": { "securitySchemes": { "ClaveApi": { "type": "http", "scheme": "bearer", "description": "Clave de API creada por el gestor desde su panel." } }, "parameters": { "Cliente": { "name": "X-CG-Client", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Identificador del cliente final. Los que puedes usar salen en GET /clients." }, "Idempotencia": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "UUID distinto por operación. Repite el MISMO valor si reintentas." }, "IdempotenciaOpcional": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opcional en esta operación. Si la mandas, un reintento con el mismo valor devuelve la misma respuesta en vez de repetir la operación." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Valor de next_cursor de la página anterior, tal cual (es opaco). Un cursor que no tenga esa forma responde 400 `cursor_no_valido`." }, "Limite": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Elementos por página, de 1 a 100 (por defecto 25). Un valor fuera de rango o que no sea un número responde 400 `limite_no_valido`." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "Familia del error" }, "code": { "type": "string", "description": "Código estable; no cambia aunque cambie el texto" }, "message": { "type": "string" }, "param": { "type": "string", "description": "Campo concreto que falla" }, "doc_url": { "type": "string" }, "request_id": { "type": "string" }, "request_log_url": { "type": "string" } } } } }, "Lista": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } }, "security": [ { "ClaveApi": [] } ], "x-scopes": { "clientes:leer": "Ver los clientes autorizados, sus datos fiscales y sus actividades", "clientes:derechos": "Atender los derechos del cliente: exportar todo su histórico y borrar su rastro", "facturas:leer": "Consultar las facturas emitidas y recibidas", "facturas:escribir": "Emitir facturas nuevas en nombre del cliente", "documentos:leer": "Consultar los documentos digitalizados y sus datos extraídos", "documentos:escribir": "Enviar documentos a digitalizar, corregirlos y retirarlos", "gastos:leer": "Consultar los gastos y recibos sin factura", "gastos:escribir": "Registrar gastos y recibos (quedan en borrador hasta que el gestor confirme)", "contabilidad:leer": "Consultar asientos contables, plan contable y periodos", "bancos:leer": "Consultar cuentas, movimientos, importaciones de extractos y propuestas de conciliación", "nominas:leer": "Consultar las nóminas generadas", "modelos:leer": "Consultar los modelos fiscales y descargar sus ficheros", "modelos:escribir": "Generar modelos fiscales nuevos", "modelos:presentar": "Descargar el justificante de los modelos ya presentados ante la AEAT", "webhooks:gestionar": "Configurar avisos automáticos hacia un servidor propio", "facturas:cobros": "Registrar cobros de facturas emitidas y marcar vencimientos como cobrados", "directorio:leer": "Consultar los destinatarios y productos que el cliente usa al facturar", "directorio:escribir": "Dar de alta y modificar destinatarios y productos de facturación", "recurrentes:leer": "Consultar las facturas recurrentes y sus próximas emisiones", "recurrentes:escribir": "Crear, modificar, pausar, reanudar y cancelar facturas recurrentes", "gastos:confirmar": "Confirmar gastos en borrador (desde ese momento cuentan en el Modelo 130)", "irpf:leer": "Consultar los pagos con retención de IRPF", "irpf:escribir": "Registrar pagos con retención de IRPF (quedan en borrador)", "irpf:confirmar": "Confirmar pagos con retención de IRPF (desde ese momento cuentan en el Modelo 111)", "contabilidad:escribir": "Dar de alta cuentas en el plan contable del cliente", "bancos:escribir": "Importar extractos bancarios", "bancos:conciliar": "Proponer qué factura corresponde a un movimiento (la conciliación la confirma el gestor)", "calendario:leer": "Consultar el calendario de obligaciones fiscales del cliente", "comunicacion:leer": "Consultar las peticiones de documentos que hace el gestor", "clientes:escribir": "Dar de alta clientes, importarlos y corregir sus datos de contacto y su configuración de empresa", "actividades:escribir": "Dar de alta, modificar y eliminar las actividades económicas (epígrafes IAE) del cliente", "sepa:gestionar": "Registrar y revocar mandatos SEPA y descargar las remesas del cliente", "nominas:empleados": "Consultar y dar de alta trabajadores y sus contratos (no genera nóminas)", "webhooks:leer": "Consultar los webhooks y su historial de entregas", "sepa:leer": "Consultar mandatos y remesas SEPA y descargar sus ficheros", "trabajadores:leer": "Consultar los trabajadores y sus contratos", "consultas:leer": "Consultar las consultas que el cliente abre en su portal, con sus mensajes y adjuntos", "consultas:responder": "Contestar, abrir, cerrar y reabrir consultas del portal en nombre del despacho", "clientes:cuenta_domiciliacion": "Consultar y cambiar la cuenta en la que se domicilian los impuestos del cliente" }, "x-cg-webhooks": { "cabecera_firma": "CG-Signature", "tolerancia_segundos": 300, "eventos": { "invoice.emitted": "Se ha emitido una factura", "invoice.verifactu_sent": "La factura se ha enviado a la AEAT", "invoice.verifactu_accepted": "La AEAT ha aceptado la factura", "invoice.verifactu_accepted_with_errors": "La AEAT la ha registrado CON INCIDENCIAS (no es un éxito)", "invoice.verifactu_rejected": "La AEAT ha rechazado la factura", "invoice.verifactu_needs_review": "Estado desconocido tras el envío: lo revisa el gestor", "invoice.annulled": "Se ha anulado una factura", "invoice.payment_recorded": "Se ha registrado un cobro", "document.processed": "Se ha digitalizado un documento", "document.rejected": "Un documento no se ha incorporado (duplicado, no es una factura o no se ha podido leer)", "document.alert_detected": "Un documento tiene incidencias que revisar", "tax_model.generated": "Se ha generado un modelo fiscal", "consent.revoked": "Se ha retirado la autorización de un cliente para esta integración", "expense.confirmed": "Se ha confirmado un gasto (ya cuenta en el Modelo 130)", "irpf_payment.confirmed": "Se ha confirmado un pago con retención de IRPF (ya cuenta en el Modelo 111)", "recurring_invoice.emitted": "Una factura recurrente ha emitido su factura del periodo", "bank_transaction.matched": "Un movimiento bancario ha quedado conciliado con una factura", "credential.expiring": "La clave de la integración se va a apagar por falta de uso", "payroll.period_closed": "Se ha cerrado el periodo de nóminas de un cliente", "payroll.period_reopened": "Se ha reabierto un periodo de nóminas cerrado", "payroll.cancelled": "Se ha anulado una nómina (o se ha eliminado una nómina subida)", "employee.terminated": "Se ha dado de baja a un trabajador", "employee.updated": "Se han modificado los datos o el contrato de un trabajador", "client.tax_account_updated": "Ha cambiado la cuenta para domiciliar los impuestos de un cliente", "consultation.created": "Se ha abierto una consulta en el portal", "consultation.message_created": "Hay un mensaje nuevo en una consulta", "consultation.closed": "Se ha cerrado una consulta", "consultation.reopened": "Se ha reabierto una consulta", "invoice.payment_reversed": "Se ha deshecho un cobro registrado en una factura" }, "reglas_de_entrega": [ "Solo se entrega lo de los clientes que el gestor ha autorizado EN ESA CLAVE y que además han consentido el permiso de lectura del evento.", "Una clave revocada o caducada deja de recibir en el acto, y sus entregas pendientes se dan por agotadas.", "Un destino que agota sus reintentos se apaga solo y se avisa al gestor: para volver a recibir hay que verificarlo otra vez desde el panel.", "Puede llegar el mismo evento más de una vez y no se garantiza el orden: descarta duplicados por el `id` del evento." ] }, "paths": { "/activities": { "get": { "summary": "Actividades económicas (epígrafes IAE) del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "activa", "in": "query", "schema": { "type": "boolean" }, "description": "true o false." } ], "x-scope": "clientes:leer", "x-plan": "Starter" }, "post": { "summary": "Dar de alta una actividad económica", "responses": { "200": { "description": "La actividad ya existía y se ha reactivado (`reactivada: true`)" }, "201": { "description": "Actividad creada" }, "409": { "description": "Tope de actividades del plan, la actividad es de otra gestoría o ya existe (`actividad_duplicada`)" }, "422": { "description": "Campo no aceptado: formato, valor de catálogo o régimen incompatible con la forma jurídica del cliente" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Si ya existía esa actividad con esa fecha de alta —aunque estuviera dada de baja— se **reactiva** y responde 200 con `reactivada: true`, conservando sus facturas. Un alta nueva responde 201.\n\nEl régimen y la sección se comprueban contra la forma jurídica del cliente (ficha de empresa y NIF): un 422 `datos_invalidos` indica en `errors[].field` el campo y en `errors[].rule` la regla (`regimen_incompatible`, `iae_epigrafe`, `fecha_iso`, `before_or_equal`…).\n\nSi el cliente queda sin actividad principal, la respuesta lo avisa en `avisos` (`sin_actividad_principal`); no se bloquea el alta.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo_iae": { "type": "string", "description": "Epígrafe del IAE, 4 cifras con el grupo entre 011 y 999 (o B01 a B05 en actividades agrarias no sujetas al IAE). `0000` se admite como «pendiente de clasificar». Un número entero (8434) se acepta y se trata como texto." }, "descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "seccion_iae": { "type": "string", "description": "empresarial, profesional o artistica. `profesional` y `artistica` solo para personas físicas: una entidad tributa en la sección empresarial (422 `regimen_incompatible`)." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica. Una sociedad solo admite `no_aplica` (422 `regimen_incompatible`)." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica. `simplificado` y `recargo_equivalencia` no son de sociedades, ni `agricultura_ganaderia` de sociedades mercantiles o cooperativas (422 `regimen_incompatible`)." }, "fecha_alta": { "type": "string", "description": "Fecha de alta en el censo (modelo 036/037), AAAA-MM-DD; se admite también fecha y hora (ISO 8601), que se reduce al día en hora de España. No puede ser futura. Se da por confirmada: determina desde qué trimestre se presenta el Modelo 130 y su casilla 13." }, "fecha_baja": { "type": "string", "description": "AAAA-MM-DD, posterior a la fecha de alta." }, "es_principal": { "type": "boolean", "description": "Marcarla como principal desmarca la anterior." }, "retencion_irpf_tipo": { "type": "string", "description": "Retención de sus facturas: ninguna, general (15 %), inicio (7 %), agraria (2 %) o personalizada. Se aplica cuando el destinatario es empresario o profesional." }, "retencion_irpf_pct": { "type": "number", "description": "Obligatorio con `personalizada`: 0, 1, 2, 7, 15, 19 o 21." }, "se_acoge_ric": { "type": "boolean", "description": "Se acoge a la Reserva para Inversiones en Canarias (lleva contabilidad completa)." } }, "required": [ "codigo_iae", "descripcion", "seccion_iae", "regimen_irpf", "regimen_iva", "fecha_alta" ] } } } }, "x-scope": "actividades:escribir", "x-plan": "Enterprise" } }, "/activities/{id}": { "put": { "summary": "Modificar una actividad económica", "responses": { "409": { "description": "Ya existe otra actividad con ese epígrafe y esa fecha de alta" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Solo los campos que mandes. Una fecha de baja tiene que ser posterior a la de alta, también a la ya guardada (422).\n\n**Dar de baja una actividad:** basta con `fecha_baja`; si esa fecha ya ha llegado, la actividad queda inactiva. `activa: true` la reactiva y quita la baja. También admite `PATCH`.\n\nCambiar el epígrafe o la fecha de alta a los de otra actividad del cliente —aunque esté dada de baja— responde 409 `actividad_duplicada`: reactívala en vez de duplicarla.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo_iae": { "type": "string", "description": "Epígrafe del IAE, 4 cifras con el grupo entre 011 y 999 (o B01 a B05 en actividades agrarias no sujetas al IAE). `0000` se admite como «pendiente de clasificar». Un número entero (8434) se acepta y se trata como texto." }, "descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "seccion_iae": { "type": "string", "description": "empresarial, profesional o artistica. `profesional` y `artistica` solo para personas físicas: una entidad tributa en la sección empresarial (422 `regimen_incompatible`)." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica. Una sociedad solo admite `no_aplica` (422 `regimen_incompatible`)." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica. `simplificado` y `recargo_equivalencia` no son de sociedades, ni `agricultura_ganaderia` de sociedades mercantiles o cooperativas (422 `regimen_incompatible`)." }, "fecha_alta": { "type": "string", "description": "Fecha de alta en el censo (modelo 036/037), AAAA-MM-DD; se admite también fecha y hora (ISO 8601), que se reduce al día en hora de España. No puede ser futura. Se da por confirmada: determina desde qué trimestre se presenta el Modelo 130 y su casilla 13." }, "fecha_baja": { "type": "string", "description": "AAAA-MM-DD, posterior a la fecha de alta." }, "es_principal": { "type": "boolean", "description": "Marcarla como principal desmarca la anterior." }, "retencion_irpf_tipo": { "type": "string", "description": "Retención de sus facturas: ninguna, general (15 %), inicio (7 %), agraria (2 %) o personalizada. Se aplica cuando el destinatario es empresario o profesional." }, "retencion_irpf_pct": { "type": "number", "description": "Obligatorio con `personalizada`: 0, 1, 2, 7, 15, 19 o 21." }, "se_acoge_ric": { "type": "boolean", "description": "Se acoge a la Reserva para Inversiones en Canarias (lleva contabilidad completa)." }, "activa": { "type": "boolean", "description": "Dar de baja o reactivar la actividad." } } } } } }, "x-scope": "actividades:escribir", "x-plan": "Enterprise" }, "patch": { "summary": "Modificar una actividad económica (igual que PUT)", "responses": { "409": { "description": "Ya existe otra actividad con ese epígrafe y esa fecha de alta" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Mismo efecto que `PUT /activities/{id}`: solo cambian los campos que mandes. Para darla de baja basta con `fecha_baja`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo_iae": { "type": "string", "description": "Epígrafe del IAE, 4 cifras con el grupo entre 011 y 999 (o B01 a B05 en actividades agrarias no sujetas al IAE). `0000` se admite como «pendiente de clasificar». Un número entero (8434) se acepta y se trata como texto." }, "descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "seccion_iae": { "type": "string", "description": "empresarial, profesional o artistica. `profesional` y `artistica` solo para personas físicas: una entidad tributa en la sección empresarial (422 `regimen_incompatible`)." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica. Una sociedad solo admite `no_aplica` (422 `regimen_incompatible`)." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica. `simplificado` y `recargo_equivalencia` no son de sociedades, ni `agricultura_ganaderia` de sociedades mercantiles o cooperativas (422 `regimen_incompatible`)." }, "fecha_alta": { "type": "string", "description": "Fecha de alta en el censo (modelo 036/037), AAAA-MM-DD; se admite también fecha y hora (ISO 8601), que se reduce al día en hora de España. No puede ser futura. Se da por confirmada: determina desde qué trimestre se presenta el Modelo 130 y su casilla 13." }, "fecha_baja": { "type": "string", "description": "AAAA-MM-DD, posterior a la fecha de alta." }, "es_principal": { "type": "boolean", "description": "Marcarla como principal desmarca la anterior." }, "retencion_irpf_tipo": { "type": "string", "description": "Retención de sus facturas: ninguna, general (15 %), inicio (7 %), agraria (2 %) o personalizada. Se aplica cuando el destinatario es empresario o profesional." }, "retencion_irpf_pct": { "type": "number", "description": "Obligatorio con `personalizada`: 0, 1, 2, 7, 15, 19 o 21." }, "se_acoge_ric": { "type": "boolean", "description": "Se acoge a la Reserva para Inversiones en Canarias (lleva contabilidad completa)." }, "activa": { "type": "boolean", "description": "Dar de baja o reactivar la actividad." } } } } } }, "x-scope": "actividades:escribir", "x-plan": "Enterprise" }, "delete": { "summary": "Dar de baja una actividad económica", "responses": { "409": { "description": "La actividad tiene operaciones asociadas" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "No se puede eliminar una actividad con facturas, pagos, modelos o asientos: quedarían «sin actividad» y el Modelo 130 por actividad dejaría de cuadrar (409 `actividad_con_operaciones`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "actividades:escribir", "x-plan": "Enterprise" } }, "/bank-accounts": { "get": { "summary": "Cuentas bancarias (IBAN enmascarado)", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "iban", "in": "query", "schema": { "type": "string" }, "description": "IBAN completo; se ignoran los espacios." }, { "name": "sincronizada", "in": "query", "schema": { "type": "boolean" }, "description": "true para las cuentas con sincronización bancaria activada." } ], "x-scope": "bancos:leer", "x-plan": "Professional" } }, "/bank-imports/{id}": { "get": { "summary": "Cómo va una importación de extracto", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Estado, movimientos importados, repetidos (`duplicados`, ya estaban de una importación anterior) y con error, y conciliaciones propuestas.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "bancos:leer", "x-plan": "Professional" } }, "/bank-transactions": { "get": { "summary": "Movimientos bancarios", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Del más reciente al más antiguo. `fecha_desde`/`fecha_hasta` filtran por la fecha del movimiento (un rango al revés responde 400 `rango_invertido`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "fecha_desde", "in": "query", "schema": { "type": "string" }, "description": "Fecha del movimiento bancario, en AAAA-MM-DD." }, { "name": "fecha_hasta", "in": "query", "schema": { "type": "string" }, "description": "Fecha del movimiento bancario, en AAAA-MM-DD." }, { "name": "match_status", "in": "query", "schema": { "type": "string" }, "description": "unmatched, auto_matched, manual_matched, matched o ignored." } ], "x-scope": "bancos:leer", "x-plan": "Professional" } }, "/bank-transactions/import": { "post": { "summary": "Importar un extracto bancario", "responses": { "202": { "description": "Aceptado; consulta el trabajo o `GET /bank-imports/{id}`" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Multipart con el fichero: CSV, Norma 43, OFX o XLSX. Responde **202** con un trabajo.\n\nLa cuenta se da de alta sola con el primer extracto, por su IBAN, igual que en el panel.\n\n**Conciliación automática:** `auto_match` vale `false` por defecto. Si lo pides, solo se aplica cuando la clave tiene `bancos:conciliar`, el plan lo incluye, el cliente lo ha autorizado y la clave es de producción; la respuesta dice en `conciliacion_automatica` si se aplicó y, si la pediste y no, lo explica en `aviso`. Sin ella, los emparejamientos quedan como propuestas para el gestor.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV, TXT, TSV, Norma 43 (N43, C43, CSB, AEB), OFX, QFX, PDF, XLSX o XLS. Máximo 10 MB." }, "bank_name": { "type": "string", "description": "Hasta 50 caracteres." }, "iban": { "type": "string", "description": "IBAN español (ES y 22 cifras). Da de alta la cuenta con el primer extracto." }, "account_name": { "type": "string", "description": "Hasta 100 caracteres." }, "auto_match": { "type": "boolean", "description": "Confirmar solos los emparejamientos exactos. Por defecto false, y solo se aplica si la clave tiene `bancos:conciliar`, el plan lo incluye, el cliente lo ha autorizado y la clave es de producción. Si no, la respuesta lo avisa en `aviso`." } }, "required": [ "file" ] } } } }, "x-scope": "bancos:escribir", "x-plan": "Professional" } }, "/bank-transactions/{id}/match-proposals": { "post": { "summary": "Proponer la conciliación de un movimiento con una factura", "responses": { "201": { "description": "Propuesta creada" }, "409": { "description": "Ya conciliado o propuesta rechazada antes" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "🚨 **Propone, no concilia.** Crea una propuesta en estado `suggested` que el gestor confirma desde su panel; la API nunca da por cobrada una factura ni genera el asiento.\n\nRepetir la misma propuesta no la duplica (200 `ya_existia`). Si el movimiento ya está conciliado o la propuesta se rechazó, responde 409.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "description": "Factura de este mismo cliente con la que casar el movimiento." } }, "required": [ "invoice_id" ] } } } }, "x-scope": "bancos:conciliar", "x-plan": "Professional" } }, "/bank-transactions/{id}/matches": { "get": { "summary": "Conciliaciones propuestas para un movimiento", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "bancos:leer", "x-plan": "Professional" } }, "/chart-of-accounts": { "get": { "summary": "Plan contable del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "tipo", "in": "query", "schema": { "type": "string" }, "description": "proveedor, acreedor, cliente, gasto, ingreso, activo, pasivo, iva_soportado, iva_repercutido, irpf u otro." } ], "x-scope": "contabilidad:leer", "x-plan": "Professional" }, "post": { "summary": "Dar de alta una subcuenta", "responses": { "201": { "description": "Cuenta creada" }, "200": { "description": "La cuenta ya existía (`ya_existia: true`)" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Lo único que se escribe en contabilidad por API. **Los asientos no**: es donde un error se propaga a los modelos fiscales y de ahí a una declaración.\n\nLa cuenta se valida contra el PGC; si no indicas subcuenta, se reserva la siguiente libre. Responde **201** con la cuenta nueva, o **200** con `ya_existia: true` si ya estaba.\n\nSi la cuenta tiene una longitud distinta de la del plan del cliente se crea igual y se avisa en `avisos` (`longitud_distinta_del_plan`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cuenta": { "type": "string", "description": "Subcuenta completa, hasta 20 caracteres. Obligatoria si no mandas `prefijo`." }, "prefijo": { "type": "string", "description": "Cuenta del PGC de la que colgar la subcuenta (hasta 4 cifras, empieza por 1 a 9). Obligatorio si no mandas `cuenta`; se reserva la siguiente libre." }, "descripcion": { "type": "string", "description": "Hasta 100 caracteres." }, "tipo": { "type": "string", "description": "proveedor, acreedor, cliente, gasto, ingreso, activo, pasivo, iva_soportado, iva_repercutido, irpf u otro. Si no lo mandas, se deduce de la cuenta." } }, "required": [ "descripcion" ] } } } }, "x-scope": "contabilidad:escribir", "x-plan": "Professional" } }, "/clients": { "get": { "summary": "Clientes que esta clave puede tocar", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Devuelve SOLO los que el gestor ha autorizado. Si no ha marcado ninguno, la lista viene vacía: no es un error.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "nif", "in": "query", "schema": { "type": "string" }, "description": "NIF, con o sin el prefijo ES: se normaliza antes de buscar." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Búsqueda por nombre. Mínimo dos caracteres." }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "`actividades` para traer las actividades económicas de cada cliente en el listado." } ], "x-scope": "clientes:leer", "x-plan": "Starter" }, "post": { "summary": "Dar de alta un cliente en la cartera de la gestoría", "responses": { "201": { "description": "Cliente creado" }, "409": { "description": "Correo o NIF ya en uso, o tope de clientes o de actividades del plan" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Alta completa:** con `configuracion_empresa` y `actividades`, el cliente queda listo para trabajar. Todo se valida antes de crear nada: o queda completo o no se crea.\n\n**Autorización:** con la opción «Autorizar en esta clave los clientes que dé de alta» activada, el cliente queda autorizado con los permisos de la clave, hasta su máximo de clientes (`autorizado_en_esta_clave`). Si no, `siguiente_paso` indica el motivo.\n\nComo el alta del panel: NIF sin duplicar en la cartera, contrato de encargo de tratamiento y correo de bienvenida con la contraseña temporal (`enviar_bienvenida: false` lo evita). Sin `actividades`, se crea una actividad provisional con epígrafe `0000`.\n\n**Autónomos:** `regimen_fiscal` y `pgc_tipo` no hacen falta (son del Impuesto sobre Sociedades y de las cuentas anuales). Conviene enviar `configuracion_empresa.tipo_sociedad: autonomo`: sin él, la ficha queda como sociedad limitada (`sl`).\n\nConflictos: `email_en_uso`, `nif_ya_en_cartera`, `limite_clientes`, `limite_actividades`.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre, hasta 255 caracteres." }, "email": { "type": "string", "description": "Correo del cliente: es su acceso al portal y no puede estar ya en uso." }, "vat": { "type": "string", "description": "NIF o CIF español. Con `pais_residencia_fiscal` de otro país, también el identificador fiscal de ese país: se guarda con su prefijo (DE…, GB…; Grecia, EL…)." }, "pais_residencia_fiscal": { "type": "string", "description": "Código ISO de dos letras del país de residencia fiscal. Sin él, o con ES, el cliente es español." }, "tipo_persona": { "type": "string", "description": "fisica o juridica. Obligatorio cuando `vat` es el identificador de otro país." }, "nif_pais_residencia": { "type": "string", "description": "Identificador fiscal en el país de residencia cuando `vat` lleva un NIF español. Hasta 20 caracteres." }, "establecimiento_permanente": { "type": "boolean", "description": "Si el cliente no residente tiene establecimiento permanente en España." }, "domicilio_exterior": { "type": "string", "description": "Dirección en el país de residencia, hasta 255 caracteres." }, "codigo_postal_exterior": { "type": "string", "description": "Código postal en el país de residencia, hasta 20 caracteres." }, "localidad_exterior": { "type": "string", "description": "Hasta 100 caracteres." }, "region_exterior": { "type": "string", "description": "Hasta 100 caracteres." }, "phone_number": { "type": "string", "description": "Hasta 20 caracteres." }, "company": { "type": "string", "description": "Razón social, hasta 255 caracteres." }, "address": { "type": "string", "description": "Domicilio en España, hasta 255 caracteres." }, "postal_code": { "type": "string", "description": "Código postal español, hasta 10 caracteres." }, "comunidad_autonoma_aeat": { "type": "string", "description": "Código de comunidad autónoma de la AEAT, de 01 a 20." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica. Una sociedad solo admite no_aplica." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica." }, "enviar_bienvenida": { "type": "boolean", "description": "Por defecto true: el cliente recibe por correo su contraseña temporal." }, "configuracion_empresa": { "type": "object", "description": "Configuración de empresa con los mismos campos que `PATCH /clients/{id}/company-config`. Se valida antes de crear nada: si un campo no es válido, no se da de alta el cliente." }, "actividades": { "type": "array", "items": { "type": "object" }, "description": "De 1 a 50 actividades con los mismos campos que `POST /activities` (codigo_iae, descripcion, seccion_iae, regimen_irpf, regimen_iva, fecha_alta, fecha_baja, es_principal, retencion_irpf_tipo, retencion_irpf_pct, se_acoge_ric). Una sola principal; si no se marca ninguna, la primera. Con ellas no se crea la actividad provisional `0000`, y `regimen_irpf`/`regimen_iva` van dentro de cada actividad." } }, "required": [ "name", "email", "vat" ] } } } }, "x-scope": "clientes:escribir", "x-plan": "Enterprise" } }, "/clients/import": { "post": { "summary": "Importar un CSV de clientes", "responses": { "202": { "description": "Aceptado; consulta el trabajo en `consultar_en`" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Multipart con el campo `csv`. Columnas mínimas: `nombre`, `email`, `nif_cif`.\n\nResponde **202** con un trabajo: cada fila crea un usuario y manda un correo, y eso no cabe en una petición HTTP. El resultado dice cuántos entraron y por qué se saltó cada fila.\n\nSi la clave autoriza sus altas, el resultado indica cuántos clientes han quedado autorizados (`autorizados_en_esta_clave`).", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "format": "binary", "description": "CSV de hasta 5 MB con, al menos, las columnas nombre, email y nif_cif." } }, "required": [ "csv" ] } } } }, "x-scope": "clientes:escribir", "x-plan": "Enterprise" } }, "/clients/{id}": { "get": { "summary": "Ficha de un cliente con sus actividades económicas", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:leer", "x-plan": "Starter" }, "patch": { "summary": "Corregir los datos de contacto y el acceso al portal de un cliente", "responses": { "409": { "description": "Se ha intentado cambiar el NIF o el correo" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Solo los campos que mandes: `name`, `phone_number`, `company`, `address`, `postal_code` y `comunidad_autonoma_aeat`.\n\n**Acceso al portal:** `perfil_portal` (un perfil de `GET /portal-profiles`, o null para la configuración general), `portal_abierto` (false cierra el portal y la app, también para «Recuperar contraseña», y cierra sus sesiones) y `limite_facturas_portal_mes` (máximo de facturas que el cliente emite al mes desde su portal o la app; null = sin límite, 0 = ninguna).\n\n**Cuenta de domiciliación de impuestos:** `iban_domiciliacion` (null la quita) y `titular_domiciliacion`. Exigen además el permiso `clientes:cuenta_domiciliacion` (403 `scope_insuficiente` sin él). IBAN de un país SEPA: si no, 422 `iban_invalido` o `iban_no_sepa`. Lo mismo hace `PATCH /clients/{id}/tax-account`.\n\n🚨 **El NIF y el correo no se cambian por aquí** (409 `nif_no_modificable` / `email_no_modificable`). Del NIF cuelga la pertenencia de cada factura —en los documentos no hay cliente, hay NIF—, y el correo es el acceso del cliente a su portal. Los dos se corrigen desde el panel.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Hasta 255 caracteres." }, "phone_number": { "type": "string", "description": "Hasta 20 caracteres." }, "company": { "type": "string", "description": "Hasta 255 caracteres." }, "address": { "type": "string", "description": "Hasta 255 caracteres." }, "postal_code": { "type": "string", "description": "Hasta 10 caracteres." }, "comunidad_autonoma_aeat": { "type": "string", "description": "Código de la AEAT, de 01 a 20." }, "perfil_portal": { "type": "integer", "description": "Perfil de acceso al portal (GET /portal-profiles). null = la configuración general." }, "portal_abierto": { "type": "boolean", "description": "false cierra el portal y la app del cliente; true lo vuelve a abrir." }, "limite_facturas_portal_mes": { "type": "integer", "description": "Máximo de facturas al mes desde el portal o la app. null = sin límite, 0 = ninguna." }, "iban_domiciliacion": { "type": "string", "description": "IBAN donde se domicilian los impuestos (país SEPA). null la quita. Exige el permiso clientes:cuenta_domiciliacion." }, "titular_domiciliacion": { "type": "string", "description": "Titular de esa cuenta, hasta 150 caracteres. Exige el permiso clientes:cuenta_domiciliacion." } } } } } }, "x-scope": "clientes:escribir", "x-plan": "Enterprise" } }, "/clients/{id}/activity": { "get": { "summary": "Qué ha hecho esta integración con los datos de un cliente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El derecho de acceso del art. 15 del RGPD: las 500 últimas llamadas de esta integración sobre ese cliente —las de esta clave y las de las claves de las que se rotó—, con su permiso usado y su resultado, más la fecha en que se otorgó el consentimiento. Lo que hagan otras integraciones de la gestoría no sale aquí.\n\nExige consentimiento vigente, igual que la ficha.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:leer", "x-plan": "Starter" } }, "/clients/{id}/company-config": { "get": { "summary": "Configuración de empresa de un cliente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Forma jurídica, régimen fiscal, territorio, régimen de IVA, domicilio fiscal, personas y datos laborales. Sin configuración guardada: `existe: false` y valores a `null`.\n\n`confirmaciones` indica si están confirmados la forma jurídica, el territorio fiscal y el régimen de IVA. Sin confirmar, el valor es el de la ficha por defecto.\n\nAdministradores y titulares reales solo se devuelven si la clave y la autorización del cliente incluyen «Dar de alta clientes, importarlos y corregir sus datos de contacto y su configuración de empresa»; si no, `personas_omitidas: true`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:leer", "x-plan": "Starter" }, "patch": { "summary": "Completar o corregir la configuración de empresa de un cliente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Solo cambia lo enviado.** Un campo no enviado no se toca; vacío o `null` lo borra si admite estar vacío. Un campo desconocido se rechaza (422, regla `campo_desconocido`).\n\n`tipo_sociedad`, `territorio_fiscal` y cualquier campo del régimen de IVA quedan **confirmados** al enviarlos, como desde el panel. Un régimen general se confirma con `recc: false`.\n\nMismos criterios que la ficha del panel: fecha del criterio de caja, territorio foral incompatible con Canarias, Ceuta, Melilla y Andorra, preguntas de control con régimen de nueva creación y forma jurídica compatible con el NIF y las actividades. `administradores` y `titulares_reales` se sustituyen enteras.\n\nLongitud del plan contable, cuentas por defecto y códigos de enlace con otros programas: solo desde el panel.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cnae_principal": { "type": "string", "description": "Clase del CNAE de la actividad principal, 4 cifras (se admite con punto: 62.01; se guarda 6201). Recomendado el CNAE-2025, que es el que exigen el depósito de cuentas y los modelos de la AEAT desde 2026; una declaración del ejercicio 2025 lo espera en la versión de 2009. Hay uno por cliente; cada actividad lleva su epígrafe del IAE." }, "cnae_descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "tipo_sociedad": { "type": "string", "description": "Forma jurídica: sl, sa, slp, slne, slu, coop, cb, sc, autonomo, otra. Al enviarla queda confirmada." }, "forma_juridica": { "type": "string", "description": "Texto libre, hasta 100 caracteres." }, "fecha_constitucion": { "type": "string", "description": "AAAA-MM-DD." }, "regimen_fiscal": { "type": "string", "description": "Régimen del Impuesto sobre Sociedades: general, erd, microempresa, nueva_creacion, startup, cooperativa, socimi, sin_fines_lucrativos, inversion_colectiva, fondo_pensiones, entidad_credito, zec, capital_riesgo, naviera_tonelaje, otro. Con `nueva_creacion`, las tres preguntas de control son obligatorias." }, "pgc_tipo": { "type": "string", "description": "Modelo de cuentas anuales: normal, mixto, abreviado, pyme, microempresa." }, "territorio_fiscal": { "type": "string", "description": "PENINSULA_BALEARES, CANARIAS, CEUTA, MELILLA, ANDORRA. Al enviarlo queda confirmado." }, "territorio_foral": { "type": "string", "description": "no, bizkaia, gipuzkoa, araba o navarra. Incompatible con Canarias, Ceuta, Melilla y Andorra." }, "periodicidad_iva": { "type": "string", "description": "trimestral o mensual. Es la periodicidad con que se cierran en contabilidad las cuentas de IVA (472/477); no cambia la del Modelo 303." }, "ejercicio_inicio_mes": { "type": "integer", "description": "Mes de inicio del ejercicio, 1 a 12." }, "ejercicio_fin_mes": { "type": "integer", "description": "Mes de cierre del ejercicio, 1 a 12." }, "nc_grupo_art42": { "type": "boolean", "description": "Pregunta de control del art. 29.1 LIS: ¿forma parte de un grupo en los términos del art. 42 del Código de Comercio?" }, "nc_actividad_vinculadas_transmitida": { "type": "boolean", "description": "Pregunta de control del art. 29.1.a LIS: ¿la actividad la realizaba antes una persona o entidad vinculada y se ha transmitido a la sociedad?" }, "nc_socio_mayoritario_actividad_previa": { "type": "boolean", "description": "Pregunta de control del art. 29.1.b LIS: ¿una persona física con más del 50 % del capital ejerció la misma actividad durante el año anterior a la constitución?" }, "fecha_inicio_actividad": { "type": "string", "description": "AAAA-MM-DD." }, "confirmar_sin_quince": { "type": "boolean", "description": "Con régimen `nueva_creacion` y un «sí» en las preguntas de control, confirma guardarlo sabiendo que excluye el 15 %. No se guarda." }, "recc": { "type": "boolean", "description": "Criterio de caja. Con `true`, `recc_desde` es obligatoria (desde 2014-01-01)." }, "recc_desde": { "type": "string", "description": "AAAA-MM-DD." }, "prorrata_tipo": { "type": "string", "description": "no, general o especial." }, "prorrata_pct": { "type": "number", "description": "Porcentaje de prorrata, 0 a 100 (solo con prorrata general)." }, "redeme": { "type": "boolean", "description": "Registro de devolución mensual." }, "grupo_entidades_iva": { "type": "boolean", "description": "Grupo de entidades del IVA (art. 163 quinquies LIVA)." }, "sii": { "type": "boolean", "description": "Suministro Inmediato de Información." }, "sii_desde": { "type": "string", "description": "AAAA-MM-DD." }, "sii_modalidad": { "type": "string", "description": "obligatorio o voluntario." }, "libros_atc": { "type": "boolean", "description": "Libros registro del IGIC en la Sede de la ATC." }, "repe": { "type": "boolean", "description": "Régimen especial del pequeño empresario del IGIC (solo personas físicas)." }, "repe_desde": { "type": "string", "description": "AAAA-MM-DD." }, "minorista_igic": { "type": "boolean", "description": "Comerciante minorista del IGIC." }, "minorista_igic_desde": { "type": "string", "description": "AAAA-MM-DD." }, "domicilio": { "type": "string", "description": "Domicilio fiscal, hasta 100 caracteres." }, "codigo_postal": { "type": "string", "description": "Hasta 5 caracteres." }, "provincia": { "type": "string", "description": "Código INE de dos cifras (01 a 52), por ejemplo 04 para Almería. «4» o «Almería» no se admiten." }, "municipio": { "type": "string", "description": "Código INE del municipio, hasta 5 caracteres." }, "administradores": { "type": "array", "items": { "type": "object" }, "description": "Lista COMPLETA de administradores, cada uno con nif, nombre, cargo y fecha_nombramiento. Sustituye a la guardada; `[]` la vacía." }, "titulares_reales": { "type": "array", "items": { "type": "object" }, "description": "Lista COMPLETA de titulares reales, cada uno con nif, nombre, porcentaje, tipo_control, fecha_nacimiento, nacionalidad, pais_residencia, pais_documento (códigos ISO de dos letras), tipo_documento (1 a 6), porcentaje_indirecto y via (capital_y_voto, capital, voto o asimilado). Sustituye a la guardada; `[]` la vacía." }, "ccc": { "type": "string", "description": "Código de cuenta de cotización de la Seguridad Social (11 o 15 cifras)." }, "autorizado_red": { "type": "string", "description": "Número de autorización del Sistema RED, hasta 50 caracteres." } } } } } }, "x-scope": "clientes:escribir", "x-plan": "Enterprise" } }, "/clients/{id}/consultas": { "get": { "summary": "Consultas que el cliente ha abierto en su portal", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Cada una con su `asunto` (primera línea del mensaje), `estado` (`abierta` = sin respuesta del despacho, `respondida` = lo último es del despacho, `cerrada`), `origen` (cliente, chat o despacho) y `actualizada_at` (último mensaje).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "estado", "in": "query", "schema": { "type": "string" }, "description": "abierta (sin respuesta del despacho), respondida o cerrada." }, { "name": "actualizada_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo las que tienen algún cambio o mensaje desde esa fecha (AAAA-MM-DD o ISO 8601)." } ], "x-scope": "consultas:leer", "x-plan": "Professional" }, "post": { "summary": "Abrir una consulta desde el despacho", "responses": { "201": { "description": "Consulta abierta" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El cliente la ve en «Mis consultas» con el despacho como autor del primer mensaje, y recibe el aviso por correo.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "texto": { "type": "string", "description": "Primer mensaje, hasta 5000 caracteres. Su primera línea es el asunto." }, "autor_nombre": { "type": "string", "description": "Nombre del asesor que la abre. Hasta 120 caracteres." }, "prioridad": { "type": "string", "description": "baja, media (por defecto) o alta." }, "adjuntos": { "type": "array", "items": { "type": "object" }, "description": "Ficheros (multipart/form-data, `adjuntos[]`)." } }, "required": [ "texto", "autor_nombre" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "texto": { "type": "string", "description": "Primer mensaje, hasta 5000 caracteres. Su primera línea es el asunto." }, "autor_nombre": { "type": "string", "description": "Nombre del asesor que la abre. Hasta 120 caracteres." }, "prioridad": { "type": "string", "description": "baja, media (por defecto) o alta." }, "adjuntos": { "type": "array", "items": { "type": "object" }, "description": "Ficheros (multipart/form-data, `adjuntos[]`)." } }, "required": [ "texto", "autor_nombre" ] } } } }, "x-scope": "consultas:responder", "x-plan": "Professional" } }, "/clients/{id}/data": { "delete": { "summary": "Supresión: retirar a este cliente de tu integración (RGPD art. 17)", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Revoca el consentimiento, te desautoriza sobre ese cliente y **anonimiza tu rastro de llamadas**: se retiran la IP y el navegador. Alcanza a toda la integración: también a la clave de la que se rotó, aunque siga en su periodo de solape.\n\nLas filas del registro se conservan, y no es un olvido: son la prueba de qué leyó tu integración y cuándo, que el art. 17.3.e) del RGPD deja fuera del derecho de supresión por ser necesaria para la defensa de reclamaciones.\n\n**No borra sus facturas, asientos ni modelos**: son documentación contable con plazos de conservación propios, y esa decisión es del gestor.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:derechos", "x-plan": "Professional" } }, "/clients/{id}/export": { "get": { "summary": "Portabilidad: todos los datos del cliente en un fichero (RGPD art. 20)", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Ficha, documentos, asientos y modelos fiscales, con la misma forma siempre. Tope de 5.000 documentos y asientos.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:derechos", "x-plan": "Professional" } }, "/clients/{id}/inbox": { "post": { "summary": "Crear la dirección de correo de facturas del cliente", "responses": { "201": { "description": "Buzón creado" }, "200": { "description": "El buzón ya existía (o se ha reactivado)" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Crea el buzón o reactiva el que estaba en pausa. Cuenta para el máximo de buzones del plan (409 `limite_buzones`); uno que ya está activo no cambia.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "clientes:escribir", "x-plan": "Enterprise" }, "get": { "summary": "Dirección de correo de facturas del cliente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "La dirección a la que el cliente (o sus proveedores) reenvía las facturas para que entren solas. `direccion` es null si aún no tiene buzón.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "clientes:leer", "x-plan": "Starter" } }, "/clients/{id}/tax-account": { "patch": { "summary": "Cuenta para domiciliar los impuestos del cliente", "responses": { "200": { "description": "Cuenta guardada (enmascarada)" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "La misma cuenta que el gestor pone en la ficha del cliente. `null` la borra. Errores con código: 422 `iban_invalido` (formato o dígito de control) e `iban_no_sepa` (fuera de la zona SEPA).\n\nPermiso propio, `clientes:cuenta_domiciliacion`. `GET /clients/{id}` la devuelve enmascarada (últimos cuatro), con su titular y la fecha del último cambio, cuando la clave tiene ese permiso. Cualquier cambio, también desde el panel, avisa con `client.tax_account_updated`.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "iban_domiciliacion": { "type": "string", "description": "IBAN de la cuenta, de la zona SEPA. null la borra." }, "titular_domiciliacion": { "type": "string", "description": "Titular de la cuenta, si no es el propio cliente. Hasta 150 caracteres." } }, "required": [ "iban_domiciliacion" ] } } } }, "x-scope": "clientes:cuenta_domiciliacion", "x-plan": "Professional" } }, "/clients/{id}/welcome": { "post": { "summary": "Reenviar el correo de bienvenida al portal", "responses": { "200": { "description": "Correo enviado (`enviado_a` dice a qué dirección)" }, "409": { "description": "Portal cerrado, cliente sin correo, cliente de ejemplo o demasiados reenvíos seguidos" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El mismo reenvío que el botón de la ficha del cliente en el panel.\n\n🚨 **Genera una contraseña nueva**: la anterior deja de valer. Con el portal cerrado, o un cliente sin correo, responde 409 sin enviar nada.", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "clientes:escribir", "x-plan": "Enterprise" } }, "/consultas/{id}": { "patch": { "summary": "Cerrar, reabrir o marcar como leída una consulta", "responses": { "200": { "description": "Consulta actualizada" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "estado": { "type": "string", "description": "cerrada o abierta." }, "leida": { "type": "boolean", "description": "true marca como leídos los mensajes del cliente." } } } } } }, "x-scope": "consultas:responder", "x-plan": "Professional" } }, "/consultas/{id}/mensajes": { "get": { "summary": "Hilo de una consulta", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El mensaje inicial (`id = inicial`) y el resto, cada uno con `autor` (cliente o despacho), `autor_nombre`, `texto`, `fecha`, `leido` (si la otra parte ya lo ha abierto) y sus `adjuntos`, con la URL para descargarlos.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "consultas:leer", "x-plan": "Professional" }, "post": { "summary": "Contestar una consulta como el despacho", "responses": { "201": { "description": "Respuesta guardada (`cliente_avisado` dice si salió el correo)" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El cliente ve la respuesta firmada con `autor_nombre` y recibe el mismo aviso por correo que si se contesta desde el panel. Si la consulta estaba cerrada, se reabre.\n\nCon adjuntos, en `multipart/form-data` (`adjuntos[]`, hasta 5 ficheros).", "parameters": [ { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "texto": { "type": "string", "description": "Texto de la respuesta, hasta 5000 caracteres." }, "autor_nombre": { "type": "string", "description": "Nombre con el que el cliente verá firmada la respuesta (el asesor). Hasta 120 caracteres." }, "adjuntos": { "type": "array", "items": { "type": "object" }, "description": "Ficheros (multipart/form-data, `adjuntos[]`): PDF, imagen, hoja de cálculo, documento o ZIP, hasta 10 MB cada uno." } }, "required": [ "texto", "autor_nombre" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "texto": { "type": "string", "description": "Texto de la respuesta, hasta 5000 caracteres." }, "autor_nombre": { "type": "string", "description": "Nombre con el que el cliente verá firmada la respuesta (el asesor). Hasta 120 caracteres." }, "adjuntos": { "type": "array", "items": { "type": "object" }, "description": "Ficheros (multipart/form-data, `adjuntos[]`): PDF, imagen, hoja de cálculo, documento o ZIP, hasta 10 MB cada uno." } }, "required": [ "texto", "autor_nombre" ] } } } }, "x-scope": "consultas:responder", "x-plan": "Professional" } }, "/consultas/{id}/mensajes/{m}/adjuntos/{a}": { "get": { "summary": "Descargar un adjunto de una consulta", "responses": { "200": { "description": "El fichero" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "m", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "a", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "consultas:leer", "x-plan": "Professional" } }, "/deadlines": { "get": { "summary": "Plazos fiscales que le aplican a este cliente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Filtrado por las obligaciones reales del cliente: no salen los plazos de modelos que no presenta.\n\n`status` vale pending, draft, submitted, overdue o **pending_confirmation**: un modelo que solo es obligatorio si hubo operaciones (`obligacion: segun_operaciones`) no se da por vencido sin confirmarlo.\n\n`recargo_pct`: recargo del art. 27 LGT de un plazo vencido, a día de hoy. En las informativas (180, 190, 193, 347, 349, 390) es `null`: se aplica el art. 198 LGT (ver `recargo_aviso`).\n\nEs **informativo**: la fecha de un plazo no obliga a nada por sí sola, y presentar no está en la API.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "desde", "in": "query", "schema": { "type": "string" }, "description": "Primer día del rango, en AAAA-MM-DD. Si no lo mandas, hoy." }, { "name": "hasta", "in": "query", "schema": { "type": "string" }, "description": "Último día del rango, en AAAA-MM-DD. Si no lo mandas, 90 días después de `desde`. Máximo 400 días." }, { "name": "modelo", "in": "query", "schema": { "type": "string" }, "description": "Código del modelo (303, 111…) para quedarte solo con sus plazos." } ], "x-scope": "calendario:leer", "x-plan": "Professional" } }, "/document-requests": { "get": { "summary": "Documentos que el gestor le ha pedido al cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Cambio de oct-2026: una petición puede quedar en `revisado` con `document_id` nulo. Es la que el cliente respondió sin documento («no hubo operación ese mes», «anulada», «no dispongo de ella»…) y la gestoría dio por buena. Ya no está pendiente y no admite subida.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estado del recurso." } ], "x-scope": "comunicacion:leer", "x-plan": "Professional" } }, "/document-requests/{id}/upload": { "post": { "summary": "Responder a una petición subiendo el documento", "responses": { "202": { "description": "Aceptado; consulta el trabajo en `consultar_en`" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Exige DOS permisos: leer la comunicación y escribir documentos.\n\nResponde 202 con un trabajo. Si el OCR o el cupo fallan, la petición vuelve a su estado anterior: no se queda en «subido» sin documento.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF, JPG, PNG, WEBP o HEIC. Máximo 20 MB." } }, "required": [ "file" ] } } } }, "x-scope": [ "comunicacion:leer", "documentos:escribir" ], "x-plan": "Professional" } }, "/documents": { "get": { "summary": "Documentos digitalizados", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Del más reciente al más antiguo. `status` admite processing, completed o failed. Para sincronizar solo lo nuevo o lo modificado, usa `modificado_desde`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "processing, completed o failed." }, { "name": "clasificacion", "in": "query", "schema": { "type": "string" }, "description": "emitida, recibida o rectificativa." }, { "name": "fecha_desde", "in": "query", "schema": { "type": "string" }, "description": "Fecha de ALTA en el sistema (no la de la factura), en AAAA-MM-DD." }, { "name": "fecha_hasta", "in": "query", "schema": { "type": "string" }, "description": "Fecha de ALTA en el sistema (no la de la factura), en AAAA-MM-DD." }, { "name": "modificado_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo lo creado o modificado desde esa fecha (AAAA-MM-DD) o fecha y hora ISO 8601. Para sincronizar de forma incremental." } ], "x-scope": "documentos:leer", "x-plan": "Starter" }, "post": { "summary": "Enviar un documento a digitalizar", "responses": { "202": { "description": "Aceptado; consulta el trabajo en `consultar_en`" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Responde **202**: el OCR no cabe en una petición HTTP. El cuerpo trae un trabajo con `consultar_en`; cuando su estado sea `succeeded`, `resultado` traerá los documentos.\n\nUn mismo fichero puede contener varias facturas: el resultado las devuelve todas.\n\nSi el trabajo acaba en `failed`, `error.code` dice qué hacer:\n- `recibo_de_gasto`: no es una factura sino un recibo sin IVA (cuota de autónomos, seguro, IBI…). Si `resultado.expense_id` viene relleno, ya está guardado como gasto en borrador para que lo confirme el gestor; si no, regístralo con `POST /expenses`.\n- `documento_ilegible`: protegido con contraseña, dañado o demasiado grande. Súbelo en un PDF sin contraseña.\n- `documento_rechazado`: no es una factura (una nómina, una declaración, un albarán). Volver a subirlo dará lo mismo.\n- `documento_duplicado`: ya se había digitalizado en la gestoría.\n- `digitalizacion_fallida`: fallo nuestro. Vuelve a intentarlo.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF, imagen o Word. Máximo 20 MB." } }, "required": [ "file" ] } } } }, "x-scope": "documentos:escribir", "x-plan": "Professional" } }, "/documents/{id}": { "get": { "summary": "Ficha de un documento, con lo que extrajo el OCR", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Incluye los datos extraídos de la factura (NIF, importes, fechas) y las incidencias detectadas al digitalizarla.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "documentos:leer", "x-plan": "Starter" }, "patch": { "summary": "Corregir lo que leyó el OCR", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Número, fecha, NIF y nombre de emisor y receptor, base imponible y total. La corrección se marca como manual y **recalcula la confianza**.\n\nCambiar un NIF puede reclasificar el documento (de recibida a emitida o al revés): si ya hay un pago de IRPF declarado sobre él, se responde 409.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "numero_factura": { "type": "string", "description": "Hasta 255 caracteres." }, "fecha_emision": { "type": "string", "description": "AAAA-MM-DD." }, "nif_emisor": { "type": "string", "description": "Cambiarlo puede reclasificar el documento." }, "nombre_emisor": { "type": "string", "description": "Hasta 255 caracteres." }, "nif_receptor": { "type": "string", "description": "Cambiarlo puede reclasificar el documento." }, "nombre_receptor": { "type": "string", "description": "Hasta 255 caracteres." }, "base_imponible": { "type": "number", "description": "No negativa, salvo en rectificativas y cierres de TPV." }, "total": { "type": "number", "description": "No negativo, salvo en rectificativas y cierres de TPV." } } } } } }, "x-scope": "documentos:escribir", "x-plan": "Professional" }, "delete": { "summary": "Dar de baja un documento", "responses": { "409": { "description": "El documento tiene consecuencias fiscales o contables" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Baja **lógica**: el documento deja de contar, no se destruye.\n\nSe rechaza (409) si es una factura emitida, si tiene asiento contabilizado, si hay un pago de IRPF declarado, si tiene cobros anotados o si está conciliado con el banco. Todo eso lo decide el gestor desde su panel.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "documentos:escribir", "x-plan": "Professional" } }, "/documents/{id}/file": { "get": { "summary": "Descargar el fichero original", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El fichero tal como se subió. Un documento generado desde facturación no tiene fichero original: su PDF se descarga con `GET /invoices/{id}/pdf`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "documentos:leer", "x-plan": "Starter" } }, "/employees": { "get": { "summary": "Trabajadores del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Leerlos va con `trabajadores:leer` (o con `nominas:empleados`); darlos de alta, modificarlos o darlos de baja, solo con `nominas:empleados`. Cada uno trae su `fecha_alta`, su `fecha_baja` y su `estado`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "activo", "in": "query", "schema": { "type": "boolean" }, "description": "true para los trabajadores en alta; false para los dados de baja." }, { "name": "baja_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo los dados de baja desde esa fecha (AAAA-MM-DD)." }, { "name": "actualizado_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo los creados o modificados desde esa fecha (AAAA-MM-DD o ISO 8601)." } ], "x-scope": "trabajadores:leer|nominas:empleados", "x-plan": "Enterprise" }, "post": { "summary": "Dar de alta un trabajador", "responses": { "201": { "description": "Trabajador dado de alta" }, "409": { "description": "NIF duplicado o tope de trabajadores del plan" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Crea el trabajador y su ficha de nóminas en la MISMA transacción: o los dos o ninguno.\n\nEl mismo NIF no se da de alta dos veces en la misma gestoría (409). **No genera nóminas**: eso lo decide el gestor.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nif": { "type": "string", "description": "NIF o NIE del trabajador. No puede repetirse en el cliente." }, "name": { "type": "string", "description": "Nombre completo, hasta 200 caracteres." }, "naf": { "type": "string", "description": "Número de afiliación a la Seguridad Social." }, "email": { "type": "string", "description": "Correo." }, "address": { "type": "string", "description": "Hasta 500 caracteres." }, "iban": { "type": "string", "description": "IBAN español para la nómina." }, "birth_date": { "type": "string", "description": "AAAA-MM-DD." }, "grupo_cotizacion": { "type": "integer", "description": "Grupo de cotización, de 1 a 11." }, "tipo_contrato_tgss": { "type": "string", "description": "Código de contrato de 3 cifras (100, 402…). Lo heredan sus contratos si no indican modalidad." }, "cnae": { "type": "string", "description": "Hasta 5 caracteres." }, "ccc": { "type": "string", "description": "Código de cuenta de cotización." }, "position": { "type": "string", "description": "Puesto." }, "collective_agreement": { "type": "string", "description": "Convenio colectivo." }, "salary": { "type": "number", "description": "Salario." }, "jornada_tipo": { "type": "string", "description": "completa o parcial." }, "jornada_horas_semana": { "type": "number", "description": "De 1 a 40." }, "base_cotizacion": { "type": "number", "description": "Base de cotización." }, "fecha_alta": { "type": "string", "description": "AAAA-MM-DD." }, "activity_id": { "type": "integer", "description": "Actividad del cliente." }, "situacion_familiar": { "type": "integer", "description": "Modelo 145: 1, 2 o 3." }, "n_hijos_a_cargo": { "type": "integer", "description": "Modelo 145." }, "n_hijos_menores_3_anyos": { "type": "integer", "description": "Modelo 145. No más que los hijos a cargo." }, "n_ascendientes_mayor_65": { "type": "integer", "description": "Modelo 145." }, "n_ascendientes_mayor_75": { "type": "integer", "description": "Modelo 145. No más que los mayores de 65." }, "discapacidad_propia": { "type": "string", "description": "Modelo 145: none, 33_65, 33_65_movilidad, mas_65 o mas_65_ayuda." }, "movilidad_geografica": { "type": "boolean", "description": "Modelo 145." }, "pension_compensatoria_conyuge": { "type": "number", "description": "Modelo 145." }, "anualidades_alimentos_hijos": { "type": "number", "description": "Modelo 145." }, "provincia": { "type": "string", "description": "Hasta 50 caracteres." }, "codigo_postal": { "type": "string", "description": "Hasta 10 caracteres." }, "descendientes_por_entero": { "type": "boolean", "description": "Modelo 145." }, "n_descendientes_discapacidad_33_65": { "type": "integer", "description": "Modelo 145." }, "n_descendientes_discapacidad_mas_65": { "type": "integer", "description": "Modelo 145." }, "n_descendientes_movilidad_reducida": { "type": "integer", "description": "Modelo 145." }, "n_ascendientes_discapacidad_33_65": { "type": "integer", "description": "Modelo 145." }, "n_ascendientes_discapacidad_mas_65": { "type": "integer", "description": "Modelo 145." }, "n_ascendientes_movilidad_reducida": { "type": "integer", "description": "Modelo 145." }, "situacion_perceptor": { "type": "string", "description": "activo, pensionista o desempleado." }, "excepcion_tipo_minimo": { "type": "string", "description": "penado o centro_especial_empleo." }, "prestamo_vivienda_pre2013": { "type": "boolean", "description": "Modelo 145." }, "ceuta_melilla": { "type": "boolean", "description": "Rentas obtenidas en Ceuta o Melilla." }, "es_administrador_consejero": { "type": "boolean" }, "es_relacion_laboral_especial": { "type": "boolean" }, "pluriactividad": { "type": "boolean" }, "dos_pagadores": { "type": "boolean" }, "convenio_especial_tgss": { "type": "boolean" }, "tipo_retencion_solicitado": { "type": "number", "description": "Retención voluntaria, de 0 a 47." }, "tipo_retencion_solicitado_fecha": { "type": "string", "description": "AAAA-MM-DD." }, "situacion_jubilacion": { "type": "string", "description": "exencion_art_152 o jubilacion_activa." }, "fecha_antiguedad": { "type": "string", "description": "AAAA-MM-DD." }, "apellido1": { "type": "string", "description": "Hasta 40 caracteres." }, "apellido2": { "type": "string", "description": "Hasta 40 caracteres." }, "sexo": { "type": "string", "description": "1, 2 o 3." }, "nacionalidad": { "type": "string", "description": "Código de país de 3 cifras." }, "pais_residencia": { "type": "string", "description": "Código de país de 3 cifras." }, "municipio_residencia": { "type": "string", "description": "Código INE de municipio, 5 cifras." }, "nivel_formativo": { "type": "string", "description": "2 cifras." }, "codigo_ocupacion": { "type": "string", "description": "4 cifras." }, "situacion_laboral": { "type": "string", "description": "De 1 a 6." }, "regimen_ss": { "type": "string", "description": "Régimen de la Seguridad Social, 2 cifras." }, "regimen_ss_cotizacion": { "type": "string", "description": "general, reta, hogar, agrario, mar, artistas, representantes o mineria_carbon." } }, "required": [ "nif", "name" ] } } } }, "x-scope": "nominas:empleados", "x-plan": "Enterprise" } }, "/employees/{id}": { "patch": { "summary": "Modificar un trabajador o darle de baja", "responses": { "200": { "description": "Trabajador modificado" }, "404": { "description": "El trabajador no es de este cliente" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Los datos se corrigen igual que en la ficha laboral del panel; el NIF no se cambia.\n\n**Baja:** `fecha_baja` y `causa_baja` (catálogo de la TGSS) juntas. Cierra sus contratos, deja de generarse su nómina desde el mes siguiente y, si tiene ficha laboral, registra el movimiento de baja en la Seguridad Social. Avisa con `employee.terminated`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre completo, hasta 120 caracteres." }, "naf": { "type": "string", "description": "Número de afiliación a la Seguridad Social." }, "email": { "type": "string", "description": "Correo." }, "address": { "type": "string", "description": "Hasta 500 caracteres." }, "iban": { "type": "string", "description": "IBAN español para la nómina." }, "birth_date": { "type": "string", "description": "AAAA-MM-DD." }, "grupo_cotizacion": { "type": "integer", "description": "Grupo de cotización, de 1 a 11." }, "tipo_contrato_tgss": { "type": "string", "description": "Código de contrato de 3 cifras." }, "cnae": { "type": "string", "description": "Hasta 5 caracteres." }, "ccc": { "type": "string", "description": "Código de cuenta de cotización." }, "position": { "type": "string", "description": "Puesto." }, "collective_agreement": { "type": "string", "description": "Convenio colectivo." }, "salary": { "type": "number", "description": "Salario." }, "jornada_tipo": { "type": "string", "description": "completa o parcial." }, "jornada_horas_semana": { "type": "number", "description": "De 1 a 40." }, "base_cotizacion": { "type": "number", "description": "Base de cotización." }, "fecha_baja": { "type": "string", "description": "Baja del trabajador, AAAA-MM-DD, no anterior al alta. Va con `causa_baja`." }, "causa_baja": { "type": "string", "description": "Causa de la baja: código del catálogo de la TGSS (51, 53, 54, 55, 56, 58, 63, 65, 67, 68, 69, 73, 74, 77, 80, 85, 89, 91, 92, 93, 94 o 99). Va con `fecha_baja`." } } } } } }, "x-scope": "nominas:empleados", "x-plan": "Enterprise" } }, "/employment-contracts": { "get": { "summary": "Contratos de trabajo", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "empleado_id", "in": "query", "schema": { "type": "integer" }, "description": "Identificador del trabajador." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "active, ended o suspended." } ], "x-scope": "trabajadores:leer|nominas:empleados", "x-plan": "Enterprise" }, "post": { "summary": "Dar de alta un contrato", "responses": { "201": { "description": "Contrato creado" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Cierra el contrato activo anterior del trabajador y crea el nuevo.\n\nSi el contrato es indefinido o temporal lo decide la **modalidad SEPE** (`modalidad_sepe`), no un campo aparte: así los dos no pueden contradecirse.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payroll_employee_id": { "type": "integer", "description": "Trabajador de este cliente (GET /employees)." }, "activity_id": { "type": "integer", "description": "Actividad del cliente del trabajador." }, "modalidad_sepe": { "type": "string", "description": "Código SEPE de 3 cifras. Si no lo mandas, se toma el del trabajador. Decide si el contrato es indefinido (1xx) o temporal." }, "fecha_inicio": { "type": "string", "description": "AAAA-MM-DD." }, "fecha_fin": { "type": "string", "description": "AAAA-MM-DD, no anterior al inicio." }, "periodo_prueba_dias": { "type": "integer", "description": "De 0 a 730." }, "es_fijo_discontinuo": { "type": "boolean" }, "es_practicas_no_remuneradas": { "type": "boolean" }, "es_practicas_remuneradas": { "type": "boolean" }, "fecha_inicio_relacion": { "type": "string", "description": "AAAA-MM-DD, no posterior al inicio." }, "ocupacion_at_ep": { "type": "string", "description": "oficina, representantes_comercio, oficios_construccion, conductores_mercancias, limpieza o seguridad." }, "empresa_ccc": { "type": "string", "description": "CCC de la empresa, hasta 15 caracteres." }, "jornada_horas_semana": { "type": "number", "description": "De 1 a 60." }, "jornada_completa": { "type": "boolean", "description": "Si no lo mandas, se deduce de 40 horas o más." }, "salario_base_mensual": { "type": "number", "description": "Salario base mensual." }, "pagas_extras_anuales": { "type": "integer", "description": "Pagas al año, de 12 a 24." }, "importe_paga_extra": { "type": "number", "description": "Importe de cada paga extra." }, "pagas_extras_prorrateadas": { "type": "boolean" }, "complementos": { "type": "array", "items": { "type": "object" }, "description": "Cada uno con nombre e importe." }, "at_ep_porcentaje": { "type": "number", "description": "Tarifa de accidentes de trabajo y enfermedades profesionales, de 1,5 a 7,15." }, "convenio_nombre": { "type": "string", "description": "Hasta 200 caracteres." }, "convenio_codigo": { "type": "string", "description": "Hasta 50 caracteres." }, "categoria_convenio": { "type": "string", "description": "Hasta 120 caracteres." }, "bonificaciones": { "type": "array", "items": { "type": "string" }, "description": "discapacidad_indefinido, discapacidad_severa, transformacion_indefinido, mujer_subrepresentada, mayor_45_larga_duracion, fijo_discontinuo_turismo o fijo_discontinuo_agrario." }, "bonif_es_mujer": { "type": "boolean" }, "bonif_es_mayor_45": { "type": "boolean" } }, "required": [ "payroll_employee_id", "fecha_inicio", "jornada_horas_semana", "salario_base_mensual", "pagas_extras_anuales", "at_ep_porcentaje" ] } } } }, "x-scope": "nominas:empleados", "x-plan": "Enterprise" } }, "/employment-contracts/{id}": { "patch": { "summary": "Modificar un contrato", "responses": { "200": { "description": "Contrato modificado (`cambios` lista lo que ha cambiado)" }, "404": { "description": "El contrato no es de este cliente" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Salario, jornada, fecha de fin, estado, complementos… Basta con enviar lo que cambia.\n\nQueda en el historial del contrato con su fecha de efecto (`efectivo_desde`) y su motivo. **Las nóminas ya emitidas no se recalculan**: la respuesta lo avisa en `aviso` si el cambio les afecta.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "active, suspended (excedencia o suspensión) o ended." }, "fecha_fin": { "type": "string", "description": "AAAA-MM-DD, no anterior al inicio." }, "modalidad_sepe": { "type": "string", "description": "Código SEPE de 3 cifras." }, "jornada_horas_semana": { "type": "number", "description": "De 1 a 60." }, "jornada_completa": { "type": "boolean", "description": "Si no se envía, se conserva la del contrato." }, "salario_base_mensual": { "type": "number", "description": "Salario base mensual." }, "pagas_extras_anuales": { "type": "integer", "description": "Entre 12 y 24." }, "importe_paga_extra": { "type": "number", "description": "Importe de cada paga extra." }, "pagas_extras_prorrateadas": { "type": "boolean", "description": "Si las pagas extra van prorrateadas." }, "at_ep_porcentaje": { "type": "number", "description": "Tarifa de accidentes, entre 1,50 y 7,15." }, "periodo_prueba_dias": { "type": "integer", "description": "Días de periodo de prueba (0 = sin periodo de prueba)." }, "empresa_ccc": { "type": "string", "description": "Código de cuenta de cotización del centro." }, "convenio_nombre": { "type": "string", "description": "Convenio colectivo." }, "categoria_convenio": { "type": "string", "description": "Categoría profesional del convenio." }, "complementos": { "type": "array", "items": { "type": "object" }, "description": "Lista COMPLETA de complementos fijos, cada uno con nombre, importe y, opcionalmente, clave del catálogo y entra_en_paga." }, "efectivo_desde": { "type": "string", "description": "Fecha de efecto del cambio, AAAA-MM-DD. Queda en el historial." }, "motivo": { "type": "string", "description": "Motivo del cambio, hasta 255 caracteres. Queda en el historial." } } } } } }, "x-scope": "nominas:empleados", "x-plan": "Enterprise" } }, "/expenses": { "get": { "summary": "Gastos y recibos sin factura", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "`status` admite draft (borrador, no cuenta en el Modelo 130), confirmed o declared. Un filtro con un valor no admitido responde 422.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." }, { "name": "trimestre", "in": "query", "schema": { "type": "integer" }, "description": "1, 2, 3 o 4." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "draft (borrador), confirmed o declared." } ], "x-scope": "gastos:leer", "x-plan": "Starter" }, "post": { "summary": "Registrar un gasto", "responses": { "201": { "description": "Gasto creado en borrador" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Nace en borrador: no entra en el Modelo 130 hasta que se confirme.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipo": { "type": "string", "description": "seguridad_social, alquiler_local, suministros, reparaciones, publicidad, gastos_financieros, amortizaciones, seguros, tributos_locales, colegios_profesionales u otros_gastos. También se admite como `expense_type`." }, "importe": { "type": "number", "description": "Total del recibo, IVA incluido. Entre 0,01 y 9.999.999,99. También `amount`." }, "iva": { "type": "number", "description": "Cuota de IVA incluida en el importe, si la hay. También `vat_amount`." }, "concepto": { "type": "string", "description": "De 3 a 200 caracteres. También `concept`." }, "descripcion": { "type": "string", "description": "Hasta 1.000 caracteres. También `description`." }, "fecha": { "type": "string", "description": "Fecha de pago, AAAA-MM-DD. No puede ser futura. También `payment_date`." }, "activity_id": { "type": "integer", "description": "Actividad del cliente a la que se imputa el gasto." } }, "required": [ "tipo", "importe", "concepto", "fecha" ] } } } }, "x-scope": "gastos:escribir", "x-plan": "Professional" } }, "/expenses/{id}": { "put": { "summary": "Corregir un gasto en borrador", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Solo borradores, y no genera asiento: un gasto sin confirmar no tiene por qué estar en el libro diario (409 `tiene_asiento` si ya lo tuviera).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipo": { "type": "string", "description": "seguridad_social, alquiler_local, suministros, reparaciones, publicidad, gastos_financieros, amortizaciones, seguros, tributos_locales, colegios_profesionales u otros_gastos. También se admite como `expense_type`." }, "importe": { "type": "number", "description": "Total del recibo, IVA incluido. Entre 0,01 y 9.999.999,99. También `amount`." }, "iva": { "type": "number", "description": "Cuota de IVA incluida en el importe, si la hay. También `vat_amount`." }, "concepto": { "type": "string", "description": "De 3 a 200 caracteres. También `concept`." }, "descripcion": { "type": "string", "description": "Hasta 1.000 caracteres. También `description`." }, "fecha": { "type": "string", "description": "Fecha de pago, AAAA-MM-DD. No puede ser futura. También `payment_date`." }, "activity_id": { "type": "integer", "description": "Actividad del cliente a la que se imputa el gasto." } }, "required": [ "tipo", "importe", "concepto", "fecha" ] } } } }, "x-scope": "gastos:escribir", "x-plan": "Professional" } }, "/expenses/{id}/confirm": { "post": { "summary": "Confirmar un gasto", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Es la frontera del Modelo 130, y por eso lleva permiso propio: al confirmar, el gasto pasa a deducirse.\n\nIntenta además conciliarlo con el banco y generar su asiento; si eso falla, el gasto queda confirmado igualmente y se avisa. Emite `expense.confirmed`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "gastos:confirmar", "x-plan": "Professional" } }, "/invoice-products": { "get": { "summary": "Productos y servicios guardados del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Búsqueda por nombre. Mínimo dos caracteres." } ], "x-scope": "directorio:leer", "x-plan": "Professional" }, "post": { "summary": "Guardar un producto o servicio", "responses": { "201": { "description": "Producto guardado" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El `sku` no se repite en el mismo cliente (422). Admite también los nombres en castellano de las respuestas (`nombre`, `descripcion`, `precio`, `iva_pct`, `irpf_pct`, `categoria`, `cuenta_contable`, `activo`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "description": "Referencia, hasta 60 caracteres." }, "name": { "type": "string", "description": "De 2 a 200 caracteres." }, "description": { "type": "string", "description": "Hasta 1.000 caracteres." }, "default_price": { "type": "number", "description": "Precio por defecto, de 0 a 999.999,99." }, "default_iva_pct": { "type": "number", "description": "Tipo de IVA admitido en el territorio del cliente (0, 4, 10 o 21 en la península)." }, "default_irpf_pct": { "type": "integer", "description": "0, 1, 2, 7, 15, 19 o 21." }, "category": { "type": "string", "description": "Hasta 80 caracteres." }, "accounting_account": { "type": "string", "description": "Cuenta contable, hasta 16 caracteres." }, "is_active": { "type": "boolean", "description": "Al crearlo, true por defecto. Al modificarlo, si no lo mandas se conserva." } }, "required": [ "name" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoice-products/import": { "post": { "summary": "Importar productos desde un CSV", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Multipart con el campo `csv` (máximo 5 MB), separado por comas o punto y coma, con cabecera.\n\nColumnas: `name` (o `nombre`, obligatoria), `price` (o `precio`, `importe`, `pvp`), `iva_pct` (o `iva`; si falta, 21), `irpf_pct` (o `irpf`), `description` (o `descripcion`), `sku`, `category`, `accounting_account`. Decimales con coma o con punto.\n\nLas filas con precio no numérico o IVA inexistente se rechazan (`rechazadas`) con su motivo en `avisos`; un precio negativo se guarda a 0 y se avisa. Sin ninguna fila válida, 422 `importacion_sin_filas`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "format": "binary", "description": "Fichero CSV, máximo 5 MB." } }, "required": [ "csv" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoice-products/{id}": { "put": { "summary": "Modificar un producto o servicio", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Mismas reglas que el alta. Las facturas ya emitidas conservan el precio con el que se emitieron.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "description": "Referencia, hasta 60 caracteres." }, "name": { "type": "string", "description": "De 2 a 200 caracteres." }, "description": { "type": "string", "description": "Hasta 1.000 caracteres." }, "default_price": { "type": "number", "description": "Precio por defecto, de 0 a 999.999,99." }, "default_iva_pct": { "type": "number", "description": "Tipo de IVA admitido en el territorio del cliente (0, 4, 10 o 21 en la península)." }, "default_irpf_pct": { "type": "integer", "description": "0, 1, 2, 7, 15, 19 o 21." }, "category": { "type": "string", "description": "Hasta 80 caracteres." }, "accounting_account": { "type": "string", "description": "Cuenta contable, hasta 16 caracteres." }, "is_active": { "type": "boolean", "description": "Al crearlo, true por defecto. Al modificarlo, si no lo mandas se conserva." } }, "required": [ "name" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoice-recipients": { "get": { "summary": "Destinatarios guardados del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Búsqueda por nombre. Mínimo dos caracteres." } ], "x-scope": "directorio:leer", "x-plan": "Professional" }, "post": { "summary": "Guardar un destinatario", "responses": { "201": { "description": "Destinatario guardado" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Se validan el NIF (español o intracomunitario) y el IBAN. Admite también los nombres en castellano de las respuestas (`nombre`, `direccion`, `ciudad`, `codigo_postal`, `pais`, `dias_de_pago`, `plantilla_id`, `idioma`, `moneda`, `notas`, `generico`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nif": { "type": "string", "description": "NIF español. Obligatorio salvo destinatario genérico, y no puede repetirse en el cliente." }, "is_generic": { "type": "boolean", "description": "Destinatario genérico de contado, sin NIF." }, "name": { "type": "string", "description": "De 2 a 200 caracteres." }, "email": { "type": "string", "description": "Correo." }, "address": { "type": "string", "description": "Hasta 300 caracteres." }, "city": { "type": "string", "description": "Hasta 100 caracteres." }, "zip": { "type": "string", "description": "Hasta 16 caracteres." }, "country": { "type": "string", "description": "Código de país de 2 letras." }, "iban": { "type": "string", "description": "Hasta 34 caracteres." }, "default_payment_terms_days": { "type": "integer", "description": "Días de vencimiento por defecto, de 0 a 365." }, "default_template_id": { "type": "integer", "description": "Plantilla del gestor para este cliente." }, "default_language": { "type": "string", "description": "es, en, fr, de, pt, ca, eu o gl." }, "default_currency": { "type": "string", "description": "EUR, USD, GBP o CHF." }, "notes": { "type": "string", "description": "Hasta 1.000 caracteres." } }, "required": [ "name" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoice-recipients/import": { "post": { "summary": "Importar destinatarios desde un CSV", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Multipart con el campo `csv` (máximo 5 MB), separado por comas o punto y coma, con cabecera.\n\nColumnas: `name` (o `nombre`, obligatoria), `nif` (obligatoria salvo en un cliente de contado), `is_generic` (o `generico`: 1 para un cliente de contado sin NIF), `email` (o `correo`), `address` (o `direccion`), `city` (o `ciudad`), `zip` (o `codigo_postal`, `cp`), `country` (o `pais`).\n\nUn NIF ya guardado actualiza ese destinatario; las columnas que el fichero no trae conservan su valor.\n\nLas filas con NIF o nombre no válidos se omiten (`omitidos`) y su motivo va en `avisos`; `rechazadas` son las que la base de datos no admitió. Sin ninguna fila válida, 422 `importacion_sin_filas`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "format": "binary", "description": "Fichero CSV, máximo 5 MB." } }, "required": [ "csv" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoice-recipients/{id}": { "put": { "summary": "Modificar un destinatario", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Mismas reglas que el alta. Las facturas ya emitidas conservan los datos con los que se emitieron.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nif": { "type": "string", "description": "NIF español. Obligatorio salvo destinatario genérico, y no puede repetirse en el cliente." }, "is_generic": { "type": "boolean", "description": "Destinatario genérico de contado, sin NIF." }, "name": { "type": "string", "description": "De 2 a 200 caracteres." }, "email": { "type": "string", "description": "Correo." }, "address": { "type": "string", "description": "Hasta 300 caracteres." }, "city": { "type": "string", "description": "Hasta 100 caracteres." }, "zip": { "type": "string", "description": "Hasta 16 caracteres." }, "country": { "type": "string", "description": "Código de país de 2 letras." }, "iban": { "type": "string", "description": "Hasta 34 caracteres." }, "default_payment_terms_days": { "type": "integer", "description": "Días de vencimiento por defecto, de 0 a 365." }, "default_template_id": { "type": "integer", "description": "Plantilla del gestor para este cliente." }, "default_language": { "type": "string", "description": "es, en, fr, de, pt, ca, eu o gl." }, "default_currency": { "type": "string", "description": "EUR, USD, GBP o CHF." }, "notes": { "type": "string", "description": "Hasta 1.000 caracteres." } }, "required": [ "name" ] } } } }, "x-scope": "directorio:escribir", "x-plan": "Professional" } }, "/invoices": { "get": { "summary": "Facturas del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Las fechas: `fecha_desde`/`fecha_hasta` filtran por la fecha de ALTA en el sistema; para la fecha de la factura, usa `fecha_expedicion_desde`/`fecha_expedicion_hasta`.\n\nEl listado sale del más reciente al más antiguo. Para sincronizar solo lo nuevo o lo modificado, usa `modificado_desde`.\n\n`clasificacion=rectificativa` incluye las rectificativas que emite el propio cliente (R1-R5); para un tipo concreto, `tipo_factura`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "clasificacion", "in": "query", "schema": { "type": "string" }, "description": "emitida, recibida o rectificativa." }, { "name": "tipo_factura", "in": "query", "schema": { "type": "string" }, "description": "Uno o varios tipos de documento separados por comas: F1, F2, F3, F4, F5, R1-R5, AB, PR, PS, AL, RC." }, { "name": "estado_cobro", "in": "query", "schema": { "type": "string" }, "description": "pending, partial, paid, overdue (vencida sin cobrar) o write_off." }, { "name": "nif", "in": "query", "schema": { "type": "string" }, "description": "NIF, con o sin el prefijo ES: se normaliza antes de buscar." }, { "name": "serie", "in": "query", "schema": { "type": "string" }, "description": "Serie de facturación exacta." }, { "name": "fecha_expedicion_desde", "in": "query", "schema": { "type": "string" }, "description": "Fecha de expedición de la factura, en AAAA-MM-DD." }, { "name": "fecha_expedicion_hasta", "in": "query", "schema": { "type": "string" }, "description": "Fecha de expedición de la factura, en AAAA-MM-DD." }, { "name": "fecha_desde", "in": "query", "schema": { "type": "string" }, "description": "Fecha de ALTA en el sistema (no la de la factura), en AAAA-MM-DD." }, { "name": "fecha_hasta", "in": "query", "schema": { "type": "string" }, "description": "Fecha de ALTA en el sistema (no la de la factura), en AAAA-MM-DD." }, { "name": "modificado_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo lo creado o modificado desde esa fecha (AAAA-MM-DD) o fecha y hora ISO 8601. Para sincronizar de forma incremental." } ], "x-scope": "facturas:leer", "x-plan": "Starter" }, "post": { "summary": "Emitir una factura", "responses": { "201": { "description": "Factura emitida" }, "409": { "description": "Clave de idempotencia reutilizada con otros datos, o emisión no posible" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Exige `Idempotency-Key`. La respuesta dice si la factura se remitirá a la AEAT y por qué.\n\nLa serie debe existir para el cliente en ese ejercicio (422 si no); solo la «A» se crea sola.\n\nUn **503** (`operacion_no_completada`, `firma_verifactu_fallida`) significa que no se ha emitido nada: reintenta con la MISMA `Idempotency-Key`; si la factura llegó a emitirse, te devolvemos esa misma en vez de crear otra.\n\nAnular y rectificar NO están en la API: son irreversibles y se hacen desde el panel del gestor.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receptor_nif": { "type": "string", "description": "NIF español o intracomunitario del destinatario. Obligatorio salvo en F2, PR, PS, AL y RC." }, "receptor_nombre": { "type": "string", "description": "De 2 a 200 caracteres." }, "receptor_direccion": { "type": "string", "description": "Hasta 300 caracteres." }, "receptor_ciudad": { "type": "string", "description": "Hasta 100 caracteres." }, "receptor_cp": { "type": "string", "description": "Hasta 10 caracteres." }, "receptor_email": { "type": "string", "description": "Correo del destinatario." }, "serie": { "type": "string", "description": "Serie de facturación, hasta 10 caracteres." }, "ejercicio": { "type": "integer", "description": "Año de la factura." }, "fecha_expedicion": { "type": "string", "description": "AAAA-MM-DD. No puede ser futura." }, "fecha_operacion": { "type": "string", "description": "AAAA-MM-DD, si no coincide con la expedición. No puede ser futura." }, "fecha_vencimiento": { "type": "string", "description": "AAAA-MM-DD, igual o posterior a la expedición." }, "tipo_factura": { "type": "string", "description": "F1, F2, F3, F4, F5, R1, R2, R3, R4, R5, AB, PR, PS, AL o RC." }, "activity_id": { "type": "integer", "description": "Actividad del cliente. Obligatoria si tiene más de una activa." }, "original_document_id": { "type": "string", "description": "Factura que se rectifica. Obligatorio en R1 a R5." }, "causa_rectificacion": { "type": "string", "description": "Motivo de la rectificación, hasta 300 caracteres. Obligatorio en R1 a R5." }, "tipo_rectificativa": { "type": "string", "description": "S (por sustitución) o I (por diferencias)." }, "scheduled_emission_date": { "type": "string", "description": "AAAA-MM-DD posterior a hoy, para programar la emisión." }, "template_id": { "type": "integer", "description": "Plantilla del gestor para este cliente." }, "regime_flags": { "type": "object", "description": "Regímenes especiales, booleanos: isp, recargo_equivalencia, rebu, recc, reagyp, igic, ipsi, igi, exportacion_exenta, intracomunitaria, repe, minorista_igic, exencion_art25_ref y exencion_volumen_igic. Además reagyp_pct (10.5 o 12) e isp_motivo (texto)." }, "rebu_compra_total": { "type": "number", "description": "Precio de compra, en el régimen de bienes usados." }, "lineas": { "type": "array", "items": { "type": "object" }, "description": "De 1 a 50 líneas, cada una con concepto (3 a 200 caracteres), cantidad (mayor que 0), precio_unitario (mayor que 0; negativo solo en rectificativas y AB), iva_pct (Tipo de IVA admitido en el territorio del cliente (0, 4, 10 o 21 en la península).), irpf_pct (0, 1, 2, 7, 15, 19 o 21.), descuento_pct (0 a 100) y, para VeriFactu, vf_calificacion (S1, S2, N1, N2), vf_exencion (E1 a E6) y vf_clave_regimen." }, "vf_clave_regimen": { "type": "string", "description": "Clave de régimen de VeriFactu para toda la factura." }, "observaciones": { "type": "string", "description": "Hasta 1.000 caracteres." }, "fecha_entrega": { "type": "string", "description": "AAAA-MM-DD." }, "direccion_entrega": { "type": "string", "description": "Hasta 255 caracteres." }, "referencia_pedido": { "type": "string", "description": "Hasta 100 caracteres." }, "bultos": { "type": "integer", "description": "Número de bultos." }, "currency": { "type": "string", "description": "EUR, USD, GBP, CHF o JPY." }, "language": { "type": "string", "description": "es, en, fr, de, pt, ca, eu, gl o es+en." }, "payment_schedule": { "type": "array", "items": { "type": "object" }, "description": "Hasta 24 vencimientos, cada uno con due_date (AAAA-MM-DD, no anterior a la expedición) y amount. La suma tiene que cuadrar con el total." }, "send_email": { "type": "boolean", "description": "Mandar la factura por correo al destinatario. Por defecto, false." }, "as_draft": { "type": "boolean", "description": "Guardarla como borrador, sin numerar ni firmar. Por defecto, false." } }, "required": [ "receptor_nombre", "serie", "ejercicio", "fecha_expedicion", "tipo_factura", "lineas" ] } } } }, "x-scope": "facturas:escribir", "x-plan": "Professional" } }, "/invoices/{id}": { "get": { "summary": "Ficha de una factura", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Emitida, borrador o propuesta, con sus líneas, sus importes, su estado de cobro y su estado ante la AEAT.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "facturas:leer", "x-plan": "Starter" }, "patch": { "summary": "Corregir un borrador o una propuesta", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Edición PARCIAL: manda solo los campos que cambian; el resto se conserva del documento guardado y el resultado se valida entero, como al emitir.\n\nSolo borradores y propuestas. Una factura emitida se corrige con una rectificativa.\n\nLo que la edición no aplica se devuelve en `avisos` (por ejemplo, `tipo_no_cambiado`: una propuesta se pasa a factura con `POST /invoices/{id}/convert`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "receptor_nif": { "type": "string", "description": "NIF español o intracomunitario del destinatario. Obligatorio salvo en F2, PR, PS, AL y RC." }, "receptor_nombre": { "type": "string", "description": "De 2 a 200 caracteres." }, "receptor_direccion": { "type": "string", "description": "Hasta 300 caracteres." }, "receptor_ciudad": { "type": "string", "description": "Hasta 100 caracteres." }, "receptor_cp": { "type": "string", "description": "Hasta 10 caracteres." }, "receptor_email": { "type": "string", "description": "Correo del destinatario." }, "serie": { "type": "string", "description": "Serie de facturación, hasta 10 caracteres." }, "ejercicio": { "type": "integer", "description": "Año de la factura." }, "fecha_expedicion": { "type": "string", "description": "AAAA-MM-DD. No puede ser futura." }, "fecha_operacion": { "type": "string", "description": "AAAA-MM-DD, si no coincide con la expedición. No puede ser futura." }, "fecha_vencimiento": { "type": "string", "description": "AAAA-MM-DD, igual o posterior a la expedición." }, "tipo_factura": { "type": "string", "description": "F1, F2, F3, F4, F5, R1, R2, R3, R4, R5, AB, PR, PS, AL o RC." }, "activity_id": { "type": "integer", "description": "Actividad del cliente. Obligatoria si tiene más de una activa." }, "original_document_id": { "type": "string", "description": "Factura que se rectifica. Obligatorio en R1 a R5." }, "causa_rectificacion": { "type": "string", "description": "Motivo de la rectificación, hasta 300 caracteres. Obligatorio en R1 a R5." }, "tipo_rectificativa": { "type": "string", "description": "S (por sustitución) o I (por diferencias)." }, "scheduled_emission_date": { "type": "string", "description": "AAAA-MM-DD posterior a hoy, para programar la emisión." }, "template_id": { "type": "integer", "description": "Plantilla del gestor para este cliente." }, "regime_flags": { "type": "object", "description": "Regímenes especiales, booleanos: isp, recargo_equivalencia, rebu, recc, reagyp, igic, ipsi, igi, exportacion_exenta, intracomunitaria, repe, minorista_igic, exencion_art25_ref y exencion_volumen_igic. Además reagyp_pct (10.5 o 12) e isp_motivo (texto)." }, "rebu_compra_total": { "type": "number", "description": "Precio de compra, en el régimen de bienes usados." }, "lineas": { "type": "array", "items": { "type": "object" }, "description": "De 1 a 50 líneas, cada una con concepto (3 a 200 caracteres), cantidad (mayor que 0), precio_unitario (mayor que 0; negativo solo en rectificativas y AB), iva_pct (Tipo de IVA admitido en el territorio del cliente (0, 4, 10 o 21 en la península).), irpf_pct (0, 1, 2, 7, 15, 19 o 21.), descuento_pct (0 a 100) y, para VeriFactu, vf_calificacion (S1, S2, N1, N2), vf_exencion (E1 a E6) y vf_clave_regimen." }, "vf_clave_regimen": { "type": "string", "description": "Clave de régimen de VeriFactu para toda la factura." }, "observaciones": { "type": "string", "description": "Hasta 1.000 caracteres." }, "fecha_entrega": { "type": "string", "description": "AAAA-MM-DD." }, "direccion_entrega": { "type": "string", "description": "Hasta 255 caracteres." }, "referencia_pedido": { "type": "string", "description": "Hasta 100 caracteres." }, "bultos": { "type": "integer", "description": "Número de bultos." }, "currency": { "type": "string", "description": "EUR, USD, GBP, CHF o JPY." }, "language": { "type": "string", "description": "es, en, fr, de, pt, ca, eu, gl o es+en." }, "payment_schedule": { "type": "array", "items": { "type": "object" }, "description": "Hasta 24 vencimientos, cada uno con due_date (AAAA-MM-DD, no anterior a la expedición) y amount. La suma tiene que cuadrar con el total." }, "send_email": { "type": "boolean", "description": "Mandar la factura por correo al destinatario. Por defecto, false." }, "as_draft": { "type": "boolean", "description": "Guardarla como borrador, sin numerar ni firmar. Por defecto, false." } }, "required": [ "receptor_nombre", "serie", "ejercicio", "fecha_expedicion", "tipo_factura", "lineas" ] } } } }, "x-scope": "facturas:escribir", "x-plan": "Professional" }, "delete": { "summary": "Descartar un borrador o una propuesta", "responses": { "409": { "description": "Factura ya emitida, o emisión en curso" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Elimina un borrador o una propuesta que no se ha convertido. No consume numeración ni deja rastro en la cadena de VeriFactu.\n\nUna factura emitida no se elimina (409 `no_eliminable`): se corrige con una rectificativa. Emisión en curso: 409 `operacion_en_curso`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "facturas:escribir", "x-plan": "Professional" } }, "/invoices/{id}/convert": { "post": { "summary": "Convertir un presupuesto o una proforma en factura", "responses": { "201": { "description": "Factura emitida a partir de la propuesta" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Una proforma o presupuesto no consume número ni firma VeriFactu; la factura resultante sí. Sobre un borrador, 409 `no_convertible`: se emite con `POST /invoices/{id}/emit`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "facturas:escribir", "x-plan": "Professional" } }, "/invoices/{id}/emit": { "post": { "summary": "Emitir un borrador", "responses": { "201": { "description": "Factura emitida, con identificador nuevo" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "🚨 **Devuelve un identificador NUEVO**: al emitir, el borrador desaparece y nace la factura. Guarda el `id` de la respuesta, no el que mandaste.\n\nSi la serie no existe en el ejercicio de emisión, 409 `serie_no_disponible`: no se emite nada; reintenta con la misma clave cuando exista.\n\nSi recibes un **500** aquí, **no reintentes**: la factura puede haber quedado emitida. Consulta `GET /invoices` o avisa al gestor con el `request_id`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_email": { "type": "boolean", "description": "Mandar la factura por correo al destinatario. Por defecto, false." } } } } } }, "x-scope": "facturas:escribir", "x-plan": "Professional" } }, "/invoices/{id}/payment-schedules": { "get": { "summary": "Vencimientos de una factura (30/60/90)", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "facturas:leer", "x-plan": "Starter" } }, "/invoices/{id}/payments": { "post": { "summary": "Registrar un cobro", "responses": { "201": { "description": "Cobro registrado" }, "409": { "description": "La factura es un borrador o una propuesta, ya está cobrada o está dada por incobrable" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Admite cobros parciales, con tolerancia de un céntimo. La fila se bloquea mientras se apunta, así que dos cobros simultáneos no dejan la factura cobrada dos veces.\n\nEmite el evento `invoice.payment_recorded`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Importe cobrado. Admite cobros parciales." }, "payment_method": { "type": "string", "description": "transferencia, efectivo, tarjeta, domiciliacion u otro." }, "paid_at": { "type": "string", "description": "AAAA-MM-DD. Por defecto, hoy. No puede ser futura." } }, "required": [ "amount", "payment_method" ] } } } }, "x-scope": "facturas:cobros", "x-plan": "Professional" } }, "/invoices/{id}/payments/{paymentId}": { "delete": { "summary": "Deshacer un cobro de una factura emitida", "responses": { "200": { "description": "Cobro deshecho: la factura con su estado de cobro actualizado" }, "409": { "description": "Periodo contable cerrado, o cobro de una remesa" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Por ejemplo, si el recibo se devuelve. El `paymentId` es el de `historial_cobros` en `GET /invoices/{id}`.\n\nRevierte el asiento de tesorería del cobro y recalcula lo cobrado; si la factura deja de estar cobrada, reabre sus vencimientos. Con el cobro contabilizado en un periodo cerrado responde **409** `periodo_cerrado` y no cambia nada. Un cobro que entró con una remesa o un confirming responde **409** `cobro_de_remesa`: se deshace desde la remesa, en el panel. Avisa con `invoice.payment_reversed`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "facturas:cobros", "x-plan": "Professional" } }, "/invoices/{id}/pdf": { "get": { "summary": "PDF de la factura", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "También de borradores y propuestas, que llevan la leyenda de que no son una factura válida para deducir impuestos.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "facturas:leer", "x-plan": "Starter" } }, "/invoices/{id}/xml": { "get": { "summary": "Factura en XML (Facturae o UBL)", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Solo facturas emitidas: un borrador o una propuesta dan 409 `no_emitida`. Exige receptor con NIF. Si falta un dato obligatorio, 409 `datos_incompletos` con la lista.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string" }, "description": "facturae (3.2.2) o ubl (2.1, EN 16931)." } ], "x-scope": "facturas:leer", "x-plan": "Starter" } }, "/irpf-payments": { "get": { "summary": "Pagos con retención de IRPF", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." }, { "name": "trimestre", "in": "query", "schema": { "type": "integer" }, "description": "1, 2, 3 o 4." }, { "name": "mes", "in": "query", "schema": { "type": "integer" }, "description": "1 a 12." }, { "name": "tipo", "in": "query", "schema": { "type": "string" }, "description": "Tipo de registro. En los modelos, su código (303, 130…)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estado del recurso." } ], "x-scope": "irpf:leer", "x-plan": "Professional" }, "post": { "summary": "Registrar un pago con retención", "responses": { "201": { "description": "Pago creado en borrador" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Nace en borrador: el Modelo 111 solo cuenta los confirmados.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_type": { "type": "string", "description": "nomina, profesional, alquiler, capital_mobiliario, premios, actividades_economicas u otros." }, "payer_nif": { "type": "string", "description": "NIF de quien paga y retiene." }, "payer_name": { "type": "string", "description": "Hasta 255 caracteres." }, "recipient_nif": { "type": "string", "description": "NIF de quien cobra." }, "recipient_name": { "type": "string", "description": "Hasta 255 caracteres." }, "recipient_type": { "type": "string", "description": "persona_fisica o persona_juridica." }, "base_amount": { "type": "number", "description": "Base sobre la que se retiene." }, "retention_percentage": { "type": "number", "description": "De 0 a 100." }, "payment_date": { "type": "string", "description": "AAAA-MM-DD." }, "invoice_number": { "type": "string", "description": "Hasta 50 caracteres." }, "service_description": { "type": "string", "description": "Hasta 1.000 caracteres." }, "property_reference": { "type": "string", "description": "Referencia catastral, en alquileres." }, "property_address": { "type": "string", "description": "Dirección del inmueble, en alquileres." }, "notes": { "type": "string", "description": "Hasta 1.000 caracteres." }, "activity_id": { "type": "integer", "description": "Actividad del cliente." } }, "required": [ "payment_type", "payer_nif", "payer_name", "recipient_nif", "recipient_name", "recipient_type", "base_amount", "retention_percentage", "payment_date" ] } } } }, "x-scope": "irpf:escribir", "x-plan": "Professional" } }, "/irpf-payments/{id}/confirm": { "post": { "summary": "Confirmar un pago con retención", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "A partir de aquí entra en el Modelo 111. Emite `irpf_payment.confirmed`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "irpf:confirmar", "x-plan": "Professional" } }, "/jobs": { "get": { "summary": "Trabajos en diferido de esta clave", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Del más reciente al más antiguo. Si mandas `X-CG-Client`, se acota a ese cliente; sin la cabecera salen todos los de la clave.\n\nLos trabajos caducados (24 horas) ya no se listan, pero `GET /jobs/{id}` los sigue devolviendo a quien guardó su identificador. Un `estado` que no existe responde 422.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "estado", "in": "query", "schema": { "type": "string" }, "description": "pending, running, succeeded o failed." } ], "x-plan": "Cualquier plan con API" } }, "/jobs/{id}": { "get": { "summary": "Estado de un trabajo", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Responde 200 en los cuatro estados: que el trabajo fallara no es un fallo de tu consulta — el motivo va dentro, en `error`.\n\nCuando `estado` es `succeeded`, `resultado` trae el MISMO recurso que devolvería la vía directa.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-plan": "Cualquier plan con API" } }, "/journal-entries": { "get": { "summary": "Asientos del libro diario", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Del más reciente al más antiguo. Por defecto solo los asientos contabilizados; los borradores, con `incluir_borradores=true`.\n\n`fecha_desde`/`fecha_hasta` filtran por la fecha del asiento. Con `expand=apuntes` cada asiento trae sus líneas.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." }, { "name": "fecha_desde", "in": "query", "schema": { "type": "string" }, "description": "Fecha del asiento, en AAAA-MM-DD." }, { "name": "fecha_hasta", "in": "query", "schema": { "type": "string" }, "description": "Fecha del asiento, en AAAA-MM-DD." }, { "name": "incluir_borradores", "in": "query", "schema": { "type": "boolean" }, "description": "true para incluir los asientos en borrador (por defecto solo los contabilizados)." }, { "name": "cuenta", "in": "query", "schema": { "type": "string" }, "description": "Cuenta o subcuenta del PGC. Casa por prefijo: «430» trae todas sus subcuentas." }, { "name": "nif_tercero", "in": "query", "schema": { "type": "string" }, "description": "NIF del tercero que aparece en alguna línea del asiento." }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "`apuntes` para traer las líneas de cada asiento en el listado." } ], "x-scope": "contabilidad:leer", "x-plan": "Professional" } }, "/journal-entries/{id}": { "get": { "summary": "Un asiento con todas sus líneas", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Como el listado: un borrador solo se devuelve con `incluir_borradores=true` (si no, 404).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incluir_borradores", "in": "query", "schema": { "type": "boolean" }, "description": "true para incluir los asientos en borrador (por defecto solo los contabilizados)." } ], "x-scope": "contabilidad:leer", "x-plan": "Professional" } }, "/payment-schedules/{id}/mark-paid": { "post": { "summary": "Dar por cobrado un vencimiento", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Marca el vencimiento como cobrado y anota su importe, en la fecha indicada (hoy por defecto). Nunca cobra más de lo pendiente ni cobra dos veces el mismo vencimiento.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method": { "type": "string", "description": "transferencia, efectivo, tarjeta, domiciliacion u otro." }, "paid_at": { "type": "string", "description": "AAAA-MM-DD. Por defecto, hoy. No puede ser futura." } } } } } }, "x-scope": "facturas:cobros", "x-plan": "Professional" } }, "/payroll-inputs": { "get": { "summary": "Incidencias del mes registradas", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Conceptos variables (horas extra, dietas, anticipos…), baja médica y situaciones del mes de cada trabajador.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "periodo", "in": "query", "schema": { "type": "string" }, "description": "Periodo de la nómina, en AAAA-MM (por ejemplo, 2026-03)." }, { "name": "empleado_id", "in": "query", "schema": { "type": "integer" }, "description": "Identificador del trabajador." } ], "x-scope": "nominas:leer", "x-plan": "Professional" }, "post": { "summary": "Registrar incidencias del mes de un trabajador", "responses": { "201": { "description": "Incidencias registradas (`rechazadas` lista las que no)" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Entran por el mismo camino que la plantilla de incidencias del panel, y un concepto ya registrado en el mes se actualiza.\n\n**Claves de concepto admitidas:** `salario_base`, `antiguedad`, `plus_convenio`, `plus_puesto`, `plus_penosidad`, `plus_toxicidad`, `plus_peligrosidad`, `nocturnidad`, `turnicidad`, `festivos`, `guardias`, `incentivos`, `comisiones`, `bonus`, `horas_complementarias`, `horas_extra_fuerza_mayor`, `horas_extra_estructurales`, `horas_extra_no_estructurales`, `prorrata_pagas_extras`, `paga_extra`, `atrasos_convenio`, `vacaciones_no_disfrutadas`, `salarios_preaviso`, `salario_especie`, `plus_transporte`, `dietas`, `locomocion`, `prestacion_it`, `complemento_it`, `indemnizacion`, `suplidos`, `anticipo`, `prestamo_empresa`, `embargo`, `cuota_sindical`, `sancion`, `permiso_no_retribuido`, `huelga`, `ausencia_injustificada`, `otras_deducciones`. Con una sola clave fuera del catálogo responde **422** y no registra nada (la petición entra entera o no entra).\n\nSi el periodo de ese trabajador ya está cerrado responde **409** `periodo_cerrado`: lo que haya que pagar de más va en un recibo complementario.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "empleado_id": { "type": "integer", "description": "Trabajador de este cliente (GET /employees)." }, "periodo": { "type": "string", "description": "Mes de la nómina, AAAA-MM." }, "conceptos": { "type": "array", "items": { "type": "object" }, "description": "Hasta 50 conceptos, cada uno con clave (del catálogo de conceptos de nómina: horas_extra_no_estructurales, dietas, anticipo…), importe y, si procede, cantidad (horas, días…)." }, "baja_it": { "type": "object", "description": "Baja médica del mes: dias (1 a 31), contingencia (enfermedad_comun, accidente_no_laboral, accidente_trabajo o enfermedad_profesional), base_reguladora_diaria (opcional) y dias_meses_anteriores (opcional)." }, "situaciones": { "type": "array", "items": { "type": "object" }, "description": "Situaciones del mes, cada una con clave (dias_extranjero, dias_huelga, dias_permiso_no_retribuido, dias_erte_suspension o jornadas_reales_agrario), dias y, en el extranjero, importe (opcional)." } }, "required": [ "empleado_id", "periodo" ] } } } }, "x-scope": "nominas:empleados", "x-plan": "Enterprise" } }, "/payrolls": { "get": { "summary": "Nóminas del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Une las nóminas **calculadas** en Copilot y las **subidas** ya hechas (`origen`). Cada una trae periodo, trabajador (`empleado_id` y `nif`), `tipo_recibo`, `secuencia`, `rectifica_a`, `estado` y `anulada`.\n\n**Para contar una nómina por trabajador y mes**, cuenta las que traen `en_recuento = true`: es exactamente una por trabajador y mes. Una ordinaria recalculada es la misma nómina, y una complementaria, una paga extra, unos atrasos o un finiquito son recibos aparte (`secuencia` 2 o más) y no entran en el recuento. Una nómina subida se trata como ordinaria. Si un trabajador tiene más de una nómina ese mes (una calculada y una subida, o dos subidas), cuenta la calculada —o, si no la hay, la primera subida— y todas las de ese trabajador y mes salen con `requiere_revision = true` para que el despacho lo revise.\n\n**Cuándo está cerrada:** cuando el despacho cierra el periodo del cliente, por cuenta de cotización. Un cierre se puede reabrir (evento `payroll.period_reopened`), y una nómina de un trabajador sin NAF se paga pero sigue en `calculada`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "empleado_id", "in": "query", "schema": { "type": "integer" }, "description": "Identificador del trabajador." }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." }, { "name": "periodo", "in": "query", "schema": { "type": "string" }, "description": "Periodo de la nómina, en AAAA-MM (por ejemplo, 2026-03)." }, { "name": "estado", "in": "query", "schema": { "type": "string" }, "description": "borrador, calculada, cerrada, anulada, en_proceso o fallida (estos dos, solo en las subidas)." }, { "name": "tipo_recibo", "in": "query", "schema": { "type": "string" }, "description": "ordinaria, paga_extra, complementaria, atrasos o finiquito. Una nómina subida es siempre ordinaria." }, { "name": "origen", "in": "query", "schema": { "type": "string" }, "description": "calculada (la calculó Copilot) o importada (se subió ya hecha). Sin el filtro, las dos." }, { "name": "actualizada_desde", "in": "query", "schema": { "type": "string" }, "description": "Solo las creadas, modificadas, cerradas o anuladas desde esa fecha (AAAA-MM-DD o ISO 8601)." }, { "name": "incluir_anuladas", "in": "query", "schema": { "type": "boolean" }, "description": "true para incluir también las nóminas subidas que se han eliminado (salen con estado anulada)." } ], "x-scope": "nominas:leer", "x-plan": "Professional" } }, "/payrolls/{id}": { "get": { "summary": "Ficha de una nómina", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Lo mismo que en la lista, más la retención de IRPF. El identificador de una nómina subida es un UUID; el de una calculada, un número.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "nominas:leer", "x-plan": "Professional" } }, "/portal-profiles": { "get": { "summary": "Perfiles de acceso al portal de la gestoría", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Cada perfil fija las secciones que ven los clientes que lo tienen: en el portal web (`secciones`) y en la app (`secciones_app`). Se crean en el panel y se asignan con `PATCH /clients/{id}` (`perfil_portal`).", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "clientes:leer", "x-plan": "Starter" } }, "/recurring-invoices": { "get": { "summary": "Facturas recurrentes del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estado del recurso." } ], "x-scope": "recurrentes:leer", "x-plan": "Professional" }, "post": { "summary": "Crear una factura recurrente", "responses": { "201": { "description": "Recurrente creada" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Cada emisión es una factura real: consume número y se firma. Si no mandas `day_of_month`, se toma el día de `next_emission_date`.\n\nEl destinatario se añade al directorio si no existía, sin modificar uno existente. Una retención a un particular se advierte en `avisos`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "De 3 a 200 caracteres." }, "frequency": { "type": "string", "description": "monthly, quarterly o yearly." }, "next_emission_date": { "type": "string", "description": "AAAA-MM-DD. Al crearla, hoy o después." }, "day_of_month": { "type": "integer", "description": "Día del mes en que se emite, de 1 a 31." }, "ipc_clause": { "type": "boolean", "description": "Actualizar el importe con el IPC." }, "end_date": { "type": "string", "description": "AAAA-MM-DD, posterior a la próxima emisión." }, "template_data": { "type": "object", "description": "La factura que se repite: receptor_nif y receptor_nombre (obligatorios), receptor_email, receptor_direccion, receptor_ciudad, receptor_cp, observaciones, dias_vencimiento (0 a 365), categoria, activity_id, serie (activa, de facturas completas y de esa actividad o sin actividad; sin ella, la predeterminada del cliente), vf_clave_regimen y lineas (1 a 50, cada una con concepto, cantidad, precio_unitario, iva_pct, irpf_pct, descuento_pct y vf_naturaleza)." } }, "required": [ "name", "frequency", "next_emission_date", "template_data" ] } } } }, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/recurring-invoices/{id}": { "get": { "summary": "Ficha de una recurrente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Incluye la frecuencia, la próxima fecha de emisión y el estado (activa, pausada o cancelada).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "recurrentes:leer", "x-plan": "Professional" }, "put": { "summary": "Modificar una recurrente", "responses": { "409": { "description": "La recurrente está cancelada" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Sustitución completa: se manda el cuerpo entero, como en el alta, plantilla incluida.\n\nLa **frecuencia no se cambia** (422): cambiarla movería las fechas ya calculadas. Cancela la recurrente y crea otra. Una recurrente cancelada no se modifica (409 `recurrente_cancelada`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "De 3 a 200 caracteres." }, "frequency": { "type": "string", "description": "La que ya tiene: la frecuencia no se cambia." }, "next_emission_date": { "type": "string", "description": "AAAA-MM-DD." }, "day_of_month": { "type": "integer", "description": "Día del mes en que se emite, de 1 a 31." }, "ipc_clause": { "type": "boolean", "description": "Actualizar el importe con el IPC." }, "end_date": { "type": "string", "description": "AAAA-MM-DD, posterior a la próxima emisión." }, "template_data": { "type": "object", "description": "La factura que se repite: receptor_nif y receptor_nombre (obligatorios), receptor_email, receptor_direccion, receptor_ciudad, receptor_cp, observaciones, dias_vencimiento (0 a 365), categoria, activity_id, serie (activa, de facturas completas y de esa actividad o sin actividad; sin ella, la predeterminada del cliente), vf_clave_regimen y lineas (1 a 50, cada una con concepto, cantidad, precio_unitario, iva_pct, irpf_pct, descuento_pct y vf_naturaleza)." } }, "required": [ "name", "frequency", "next_emission_date", "template_data" ] } } } }, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/recurring-invoices/{id}/cancel": { "post": { "summary": "Cancelar una recurrente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Irreversible: una recurrente cancelada no se reanuda ni se modifica. Las facturas ya emitidas no se tocan.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/recurring-invoices/{id}/pause": { "post": { "summary": "Pausar una recurrente", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "No se emite nada mientras esté pausada. Se reanuda con `POST /recurring-invoices/{id}/resume`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/recurring-invoices/{id}/preview": { "get": { "summary": "Próximas emisiones previstas", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Calcula las fechas que vienen sin emitir nada. Útil para enseñarle al cliente qué se le va a facturar.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "n", "in": "query", "schema": { "type": "integer" }, "description": "Cuántas emisiones futuras quieres ver. De 1 a 60." } ], "x-scope": "recurrentes:leer", "x-plan": "Professional" } }, "/recurring-invoices/{id}/resume": { "post": { "summary": "Reanudar una recurrente pausada", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Solo pausadas: una cancelada no se reanuda (409 `ya_cancelada`).", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/recurring-invoices/{id}/skip": { "post": { "summary": "Saltar la próxima emisión", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Pasa la próxima fecha a la siguiente según la frecuencia, sin emitir nada.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "motivo": { "type": "string", "description": "Por qué se salta, hasta 200 caracteres." } } } } } }, "x-scope": "recurrentes:escribir", "x-plan": "Professional" } }, "/sepa-mandates": { "get": { "summary": "Mandatos SEPA del cliente (IBAN enmascarado)", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Lectura: `sepa:leer` o `sepa:gestionar`; alta y revocación: `sepa:gestionar`. Con el módulo de remesas desactivado, 403 `modulo_sepa_inactivo`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estado del recurso." } ], "x-scope": "sepa:leer|sepa:gestionar", "x-plan": "Professional" }, "post": { "summary": "Dar de alta un mandato SEPA", "responses": { "201": { "description": "Mandato creado" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El IBAN se valida con el mismo mod-97 que genera los adeudos (422 `iban_no_valido`).\n\nSin el documento firmado **y** su fecha de firma, el mandato queda `pending_signature` y no se puede domiciliar nada con él.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "debtor_name": { "type": "string", "description": "Hasta 200 caracteres." }, "debtor_nif": { "type": "string", "description": "Hasta 32 caracteres." }, "debtor_iban": { "type": "string", "description": "IBAN del deudor. Se comprueba su dígito de control." }, "scheme": { "type": "string", "description": "CORE o B2B." }, "seq_type": { "type": "string", "description": "FRST, RCUR, OOFF o FNAL." }, "signed_at": { "type": "string", "description": "AAAA-MM-DD. Obligatoria si adjuntas el mandato firmado." }, "pdf": { "type": "string", "format": "binary", "description": "Mandato firmado: PDF, JPG o PNG, máximo 8 MB. Sin él y sin fecha de firma, queda pendiente de firma." } }, "required": [ "debtor_name", "debtor_iban", "scheme" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "debtor_name": { "type": "string", "description": "Hasta 200 caracteres." }, "debtor_nif": { "type": "string", "description": "Hasta 32 caracteres." }, "debtor_iban": { "type": "string", "description": "IBAN del deudor. Se comprueba su dígito de control." }, "scheme": { "type": "string", "description": "CORE o B2B." }, "seq_type": { "type": "string", "description": "FRST, RCUR, OOFF o FNAL." }, "signed_at": { "type": "string", "description": "AAAA-MM-DD. Obligatoria si adjuntas el mandato firmado." }, "pdf": { "type": "string", "format": "binary", "description": "Mandato firmado: PDF, JPG o PNG, máximo 8 MB. Sin él y sin fecha de firma, queda pendiente de firma." } }, "required": [ "debtor_name", "debtor_iban", "scheme" ] } } } }, "x-scope": "sepa:gestionar", "x-plan": "Enterprise" } }, "/sepa-mandates/{id}/revoke": { "post": { "summary": "Revocar un mandato", "responses": { "409": { "description": "Ya estaba revocado" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Irreversible: un mandato revocado no se reactiva, hay que firmar uno nuevo con referencia nueva.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "sepa:gestionar", "x-plan": "Enterprise" } }, "/sepa-remittances": { "get": { "summary": "Remesas SEPA del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Generar remesas NO está en la API: presentar adeudos al banco lo decide el gestor.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "sepa:leer|sepa:gestionar", "x-plan": "Professional" } }, "/sepa-remittances/{id}/xml": { "get": { "summary": "Fichero XML de una remesa", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "El fichero SEPA tal como se generó en el panel. Cada descarga queda registrada en el registro de actividad del gestor, como las de facturas.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "sepa:leer|sepa:gestionar", "x-plan": "Professional" } }, "/status": { "get": { "summary": "Señal de vida, permisos de la clave y límites del plan", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "No consume cupo ni exige ningún permiso. Es lo primero que conviene llamar.\n\nTrae el bloque `plan`: cuántas claves admite, qué permisos incluye y qué modelos fiscales puede generar esta gestoría.", "x-plan": "Cualquier plan con API" } }, "/tax-models": { "get": { "summary": "Modelos fiscales del cliente", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "La ficha de cada modelo (`GET /tax-models/{id}`) trae además sus alertas. `tipo` es el número del modelo (303, 130…); un filtro con un valor no admitido responde 422.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." }, { "name": "tipo", "in": "query", "schema": { "type": "string" }, "description": "Tipo de registro. En los modelos, su código (303, 130…)." }, { "name": "trimestre", "in": "query", "schema": { "type": "integer" }, "description": "1, 2, 3 o 4." } ], "x-scope": "modelos:leer", "x-plan": "Professional" }, "post": { "summary": "Generar un modelo fiscal", "responses": { "201": { "description": "Modelo generado (trimestrales)" }, "202": { "description": "Aceptado; consulta el trabajo en `consultar_en` (anuales)" }, "409": { "description": "Ya existe ese modelo para ese periodo, o se está generando" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Trimestrales (respuesta directa, 201):** 303, 111, 130, 131, 115, 123. Exigen `trimestre`.\n\n**Anuales (respuesta 202 + trabajo):** 100, 180, 190, 193, 200, 202, 347, 349, 390. Tardan más de lo que aguanta una petición HTTP.\nEl 202 y el 349 exigen `periodo` (y el 349, además, `periodo_tipo` M o T). El 100 exige `comunidad_autonoma`.\n\n`activity_id` solo se admite en el 130 y el 131: los demás se declaran por NIF y no se pueden fraccionar por actividad.\n\nSi falla: **503** `agente_fiscal_no_disponible` (no se ha generado nada, reintenta en unos minutos con la misma `Idempotency-Key`), **422** `modelo_no_generado` (el cálculo ha rechazado los datos y el mensaje dice qué corregir) o **409** `modelo_ya_existe` / `generacion_en_curso`. En los anuales, esos mismos códigos llegan dentro del trabajo.\n\nPresentar ante la AEAT NO está en la API: exige la contraseña del certificado del cliente, que no guardamos.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Idempotencia" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipo": { "type": "string", "description": "303, 111, 130, 131, 115 o 123 (respuesta directa); 100, 180, 190, 193, 200, 202, 347, 349 o 390 (en diferido)." }, "ejercicio": { "type": "integer", "description": "Año, en cuatro cifras." }, "trimestre": { "type": "integer", "description": "De 1 a 4. Obligatorio en los trimestrales." }, "activity_id": { "type": "integer", "description": "Solo filtra el cálculo en el 130 y el 131." }, "periodo": { "type": "integer", "description": "Obligatorio en el 202 (1, 2 o 3) y en el 349 (mes o trimestre)." }, "periodo_tipo": { "type": "string", "description": "mensual o trimestral (también M o T), en el 349." }, "comunidad_autonoma": { "type": "string", "description": "Obligatoria en el 100." }, "tipo_tributacion": { "type": "string", "description": "individual o conjunta, en el 100." }, "rendimiento_neto_anual": { "type": "number", "description": "Modelo 131: obligatorio." }, "num_empleados": { "type": "number", "description": "Modelo 131: obligatorio." }, "volumen_ventas_sin_datos": { "type": "number", "description": "Modelo 131." }, "volumen_ingresos_agricolas": { "type": "number", "description": "Modelo 131." }, "retenciones_trimestre": { "type": "number", "description": "Modelo 131." }, "rendimiento_neto_previo_anual": { "type": "number", "description": "Modelo 131." }, "resultados_negativos_anteriores": { "type": "number", "description": "Modelo 131." }, "deduccion_vivienda": { "type": "number", "description": "Modelo 131: hasta 660,14." }, "ceuta_melilla": { "type": "boolean", "description": "Modelo 131." }, "agricultor_joven": { "type": "boolean", "description": "Modelo 131." } }, "required": [ "tipo", "ejercicio" ] } } } }, "x-scope": "modelos:escribir", "x-plan": "Professional" } }, "/tax-models/export": { "get": { "summary": "Todos los modelos de un ejercicio, de una vez", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Pensado para migrar un cliente o cerrar el año sin recorrer el cursor N veces. Tope de 500 modelos.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "ejercicio", "in": "query", "schema": { "type": "integer" }, "description": "Año, en cuatro cifras." } ], "x-scope": "modelos:leer", "x-plan": "Professional" } }, "/tax-models/{id}": { "get": { "summary": "Ficha de un modelo, con sus alertas", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Casillas calculadas, resultado y alertas de revisión del modelo.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "modelos:leer", "x-plan": "Professional" } }, "/tax-models/{id}/file": { "get": { "summary": "Fichero oficial del modelo para la Sede", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Devuelve el fichero en el diseño oficial de la AEAT (texto ISO-8859-1), el mismo que el gestor importaría en la Sede. **No presenta nada.**\n\nExiste cuando el gestor ha exportado el modelo desde su panel; si no, 409 `fichero_no_generado`. Los modelos de la ATC (415, 420, 425) no tienen fichero de la AEAT: 409 `sin_fichero_aeat`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "modelos:leer", "x-plan": "Professional" } }, "/tax-models/{id}/receipt": { "get": { "summary": "Justificante de una presentación ya hecha ante la AEAT", "responses": { "409": { "description": "El modelo no consta presentado" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Devuelve el CSV, el número de justificante y un enlace temporal al PDF.\n\nRequiere `modelos:presentar`, no `modelos:leer`: el justificante acredita la presentación ante terceros. **Este permiso no presenta nada ante la AEAT.**\n\nPresentar en sí no está en la API — exige la contraseña del certificado del cliente, que no guardamos.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "modelos:presentar", "x-plan": "Professional" } }, "/webhooks": { "get": { "summary": "Destinos de webhook configurados", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Los de esta clave, sin el secreto (se muestra una sola vez, al crear el destino). Leerlos va con `webhooks:leer` o `webhooks:gestionar`.\n\nUna clave de pruebas (`cg_test_`) también puede gestionar sus destinos: es configuración de la integración, no datos de clientes.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "webhooks:leer|webhooks:gestionar", "x-plan": "Professional" }, "post": { "summary": "Dar de alta un destino", "responses": { "201": { "description": "Destino creado; el secreto se muestra una sola vez" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Nace apagado. Hay que verificarlo antes de que reciba nada, y el secreto se muestra una sola vez.\n\nAquí `Idempotency-Key` es **opcional**: sin ella funciona igual, y con ella un reintento del alta no crea un segundo destino.", "parameters": [ { "$ref": "#/components/parameters/IdempotenciaOpcional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Dirección https de tu servidor, hasta 500 caracteres. No puede apuntar a una dirección interna." }, "eventos": { "type": "array", "items": { "type": "string" }, "description": "Uno o más eventos del catálogo (GET /webhooks/eventos)." } }, "required": [ "url", "eventos" ] } } } }, "x-scope": "webhooks:gestionar", "x-plan": "Professional" } }, "/webhooks/eventos": { "get": { "summary": "Catálogo de eventos y cómo verificar la firma", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-plan": "Cualquier plan con API" } }, "/webhooks/{id}": { "delete": { "summary": "Eliminar un destino", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Deja de recibir eventos en el acto, y su historial de entregas se elimina con él.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "webhooks:gestionar", "x-plan": "Professional" } }, "/webhooks/{id}/entregas": { "get": { "summary": "Entregas de un destino, con su resultado", "responses": { "200": { "description": "Listado paginado por cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lista" } } } }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "x-scope": "webhooks:leer|webhooks:gestionar", "x-plan": "Professional" } }, "/webhooks/{id}/entregas/{entregaId}/reenviar": { "post": { "summary": "Reenviar una entrega", "responses": { "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflicto con el estado del recurso, o Idempotency-Key reutilizada con otros datos. Los conflictos transitorios (`operacion_en_curso`, `emision_no_posible`, `edicion_no_posible`, `generacion_en_curso`, `nif_no_valido`, `serie_no_disponible`) se pueden reintentar con la misma clave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Para recuperar lo que se perdió mientras tu servidor estuvo caído.", "parameters": [ { "$ref": "#/components/parameters/IdempotenciaOpcional" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entregaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "webhooks:gestionar", "x-plan": "Professional" } }, "/webhooks/{id}/verificar": { "post": { "summary": "Comprobar que tu servidor valida la firma", "responses": { "409": { "description": "Tu servidor no valida la firma correctamente" }, "200": { "description": "Correcto" }, "400": { "description": "Petición mal formada: JSON ilegible (`json_invalido`), falta una cabecera obligatoria (X-CG-Client, Idempotency-Key), `limit` o `cursor` no válidos, o un parámetro de consulta con un formato imposible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Clave ausente o inválida. Lleva la cabecera `WWW-Authenticate: Bearer`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falta el permiso, el plan no lo incluye, el cliente no está autorizado o no ha consentido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No existe, o es de un cliente que esta clave no puede tocar (se responde igual a propósito)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método HTTP no admitido en esta ruta. Los admitidos van en la cabecera Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "El valor de un campo no es válido (`datos_invalidos` o un código propio del campo): el detalle va en `error.errors`, con el nombre que enviaste. Las fechas, siempre en AAAA-MM-DD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite de peticiones o cupo mensual alcanzado. Mira Retry-After y X-CG-Rate-Limited-Reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Servicio no disponible y no se ha hecho nada: reintenta más tarde con la misma Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Enviamos una carga con firma válida (debe responder 2xx) y otra con firma inválida (debe responder **exactamente 401**). Si a la mala respondes cualquier otra cosa —un 2xx, pero también un 400 o un 403—, el destino no se activa y el mensaje dice qué código recibimos.", "parameters": [ { "$ref": "#/components/parameters/IdempotenciaOpcional" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-sin-cuerpo": true, "x-scope": "webhooks:gestionar", "x-plan": "Professional" } } } }