{ "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://www.copilotgestoria.com/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", "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" }, "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" }, "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": { "201": { "description": "Actividad creada" }, "409": { "description": "Tope de actividades del plan, la actividad es de otra gestoría o ya existe (`actividad_duplicada`)" }, "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": "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.", "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 (o B01 a B05 en actividades agrarias no sujetas al IAE)." }, "descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "seccion_iae": { "type": "string", "description": "empresarial, profesional o artistica." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica." }, "fecha_alta": { "type": "string", "description": "AAAA-MM-DD. No puede ser futura." }, "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\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 (o B01 a B05 en actividades agrarias no sujetas al IAE)." }, "descripcion": { "type": "string", "description": "Hasta 255 caracteres." }, "seccion_iae": { "type": "string", "description": "empresarial, profesional o artistica." }, "regimen_irpf": { "type": "string", "description": "estimacion_directa_normal, estimacion_directa_simplificada, estimacion_objetiva_modulos o no_aplica." }, "regimen_iva": { "type": "string", "description": "general, simplificado, recargo_equivalencia, agricultura_ganaderia, exento o no_aplica." }, "fecha_alta": { "type": "string", "description": "AAAA-MM-DD. No puede ser futura." }, "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 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": "El cliente nace **sin autorizar en ninguna clave**: para operar sobre él, el gestor tiene que marcarlo en la clave desde su panel. La respuesta lo dice en `siguiente_paso`.\n\nHace lo mismo que el alta del panel: NIF sin duplicar en la cartera, actividad inicial, contrato de encargo de tratamiento y correo de bienvenida con la contraseña temporal (se puede evitar con `enviar_bienvenida: false`).\n\nConflictos: `email_en_uso`, `nif_ya_en_cartera`, `limite_clientes`.", "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." } }, "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.", "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 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🚨 **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 500 caracteres." }, "postal_code": { "type": "string", "description": "Hasta 10 caracteres." }, "comunidad_autonoma_aeat": { "type": "string", "description": "Código de la AEAT, de 01 a 20." } } } } } }, "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}/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" } }, "/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" } } } } }, "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, solo con `nominas:empleados`.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limite" } ], "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 o representantes." } }, "required": [ "nif", "name" ] } } } }, "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": "Estado del recurso." } ], "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": "12, 14, 15 o 16." }, "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" } }, "/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}/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" } }, "/payrolls": { "get": { "summary": "Nóminas generadas", "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": "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)." } ], "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": "Periodo, tipo de recibo, total devengado, total de deducciones, líquido a percibir y estado.", "parameters": [ { "$ref": "#/components/parameters/Cliente" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-scope": "nominas:leer", "x-plan": "Professional" } }, "/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, 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, 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" } } } }