{ "info": { "name": "API de CopilotGestoria", "description": "Generada desde la especificación OpenAPI. Rellena las variables baseUrl, apiKey y clienteId.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://www.copilotgestoria.com/api/public/v1" }, { "key": "apiKey", "value": "" }, { "key": "clienteId", "value": "" } ], "item": [ { "name": "activities", "item": [ { "name": "Actividades económicas (epígrafes IAE) del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/activities", "host": [ "{{baseUrl}}" ], "path": [ "activities" ] }, "description": "\n\nPermiso: clientes:leer" } }, { "name": "Dar de alta una actividad económica", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/activities", "host": [ "{{baseUrl}}" ], "path": [ "activities" ] }, "description": "Si ya existía esa actividad con esa fecha de alta —aunque estuviera dada de baja— se **reactiva** y responde 200 con `reactivada: true`, conservando sus facturas. Un alta nueva responde 201.\n\nPermiso: actividades:escribir", "body": { "mode": "raw", "raw": "{\n \"codigo_iae\": \"\",\n \"descripcion\": \"\",\n \"seccion_iae\": \"\",\n \"regimen_irpf\": \"\",\n \"regimen_iva\": \"\",\n \"fecha_alta\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Modificar una actividad económica", "request": { "method": "PUT", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "activities", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: actividades:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Dar de baja una actividad económica", "request": { "method": "DELETE", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "activities", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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`).\n\nPermiso: actividades:escribir" } } ] }, { "name": "bank-accounts", "item": [ { "name": "Cuentas bancarias (IBAN enmascarado)", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/bank-accounts", "host": [ "{{baseUrl}}" ], "path": [ "bank-accounts" ] }, "description": "\n\nPermiso: bancos:leer" } } ] }, { "name": "bank-imports", "item": [ { "name": "Cómo va una importación de extracto", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/bank-imports/:id", "host": [ "{{baseUrl}}" ], "path": [ "bank-imports", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Estado, movimientos importados, repetidos (`duplicados`, ya estaban de una importación anterior) y con error, y conciliaciones propuestas.\n\nPermiso: bancos:leer" } } ] }, { "name": "bank-transactions", "item": [ { "name": "Movimientos bancarios", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/bank-transactions", "host": [ "{{baseUrl}}" ], "path": [ "bank-transactions" ] }, "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`).\n\nPermiso: bancos:leer" } }, { "name": "Importar un extracto bancario", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/bank-transactions/import", "host": [ "{{baseUrl}}" ], "path": [ "bank-transactions", "import" ] }, "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.\n\nPermiso: bancos:escribir" } }, { "name": "Proponer la conciliación de un movimiento con una factura", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/bank-transactions/:id/match-proposals", "host": [ "{{baseUrl}}" ], "path": [ "bank-transactions", ":id", "match-proposals" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: bancos:conciliar", "body": { "mode": "raw", "raw": "{\n \"invoice_id\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Conciliaciones propuestas para un movimiento", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/bank-transactions/:id/matches", "host": [ "{{baseUrl}}" ], "path": [ "bank-transactions", ":id", "matches" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "\n\nPermiso: bancos:leer" } } ] }, { "name": "chart-of-accounts", "item": [ { "name": "Plan contable del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/chart-of-accounts", "host": [ "{{baseUrl}}" ], "path": [ "chart-of-accounts" ] }, "description": "\n\nPermiso: contabilidad:leer" } }, { "name": "Dar de alta una subcuenta", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/chart-of-accounts", "host": [ "{{baseUrl}}" ], "path": [ "chart-of-accounts" ] }, "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`).\n\nPermiso: contabilidad:escribir", "body": { "mode": "raw", "raw": "{\n \"descripcion\": \"\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "clients", "item": [ { "name": "Clientes que esta clave puede tocar", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients", "host": [ "{{baseUrl}}" ], "path": [ "clients" ] }, "description": "Devuelve SOLO los que el gestor ha autorizado. Si no ha marcado ninguno, la lista viene vacía: no es un error.\n\nPermiso: clientes:leer" } }, { "name": "Dar de alta un cliente en la cartera de la gestoría", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/clients", "host": [ "{{baseUrl}}" ], "path": [ "clients" ] }, "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`.\n\nPermiso: clientes:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"email\": \"\",\n \"vat\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Importar un CSV de clientes", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/clients/import", "host": [ "{{baseUrl}}" ], "path": [ "clients", "import" ] }, "description": "Multipart con el campo `csv`. Columnas mínimas: `nombre`, `email`, `nif_cif`.\n\nResponde **202** con un trabajo: cada fila crea un usuario y manda un correo, y eso no cabe en una petición HTTP. El resultado dice cuántos entraron y por qué se saltó cada fila.\n\nPermiso: clientes:escribir" } }, { "name": "Ficha de un cliente con sus actividades económicas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "\n\nPermiso: clientes:leer" } }, { "name": "Corregir los datos de contacto de un cliente", "request": { "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/clients/:id", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: clientes:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Qué ha hecho esta integración con los datos de un cliente", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/activity", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "activity" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: clientes:leer" } }, { "name": "Supresión: retirar a este cliente de tu integración (RGPD art. 17)", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/data", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "data" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: clientes:derechos" } }, { "name": "Portabilidad: todos los datos del cliente en un fichero (RGPD art. 20)", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/export", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "export" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Ficha, documentos, asientos y modelos fiscales, con la misma forma siempre. Tope de 5.000 documentos y asientos.\n\nPermiso: clientes:derechos" } } ] }, { "name": "deadlines", "item": [ { "name": "Plazos fiscales que le aplican a este cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/deadlines", "host": [ "{{baseUrl}}" ], "path": [ "deadlines" ] }, "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.\n\nPermiso: calendario:leer" } } ] }, { "name": "document-requests", "item": [ { "name": "Documentos que el gestor le ha pedido al cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/document-requests", "host": [ "{{baseUrl}}" ], "path": [ "document-requests" ] }, "description": "\n\nPermiso: comunicacion:leer" } }, { "name": "Responder a una petición subiendo el documento", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/document-requests/:id/upload", "host": [ "{{baseUrl}}" ], "path": [ "document-requests", ":id", "upload" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: comunicacion:leer | documentos:escribir" } } ] }, { "name": "documents", "item": [ { "name": "Documentos digitalizados", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/documents", "host": [ "{{baseUrl}}" ], "path": [ "documents" ] }, "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`.\n\nPermiso: documentos:leer" } }, { "name": "Enviar un documento a digitalizar", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/documents", "host": [ "{{baseUrl}}" ], "path": [ "documents" ] }, "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.\n\nPermiso: documentos:escribir" } }, { "name": "Ficha de un documento, con lo que extrajo el OCR", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/documents/:id", "host": [ "{{baseUrl}}" ], "path": [ "documents", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Incluye los datos extraídos de la factura (NIF, importes, fechas) y las incidencias detectadas al digitalizarla.\n\nPermiso: documentos:leer" } }, { "name": "Corregir lo que leyó el OCR", "request": { "method": "PATCH", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/documents/:id", "host": [ "{{baseUrl}}" ], "path": [ "documents", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: documentos:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Dar de baja un documento", "request": { "method": "DELETE", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/documents/:id", "host": [ "{{baseUrl}}" ], "path": [ "documents", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: documentos:escribir" } }, { "name": "Descargar el fichero original", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/documents/:id/file", "host": [ "{{baseUrl}}" ], "path": [ "documents", ":id", "file" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: documentos:leer" } } ] }, { "name": "employees", "item": [ { "name": "Trabajadores del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/employees", "host": [ "{{baseUrl}}" ], "path": [ "employees" ] }, "description": "Leerlos va con `trabajadores:leer` (o con `nominas:empleados`); darlos de alta, solo con `nominas:empleados`.\n\nPermiso: trabajadores:leer|nominas:empleados" } }, { "name": "Dar de alta un trabajador", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/employees", "host": [ "{{baseUrl}}" ], "path": [ "employees" ] }, "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.\n\nPermiso: nominas:empleados", "body": { "mode": "raw", "raw": "{\n \"nif\": \"\",\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "employment-contracts", "item": [ { "name": "Contratos de trabajo", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/employment-contracts", "host": [ "{{baseUrl}}" ], "path": [ "employment-contracts" ] }, "description": "\n\nPermiso: trabajadores:leer|nominas:empleados" } }, { "name": "Dar de alta un contrato", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/employment-contracts", "host": [ "{{baseUrl}}" ], "path": [ "employment-contracts" ] }, "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.\n\nPermiso: nominas:empleados", "body": { "mode": "raw", "raw": "{\n \"payroll_employee_id\": 0,\n \"fecha_inicio\": \"\",\n \"jornada_horas_semana\": 0,\n \"salario_base_mensual\": 0,\n \"pagas_extras_anuales\": 0,\n \"at_ep_porcentaje\": 0\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "expenses", "item": [ { "name": "Gastos y recibos sin factura", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/expenses", "host": [ "{{baseUrl}}" ], "path": [ "expenses" ] }, "description": "`status` admite draft (borrador, no cuenta en el Modelo 130), confirmed o declared. Un filtro con un valor no admitido responde 422.\n\nPermiso: gastos:leer" } }, { "name": "Registrar un gasto", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/expenses", "host": [ "{{baseUrl}}" ], "path": [ "expenses" ] }, "description": "Nace en borrador: no entra en el Modelo 130 hasta que se confirme.\n\nPermiso: gastos:escribir", "body": { "mode": "raw", "raw": "{\n \"tipo\": \"\",\n \"importe\": 0,\n \"concepto\": \"\",\n \"fecha\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Corregir un gasto en borrador", "request": { "method": "PUT", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/expenses/:id", "host": [ "{{baseUrl}}" ], "path": [ "expenses", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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).\n\nPermiso: gastos:escribir", "body": { "mode": "raw", "raw": "{\n \"tipo\": \"\",\n \"importe\": 0,\n \"concepto\": \"\",\n \"fecha\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Confirmar un gasto", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/expenses/:id/confirm", "host": [ "{{baseUrl}}" ], "path": [ "expenses", ":id", "confirm" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: gastos:confirmar" } } ] }, { "name": "invoice-products", "item": [ { "name": "Productos y servicios guardados del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoice-products", "host": [ "{{baseUrl}}" ], "path": [ "invoice-products" ] }, "description": "\n\nPermiso: directorio:leer" } }, { "name": "Guardar un producto o servicio", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoice-products", "host": [ "{{baseUrl}}" ], "path": [ "invoice-products" ] }, "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`).\n\nPermiso: directorio:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Importar productos desde un CSV", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/invoice-products/import", "host": [ "{{baseUrl}}" ], "path": [ "invoice-products", "import" ] }, "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`.\n\nPermiso: directorio:escribir" } }, { "name": "Modificar un producto o servicio", "request": { "method": "PUT", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoice-products/:id", "host": [ "{{baseUrl}}" ], "path": [ "invoice-products", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Mismas reglas que el alta. Las facturas ya emitidas conservan el precio con el que se emitieron.\n\nPermiso: directorio:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "invoice-recipients", "item": [ { "name": "Destinatarios guardados del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoice-recipients", "host": [ "{{baseUrl}}" ], "path": [ "invoice-recipients" ] }, "description": "\n\nPermiso: directorio:leer" } }, { "name": "Guardar un destinatario", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoice-recipients", "host": [ "{{baseUrl}}" ], "path": [ "invoice-recipients" ] }, "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`).\n\nPermiso: directorio:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Importar destinatarios desde un CSV", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/invoice-recipients/import", "host": [ "{{baseUrl}}" ], "path": [ "invoice-recipients", "import" ] }, "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`.\n\nPermiso: directorio:escribir" } }, { "name": "Modificar un destinatario", "request": { "method": "PUT", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoice-recipients/:id", "host": [ "{{baseUrl}}" ], "path": [ "invoice-recipients", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Mismas reglas que el alta. Las facturas ya emitidas conservan los datos con los que se emitieron.\n\nPermiso: directorio:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "invoices", "item": [ { "name": "Facturas del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoices", "host": [ "{{baseUrl}}" ], "path": [ "invoices" ] }, "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`.\n\nPermiso: facturas:leer" } }, { "name": "Emitir una factura", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoices", "host": [ "{{baseUrl}}" ], "path": [ "invoices" ] }, "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.\n\nPermiso: facturas:escribir", "body": { "mode": "raw", "raw": "{\n \"receptor_nombre\": \"\",\n \"serie\": \"\",\n \"ejercicio\": 0,\n \"fecha_expedicion\": \"\",\n \"tipo_factura\": \"\",\n \"lineas\": [\n {}\n ]\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Ficha de una factura", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Emitida, borrador o propuesta, con sus líneas, sus importes, su estado de cobro y su estado ante la AEAT.\n\nPermiso: facturas:leer" } }, { "name": "Corregir un borrador o una propuesta", "request": { "method": "PATCH", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoices/:id", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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`).\n\nPermiso: facturas:escribir", "body": { "mode": "raw", "raw": "{\n \"receptor_nombre\": \"\",\n \"serie\": \"\",\n \"ejercicio\": 0,\n \"fecha_expedicion\": \"\",\n \"tipo_factura\": \"\",\n \"lineas\": [\n {}\n ]\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Descartar un borrador o una propuesta", "request": { "method": "DELETE", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: facturas:escribir" } }, { "name": "Convertir un presupuesto o una proforma en factura", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/convert", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "convert" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: facturas:escribir" } }, { "name": "Emitir un borrador", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/emit", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "emit" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: facturas:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Vencimientos de una factura (30/60/90)", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/payment-schedules", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "payment-schedules" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "\n\nPermiso: facturas:leer" } }, { "name": "Registrar un cobro", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/payments", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "payments" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: facturas:cobros", "body": { "mode": "raw", "raw": "{\n \"amount\": 0,\n \"payment_method\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "PDF de la factura", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/pdf", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "pdf" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "También de borradores y propuestas, que llevan la leyenda de que no son una factura válida para deducir impuestos.\n\nPermiso: facturas:leer" } }, { "name": "Factura en XML (Facturae o UBL)", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/xml", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "xml" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: facturas:leer" } } ] }, { "name": "irpf-payments", "item": [ { "name": "Pagos con retención de IRPF", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/irpf-payments", "host": [ "{{baseUrl}}" ], "path": [ "irpf-payments" ] }, "description": "\n\nPermiso: irpf:leer" } }, { "name": "Registrar un pago con retención", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/irpf-payments", "host": [ "{{baseUrl}}" ], "path": [ "irpf-payments" ] }, "description": "Nace en borrador: el Modelo 111 solo cuenta los confirmados.\n\nPermiso: irpf:escribir", "body": { "mode": "raw", "raw": "{\n \"payment_type\": \"\",\n \"payer_nif\": \"\",\n \"payer_name\": \"\",\n \"recipient_nif\": \"\",\n \"recipient_name\": \"\",\n \"recipient_type\": \"\",\n \"base_amount\": 0,\n \"retention_percentage\": 0,\n \"payment_date\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Confirmar un pago con retención", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/irpf-payments/:id/confirm", "host": [ "{{baseUrl}}" ], "path": [ "irpf-payments", ":id", "confirm" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "A partir de aquí entra en el Modelo 111. Emite `irpf_payment.confirmed`.\n\nPermiso: irpf:confirmar" } } ] }, { "name": "jobs", "item": [ { "name": "Trabajos en diferido de esta clave", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/jobs", "host": [ "{{baseUrl}}" ], "path": [ "jobs" ] }, "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." } }, { "name": "Estado de un trabajo", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/jobs/:id", "host": [ "{{baseUrl}}" ], "path": [ "jobs", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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." } } ] }, { "name": "journal-entries", "item": [ { "name": "Asientos del libro diario", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/journal-entries", "host": [ "{{baseUrl}}" ], "path": [ "journal-entries" ] }, "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.\n\nPermiso: contabilidad:leer" } }, { "name": "Un asiento con todas sus líneas", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/journal-entries/:id", "host": [ "{{baseUrl}}" ], "path": [ "journal-entries", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Como el listado: un borrador solo se devuelve con `incluir_borradores=true` (si no, 404).\n\nPermiso: contabilidad:leer" } } ] }, { "name": "payment-schedules", "item": [ { "name": "Dar por cobrado un vencimiento", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/payment-schedules/:id/mark-paid", "host": [ "{{baseUrl}}" ], "path": [ "payment-schedules", ":id", "mark-paid" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: facturas:cobros", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "payrolls", "item": [ { "name": "Nóminas generadas", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/payrolls", "host": [ "{{baseUrl}}" ], "path": [ "payrolls" ] }, "description": "\n\nPermiso: nominas:leer" } }, { "name": "Ficha de una nómina", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/payrolls/:id", "host": [ "{{baseUrl}}" ], "path": [ "payrolls", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Periodo, tipo de recibo, total devengado, total de deducciones, líquido a percibir y estado.\n\nPermiso: nominas:leer" } } ] }, { "name": "recurring-invoices", "item": [ { "name": "Facturas recurrentes del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices" ] }, "description": "\n\nPermiso: recurrentes:leer" } }, { "name": "Crear una factura recurrente", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices" ] }, "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`.\n\nPermiso: recurrentes:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"frequency\": \"\",\n \"next_emission_date\": \"\",\n \"template_data\": {}\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Ficha de una recurrente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Incluye la frecuencia, la próxima fecha de emisión y el estado (activa, pausada o cancelada).\n\nPermiso: recurrentes:leer" } }, { "name": "Modificar una recurrente", "request": { "method": "PUT", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "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`).\n\nPermiso: recurrentes:escribir", "body": { "mode": "raw", "raw": "{\n \"name\": \"\",\n \"frequency\": \"\",\n \"next_emission_date\": \"\",\n \"template_data\": {}\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Cancelar una recurrente", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id/cancel", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id", "cancel" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Irreversible: una recurrente cancelada no se reanuda ni se modifica. Las facturas ya emitidas no se tocan.\n\nPermiso: recurrentes:escribir" } }, { "name": "Pausar una recurrente", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id/pause", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id", "pause" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "No se emite nada mientras esté pausada. Se reanuda con `POST /recurring-invoices/{id}/resume`.\n\nPermiso: recurrentes:escribir" } }, { "name": "Próximas emisiones previstas", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id/preview", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id", "preview" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Calcula las fechas que vienen sin emitir nada. Útil para enseñarle al cliente qué se le va a facturar.\n\nPermiso: recurrentes:leer" } }, { "name": "Reanudar una recurrente pausada", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id/resume", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id", "resume" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Solo pausadas: una cancelada no se reanuda (409 `ya_cancelada`).\n\nPermiso: recurrentes:escribir" } }, { "name": "Saltar la próxima emisión", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/recurring-invoices/:id/skip", "host": [ "{{baseUrl}}" ], "path": [ "recurring-invoices", ":id", "skip" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Pasa la próxima fecha a la siguiente según la frecuencia, sin emitir nada.\n\nPermiso: recurrentes:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "sepa-mandates", "item": [ { "name": "Mandatos SEPA del cliente (IBAN enmascarado)", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/sepa-mandates", "host": [ "{{baseUrl}}" ], "path": [ "sepa-mandates" ] }, "description": "Lectura: `sepa:leer` o `sepa:gestionar`; alta y revocación: `sepa:gestionar`. Con el módulo de remesas desactivado, 403 `modulo_sepa_inactivo`.\n\nPermiso: sepa:leer|sepa:gestionar" } }, { "name": "Dar de alta un mandato SEPA", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/sepa-mandates", "host": [ "{{baseUrl}}" ], "path": [ "sepa-mandates" ] }, "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.\n\nPermiso: sepa:gestionar", "body": { "mode": "raw", "raw": "{\n \"debtor_name\": \"\",\n \"debtor_iban\": \"\",\n \"scheme\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Revocar un mandato", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/sepa-mandates/:id/revoke", "host": [ "{{baseUrl}}" ], "path": [ "sepa-mandates", ":id", "revoke" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Irreversible: un mandato revocado no se reactiva, hay que firmar uno nuevo con referencia nueva.\n\nPermiso: sepa:gestionar" } } ] }, { "name": "sepa-remittances", "item": [ { "name": "Remesas SEPA del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/sepa-remittances", "host": [ "{{baseUrl}}" ], "path": [ "sepa-remittances" ] }, "description": "Generar remesas NO está en la API: presentar adeudos al banco lo decide el gestor.\n\nPermiso: sepa:leer|sepa:gestionar" } }, { "name": "Fichero XML de una remesa", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/sepa-remittances/:id/xml", "host": [ "{{baseUrl}}" ], "path": [ "sepa-remittances", ":id", "xml" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: sepa:leer|sepa:gestionar" } } ] }, { "name": "status", "item": [ { "name": "Señal de vida, permisos de la clave y límites del plan", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/status", "host": [ "{{baseUrl}}" ], "path": [ "status" ] }, "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." } } ] }, { "name": "tax-models", "item": [ { "name": "Modelos fiscales del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/tax-models", "host": [ "{{baseUrl}}" ], "path": [ "tax-models" ] }, "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.\n\nPermiso: modelos:leer" } }, { "name": "Generar un modelo fiscal", "request": { "method": "POST", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/tax-models", "host": [ "{{baseUrl}}" ], "path": [ "tax-models" ] }, "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.\n\nPermiso: modelos:escribir", "body": { "mode": "raw", "raw": "{\n \"tipo\": \"\",\n \"ejercicio\": 0\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Todos los modelos de un ejercicio, de una vez", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/tax-models/export", "host": [ "{{baseUrl}}" ], "path": [ "tax-models", "export" ] }, "description": "Pensado para migrar un cliente o cerrar el año sin recorrer el cursor N veces. Tope de 500 modelos.\n\nPermiso: modelos:leer" } }, { "name": "Ficha de un modelo, con sus alertas", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/tax-models/:id", "host": [ "{{baseUrl}}" ], "path": [ "tax-models", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Casillas calculadas, resultado y alertas de revisión del modelo.\n\nPermiso: modelos:leer" } }, { "name": "Fichero oficial del modelo para la Sede", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/tax-models/:id/file", "host": [ "{{baseUrl}}" ], "path": [ "tax-models", ":id", "file" ], "variable": [ { "key": "id", "value": "" } ] }, "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`.\n\nPermiso: modelos:leer" } }, { "name": "Justificante de una presentación ya hecha ante la AEAT", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/tax-models/:id/receipt", "host": [ "{{baseUrl}}" ], "path": [ "tax-models", ":id", "receipt" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: modelos:presentar" } } ] }, { "name": "webhooks", "item": [ { "name": "Destinos de webhook configurados", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] }, "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.\n\nPermiso: webhooks:leer|webhooks:gestionar" } }, { "name": "Dar de alta un destino", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] }, "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.\n\nPermiso: webhooks:gestionar", "body": { "mode": "raw", "raw": "{\n \"url\": \"\",\n \"eventos\": []\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Catálogo de eventos y cómo verificar la firma", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/eventos", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", "eventos" ] }, "description": "" } }, { "name": "Eliminar un destino", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/:id", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Deja de recibir eventos en el acto, y su historial de entregas se elimina con él.\n\nPermiso: webhooks:gestionar" } }, { "name": "Entregas de un destino, con su resultado", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/:id/entregas", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", ":id", "entregas" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "\n\nPermiso: webhooks:leer|webhooks:gestionar" } }, { "name": "Reenviar una entrega", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true } ], "url": { "raw": "{{baseUrl}}/webhooks/:id/entregas/:entregaId/reenviar", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", ":id", "entregas", ":entregaId", "reenviar" ], "variable": [ { "key": "id", "value": "" }, { "key": "entregaId", "value": "" } ] }, "description": "Para recuperar lo que se perdió mientras tu servidor estuvo caído.\n\nPermiso: webhooks:gestionar" } }, { "name": "Comprobar que tu servidor valida la firma", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}", "disabled": true } ], "url": { "raw": "{{baseUrl}}/webhooks/:id/verificar", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", ":id", "verificar" ], "variable": [ { "key": "id", "value": "" } ] }, "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.\n\nPermiso: webhooks:gestionar" } } ] } ] }