{ "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://copilot.asesores.click/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\nEl régimen y la sección se comprueban contra la forma jurídica del cliente (ficha de empresa y NIF): un 422 `datos_invalidos` indica en `errors[].field` el campo y en `errors[].rule` la regla (`regimen_incompatible`, `iae_epigrafe`, `fecha_iso`, `before_or_equal`…).\n\nSi el cliente queda sin actividad principal, la respuesta lo avisa en `avisos` (`sin_actividad_principal`); no se bloquea el alta.\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\n**Dar de baja una actividad:** basta con `fecha_baja`; si esa fecha ya ha llegado, la actividad queda inactiva. `activa: true` la reactiva y quita la baja. También admite `PATCH`.\n\nCambiar el epígrafe o la fecha de alta a los de otra actividad del cliente —aunque esté dada de baja— responde 409 `actividad_duplicada`: reactívala en vez de duplicarla.\n\nPermiso: actividades:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Modificar una actividad económica (igual que PUT)", "request": { "method": "PATCH", "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": "Mismo efecto que `PUT /activities/{id}`: solo cambian los campos que mandes. Para darla de baja basta con `fecha_baja`.\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": "**Alta completa:** con `configuracion_empresa` y `actividades`, el cliente queda listo para trabajar. Todo se valida antes de crear nada: o queda completo o no se crea.\n\n**Autorización:** con la opción «Autorizar en esta clave los clientes que dé de alta» activada, el cliente queda autorizado con los permisos de la clave, hasta su máximo de clientes (`autorizado_en_esta_clave`). Si no, `siguiente_paso` indica el motivo.\n\nComo el alta del panel: NIF sin duplicar en la cartera, contrato de encargo de tratamiento y correo de bienvenida con la contraseña temporal (`enviar_bienvenida: false` lo evita). Sin `actividades`, se crea una actividad provisional con epígrafe `0000`.\n\n**Autónomos:** `regimen_fiscal` y `pgc_tipo` no hacen falta (son del Impuesto sobre Sociedades y de las cuentas anuales). Conviene enviar `configuracion_empresa.tipo_sociedad: autonomo`: sin él, la ficha queda como sociedad limitada (`sl`).\n\nConflictos: `email_en_uso`, `nif_ya_en_cartera`, `limite_clientes`, `limite_actividades`.\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\nSi la clave autoriza sus altas, el resultado indica cuántos clientes han quedado autorizados (`autorizados_en_esta_clave`).\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 y el acceso al portal 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**Acceso al portal:** `perfil_portal` (un perfil de `GET /portal-profiles`, o null para la configuración general), `portal_abierto` (false cierra el portal y la app, también para «Recuperar contraseña», y cierra sus sesiones) y `limite_facturas_portal_mes` (máximo de facturas que el cliente emite al mes desde su portal o la app; null = sin límite, 0 = ninguna).\n\n**Cuenta de domiciliación de impuestos:** `iban_domiciliacion` (null la quita) y `titular_domiciliacion`. Exigen además el permiso `clientes:cuenta_domiciliacion` (403 `scope_insuficiente` sin él). IBAN de un país SEPA: si no, 422 `iban_invalido` o `iban_no_sepa`. Lo mismo hace `PATCH /clients/{id}/tax-account`.\n\n🚨 **El NIF y el correo no se cambian por aquí** (409 `nif_no_modificable` / `email_no_modificable`). Del NIF cuelga la pertenencia de cada factura —en los documentos no hay cliente, hay NIF—, y el correo es el acceso del cliente a su portal. Los dos se corrigen desde el panel.\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": "Configuración de empresa de un cliente", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/company-config", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "company-config" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Forma jurídica, régimen fiscal, territorio, régimen de IVA, domicilio fiscal, personas y datos laborales. Sin configuración guardada: `existe: false` y valores a `null`.\n\n`confirmaciones` indica si están confirmados la forma jurídica, el territorio fiscal y el régimen de IVA. Sin confirmar, el valor es el de la ficha por defecto.\n\nAdministradores y titulares reales solo se devuelven si la clave y la autorización del cliente incluyen «Dar de alta clientes, importarlos y corregir sus datos de contacto y su configuración de empresa»; si no, `personas_omitidas: true`.\n\nPermiso: clientes:leer" } }, { "name": "Completar o corregir la configuración de empresa de un cliente", "request": { "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/clients/:id/company-config", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "company-config" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "**Solo cambia lo enviado.** Un campo no enviado no se toca; vacío o `null` lo borra si admite estar vacío. Un campo desconocido se rechaza (422, regla `campo_desconocido`).\n\n`tipo_sociedad`, `territorio_fiscal` y cualquier campo del régimen de IVA quedan **confirmados** al enviarlos, como desde el panel. Un régimen general se confirma con `recc: false`.\n\nMismos criterios que la ficha del panel: fecha del criterio de caja, territorio foral incompatible con Canarias, Ceuta, Melilla y Andorra, preguntas de control con régimen de nueva creación y forma jurídica compatible con el NIF y las actividades. `administradores` y `titulares_reales` se sustituyen enteras.\n\nLongitud del plan contable, cuentas por defecto y códigos de enlace con otros programas: solo desde el panel.\n\nPermiso: clientes:escribir", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Consultas que el cliente ha abierto en su portal", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/consultas", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "consultas" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Cada una con su `asunto` (primera línea del mensaje), `estado` (`abierta` = sin respuesta del despacho, `respondida` = lo último es del despacho, `cerrada`), `origen` (cliente, chat o despacho) y `actualizada_at` (último mensaje).\n\nPermiso: consultas:leer" } }, { "name": "Abrir una consulta desde el despacho", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/clients/:id/consultas", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "consultas" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "El cliente la ve en «Mis consultas» con el despacho como autor del primer mensaje, y recibe el aviso por correo.\n\nPermiso: consultas:responder", "body": { "mode": "raw", "raw": "{\n \"texto\": \"\",\n \"autor_nombre\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "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": "Crear la dirección de correo de facturas del cliente", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/clients/:id/inbox", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "inbox" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Crea el buzón o reactiva el que estaba en pausa. Cuenta para el máximo de buzones del plan (409 `limite_buzones`); uno que ya está activo no cambia.\n\nPermiso: clientes:escribir" } }, { "name": "Dirección de correo de facturas del cliente", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/clients/:id/inbox", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "inbox" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "La dirección a la que el cliente (o sus proveedores) reenvía las facturas para que entren solas. `direccion` es null si aún no tiene buzón.\n\nPermiso: clientes:leer" } }, { "name": "Cuenta para domiciliar los impuestos del cliente", "request": { "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/clients/:id/tax-account", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "tax-account" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "La misma cuenta que el gestor pone en la ficha del cliente. `null` la borra. Errores con código: 422 `iban_invalido` (formato o dígito de control) e `iban_no_sepa` (fuera de la zona SEPA).\n\nPermiso propio, `clientes:cuenta_domiciliacion`. `GET /clients/{id}` la devuelve enmascarada (últimos cuatro), con su titular y la fecha del último cambio, cuando la clave tiene ese permiso. Cualquier cambio, también desde el panel, avisa con `client.tax_account_updated`.\n\nPermiso: clientes:cuenta_domiciliacion", "body": { "mode": "raw", "raw": "{\n \"iban_domiciliacion\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Reenviar el correo de bienvenida al portal", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/clients/:id/welcome", "host": [ "{{baseUrl}}" ], "path": [ "clients", ":id", "welcome" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "El mismo reenvío que el botón de la ficha del cliente en el panel.\n\n🚨 **Genera una contraseña nueva**: la anterior deja de valer. Con el portal cerrado, o un cliente sin correo, responde 409 sin enviar nada.\n\nPermiso: clientes:escribir" } } ] }, { "name": "consultas", "item": [ { "name": "Cerrar, reabrir o marcar como leída una consulta", "request": { "method": "PATCH", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/consultas/:id", "host": [ "{{baseUrl}}" ], "path": [ "consultas", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "\n\nPermiso: consultas:responder", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Hilo de una consulta", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/consultas/:id/mensajes", "host": [ "{{baseUrl}}" ], "path": [ "consultas", ":id", "mensajes" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "El mensaje inicial (`id = inicial`) y el resto, cada uno con `autor` (cliente o despacho), `autor_nombre`, `texto`, `fecha`, `leido` (si la otra parte ya lo ha abierto) y sus `adjuntos`, con la URL para descargarlos.\n\nPermiso: consultas:leer" } }, { "name": "Contestar una consulta como el despacho", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/consultas/:id/mensajes", "host": [ "{{baseUrl}}" ], "path": [ "consultas", ":id", "mensajes" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "El cliente ve la respuesta firmada con `autor_nombre` y recibe el mismo aviso por correo que si se contesta desde el panel. Si la consulta estaba cerrada, se reabre.\n\nCon adjuntos, en `multipart/form-data` (`adjuntos[]`, hasta 5 ficheros).\n\nPermiso: consultas:responder", "body": { "mode": "raw", "raw": "{\n \"texto\": \"\",\n \"autor_nombre\": \"\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Descargar un adjunto de una consulta", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/consultas/:id/mensajes/:m/adjuntos/:a", "host": [ "{{baseUrl}}" ], "path": [ "consultas", ":id", "mensajes", ":m", "adjuntos", ":a" ], "variable": [ { "key": "id", "value": "" }, { "key": "m", "value": "" }, { "key": "a", "value": "" } ] }, "description": "\n\nPermiso: consultas:leer" } } ] }, { "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": "Cambio de oct-2026: una petición puede quedar en `revisado` con `document_id` nulo. Es la que el cliente respondió sin documento («no hubo operación ese mes», «anulada», «no dispongo de ella»…) y la gestoría dio por buena. Ya no está pendiente y no admite subida.\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, modificarlos o darlos de baja, solo con `nominas:empleados`. Cada uno trae su `fecha_alta`, su `fecha_baja` y su `estado`.\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": "Modificar un trabajador o darle de baja", "request": { "method": "PATCH", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/employees/:id", "host": [ "{{baseUrl}}" ], "path": [ "employees", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Los datos se corrigen igual que en la ficha laboral del panel; el NIF no se cambia.\n\n**Baja:** `fecha_baja` y `causa_baja` (catálogo de la TGSS) juntas. Cierra sus contratos, deja de generarse su nómina desde el mes siguiente y, si tiene ficha laboral, registra el movimiento de baja en la Seguridad Social. Avisa con `employee.terminated`.\n\nPermiso: nominas:empleados", "body": { "mode": "raw", "raw": "{}", "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": "Modificar un contrato", "request": { "method": "PATCH", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/employment-contracts/:id", "host": [ "{{baseUrl}}" ], "path": [ "employment-contracts", ":id" ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Salario, jornada, fecha de fin, estado, complementos… Basta con enviar lo que cambia.\n\nQueda en el historial del contrato con su fecha de efecto (`efectivo_desde`) y su motivo. **Las nóminas ya emitidas no se recalculan**: la respuesta lo avisa en `aviso` si el cambio les afecta.\n\nPermiso: nominas:empleados", "body": { "mode": "raw", "raw": "{}", "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": "Deshacer un cobro de una factura emitida", "request": { "method": "DELETE", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" }, { "key": "Idempotency-Key", "value": "{{$guid}}" } ], "url": { "raw": "{{baseUrl}}/invoices/:id/payments/:paymentId", "host": [ "{{baseUrl}}" ], "path": [ "invoices", ":id", "payments", ":paymentId" ], "variable": [ { "key": "id", "value": "" }, { "key": "paymentId", "value": "" } ] }, "description": "Por ejemplo, si el recibo se devuelve. El `paymentId` es el de `historial_cobros` en `GET /invoices/{id}`.\n\nRevierte el asiento de tesorería del cobro y recalcula lo cobrado; si la factura deja de estar cobrada, reabre sus vencimientos. Con el cobro contabilizado en un periodo cerrado responde **409** `periodo_cerrado` y no cambia nada. Un cobro que entró con una remesa o un confirming responde **409** `cobro_de_remesa`: se deshace desde la remesa, en el panel. Avisa con `invoice.payment_reversed`.\n\nPermiso: facturas:cobros" } }, { "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": "payroll-inputs", "item": [ { "name": "Incidencias del mes registradas", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/payroll-inputs", "host": [ "{{baseUrl}}" ], "path": [ "payroll-inputs" ] }, "description": "Conceptos variables (horas extra, dietas, anticipos…), baja médica y situaciones del mes de cada trabajador.\n\nPermiso: nominas:leer" } }, { "name": "Registrar incidencias del mes de 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}}/payroll-inputs", "host": [ "{{baseUrl}}" ], "path": [ "payroll-inputs" ] }, "description": "Entran por el mismo camino que la plantilla de incidencias del panel, y un concepto ya registrado en el mes se actualiza.\n\n**Claves de concepto admitidas:** `salario_base`, `antiguedad`, `plus_convenio`, `plus_puesto`, `plus_penosidad`, `plus_toxicidad`, `plus_peligrosidad`, `nocturnidad`, `turnicidad`, `festivos`, `guardias`, `incentivos`, `comisiones`, `bonus`, `horas_complementarias`, `horas_extra_fuerza_mayor`, `horas_extra_estructurales`, `horas_extra_no_estructurales`, `prorrata_pagas_extras`, `paga_extra`, `atrasos_convenio`, `vacaciones_no_disfrutadas`, `salarios_preaviso`, `salario_especie`, `plus_transporte`, `dietas`, `locomocion`, `prestacion_it`, `complemento_it`, `indemnizacion`, `suplidos`, `anticipo`, `prestamo_empresa`, `embargo`, `cuota_sindical`, `sancion`, `permiso_no_retribuido`, `huelga`, `ausencia_injustificada`, `otras_deducciones`. Con una sola clave fuera del catálogo responde **422** y no registra nada (la petición entra entera o no entra).\n\nSi el periodo de ese trabajador ya está cerrado responde **409** `periodo_cerrado`: lo que haya que pagar de más va en un recibo complementario.\n\nPermiso: nominas:empleados", "body": { "mode": "raw", "raw": "{\n \"empleado_id\": 0,\n \"periodo\": \"\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "payrolls", "item": [ { "name": "Nóminas del cliente", "request": { "method": "GET", "header": [ { "key": "X-CG-Client", "value": "{{clienteId}}" } ], "url": { "raw": "{{baseUrl}}/payrolls", "host": [ "{{baseUrl}}" ], "path": [ "payrolls" ] }, "description": "Une las nóminas **calculadas** en Copilot y las **subidas** ya hechas (`origen`). Cada una trae periodo, trabajador (`empleado_id` y `nif`), `tipo_recibo`, `secuencia`, `rectifica_a`, `estado` y `anulada`.\n\n**Para contar una nómina por trabajador y mes**, cuenta las que traen `en_recuento = true`: es exactamente una por trabajador y mes. Una ordinaria recalculada es la misma nómina, y una complementaria, una paga extra, unos atrasos o un finiquito son recibos aparte (`secuencia` 2 o más) y no entran en el recuento. Una nómina subida se trata como ordinaria. Si un trabajador tiene más de una nómina ese mes (una calculada y una subida, o dos subidas), cuenta la calculada —o, si no la hay, la primera subida— y todas las de ese trabajador y mes salen con `requiere_revision = true` para que el despacho lo revise.\n\n**Cuándo está cerrada:** cuando el despacho cierra el periodo del cliente, por cuenta de cotización. Un cierre se puede reabrir (evento `payroll.period_reopened`), y una nómina de un trabajador sin NAF se paga pero sigue en `calculada`.\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": "Lo mismo que en la lista, más la retención de IRPF. El identificador de una nómina subida es un UUID; el de una calculada, un número.\n\nPermiso: nominas:leer" } } ] }, { "name": "portal-profiles", "item": [ { "name": "Perfiles de acceso al portal de la gestoría", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/portal-profiles", "host": [ "{{baseUrl}}" ], "path": [ "portal-profiles" ] }, "description": "Cada perfil fija las secciones que ven los clientes que lo tienen: en el portal web (`secciones`) y en la app (`secciones_app`). Se crean en el panel y se asignan con `PATCH /clients/{id}` (`perfil_portal`).\n\nPermiso: clientes: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" } } ] } ] }