{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/fe.almendro.cr" } ], "info": { "name": "Almendro Factura Electr\u00f3nica | API REST v1.0.0", "_postman_id": "370b141a-8d37-4a19-8b80-ae21b5ae1ff1", "description": "Almendro Factura Electr\u00f3nica | API REST v1 | Facturaci\u00f3n electr\u00f3nica Costa Rica XML v4.4", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json", "version": "1.0.0" }, "item": [ { "name": "Comprobantes Electr\u00f3nicos", "description": "", "item": [ { "name": "Listar comprobantes con filtros y paginaci\u00f3n", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers", "query": [ { "key": "status", "value": "accepted%2Crejected", "description": "Estado(s) separados por coma. `draft`, `pending`, `sent`, `accepted`, `rejected`, `error`, `cancelled`.", "disabled": false }, { "key": "voucher_type", "value": "01%2C04", "description": "Tipo(s) separados por coma. `01`=FE, `02`=ND, `03`=NC, `04`=TE, `08`=FEC, `09`=FEE, `10`=REP.", "disabled": false }, { "key": "date_from", "value": "2026-04-01", "description": "Fecha de emisi\u00f3n desde (YYYY-MM-DD).", "disabled": false }, { "key": "date_to", "value": "2026-04-30", "description": "Fecha de emisi\u00f3n hasta (YYYY-MM-DD).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos).", "disabled": false }, { "key": "external_reference", "value": "ORD-12345", "description": "Su identificador del documento, tal como lo envi\u00f3 al\n emitir. Coincidencia exacta. Es la forma de averiguar si una emisi\u00f3n se complet\u00f3 cuando la\n respuesta no le lleg\u00f3: consulte por la referencia de su orden antes de reintentar.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: `sandbox` o `production`.", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "C\u00f3digo ISO 4217.", "disabled": false }, { "key": "contributor_id", "value": "019d867d-0241-7288-8ece-fd64da75616d", "description": "UUID del cliente gestionado cuyos comprobantes quiere ver.\n Solo para integradores con relaci\u00f3n activa. Sin \u00e9l ve los suyos.", "disabled": false }, { "key": "scope", "value": "own", "description": "`all` (default) o `own` para excluir los emitidos a nombre de clientes gestionados.", "disabled": false }, { "key": "sort_by", "value": "issued_at", "description": "Campo de ordenamiento. Default: `issued_at`.", "disabled": false }, { "key": "sort_dir", "value": "desc", "description": "Direcci\u00f3n: `asc` o `desc`. Default: `desc`.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100). Default: 15.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers?status=accepted%2Crejected&voucher_type=01%2C04&date_from=2026-04-01&date_to=2026-04-30&receiver_id_number=3101234567&external_reference=ORD-12345&environment=production¤cy_code=CRC&contributor_id=019d867d-0241-7288-8ece-fd64da75616d&scope=own&sort_by=issued_at&sort_dir=desc&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todos los comprobantes emitidos por el contribuyente,\ncon paginaci\u00f3n y filtros por estado, tipo, rango de fechas, receptor,\nambiente y moneda. Los filtros `status` y `voucher_type` aceptan\nm\u00faltiples valores separados por coma.\n\nEl listado retorna campos resumidos (sin XML ni totales detallados)\npara m\u00e1xima eficiencia. Para el detalle completo de un comprobante,\nuse `GET \/vouchers\/{key}`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"voucher_key\": \"50620032600206270652001000010100000000011XXXXXXXX\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"consecutive_number\": \"00100001010000000001\",\n \"issued_at\": \"2026-03-20T10:30:00-06:00\",\n \"situation\": \"1\",\n \"sale_condition\": \"01\",\n \"sale_condition_label\": \"Contado\",\n \"receiver\": {\"id_type\": \"02\", \"id_number\": \"3102345678\", \"name\": \"Empresa S.A.\"},\n \"currency_code\": \"CRC\",\n \"total_comprobante\": \"56500.00000\",\n \"status\": \"accepted\",\n \"hacienda\": {\"status\": \"aceptado\", \"sent_at\": \"2026-03-20T10:31:00-06:00\", \"processed_at\": \"2026-03-20T10:32:00-06:00\"},\n \"environment\": \"sandbox\",\n \"is_xml_available\": true,\n \"line_items_count\": 3,\n \"created_at\": \"2026-03-20T10:30:00-06:00\",\n \"updated_at\": \"2026-03-20T10:32:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 5, \"per_page\": 15, \"total\": 72, \"from\": 1, \"to\": 15},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": \"...\"}\n}", "name": "Listado paginado" } ] }, { "name": "GET \/api\/v1\/public\/vouchers\/issuers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/issuers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/issuers" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Opciones disponibles para los filtros del listado, calculadas a partir\nde los comprobantes que realmente existen (acotados al ambiente). Evita\nofrecer en los desplegables valores que no devolver\u00edan nada.\n\nRetorna:\n has_own \u2192 true si la cuenta tiene comprobantes propios\n clients \u2192 clientes gestionados con al menos un comprobante\n voucher_types \u2192 tipos de comprobante presentes (01, 03, \u2026)\n statuses \u2192 estados presentes (accepted, rejected, \u2026)" }, "response": [] }, { "name": "Emitir un comprobante electr\u00f3nico", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "Identificador \u00fanico de ESTA emisi\u00f3n, generado por usted (recomendado: un" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_type\":\"01\",\"situation\":\"1\",\"local_code\":\"564\",\"terminal_code\":\"56425\",\"voucher_key\":\"56425593142326822820492192294472586671521743076933\",\"consecutive_number\":\"56425593142326822820\",\"issued_at\":\"2026-04-20T10:30:00-06:00\",\"issuer_activity_code\":\"6201.0\",\"receiver_activity_code\":\"4711.0\",\"sale_condition\":\"01\",\"sale_condition_other\":\"Acuerdo especial de intercambio\",\"credit_term\":\"30\",\"currency_code\":\"CRC\",\"exchange_rate\":\"1.00000\",\"external_reference\":\"ORD-12345\",\"xml_otros\":[{\"tipo\":\"texto\",\"codigo\":\"orden\",\"valor\":\"ORD-0001\"}],\"client_id\":\"019d1234-0000-0000-0000-000000000001\",\"managed_contributor_id\":\"019d867d-0241-7288-8ece-fd64da75616d\",\"receiver\":{\"name\":\"Empresa Ejemplo S.A.\",\"id_type\":\"02\",\"id_number\":\"3101000001\",\"commercial_name\":\"p\",\"emails\":[\"architecto\"],\"province\":1,\"canton\":\"56\",\"district\":\"56\",\"address\":\"i\",\"phone_country_code\":8,\"phone\":\"564255931\"},\"line_items\":[{\"item_id\":\"019d1234-0000-0000-0000-000000000002\",\"line_number\":1,\"cabys_code\":\"5311100000000\",\"arancelary_partition\":\"564255931423\",\"quantity\":\"1.000\",\"unit_of_measure\":\"Unid\",\"detail\":\"Servicio de consultor\u00eda\",\"unit_price\":\"10000.00000\",\"total_amount\":\"10000.00000\",\"sub_total\":\"10000.00000\",\"base_imponible\":\"10000.00000\",\"discounts\":[{\"monto\":39,\"codigo\":6}],\"taxes\":[{\"codigo\":\"01\",\"codigoTarifa\":\"08\",\"tarifa\":\"13.00\",\"factorCalculo\":4326.41688,\"monto\":\"1300.00000\",\"monto_exportacion\":77,\"exoneracion\":{\"tipoDocumento\":\"iy\",\"numeroDocumento\":\"v\",\"nombreInstitucion\":\"d\",\"fechaEmision\":\"2026-08-11T21:37:46\",\"tarifaExonerada\":37,\"montoExoneracion\":9}}],\"impuesto_neto\":\"1300.00000\",\"total_line_amount\":\"11300.00000\",\"medicine_registration\":\"n\",\"pharma_form_code\":\"564\",\"commercial_codes\":[{\"tipo\":4,\"codigo\":\"yvdljnikhwaykcmy\"}],\"vin_numbers\":[\"u\"]}],\"references\":[{\"doc_type\":\"01\",\"number\":\"50613032600206270652001000010100000000001XXXXXXXX\",\"issued_at\":\"2026-03-01T10:00:00-06:00\",\"code\":\"01\",\"reason\":\"Anulaci\u00f3n por error en monto\"}],\"payment_methods\":[{\"tipo\":\"01\"}],\"other_charges\":[{\"tipo\":\"06\",\"description\":\"Quidem nostrum qui commodi incidunt iure odit.\",\"percentage\":10,\"amount\":5000}]}" }, "description": "Genera, valida contra el XSD oficial v4.4, firma digitalmente con\nXAdES-EPES y env\u00eda autom\u00e1ticamente a Hacienda cualquiera de los 7\ntipos de comprobante soportados.\n\nLa respuesta es **HTTP 202 Accepted** | el env\u00edo a Hacienda es\nas\u00edncrono. Para obtener el resultado final (aceptado\/rechazado),\nsuscr\u00edbase a los eventos `voucher.accepted` y `voucher.rejected` v\u00eda\nwebhooks (ver grupo **Webhooks**), o consulte peri\u00f3dicamente\n`GET \/vouchers\/{key}`.\n\n> **HTTP 202 no significa \"aceptado por Hacienda\".** Solo confirma\n> que el comprobante fue generado, firmado y encolado exitosamente.\n> El estado inicial en la respuesta es `pending`.\n\nPara ejemplos completos de payload por cada tipo de comprobante,\nrevise la secci\u00f3n **\"Ejemplos completos de payload por tipo\"** de\nla gu\u00eda de integraci\u00f3n al inicio de este grupo." }, "response": [ { "header": [], "code": 202, "body": "{\n \"success\": true,\n \"data\": {\n \"voucher_key\": \"50620042600206270652001000010100000000011XXXXXXXX\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"consecutive_number\": \"00100001010000000001\",\n \"issued_at\": \"2026-04-20T10:30:00-06:00\",\n \"situation\": \"1\",\n \"situation_label\": \"Normal\",\n \"sale_condition\": \"01\",\n \"sale_condition_label\": \"Contado\",\n \"sale_condition_other\": null,\n \"credit_term\": null,\n \"receiver\": {\n \"id_type\": \"02\",\n \"id_number\": \"3101000001\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"commercial_name\": null,\n \"emails\": [\"facturacion@ejemplo.cr\"]\n },\n \"currency_code\": \"CRC\",\n \"exchange_rate\": \"1.00000\",\n \"totals\": {\n \"serv_gravados\": \"10000.00000\",\n \"serv_exentos\": \"0.00000\",\n \"serv_exonerado\": \"0.00000\",\n \"serv_no_sujeto\": \"0.00000\",\n \"merc_gravadas\": \"0.00000\",\n \"merc_exentas\": \"0.00000\",\n \"merc_exonerada\": \"0.00000\",\n \"merc_no_sujeta\": \"0.00000\",\n \"total_gravado\": \"10000.00000\",\n \"total_exento\": \"0.00000\",\n \"total_exonerado\": \"0.00000\",\n \"total_no_sujeto\": \"0.00000\",\n \"total_venta\": \"10000.00000\",\n \"total_descuentos\": \"0.00000\",\n \"total_venta_neta\": \"10000.00000\",\n \"total_impuesto\": \"1300.00000\",\n \"total_imp_asum_emisor_fab\": \"0.00000\",\n \"total_iva_devuelto\": \"0.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"11300.00000\"\n },\n \"payment_methods\": [{\"tipo\": \"01\"}],\n \"status\": \"pending\",\n \"hacienda\": {\n \"status\": null,\n \"message\": null,\n \"sent_at\": null,\n \"processed_at\": null\n },\n \"environment\": \"production\",\n \"is_xml_available\": true,\n \"line_items_count\": 1,\n \"references_count\": 0,\n \"created_at\": \"2026-04-20T10:30:00-06:00\",\n \"updated_at\": \"2026-04-20T10:30:00-06:00\"\n },\n \"message\": \"Comprobante [50620042600206270652001000010100000000011XXXXXXXX] generado y encolado para env\u00edo a Hacienda.\",\n \"errors\": null\n}", "name": "Comprobante emitido correctamente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"voucher_type\": [\"El campo voucher_type es obligatorio.\"]}\n}", "name": "Error de validaci\u00f3n del payload" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Validaci\u00f3n XSD fallida para Factura Electr\u00f3nica (01) | 1 error. Primer error: [45:12] Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'.\",\n \"errors\": {\n \"voucher_type\": [\"01\"],\n \"xsd\": [\n {\"nivel\": \"error\", \"codigo\": 1824, \"linea\": 45, \"columna\": 12, \"mensaje\": \"Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'.\"}\n ]\n }\n}", "name": "Error de validaci\u00f3n XSD (no consume consecutivo)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo firmar el comprobante. El certificado digital est\u00e1 vencido. Renueve su certificado con el BCCR y vuelva a subirlo.\",\n \"errors\": {\"signature\": [\"...\"], \"code\": [\"2002\"]}\n}", "name": "Error de firma digital (consume consecutivo)" }, { "header": [], "code": 429, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"L\u00edmite mensual de comprobantes alcanzado (50\/50). Actualice a PyME para emitir m\u00e1s. Per\u00edodo: junio 2026. Precio: $29.99\/mes \u2248 \u20a115,745.\",\n \"errors\": null\n}", "name": "Cupo mensual agotado (plan sin overage)" } ] }, { "name": "Listar comprobantes de contingencia pendientes", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/pending-contingency", "query": [ { "key": "situation", "value": "3", "description": "Filtrar por situaci\u00f3n. `2`=Contingencia, `3`=Sin internet. Sin valor muestra ambas.", "disabled": false }, { "key": "expired_only", "value": "1", "description": "Mostrar solo los que superaron el plazo de 2 d\u00edas h\u00e1biles. Default: `false`.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/pending-contingency?situation=3&expired_only=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los comprobantes emitidos en **situaci\u00f3n de contingencia**\n(ca\u00edda del sistema) o **sin internet**, que a\u00fan no fueron aceptados\nni rechazados por Hacienda.\n\nLa normativa establece un plazo m\u00e1ximo de **2 d\u00edas h\u00e1biles** para\nremitir los comprobantes de contingencia. Este endpoint le muestra\ncu\u00e1ntos est\u00e1n pendientes y cu\u00e1ntos ya superaron el plazo, para\nayudarle a cumplir con el monitoreo requerido antes de incurrir en\ninfracciones tributarias.\n\n**Estados incluidos:** `draft`, `pending`, `sent`, `error`.\n\nLos comprobantes ya resueltos (`accepted`, `rejected`, `cancelled`)\nno aparecen aqu\u00ed." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"items\": [\n {\n \"voucher_key\": \"50617042026...\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"consecutive_number\": \"00100001010000000001\",\n \"status\": \"error\",\n \"situation\": \"3\",\n \"situation_label\": \"Sin Internet\",\n \"issued_at\": \"2026-04-10T14:30:00-06:00\",\n \"deadline\": \"2026-04-14\",\n \"elapsed_business_days\": 3,\n \"is_expired\": true,\n \"receiver\": {\"id_type\": \"02\", \"id_number\": \"3101000001\", \"name\": \"Empresa S.A.\"},\n \"currency_code\": \"CRC\",\n \"total_comprobante\": \"56500.00000\"\n }\n ],\n \"total\": 5,\n \"expired_count\": 2\n },\n \"message\": \"5 comprobante(s) de contingencia sin resolver. 2 superan el plazo de 2 d\u00edas h\u00e1biles.\",\n \"errors\": null\n}", "name": "Con comprobantes pendientes" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"items\": [], \"total\": 0, \"expired_count\": 0},\n \"message\": \"Sin comprobantes de contingencia pendientes.\",\n \"errors\": null\n}", "name": "Sin pendientes" } ] }, { "name": "Consultar un comprobante por clave", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key", "variable": [ { "id": "key", "key": "key", "value": "50619032600310199999900100001010000000001112345678", "description": "Clave de 50 d\u00edgitos del comprobante." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle completo de un comprobante identificado por su\nclave de 50 d\u00edgitos: datos del emisor y receptor, l\u00edneas, totales,\nestado actual y respuesta de Hacienda (si ya fue procesado).\n\nLa clave debe tener exactamente 50 d\u00edgitos num\u00e9ricos | formatos\ninv\u00e1lidos retornan 404 sin procesar la consulta." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"voucher_key\": \"50619032600310199999900100001010000000001112345678\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"consecutive_number\": \"00100001010000000001\",\n \"issued_at\": \"2026-04-13T10:00:00-06:00\",\n \"situation\": \"1\",\n \"situation_label\": \"Normal\",\n \"sale_condition\": \"01\",\n \"sale_condition_label\": \"Contado\",\n \"sale_condition_other\": null,\n \"credit_term\": null,\n \"receiver\": {\n \"id_type\": \"02\",\n \"id_number\": \"3101000001\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"commercial_name\": \"Ejemplo Comercial\",\n \"emails\": [\"facturacion@ejemplo.cr\"]\n },\n \"currency_code\": \"CRC\",\n \"exchange_rate\": \"1.00000\",\n \"totals\": {\n \"serv_gravados\": \"10000.00000\",\n \"serv_exentos\": \"0.00000\",\n \"serv_exonerado\": \"0.00000\",\n \"serv_no_sujeto\": \"0.00000\",\n \"merc_gravadas\": \"0.00000\",\n \"merc_exentas\": \"0.00000\",\n \"merc_exonerada\": \"0.00000\",\n \"merc_no_sujeta\": \"0.00000\",\n \"total_gravado\": \"10000.00000\",\n \"total_exento\": \"0.00000\",\n \"total_exonerado\": \"0.00000\",\n \"total_no_sujeto\": \"0.00000\",\n \"total_venta\": \"10000.00000\",\n \"total_descuentos\": \"0.00000\",\n \"total_venta_neta\": \"10000.00000\",\n \"total_impuesto\": \"1300.00000\",\n \"total_imp_asum_emisor_fab\": \"0.00000\",\n \"total_iva_devuelto\": \"0.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"11300.00000\"\n },\n \"payment_methods\": [{\"tipo\": \"01\"}],\n \"status\": \"accepted\",\n \"hacienda\": {\n \"status\": \"aceptado\",\n \"message\": null,\n \"sent_at\": \"2026-04-13T10:01:00-06:00\",\n \"processed_at\": \"2026-04-13T10:02:00-06:00\"\n },\n \"environment\": \"production\",\n \"is_xml_available\": true,\n \"line_items_count\": 1,\n \"references_count\": 0,\n \"created_at\": \"2026-04-13T10:00:00-06:00\",\n \"updated_at\": \"2026-04-13T10:02:00-06:00\"\n },\n \"message\": \"Comprobante obtenido correctamente.\",\n \"errors\": null\n}", "name": "Comprobante encontrado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El recurso solicitado no existe.\",\n \"errors\": null\n}", "name": "Comprobante no encontrado" } ] }, { "name": "Anular un comprobante (emite una Nota de Cr\u00e9dito)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key\/cancel", "variable": [ { "id": "key", "key": "key", "value": "50619032600310199999900100001010000000001112345678", "description": "Clave de 50 d\u00edgitos del comprobante a anular." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "Identificador \u00fanico de ESTA anulaci\u00f3n, generado por usted. Es OPCIONAL," }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "En Costa Rica, la anulaci\u00f3n de un comprobante electr\u00f3nico NO es una\noperaci\u00f3n directa. El mecanismo normativo es emitir una **Nota de\nCr\u00e9dito** que referencia al comprobante original con el c\u00f3digo\n`01` (Anula documento).\n\nEste endpoint automatiza ese proceso:\n\n1. Lee el comprobante original por su clave.\n2. Construye autom\u00e1ticamente el payload de la NC (mismas l\u00edneas,\n mismo receptor) con la referencia correspondiente.\n3. La emite por el mismo pipeline que `POST \/vouchers` (valida XSD,\n firma, env\u00eda a Hacienda).\n4. Retorna la NC generada con **HTTP 202**.\n\n**Restricciones:**\n\n- Solo comprobantes en estado `accepted` pueden anularse.\n- Solo FE (`01`) y TE (`04`) son anulables con NC.\n- Un comprobante ya cancelado no puede re-cancelarse." }, "response": [ { "header": [], "code": 202, "body": "{\n \"success\": true,\n \"data\": {\n \"voucher_key\": \"50621042600310199999900100001010000000002212345679\",\n \"voucher_type\": \"03\",\n \"voucher_type_label\": \"Nota de Cr\u00e9dito\",\n \"consecutive_number\": \"00100001030000000001\",\n \"status\": \"pending\",\n \"environment\": \"production\",\n \"created_at\": \"2026-04-21T11:00:00-06:00\"\n },\n \"message\": \"NC de anulaci\u00f3n generada. Encolada para env\u00edo a Hacienda.\",\n \"errors\": null\n}", "name": "NC de anulaci\u00f3n generada" }, { "header": [], "code": 409, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Solo comprobantes aceptados por Hacienda pueden anularse.\",\n \"errors\": null\n}", "name": "El estado no permite anulaci\u00f3n" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Validaci\u00f3n XSD fallida para Nota de Cr\u00e9dito (03) | ...\",\n \"errors\": {\"voucher_type\": [\"03\"], \"xsd\": [{\"linea\": 45, \"columna\": 12, \"mensaje\": \"...\"}]}\n}", "name": "Error de validaci\u00f3n XSD de la NC" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo firmar el comprobante. El certificado digital est\u00e1 vencido.\",\n \"errors\": {\"signature\": [\"...\"], \"code\": [\"2002\"]}\n}", "name": "Error de firma de la NC" } ] }, { "name": "Reenviar a Hacienda un comprobante que qued\u00f3 sin enviarse", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key\/resend", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key\/resend", "variable": [ { "id": "key", "key": "key", "value": "50617062600020627065200100001010000000101173247335", "description": "Clave de 50 d\u00edgitos." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Reintenta la emisi\u00f3n de un comprobante que NO lleg\u00f3 a Hacienda y por lo\ntanto NO consumi\u00f3 consecutivo all\u00e1: t\u00edpicamente qued\u00f3 en `draft` con su\nXML generado pero sin firmar (fall\u00f3 la firma por falta de certificado).\nUna vez subido el .p12, este endpoint lo firma y lo encola | **reusando\nel mismo comprobante y consecutivo**, sin generar huecos de numeraci\u00f3n.\n\nTambi\u00e9n cubre el estado `error` (Hacienda no lo proces\u00f3 por un fallo\ntemporal; ya est\u00e1 firmado y solo se reencola).\n\nEl ambiente del reenv\u00edo es el del comprobante original (un comprobante\nsandbox se firma con el certificado sandbox y se env\u00eda a sandbox)." }, "response": [] }, { "name": "Descargar el XML firmado del comprobante", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key\/xml", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key\/xml", "variable": [ { "id": "key", "key": "key", "value": "50619032600310199999900100001010000000001112345678", "description": "Clave de 50 d\u00edgitos." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el XML completo con firma digital XAdES-EPES, tal como\nfue enviado a la API de recepci\u00f3n de Hacienda. Este XML es el\n**documento fiscal con validez legal**.\n\n> **Obligaci\u00f3n de archivo:** la normativa exige conservar este XML\n> por **5 a\u00f1os**. Desc\u00e1rguelo y arch\u00edvelo de su lado dentro del\n> per\u00edodo de retenci\u00f3n de la plataforma (3 meses por defecto, hasta\n> 5 a\u00f1os con el add-on de retenci\u00f3n extendida).\n\n**Disponibilidad:**\n\n- Solo comprobantes que ya pasaron la firma digital tienen XML.\n- Comprobantes en `draft` a\u00fan no tienen XML \u2192 **404**.\n- Comprobantes cuyo XML fue purgado (retenci\u00f3n expirada) \u2192 **410 Gone**.\n\nDespu\u00e9s de la retenci\u00f3n, los metadatos del comprobante y el PDF\nsiguen disponibles | solo el XML deja de estar accesible." }, "response": [ { "header": [], "code": 200, "body": "[archivo binario application\/xml]", "name": "XML disponible" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El XML firmado a\u00fan no est\u00e1 disponible. El comprobante est\u00e1 en estado 'draft'.\",\n \"errors\": null\n}", "name": "XML a\u00fan no generado" }, { "header": [], "code": 410, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"XML purgado. Retenci\u00f3n expirada el 2026-06-15.\",\n \"errors\": null\n}", "name": "XML purgado | retenci\u00f3n expirada" } ] }, { "name": "Descargar el XML de respuesta de Hacienda (MensajeHacienda)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key\/xml-response", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key\/xml-response", "variable": [ { "id": "key", "key": "key", "value": "50619032600310199999900100001010000000001112345678", "description": "Clave de 50 d\u00edgitos." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el **MensajeHacienda XML** firmado por Hacienda que\nrepresenta el resultado oficial del procesamiento del comprobante.\nIncluye:\n\n- `Mensaje`: `1`=Aceptado, `3`=Rechazado.\n- `DetalleMensaje`: descripci\u00f3n del error (si fue rechazado).\n- `MontoTotalImpuesto`: monto de impuesto validado por Hacienda.\n\nEste XML es evidencia oficial de la validaci\u00f3n ante Hacienda. Su\nobligaci\u00f3n legal de archivo es de **5 a\u00f1os**, igual que el XML firmado.\n\n**Disponibilidad:**\n\n- Solo comprobantes que Hacienda ya proces\u00f3 (estado `accepted` o\n `rejected`) tienen este XML.\n- Comprobantes en tr\u00e1nsito (`pending`, `sent`) \u2192 **404**.\n- Si la retenci\u00f3n expir\u00f3 \u2192 **410 Gone**." }, "response": [ { "header": [], "code": 200, "body": "[archivo binario application\/xml]", "name": "XML respuesta disponible" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"La respuesta de Hacienda a\u00fan no est\u00e1 disponible. El comprobante est\u00e1 en estado 'sent'.\",\n \"errors\": null\n}", "name": "Respuesta a\u00fan no disponible" }, { "header": [], "code": 410, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"XML purgado. Retenci\u00f3n expirada el 2026-06-15.\",\n \"errors\": null\n}", "name": "XML purgado | retenci\u00f3n expirada" } ] }, { "name": "Descargar la representaci\u00f3n gr\u00e1fica (PDF) del comprobante", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/:key\/pdf", "query": [ { "key": "template_id", "value": "16", "description": "ID de una plantilla espec\u00edfica. Si no se env\u00eda, usa la plantilla default del contribuyente.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/:key\/pdf?template_id=16", "variable": [ { "id": "key", "key": "key", "value": "50619032600310199999900100001010000000001112345678", "description": "Clave de 50 d\u00edgitos." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Genera y devuelve el PDF del comprobante usando la plantilla por\ndefecto del contribuyente (o una espec\u00edfica si se indica v\u00eda\n`template_id`). El PDF incluye obligatoriamente un **c\u00f3digo QR con\nla clave de 50 d\u00edgitos** en la esquina inferior derecha, con\ntama\u00f1o m\u00ednimo de 2.5 cm conforme a la normativa.\n\n**Disponibilidad:**\n\n- Solo comprobantes que ya pasaron la firma (estado \u2260 `draft`).\n- El contribuyente debe tener al menos una plantilla PDF activa\n marcada como default.\n- El PDF **permanece disponible** incluso si el XML fue purgado \u2014\n los metadatos y totales nunca se eliminan.\n\nPara gestionar plantillas PDF personalizadas, vea el grupo\n**Plantillas PDF** de esta documentaci\u00f3n." }, "response": [ { "header": [], "code": 200, "body": "[archivo binario application\/pdf]", "name": "PDF generado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El PDF no est\u00e1 disponible. El comprobante est\u00e1 en estado 'draft'.\",\n \"errors\": null\n}", "name": "Comprobante en draft" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El contribuyente no tiene plantilla PDF default activa.\",\n \"errors\": null\n}", "name": "Sin plantilla PDF default activa" } ] } ] }, { "name": "Comprobantes \/ Borradores", "description": "", "item": [ { "name": "Listar borradores del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts", "query": [ { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100). Default: 15.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts?per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los borradores del wizard de emisi\u00f3n guardados por el\ncontribuyente, ordenados del m\u00e1s reciente al m\u00e1s antiguo (por fecha de\n\u00faltima actualizaci\u00f3n). Un borrador es el estado parcial de un comprobante\nen construcci\u00f3n; **no es un comprobante fiscal** ni consume consecutivo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-aaaa-7288-8ece-fd64da756001\",\n \"voucher_type\": \"01\",\n \"payload\": {\"client_id\": null, \"line_items\": [], \"currency_code\": \"CRC\"},\n \"totals_preview\": {\n \"currency_code\": \"CRC\",\n \"line_count\": 0,\n \"total_venta\": \"0.00000\",\n \"total_descuento\": \"0.00000\",\n \"total_gravado\": \"0.00000\",\n \"total_exento\": \"0.00000\",\n \"total_venta_neta\": \"0.00000\",\n \"total_impuesto\": \"0.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"0.00000\"\n },\n \"comments\": \"Esperando datos del cliente.\",\n \"validation\": null,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:30:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1, \"from\": 1, \"to\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Listado paginado" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 0, \"from\": null, \"to\": null},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Sin borradores" } ] }, { "name": "Crear un borrador", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_type\":\"01\",\"payload\":{\"client_id\":null,\"line_items\":[],\"currency_code\":\"CRC\"},\"comments\":\"Esperando datos del cliente.\"}" }, "description": "Guarda el estado parcial del wizard. NO consume consecutivo. Devuelve la\nvalidaci\u00f3n en vivo (errores condicionales + preview de totales).\n\nEl `payload` es el cuerpo PARCIAL del comprobante (mismo contrato que\n`POST \/vouchers`, pero puede estar incompleto entre pasos del wizard)." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-aaaa-7288-8ece-fd64da756001\",\n \"voucher_type\": \"01\",\n \"payload\": {\"client_id\": null, \"line_items\": [], \"currency_code\": \"CRC\"},\n \"totals_preview\": {\n \"currency_code\": \"CRC\",\n \"line_count\": 0,\n \"total_venta\": \"0.00000\",\n \"total_descuento\": \"0.00000\",\n \"total_gravado\": \"0.00000\",\n \"total_exento\": \"0.00000\",\n \"total_venta_neta\": \"0.00000\",\n \"total_impuesto\": \"0.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"0.00000\"\n },\n \"comments\": \"Esperando datos del cliente.\",\n \"validation\": {\n \"valid\": false,\n \"errors\": {\n \"line_items\": [\"Agreg\u00e1 al menos una l\u00ednea de detalle.\"],\n \"sale_condition\": [\"Indic\u00e1 la condici\u00f3n de venta.\"]\n },\n \"totals\": {\n \"currency_code\": \"CRC\",\n \"line_count\": 0,\n \"total_comprobante\": \"0.00000\"\n }\n },\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Borrador guardado.\",\n \"errors\": null\n}", "name": "Borrador guardado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"payload\": [\"El cuerpo del borrador (payload) es obligatorio.\"]}\n}", "name": "Payload ausente o inv\u00e1lido" } ] }, { "name": "Consultar un borrador (con validaci\u00f3n en vivo)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-aaaa-7288-8ece-fd64da756001", "description": "UUID del borrador." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle del borrador indicado, recalculando en el momento la\n**validaci\u00f3n en vivo** (errores condicionales + preview de totales) sin\npersistirla. Solo se retornan borradores que pertenecen a su\ncontribuyente. Un `id` que no sea un UUID v\u00e1lido retorna **404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-aaaa-7288-8ece-fd64da756001\",\n \"voucher_type\": \"01\",\n \"payload\": {\"client_id\": null, \"line_items\": [], \"currency_code\": \"CRC\"},\n \"totals_preview\": {\n \"currency_code\": \"CRC\",\n \"line_count\": 0,\n \"total_comprobante\": \"0.00000\"\n },\n \"comments\": \"Esperando datos del cliente.\",\n \"validation\": {\n \"valid\": false,\n \"errors\": {\"line_items\": [\"Agreg\u00e1 al menos una l\u00ednea de detalle.\"]},\n \"totals\": {\"currency_code\": \"CRC\", \"line_count\": 0, \"total_comprobante\": \"0.00000\"}\n },\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:30:00-06:00\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Borrador encontrado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] }, { "name": "Guardar un paso del wizard (actualizaci\u00f3n del borrador)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-aaaa-7288-8ece-fd64da756001", "description": "UUID del borrador." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_type\":\"01\",\"payload\":{\"client_id\":\"019d867d-0001-7288-8ece-fd64da756001\",\"sale_condition\":\"01\",\"line_items\":[{\"quantity\":1,\"unit_price\":1000}]},\"comments\":\"Listo para emitir.\"}" }, "description": "Reemplaza el estado del borrador con lo enviado (`voucher_type`,\n`payload` y `comments`) y vuelve a calcular la validaci\u00f3n en vivo\n(errores condicionales + preview de totales), persistiendo el preview.\nNO consume consecutivo ni firma. Un `id` que no sea un UUID v\u00e1lido\nretorna **404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-aaaa-7288-8ece-fd64da756001\",\n \"voucher_type\": \"01\",\n \"payload\": {\"client_id\": \"019d867d-0001-7288-8ece-fd64da756001\", \"sale_condition\": \"01\", \"line_items\": [{\"quantity\": 1, \"unit_price\": 1000}]},\n \"totals_preview\": {\n \"currency_code\": \"CRC\",\n \"line_count\": 1,\n \"total_venta\": \"1000.00000\",\n \"total_descuento\": \"0.00000\",\n \"total_gravado\": \"1000.00000\",\n \"total_exento\": \"0.00000\",\n \"total_venta_neta\": \"1000.00000\",\n \"total_impuesto\": \"130.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"1130.00000\"\n },\n \"comments\": \"Listo para emitir.\",\n \"validation\": {\n \"valid\": true,\n \"errors\": [],\n \"totals\": {\"currency_code\": \"CRC\", \"line_count\": 1, \"total_comprobante\": \"1130.00000\"}\n },\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T11:00:00-06:00\"\n },\n \"message\": \"Borrador actualizado.\",\n \"errors\": null\n}", "name": "Borrador actualizado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"payload\": [\"El cuerpo del borrador (payload) es obligatorio.\"]}\n}", "name": "Payload ausente o inv\u00e1lido" } ] }, { "name": "Emitir el comprobante a partir del borrador", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts\/:id\/issue", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts\/:id\/issue", "variable": [ { "id": "id", "key": "id", "value": "019d867d-aaaa-7288-8ece-fd64da756001", "description": "UUID del borrador a emitir." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Valida en seco (reglas condicionales); si pasa, reproduce el pipeline\nreal de POST \/vouchers (consume consecutivo, firma, valida XSD, encola\nel env\u00edo a Hacienda) y ELIMINA el borrador al tener \u00e9xito.\n\nNo recibe cuerpo: emite a partir del `payload` ya guardado en el\nborrador. La respuesta es **liviana** (no serializa el comprobante\ncompleto); el detalle se consulta en `GET \/vouchers\/{key}`. Un `id` que\nno sea un UUID v\u00e1lido retorna **404**." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-bbbb-7288-8ece-fd64da756999\",\n \"voucher_key\": \"50624062600310112345600100001010000000001100000001\",\n \"voucher_type\": \"01\",\n \"consecutive_number\": \"00100001010000000001\",\n \"status\": \"pending\"\n },\n \"message\": \"Comprobante emitido.\",\n \"errors\": null\n}", "name": "Comprobante emitido" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El borrador tiene datos incompletos para emitir.\",\n \"errors\": {\n \"line_items\": [\"Agreg\u00e1 al menos una l\u00ednea de detalle.\"],\n \"sale_condition\": [\"Indic\u00e1 la condici\u00f3n de venta.\"]\n }\n}", "name": "Borrador incompleto" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El comprobante no cumple el esquema oficial (XSD).\",\n \"errors\": {\"xsd\": [\"El elemento 'CodigoMoneda' no es v\u00e1lido.\"]}\n}", "name": "Falla del esquema oficial (XSD)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"La sucursal\/terminal indicada no existe.\",\n \"errors\": {\"terminal_code\": [\"Cr\u00e9ela primero en Sucursales y terminales.\"]}\n}", "name": "Sucursal\/terminal inexistente" } ] }, { "name": "Descartar un borrador", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/vouchers\/drafts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/vouchers\/drafts\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-aaaa-7288-8ece-fd64da756001", "description": "UUID del borrador." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Elimina el borrador indicado. No afecta a comprobantes ya emitidos (el\nborrador no es un comprobante fiscal). Un `id` que no sea un UUID v\u00e1lido\nretorna **404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Borrador descartado.\",\n \"errors\": null\n}", "name": "Borrador descartado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] } ] }, { "name": "Perfil", "description": "", "item": [ { "name": "Estad\u00edsticas de uso mensual.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/profile\/usage", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/profile\/usage" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna los conteos de comprobantes emitidos y emails enviados\ndurante el per\u00edodo mensual en curso, junto con los l\u00edmites de su plan.\n\nSolo cuenta comprobantes de producci\u00f3n aceptados por Hacienda.\nLos comprobantes emitidos en sandbox no consumen el l\u00edmite del plan.\n\nSi es integrador, el conteo agrega autom\u00e1ticamente los comprobantes\npropios y los de todos sus clientes gestionados, permitiendo\nmonitorear el consumo total del plan en una sola consulta." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"vouchers_this_month\": 87,\n \"vouchers_limit\": 500,\n \"vouchers_remaining\": 413,\n \"vouchers_percentage\": 17.4,\n \"emails_this_month\": 340,\n \"emails_limit\": 2250,\n \"period_start\": \"2026-04-01\",\n \"period_end\": \"2026-04-30\"\n },\n \"message\": \"Estad\u00edsticas de uso mensual.\",\n \"errors\": null\n}", "name": "Contribuyente normal" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"vouchers_this_month\": 12450,\n \"vouchers_limit\": 50000,\n \"vouchers_remaining\": 37550,\n \"vouchers_percentage\": 24.9,\n \"emails_this_month\": 0,\n \"emails_limit\": 5000,\n \"period_start\": \"2026-04-01\",\n \"period_end\": \"2026-04-30\"\n },\n \"message\": \"Estad\u00edsticas de uso mensual.\",\n \"errors\": null\n}", "name": "Integrador (consumo agregado con todos sus clientes)" } ] }, { "name": "Consultar perfil completo del contribuyente autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/profile", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/profile" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna todos los datos del contribuyente incluyendo el plan activo\ncon sus limites y features, las actividades economicas registradas,\nla ubicacion y la configuracion de contacto." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0241-7288-8ece-fd64da75616d\",\n \"legal_name\": \"Empresa Ejemplo S.A.\",\n \"trade_name\": \"Ejemplo Shop\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101999999\",\n \"emails\": [\"facturacion@empresa.cr\"],\n \"economic_activities\": [\"6201.0\"],\n \"location\": {\"province\": 1, \"canton\": 1, \"district\": 1},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"is_active\": true,\n \"production_enabled\": false,\n \"hacienda_environment\": \"sandbox\",\n \"plan_id\": \"019d0001-0000-0000-0000-000000000001\",\n \"is_managed\": false,\n \"is_integrator\": false,\n \"plan\": {\n \"id\": \"019d0001-0000-0000-0000-000000000001\",\n \"code\": \"pyme\",\n \"name\": \"Pyme\",\n \"description\": \"Automatice su facturaci\u00f3n con hasta 500 comprobantes\/mes.\",\n \"monthly_price_usd\": null,\n \"annual_price_usd\": 96.0,\n \"billing_mode\": \"annual_only\",\n \"annual_discount_percent\": 0,\n \"vouchers_per_month\": 500,\n \"overage_price_per_voucher\": 0.03,\n \"max_users\": 3,\n \"max_api_tokens\": 2,\n \"max_clients\": 300,\n \"max_items\": 750,\n \"max_pdf_templates\": 1,\n \"max_monthly_emails\": 2250,\n \"max_webhook_endpoints\": 1,\n \"max_branch_terminals\": 2,\n \"max_managed_contributors\": 1,\n \"api_rate_limit_per_minute\": 20,\n \"retention_months\": 3,\n \"extended_retention_eligible\": true,\n \"pdf_branding\": \"platform\",\n \"api_write_enabled\": true,\n \"api_readonly_enabled\": false,\n \"sandbox_access\": true,\n \"webhooks_enabled\": false,\n \"multi_contributor\": false,\n \"receiver_module\": true,\n \"bulk_emission\": false,\n \"sla_support\": false\n },\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-13T14:30:00-06:00\"\n },\n \"message\": \"Perfil del contribuyente.\",\n \"errors\": null\n}", "name": "Perfil completo" } ] }, { "name": "Actualizar datos editables del perfil del contribuyente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/profile", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/profile" }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"id_number\":\"3101999999\",\"id_type\":2,\"hacienda_confirmed\":true,\"legal_name\":\"Empresa Ejemplo S.A.\",\"trade_name\":\"Ejemplo Tienda\",\"emails\":[\"facturacion@empresa.cr\"],\"economic_activities\":[\"6201.0\"],\"phone\":\"22001234\",\"phone_country_code\":506,\"province\":1,\"canton\":1,\"district\":1,\"neighborhood\":\"San Pedro\",\"address\":\"200 metros norte del parque central\"}" }, "description": "Soporta actualizacion parcial: envie unicamente los campos que desea\nmodificar. Los campos no incluidos en el payload conservan su valor actual.\n\n**Campos editables:** `id_number`, `legal_name`, `trade_name`, `emails`,\n`economic_activities`, `phone`, `phone_country_code`, `province`, `canton`,\n`district`, `neighborhood`, `address`.\n\n**Campos inmutables (no se pueden cambiar desde este endpoint):**\n`id_type` (tipo de identificacion), el plan activo, `production_enabled`\n(autorizaci\u00f3n DGT | gestionada por super_admin tras verificar firma BCCR\ny cumplimiento normativo) y el estado activo\/inactivo de la cuenta.\n\nLa configuracion de email transaccional se gestiona desde su propio\nendpoint: `PUT \/email-settings`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0241-7288-8ece-fd64da75616d\",\n \"legal_name\": \"Empresa Ejemplo S.A. Actualizada\",\n \"trade_name\": \"Ejemplo Shop Nuevo\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101999999\",\n \"emails\": [\"facturacion@empresa.cr\", \"contabilidad@empresa.cr\"],\n \"economic_activities\": [\"6201.0\", \"4711.0\"],\n \"location\": {\"province\": 1, \"canton\": 1, \"district\": 1},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"is_active\": true,\n \"production_enabled\": false,\n \"hacienda_environment\": \"sandbox\",\n \"plan_id\": \"019d0001-0000-0000-0000-000000000001\",\n \"is_managed\": false,\n \"is_integrator\": false,\n \"plan\": {\n \"id\": \"019d0001-0000-0000-0000-000000000001\",\n \"code\": \"pyme\",\n \"name\": \"Pyme\",\n \"vouchers_per_month\": 500,\n \"max_clients\": 300,\n \"sandbox_access\": true\n },\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T09:15:00-06:00\"\n },\n \"message\": \"Perfil actualizado correctamente.\",\n \"errors\": null\n}", "name": "Perfil actualizado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"emails.0\": [\"El campo emails.0 debe ser un correo electr\u00f3nico v\u00e1lido.\"],\n \"economic_activities.0\": [\"El formato del c\u00f3digo de actividad econ\u00f3mica debe ser XXXX.X (ejemplo: 6201.0).\"]\n }\n}", "name": "Error de validaci\u00f3n" } ] } ] }, { "name": "Usuarios de la Cuenta", "description": "", "item": [ { "name": "Listar usuarios del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/users", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/users" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todos los usuarios (cuentas de login) asociados al\ncontribuyente activo: los **activos**, los que est\u00e1n **pendientes**\nde establecer su contrase\u00f1a y los **desactivados**. Los usuarios cuyo\nacceso fue revocado **no** aparecen.\n\nCada usuario es una cuenta de login (nombre + correo + rol), **sin\nc\u00e9dula** | la c\u00e9dula vive en el contribuyente, no en el usuario.\n\nSolo el **owner** o un **admin** del contribuyente pueden consultar\nesta lista. Otros roles reciben **HTTP 403**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"name\": \"Ana Propietaria\",\n \"email\": \"ana@empresa.cr\",\n \"role\": \"owner\",\n \"is_active\": true,\n \"is_owner\": true,\n \"status\": \"active\",\n \"created_at\": \"2026-04-01T10:00:00-06:00\"\n },\n {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"name\": \"Mar\u00eda P\u00e9rez\",\n \"email\": \"maria@empresa.cr\",\n \"role\": \"cashier\",\n \"is_active\": true,\n \"is_owner\": false,\n \"status\": \"pending\",\n \"created_at\": \"2026-04-10T14:30:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Listado de usuarios" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No ten\u00e9s permisos para gestionar usuarios.\",\n \"errors\": null\n}", "name": "Sin permisos" } ] }, { "name": "Invitar un usuario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/users", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/users" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Mar\u00eda P\u00e9rez\",\"email\":\"maria@empresa.cr\",\"role\":\"cashier\"}" }, "description": "Crea una cuenta de login (sin c\u00e9dula) y la asocia al contribuyente\nactivo. El usuario recibe un **correo con un enlace** para establecer\nsu contrase\u00f1a; mientras tanto queda en estado `pending`.\n\n**Reglas:**\n\n- El `email` debe ser **\u00fanico** en toda la plataforma. Si ya existe un\n usuario con ese correo, responde **HTTP 422**.\n- El `role` no puede ser `owner`; solo se admiten `admin`,\n `accountant`, `cashier`, `viewer` o `api_user`.\n\nSolo el **owner** o un **admin** pueden invitar usuarios. Otros roles\nreciben **HTTP 403**." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"name\": \"Mar\u00eda P\u00e9rez\",\n \"email\": \"maria@empresa.cr\",\n \"role\": \"cashier\",\n \"is_active\": true,\n \"is_owner\": false,\n \"status\": \"pending\",\n \"created_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Usuario invitado. Recibir\u00e1 un correo para establecer su contrase\u00f1a.\",\n \"errors\": null\n}", "name": "Usuario invitado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No ten\u00e9s permisos para gestionar usuarios.\",\n \"errors\": null\n}", "name": "Sin permisos" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"email\": [\"Ya existe un usuario con ese correo.\"]\n }\n}", "name": "Correo duplicado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"role\": [\"El rol seleccionado no es v\u00e1lido.\"]\n }\n}", "name": "Rol inv\u00e1lido" } ] }, { "name": "Editar un usuario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/users\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/users\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0002-7288-8ece-fd64da756002", "description": "UUID del usuario a editar." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"role\":\"viewer\",\"is_active\":true,\"password\":\"MiClaveSegura123\"}" }, "description": "Permite cambiar el **rol** y\/o el **estado** (activar \/ desactivar) de\nun usuario del contribuyente. Admite actualizaci\u00f3n parcial | env\u00ede\nsolo los campos que desea modificar.\n\n> **Acci\u00f3n sensible:** cambiar el estado `is_active` requiere enviar el\n> campo `password` con la contrase\u00f1a del usuario que opera. Si falta o\n> es incorrecta, responde **HTTP 401**.\n\nAl **activar** un usuario se respeta el `max_users` del plan: si ya se\nalcanz\u00f3 el l\u00edmite de usuarios activos, responde **HTTP 422**.\n\nEl **propietario** de la cuenta no puede modificarse (**HTTP 403**), y\nel rol `owner` no puede asignarse desde aqu\u00ed. Solo el owner o un admin\npueden editar usuarios." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"name\": \"Mar\u00eda P\u00e9rez\",\n \"email\": \"maria@empresa.cr\",\n \"role\": \"viewer\",\n \"is_active\": true,\n \"is_owner\": false,\n \"status\": \"active\",\n \"created_at\": \"2026-04-10T14:30:00-06:00\"\n },\n \"message\": \"Usuario actualizado.\",\n \"errors\": null\n}", "name": "Usuario actualizado" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Contrase\u00f1a incorrecta.\",\n \"errors\": null\n}", "name": "Contrase\u00f1a incorrecta" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No ten\u00e9s permisos para gestionar usuarios.\",\n \"errors\": null\n}", "name": "Sin permisos" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se puede modificar al propietario de la cuenta.\",\n \"errors\": null\n}", "name": "Es el propietario" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Usuario no encontrado en este contribuyente.\",\n \"errors\": null\n}", "name": "Usuario no encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Alcanzaste el l\u00edmite de usuarios activos de tu plan (3).\",\n \"errors\": {\n \"is_active\": [\"Desactiv\u00e1 otro usuario o cambi\u00e1 de plan.\"]\n }\n}", "name": "L\u00edmite del plan alcanzado" } ] }, { "name": "Revocar el acceso de un usuario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/users\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/users\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0002-7288-8ece-fd64da756002", "description": "UUID del usuario a revocar." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"password\":\"MiClaveSegura123\"}" }, "description": "Desvincula al usuario del contribuyente activo, liberando su asiento\ndel plan. La cuenta de login **global** del usuario **no se elimina**:\nsigue viva para que pueda asociarse a otro contribuyente o facturar\npor su cuenta. Simplemente deja de pertenecer a esta cuenta y\ndesaparece del listado.\n\n> **Acci\u00f3n sensible:** requiere enviar el campo `password` con la\n> contrase\u00f1a del usuario que opera. Si falta o es incorrecta, responde\n> **HTTP 401**.\n\nNo puede revocar su **propio** acceso ni el del **propietario** de la\ncuenta (ambos casos responden **HTTP 403**). Solo el owner o un admin\npueden revocar usuarios." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Usuario desvinculado de esta cuenta.\",\n \"errors\": null\n}", "name": "Acceso revocado" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Contrase\u00f1a incorrecta.\",\n \"errors\": null\n}", "name": "Contrase\u00f1a incorrecta" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No ten\u00e9s permisos para gestionar usuarios.\",\n \"errors\": null\n}", "name": "Sin permisos" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No pod\u00e9s revocar tu propio acceso.\",\n \"errors\": null\n}", "name": "No puede revocarse a s\u00ed mismo" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se puede revocar al propietario de la cuenta.\",\n \"errors\": null\n}", "name": "Es el propietario" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Usuario no encontrado en este contribuyente.\",\n \"errors\": null\n}", "name": "Usuario no encontrado" } ] } ] }, { "name": "Cambio de Contribuyente", "description": "", "item": [ { "name": "Listar contribuyentes accesibles", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-access-contributors", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-access-contributors" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los contribuyentes a los que el usuario autenticado tiene\nacceso operativo (pivote `user_contributors` activo y aceptado), por\nejemplo como due\u00f1o de su propia empresa o como contador de varios\nclientes. Solo se incluyen los contribuyentes que est\u00e9n **activos**.\n\nEl campo `is_current` indica cu\u00e1l de ellos es el contribuyente activo\nde la sesi\u00f3n (el que lee el middleware multi-tenant). Use el endpoint\n`POST \/switch-contributor` para cambiarlo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"contributor_id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"legal_name\": \"EMPRESA EJEMPLO S.A.\",\n \"id_number\": \"3101123456\",\n \"role\": \"owner\",\n \"is_current\": true\n },\n {\n \"contributor_id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"legal_name\": \"CLIENTE CONTABLE S.A.\",\n \"id_number\": \"3101987654\",\n \"role\": \"accountant\",\n \"is_current\": false\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Contribuyentes accesibles" } ] }, { "name": "Cambiar el contribuyente activo", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/switch-contributor", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/switch-contributor" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"contributor_id\":\"019d867d-0002-7288-8ece-fd64da756002\"}" }, "description": "Cambia el contribuyente activo de la sesi\u00f3n del usuario autenticado.\nEl usuario debe tener acceso operativo (pivote `user_contributors`\nactivo y aceptado) al contribuyente destino, y este debe estar\n**activo**. El mismo token sigue siendo v\u00e1lido tras el cambio.\n\nSi el usuario no tiene acceso al contribuyente indicado, responde\n**HTTP 403**. Si el contribuyente no existe o est\u00e1 inactivo, responde\n**HTTP 404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"contributor_id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"legal_name\": \"CLIENTE CONTABLE S.A.\",\n \"role\": \"accountant\"\n },\n \"message\": \"Contribuyente activo cambiado.\",\n \"errors\": null\n}", "name": "Contribuyente cambiado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No ten\u00e9s acceso a ese contribuyente.\",\n \"errors\": null\n}", "name": "Sin acceso al contribuyente" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El contribuyente no existe o est\u00e1 inactivo.\",\n \"errors\": null\n}", "name": "Contribuyente inexistente o inactivo" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"contributor_id\": [\"El campo contributor id es obligatorio.\"]\n }\n}", "name": "Validaci\u00f3n fallida" } ] } ] }, { "name": "Certificados Digitales", "description": "", "item": [ { "name": "Listar certificados digitales del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/certificates" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el historial completo de certificados digitales registrados\npor el contribuyente: el certificado actualmente activo y todos los\nque fueron desactivados previamente (conservados para auditor\u00eda).\n\nLos datos sensibles del certificado (contenido del archivo `.p12`,\ncontrase\u00f1a y PIN de Hacienda) **nunca se incluyen** en la respuesta,\nincluso si usted mismo los carg\u00f3.\n\nCada registro incluye:\n\n- Ambiente (`sandbox` \/ `production`).\n- Estado (`is_active`) y fecha de desactivaci\u00f3n si aplica.\n- Vigencia del certificado (`valid_from`, `valid_until`).\n- **D\u00edas restantes** hasta la expiraci\u00f3n (`days_remaining`) | \u00fatil\n para monitorear renovaci\u00f3n.\n- Subject del certificado X.509 (nombre del titular).\n- N\u00famero de serie del certificado.\n\nOrdenamiento: el m\u00e1s reciente primero." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Listado de certificados" } ] }, { "name": "Consultar disponibilidad de subida de certificado por ambiente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificates\/availability", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/certificates\/availability" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Indica para cada ambiente (`sandbox`, `production`) si est\u00e1\n**disponible** para subir un certificado nuevo o si ya hay uno\nactivo que debe desactivarse primero.\n\n\u00datil para mostrar el formulario de subida con el selector de\nambiente correctamente deshabilitado, evitando que el usuario\nintente subir un .p12 que ser\u00eda rechazado con HTTP 422.\n\n**Reglas:**\n\n- `available = true` \u2192 no hay certificado activo en ese ambiente,\n se puede subir uno nuevo.\n- `available = false` \u2192 ya hay certificado activo. Para subir uno\n nuevo en este ambiente debe desactivar el actual con\n `DELETE \/api\/v1\/public\/certificates\/{id}`.\n\nCuando `available = false`, el campo `active_certificate` incluye\nlos datos del certificado vigente para que el frontend pueda\nmostrar al usuario qu\u00e9 cert est\u00e1 bloqueando el upload." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"sandbox\": {\n \"available\": true,\n \"active_certificate\": null\n },\n \"production\": {\n \"available\": false,\n \"active_certificate\": {\n \"id\": \"019d867d-1111-7288-8ece-fd64da756001\",\n \"certificate_serial\": \"019DD6D90F43\",\n \"certificate_subject\": \"CN=ALBERT MENDEZ, serialNumber=CPF-02-0627-0652\",\n \"valid_from\": \"2025-12-15T10:30:00-06:00\",\n \"valid_until\": \"2027-12-15T10:30:00-06:00\",\n \"days_remaining\": 596,\n \"is_expired\": false,\n \"created_at\": \"2026-04-15T08:00:00-06:00\"\n }\n }\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Sandbox disponible, producci\u00f3n ocupada" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"sandbox\": {\"available\": true, \"active_certificate\": null},\n \"production\": {\"available\": true, \"active_certificate\": null}\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Ambos ambientes disponibles" } ] }, { "name": "Subir y activar un certificado digital `.p12`", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/certificates" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "p12_password", "value": "architecto", "type": "text", "description": "Contrase\u00f1a del archivo `.p12` (PIN del archivo). NO confunda con la contrase\u00f1a del IdP de Hacienda | son distintas." }, { "key": "hacienda_pin", "value": "architecto", "type": "text", "description": "Contrase\u00f1a del IdP de Hacienda (asignada por TRIBU-CR al registrarse como emisor). NO confunda con el PIN del archivo .p12." }, { "key": "environment", "value": "architecto", "type": "text", "description": "Ambiente: `sandbox` o `production`." }, { "key": "p12_file", "src": [], "type": "file" } ] }, "description": "Sube un archivo `.p12` (PKCS#12) con su contrase\u00f1a y la contrase\u00f1a\ndel IdP de Hacienda, y lo activa como certificado para firmar\ncomprobantes en el ambiente indicado.\n\nEste request **debe enviarse como `multipart\/form-data`** (no JSON),\nporque incluye un archivo binario.\n\n**Validaciones que se ejecutan ANTES de guardar:**\n\n1. **Disponibilidad del ambiente**: solo puede subir cert si NO hay\n uno activo en ese ambiente. Si ya hay uno, debe desactivarlo\n primero con `DELETE \/certificates\/{id}` o usar el endpoint\n `GET \/certificates\/availability` para chequear estado.\n2. **PIN del .p12**: el archivo debe abrirse con la contrase\u00f1a\n provista en `p12_password`.\n3. **Llave privada RSA**: el .p12 debe contener una llave RSA v\u00e1lida\n (Hacienda CR exige RSA-SHA256 para XAdES-EPES).\n4. **Subject del certificado**: el cert debe pertenecer al\n contribuyente que lo est\u00e1 subiendo (anti-fraude | REGLAMENTO art. 16).\n5. **Vigencia del certificado**: el X.509 no puede estar vencido\n ni ser prematuro.\n6. **Credenciales IdP de Hacienda**: el `hacienda_pin` debe autenticar\n correctamente contra el IdP del ambiente solicitado (POST\n grant_type=password). Si falla, el cert NO se guarda | ser\u00eda\n inutilizable sin token OAuth2 v\u00e1lido.\n\nSi **CUALQUIERA** de las 6 validaciones falla, se retorna HTTP 422\n(o 503 si el IdP de Hacienda no responde) y NADA se guarda en DB.\n\n**Ejemplo con `curl`:**\n\n```bash\ncurl -X POST https:\/\/api.almendro.cr\/api\/v1\/public\/certificates \\\n -H \"Authorization: Bearer {su_token}\" \\\n -F \"p12_file=@\/ruta\/a\/certificado.p12\" \\\n -F \"p12_password=PIN-del-archivo-p12\" \\\n -F \"hacienda_pin=Contrase\u00f1a-del-IdP-de-Hacienda\" \\\n -F \"environment=sandbox\"\n```" }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-1111-7288-8ece-fd64da756001\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 596,\n \"valid_from\": \"2025-12-15T10:30:00-06:00\",\n \"valid_until\": \"2027-12-15T10:30:00-06:00\",\n \"certificate_subject\": \"CN=ALBERT MENDEZ, serialNumber=CPF-02-0627-0652\",\n \"certificate_serial\": \"019DD6C62577\",\n \"created_at\": \"2026-04-29T08:00:00-06:00\"\n },\n \"message\": \"Certificado registrado y activado correctamente.\",\n \"errors\": null\n}", "name": "Certificado registrado exitosamente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El PIN del archivo .p12 es incorrecto, el archivo est\u00e1 corrupto, o no es un PKCS#12 v\u00e1lido emitido por el BCCR. ...\",\n \"errors\": {\"p12_password\": [\"El PIN del archivo .p12 es incorrecto, ...\"]}\n}", "name": "PIN del archivo .p12 incorrecto (5001)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El certificado .p12 NO pertenece a este contribuyente. ...\",\n \"errors\": {\"p12_file\": [\"El certificado .p12 NO pertenece a este contribuyente. ...\"]}\n}", "name": "Cert no pertenece al contribuyente (5002)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El IdP de Hacienda rechaz\u00f3 las credenciales con HTTP 401. ...\",\n \"errors\": {\"hacienda_pin\": [\"El IdP de Hacienda rechaz\u00f3 las credenciales con HTTP 401. ...\"]}\n}", "name": "Credenciales IdP rechazadas (5003)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe un certificado activo en el ambiente 'sandbox'. ...\",\n \"errors\": {\"environment\": [\"Ya existe un certificado activo en el ambiente 'sandbox'. ...\"]}\n}", "name": "Ya hay cert activo en el ambiente (5004)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El certificado .p12 pertenece al ambiente de sandbox (pruebas) pero usted lo est\u00e1 subiendo como producci\u00f3n. ...\",\n \"errors\": {\"p12_file\": [\"El certificado .p12 pertenece al ambiente de sandbox (pruebas) pero usted lo est\u00e1 subiendo como producci\u00f3n. ...\"]}\n}", "name": "El .p12 pertenece al otro ambiente (5005)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No es posible validar el certificado porque el contribuyente todav\u00eda no tiene registrada su identificaci\u00f3n (tipo y n\u00famero de c\u00e9dula) en el perfil. ...\",\n \"errors\": {\"p12_file\": [\"No es posible validar el certificado porque el contribuyente todav\u00eda no tiene registrada su identificaci\u00f3n ...\"]}\n}", "name": "Perfil sin identificaci\u00f3n registrada (5006)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El certificado del contribuyente '...' no est\u00e1 vigente. ...\",\n \"errors\": {\"p12_file\": [\"El certificado del contribuyente '...' no est\u00e1 vigente. ...\"]}\n}", "name": "Certificado vencido (2002)" }, { "header": [], "code": 503, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El IdP de Hacienda no responde temporalmente. Intente nuevamente en unos minutos.\",\n \"errors\": null\n}", "name": "IdP de Hacienda no responde temporalmente" } ] }, { "name": "Desactivar un certificado digital", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/certificates\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-1111-7288-8ece-fd64da756001", "description": "UUID del certificado a desactivar." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Marca el certificado como **inactivo**. El registro **no se elimina**:\npermanece en el hist\u00f3rico para auditor\u00eda de todas las firmas\nrealizadas durante su vigencia.\n\n**Consecuencias inmediatas:**\n\n- Si el certificado desactivado era el activo de su ambiente, la\n emisi\u00f3n en ese ambiente **queda bloqueada** hasta que suba un\n nuevo certificado activo.\n- Si alg\u00fan integrador ten\u00eda acceso delegado a este certificado, el\n acceso se **revoca autom\u00e1ticamente** y se le env\u00eda una notificaci\u00f3n.\n- El conteo de accesos revocados aparece en el `message` de la\n respuesta.\n\nSolo puede desactivar certificados propios. Si el UUID no\ncorresponde a su contribuyente, retorna **404**.\n\n> **Casos t\u00edpicos para desactivar:**\n> - El certificado fue comprometido (p\u00e9rdida, acceso no autorizado).\n> - Va a subir un certificado nuevo (debe desactivar el vigente\n> primero | el sistema no permite dos activos en el mismo ambiente).\n> - Migraci\u00f3n de un contribuyente a otra plataforma." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Certificado desactivado correctamente.\",\n \"errors\": null\n}", "name": "Certificado desactivado (sin accesos asociados)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Certificado desactivado correctamente. Se revocaron 2 accesos de integradores asociados.\",\n \"errors\": null\n}", "name": "Certificado desactivado con auto-revocaci\u00f3n de accesos" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Certificado no encontrado.\",\n \"errors\": null\n}", "name": "Certificado no encontrado o no pertenece al contribuyente" } ] } ] }, { "name": "Plantillas PDF", "description": "", "item": [ { "name": "Listar plantillas PDF del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todas las plantillas PDF activas del contribuyente,\nordenadas con la plantilla **por defecto primero** (`is_default=true`)\ny luego por nombre alfab\u00e9ticamente.\n\nEste endpoint **no pagina** | el n\u00famero de plantillas por\ncontribuyente es peque\u00f1o (l\u00edmite por plan entre 1 y 15), por lo\nque siempre se devuelve la lista completa.\n\nCada plantilla incluye su configuraci\u00f3n completa (`config_json`)\ncon colores, fuentes, layout y par\u00e1metros del QR, adem\u00e1s de un flag\n`has_logo` que indica si tiene un logo cargado." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Classic\",\n \"is_default\": true,\n \"paper_size\": \"letter\",\n \"config_json\": {\n \"colors\": {\"primary\": \"#2d3748\", \"secondary\": \"#4a5568\", \"accent\": \"#3182ce\"},\n \"fonts\": {\"family\": \"Helvetica\", \"size_header\": 14, \"size_body\": 9},\n \"layout\": {\"show_logo\": true, \"logo_position\": \"left\", \"logo_max_height\": 60},\n \"qr\": {\"enabled\": true, \"size\": 100, \"position\": \"bottom-right\"}\n },\n \"has_logo\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-10T14:30:00-06:00\"\n },\n {\n \"id\": 2,\n \"name\": \"Minimal\",\n \"is_default\": false,\n \"paper_size\": \"A4\",\n \"config_json\": {\n \"colors\": {\"primary\": \"#000000\", \"secondary\": \"#666666\", \"accent\": \"#000000\"},\n \"fonts\": {\"family\": \"Helvetica\", \"size_header\": 12, \"size_body\": 8},\n \"layout\": {\"show_logo\": false, \"logo_position\": \"left\", \"logo_max_height\": 60},\n \"qr\": {\"enabled\": true, \"size\": 80, \"position\": \"bottom-right\"}\n },\n \"has_logo\": false,\n \"is_active\": true,\n \"created_at\": \"2026-04-05T08:00:00-06:00\",\n \"updated_at\": \"2026-04-05T08:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Listado de plantillas (default primero)" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Unauthenticated.\",\n \"errors\": null\n}", "name": "No autenticado" } ] }, { "name": "Crear una nueva plantilla PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Mi Plantilla Corporativa\",\"is_default\":false,\"paper_size\":\"letter\",\"config_json\":{\"colors\":{\"primary\":\"#0a66c2\",\"secondary\":\"#333333\",\"accent\":\"#0a66c2\"},\"fonts\":{\"family\":\"Helvetica\",\"size_header\":14,\"size_body\":9},\"layout\":{\"show_logo\":true,\"logo_position\":\"left\",\"logo_max_height\":60},\"qr\":{\"enabled\":true,\"size\":100,\"position\":\"bottom-right\"},\"margins\":{\"top\":15,\"right\":15,\"bottom\":15,\"left\":15},\"style\":\"classic\",\"footer_text\":\"Documento generado electr\u00f3nicamente | Almendro Factura Electr\u00f3nica\"}}" }, "description": "Registra una plantilla personalizada en el cat\u00e1logo del contribuyente.\nSi env\u00eda `is_default: true`, la plantilla default anterior se\ndesmarca autom\u00e1ticamente.\n\nSi **no env\u00eda** `config_json`, se aplica una configuraci\u00f3n por\ndefecto que cumple con todos los requisitos normativos (QR m\u00ednimo\n2.5 cm en la esquina inferior derecha).\n\nSi **env\u00eda** `config_json`, puede enviar un objeto parcial | las\nclaves no enviadas usan los valores del template default." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 3,\n \"name\": \"Mi Plantilla Corporativa\",\n \"is_default\": false,\n \"paper_size\": \"letter\",\n \"config_json\": {\n \"colors\": {\"primary\": \"#0a66c2\", \"secondary\": \"#333333\", \"accent\": \"#0a66c2\"},\n \"fonts\": {\"family\": \"Helvetica\", \"size_header\": 14, \"size_body\": 9},\n \"layout\": {\"show_logo\": true, \"logo_position\": \"left\", \"logo_max_height\": 60},\n \"qr\": {\"enabled\": true, \"size\": 100, \"position\": \"bottom-right\"}\n },\n \"has_logo\": false,\n \"is_active\": true,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Plantilla creada correctamente.\",\n \"errors\": null\n}", "name": "Plantilla creada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"name\": [\"Ya existe una plantilla con este nombre para el contribuyente.\"]}\n}", "name": "Nombre duplicado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"config_json.colors.primary\": [\"El color debe ser un hexadecimal v\u00e1lido (ej. #1a365d).\"]}\n}", "name": "Color hexadecimal inv\u00e1lido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"config_json.qr.size\": [\"El tama\u00f1o m\u00ednimo del QR es 70 pt (\u2248 2.5 cm) por normativa.\"]}\n}", "name": "Tama\u00f1o del QR por debajo del m\u00ednimo normativo" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan\": [\"Ha alcanzado el l\u00edmite de plantillas PDF de su plan. Actualice a un plan superior.\"]}\n}", "name": "L\u00edmite del plan alcanzado" } ] }, { "name": "Editar una plantilla PDF existente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "ID de la plantilla." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Profesional Actualizada\",\"is_default\":true,\"is_active\":true,\"paper_size\":\"letter\",\"config_json\":{\"colors\":{\"primary\":\"#1a365d\",\"secondary\":\"#4a5568\",\"text\":\"#2815Df\",\"accent\":\"#3182ce\",\"muted\":\"#2815Df\"},\"fonts\":{\"family\":\"Helvetica\",\"size_header\":14,\"size_body\":9,\"size_footer\":7},\"layout\":{\"show_logo\":true,\"logo_position\":\"left\",\"logo_max_height\":60,\"show_commercial_name\":true,\"show_address\":true,\"show_phone\":true,\"show_email\":false,\"show_observations\":true,\"show_payment_methods\":false,\"show_references\":false,\"show_other_charges\":false},\"qr\":{\"size\":100,\"position\":\"bottom-right\"},\"margins\":{\"top\":22,\"right\":24,\"bottom\":18,\"left\":8},\"style\":\"bold\",\"footer_text\":\"m\"}}" }, "description": "Admite **actualizaci\u00f3n parcial** | env\u00ede \u00fanicamente los campos que\ndesea modificar. Los campos no enviados conservan su valor actual.\n\nEl campo `config_json` se **fusiona** con la configuraci\u00f3n\nexistente (merge profundo): las claves que env\u00ede se actualizan y\nlas que no env\u00ede se mantienen intactas. Esto permite cambiar, por\nejemplo, solo los colores sin afectar fuentes, layout o QR.\n\nSi env\u00eda `is_default: true` y la plantilla no era la default, la\ndefault anterior se desmarca autom\u00e1ticamente.\n\n> **Importante:** editar una plantilla **no afecta** a los PDFs\n> ya generados con ella. Los PDFs se congelan con la configuraci\u00f3n\n> vigente al momento de la emisi\u00f3n (inmutabilidad post-emisi\u00f3n)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"name\": \"Profesional Actualizada\",\n \"is_default\": true,\n \"paper_size\": \"letter\",\n \"config_json\": {\n \"colors\": {\"primary\": \"#1a365d\", \"secondary\": \"#4a5568\", \"accent\": \"#3182ce\"},\n \"fonts\": {\"family\": \"Helvetica\", \"size_header\": 14, \"size_body\": 9},\n \"layout\": {\"show_logo\": true, \"logo_position\": \"left\", \"logo_max_height\": 60},\n \"qr\": {\"enabled\": true, \"size\": 100, \"position\": \"bottom-right\"}\n },\n \"has_logo\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T11:00:00-06:00\"\n },\n \"message\": \"Plantilla actualizada correctamente.\",\n \"errors\": null\n}", "name": "Plantilla actualizada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "Plantilla no encontrada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"name\": [\"Ya existe una plantilla con este nombre para el contribuyente.\"]}\n}", "name": "Nombre duplicado" } ] }, { "name": "Eliminar una plantilla PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id", "variable": [ { "id": "id", "key": "id", "value": "2", "description": "ID de la plantilla." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Realiza un **soft delete** de la plantilla. Los PDFs ya generados\ncon esta plantilla **no se ven afectados** | la configuraci\u00f3n se\naplica al momento de generar cada PDF y no se modifica\nretroactivamente.\n\n**Protecci\u00f3n:** no se puede eliminar una plantilla si es la\n**\u00fanica plantilla activa** del contribuyente. En ese caso el\nsistema responde HTTP 409 y debe:\n\n1. Crear otra plantilla nueva, o\n2. Reactivar otra plantilla existente,\n\nantes de eliminar la actual." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Plantilla eliminada correctamente.\",\n \"errors\": null\n}", "name": "Plantilla eliminada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "Plantilla no encontrada" }, { "header": [], "code": 409, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se puede eliminar la \u00fanica plantilla activa del contribuyente. Cree otra plantilla o marque otra como default antes de eliminar.\",\n \"errors\": null\n}", "name": "No se puede eliminar la \u00fanica plantilla activa" } ] }, { "name": "Generar un preview del PDF con datos reales", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id\/preview", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id\/preview", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "ID de la plantilla." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Renderiza un PDF de ejemplo usando la plantilla indicada y el\n**comprobante m\u00e1s reciente** emitido por el contribuyente. Permite\nverificar la apariencia de la plantilla antes de asignarla como\ndefault.\n\nLa respuesta es un archivo PDF (`Content-Type: application\/pdf`)\ninline. Puede guardarlo localmente con `-o archivo.pdf` en `curl`\no mostrarlo directamente en un iframe del navegador.\n\nSi el contribuyente a\u00fan **no ha emitido ning\u00fan comprobante**,\nretorna HTTP 404 con un mensaje indicando que debe emitir al\nmenos uno primero.\n\n> **Nota:** el comprobante usado para el preview es el m\u00e1s\n> reciente (`ORDER BY issued_at DESC LIMIT 1`). Si quiere probar\n> la plantilla con un comprobante espec\u00edfico, emita uno nuevo y\n> use este endpoint despu\u00e9s | o bien use el endpoint\n> `GET \/vouchers\/{key}\/pdf` con `?pdf_template_id={id}`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"Content-Type\": \"application\/pdf\",\n \"Content-Disposition\": \"inline; filename=\\\"preview_Classic.pdf\\\"\",\n \"Cache-Control\": \"no-store\",\n \"body\": \"%PDF-1.4 ... (binario) ... %%EOF\"\n}", "name": "PDF generado exitosamente" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No hay comprobantes emitidos para generar un preview. Emita al menos un comprobante antes de usar preview.\",\n \"errors\": null\n}", "name": "Sin comprobantes para preview" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "Plantilla no encontrada" } ] }, { "name": "Obtener el logo de una plantilla PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id\/logo", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id\/logo", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "ID de la plantilla." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el archivo de imagen del logo como respuesta binaria\ninline, con el `Content-Type` correcto seg\u00fan el formato (PNG,\nJPG\/JPEG, SVG).\n\nSi la plantilla **no tiene logo configurado**, retorna HTTP 404.\n\nEl archivo se sirve con cache privado de 1 hora y cabeceras de\nseguridad (`X-Content-Type-Options: nosniff`)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"Content-Type\": \"image\/png\",\n \"Cache-Control\": \"private, max-age=3600\",\n \"X-Content-Type-Options\": \"nosniff\",\n \"body\": \"(contenido binario de la imagen)\"\n}", "name": "Logo disponible" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Esta plantilla no tiene logo.\",\n \"errors\": null\n}", "name": "Plantilla sin logo configurado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Archivo de logo no encontrado.\",\n \"errors\": null\n}", "name": "Archivo de logo no encontrado en el servidor" } ] }, { "name": "Subir o reemplazar el logo de una plantilla PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id\/logo", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id\/logo", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "ID de la plantilla." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "logo_file", "src": [], "type": "file" } ] }, "description": "Sube un archivo de imagen que se utilizar\u00e1 como logo en el\nencabezado del PDF generado con esta plantilla. Si la plantilla ya\nten\u00eda un logo, se **reemplaza autom\u00e1ticamente** (el archivo\nanterior se elimina del servidor).\n\nEste request **debe enviarse como `multipart\/form-data`** (no\nJSON), porque incluye un archivo binario.\n\n**Restricciones del archivo:**\n\n- Extensiones permitidas: `png`, `jpg`, `jpeg`, `svg`.\n- Tama\u00f1o m\u00e1ximo: **200 KB**.\n- Para logos que se ver\u00e1n bien en el PDF, use preferentemente\n resoluci\u00f3n de **300 DPI** y dimensiones proporcionales a\n `layout.logo_max_height` configurado.\n\n**Ejemplo con `curl`:**\n\n```bash\ncurl -X POST https:\/\/api.almendro.cr\/api\/v1\/public\/pdf-templates\/1\/logo \\\n -H \"Authorization: Bearer {su_token}\" \\\n -F \"logo_file=@\/ruta\/a\/logo.png\"\n```\n\n**Ejemplo con Node.js (axios + form-data):**\n\n```javascript\nconst FormData = require('form-data')\nconst fs = require('fs')\nconst axios = require('axios')\n\nconst form = new FormData()\nform.append('logo_file', fs.createReadStream('logo.png'))\n\nawait axios.post(\n 'https:\/\/api.almendro.cr\/api\/v1\/public\/pdf-templates\/1\/logo',\n form,\n { headers: { ...form.getHeaders(), Authorization: `Bearer ${token}` } },\n)\n```" }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"name\": \"Classic\",\n \"is_default\": true,\n \"paper_size\": \"letter\",\n \"config_json\": {\"colors\": {}, \"fonts\": {}, \"layout\": {}, \"qr\": {}},\n \"has_logo\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T12:00:00-06:00\"\n },\n \"message\": \"Logo subido correctamente.\",\n \"errors\": null\n}", "name": "Logo subido exitosamente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"logo_file\": [\"El archivo del logo es obligatorio.\"]}\n}", "name": "Archivo faltante" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"logo_file\": [\"Extensi\u00f3n no permitida. Use: png, jpg, jpeg, svg.\"]}\n}", "name": "Extensi\u00f3n no permitida" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"logo_file\": [\"El logo no puede superar 200 KB.\"]}\n}", "name": "Archivo excede 200 KB" } ] }, { "name": "Eliminar el logo de una plantilla PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/pdf-templates\/:id\/logo", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/pdf-templates\/:id\/logo", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "ID de la plantilla." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Elimina el archivo de logo asociado a la plantilla. Los PDFs que\nya fueron generados con este logo **no se ven afectados**.\n\nSi la plantilla **no tiene logo** configurado, retorna HTTP 409." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"name\": \"Classic\",\n \"is_default\": true,\n \"paper_size\": \"letter\",\n \"config_json\": {\"colors\": {}, \"fonts\": {}, \"layout\": {}, \"qr\": {}},\n \"has_logo\": false,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T13:00:00-06:00\"\n },\n \"message\": \"Logo eliminado correctamente.\",\n \"errors\": null\n}", "name": "Logo eliminado" }, { "header": [], "code": 409, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Esta plantilla no tiene logo configurado.\",\n \"errors\": null\n}", "name": "Sin logo configurado" } ] } ] }, { "name": "Configuraci\u00f3n Email", "description": "", "item": [ { "name": "Consultar la configuraci\u00f3n de email del contribuyente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/email-settings", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/email-settings" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna la configuraci\u00f3n de env\u00edo autom\u00e1tico de comprobantes por\ncorreo electr\u00f3nico. Si el contribuyente nunca ha configurado estos\nvalores, se retornan los valores por defecto que cumplen con la\nobligaci\u00f3n de entrega del art. 18 del Reglamento: env\u00edo autom\u00e1tico\nactivado, XML firmado y PDF adjuntos." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"auto_send\": true,\n \"send_on_accepted_only\": true,\n \"attach_xml\": true,\n \"attach_pdf\": true,\n \"reply_to\": null,\n \"bcc\": [],\n \"custom_subject\": null,\n \"custom_message\": null\n },\n \"message\": \"Configuraci\u00f3n de email del contribuyente.\",\n \"errors\": null\n}", "name": "Valores por defecto (nunca configurado)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"auto_send\": true,\n \"send_on_accepted_only\": true,\n \"attach_xml\": true,\n \"attach_pdf\": true,\n \"reply_to\": \"facturas@miempresa.cr\",\n \"bcc\": [\"contabilidad@miempresa.cr\"],\n \"custom_subject\": \"{emisor} | {tipo} {consecutivo}\",\n \"custom_message\": \"Adjunto su comprobante electr\u00f3nico.\"\n },\n \"message\": \"Configuraci\u00f3n de email del contribuyente.\",\n \"errors\": null\n}", "name": "Configuraci\u00f3n personalizada" } ] }, { "name": "Actualizar la configuraci\u00f3n de email del contribuyente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/email-settings", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/email-settings" }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"auto_send\":true,\"send_on_accepted_only\":true,\"attach_xml\":true,\"attach_pdf\":true,\"reply_to\":\"facturas@miempresa.cr\",\"bcc\":[\"b\"],\"custom_subject\":\"{emisor} | {tipo} {consecutivo}\",\"custom_message\":\"Adjunto encontrar\u00e1 su comprobante electr\u00f3nico.\"}" }, "description": "Soporta actualizaci\u00f3n parcial: env\u00ede \u00fanicamente los campos que\ndesea modificar. Los campos omitidos conservan su valor actual\n(o el valor por defecto si nunca fueron configurados).\n\n**Advertencia normativa:** si desactiva `attach_xml` o `attach_pdf`,\nel contribuyente asume la responsabilidad de entregar los documentos\nal receptor por otro medio (descarga desde API, portal web, impresi\u00f3n),\nconforme al art. 18 del Reglamento de Comprobantes Electr\u00f3nicos.\n\n**Placeholders disponibles para `custom_subject`:**\n`{tipo}`, `{consecutivo}`, `{clave}`, `{receptor}`, `{total}`,\n`{moneda}`, `{emisor}`" }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"auto_send\": true,\n \"send_on_accepted_only\": true,\n \"attach_xml\": true,\n \"attach_pdf\": true,\n \"reply_to\": \"facturas@miempresa.cr\",\n \"bcc\": [\"contabilidad@miempresa.cr\"],\n \"custom_subject\": \"{emisor} | {tipo} {consecutivo}\",\n \"custom_message\": \"Adjunto su comprobante electr\u00f3nico.\"\n },\n \"message\": \"Configuraci\u00f3n de email actualizada correctamente.\",\n \"errors\": null\n}", "name": "Configuraci\u00f3n actualizada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"reply_to\": [\"El campo reply_to debe ser un correo electr\u00f3nico v\u00e1lido.\"],\n \"bcc.0\": [\"El campo bcc.0 debe ser un correo electr\u00f3nico v\u00e1lido.\"]\n }\n}", "name": "Error de validaci\u00f3n" } ] } ] }, { "name": "Clientes", "description": "", "item": [ { "name": "Listar clientes del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/clients", "query": [ { "key": "q", "value": "Empresa", "description": "B\u00fasqueda por nombre, nombre comercial o n\u00famero de c\u00e9dula (m\u00ednimo 2 caracteres).", "disabled": false }, { "key": "id_type", "value": "02", "description": "Filtrar por tipo de identificaci\u00f3n. Valores: `01`, `02`, `03`, `04`, `05`, `06`.", "disabled": false }, { "key": "is_active", "value": "true", "description": "Filtrar por estado. `true` = solo activos (default), `false` = solo inactivos, `all` = todos.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100). Default: 15.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/clients?q=Empresa&id_type=02&is_active=true&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los clientes (receptores reutilizables) registrados por el\ncontribuyente, con soporte para b\u00fasqueda por texto, filtro por tipo\nde identificaci\u00f3n y filtro por estado.\n\nPor defecto, el listado incluye **solo clientes activos** ordenados\nalfab\u00e9ticamente por nombre. Para ver los inactivos use\n`is_active=false`, y para ver todos use `is_active=all`.\n\nLa b\u00fasqueda por texto (`q`) es case-insensitive y busca en:\nnombre legal, nombre comercial y n\u00famero de c\u00e9dula." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101123456\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"commercial_name\": \"Ejemplo Shop\",\n \"location\": {\"province\": 1, \"canton\": \"01\", \"district\": \"01\"},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"emails\": [\"facturacion@ejemplo.cr\"],\n \"default_activity_code\": \"6121.0\",\n \"notes\": \"Cliente preferencial\",\n \"is_active\": true,\n \"has_location\": true,\n \"has_email\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-10T14:30:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 4, \"per_page\": 15, \"total\": 50, \"from\": 1, \"to\": 15},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": \"...\"}\n}", "name": "Listado paginado" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 0, \"from\": null, \"to\": null},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Sin resultados" } ] }, { "name": "Crear un nuevo cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/clients", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/clients" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"id_type\":\"02\",\"id_number\":\"3101123456\",\"name\":\"EMPRESA EJEMPLO S.A.\",\"commercial_name\":\"Ejemplo Shop\",\"province\":1,\"canton\":1,\"district\":1,\"neighborhood\":\"San Pedro\",\"address\":\"200 metros norte del parque central\",\"phone_country_code\":506,\"phone\":\"22001234\",\"emails\":[\"facturacion@ejemplo.cr\"],\"default_activity_code\":\"6121.0\",\"notes\":\"Cliente preferencial\",\"is_active\":true}" }, "description": "Registra un cliente (receptor reutilizable) en el cat\u00e1logo del\ncontribuyente. Los datos corresponden a los campos del receptor\ndefinidos en la normativa de comprobantes electr\u00f3nicos.\n\n**Reglas de validaci\u00f3n:**\n\n- `id_type` + `id_number` deben ser **\u00fanicos** por contribuyente.\n- `default_activity_code` debe estar en **formato Hacienda `XXXX.X`**\n (cuatro d\u00edgitos, punto, un d\u00edgito). Ejemplo: `6121.0`.\n- `emails` es un arreglo con m\u00e1ximo 4 correos v\u00e1lidos.\n- `phone` debe tener entre 4 y 20 d\u00edgitos.\n\nLos campos de ubicaci\u00f3n (`province`, `canton`, `district`) son\ntodos opcionales individualmente, pero si env\u00eda uno deber\u00eda\nenviar los tres para que la ubicaci\u00f3n sea coherente." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101123456\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"commercial_name\": \"Ejemplo Shop\",\n \"location\": {\"province\": 1, \"canton\": \"01\", \"district\": \"01\"},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"emails\": [\"facturacion@ejemplo.cr\"],\n \"default_activity_code\": \"6121.0\",\n \"notes\": \"Cliente preferencial\",\n \"is_active\": true,\n \"has_location\": true,\n \"has_email\": true,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Cliente creado correctamente.\",\n \"errors\": null\n}", "name": "Cliente creado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"id_number\": [\"Ya existe un cliente con este tipo y n\u00famero de identificaci\u00f3n.\"]\n }\n}", "name": "Identificaci\u00f3n duplicada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"default_activity_code\": [\"Debe tener el formato XXXX.X (ejemplo: 6121.0).\"]\n }\n}", "name": "Formato de actividad econ\u00f3mica inv\u00e1lido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"id_type\": [\"El tipo seleccionado no es v\u00e1lido.\"]\n }\n}", "name": "Tipo de identificaci\u00f3n inv\u00e1lido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"plan\": [\"Ha alcanzado el l\u00edmite de clientes de su plan. Actualice a un plan superior.\"]\n }\n}", "name": "L\u00edmite del plan alcanzado" } ] }, { "name": "Consultar un cliente por UUID", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/clients\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/clients\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID del cliente." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle completo del cliente indicado. Solo se retornan\nclientes que pertenecen a su contribuyente. Los clientes eliminados\n(soft delete) retornan **404** | no se pueden consultar." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101123456\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"commercial_name\": \"Ejemplo Shop\",\n \"location\": {\"province\": 1, \"canton\": \"01\", \"district\": \"01\"},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"emails\": [\"facturacion@ejemplo.cr\"],\n \"default_activity_code\": \"6121.0\",\n \"notes\": \"Cliente preferencial\",\n \"is_active\": true,\n \"has_location\": true,\n \"has_email\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-10T14:30:00-06:00\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Cliente encontrado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] }, { "name": "Editar un cliente existente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/clients\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/clients\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID del cliente." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"id_type\":\"02\",\"id_number\":\"3101123456\",\"name\":\"Nombre Actualizado S.A.\",\"commercial_name\":\"Nuevo Nombre Comercial\",\"province\":1,\"canton\":1,\"district\":1,\"neighborhood\":\"Escalante\",\"address\":\"Frente al parque\",\"phone_country_code\":506,\"phone\":\"22009999\",\"emails\":[\"facturacion@ejemplo.cr\",\"contabilidad@ejemplo.cr\"],\"default_activity_code\":\"6121.0\",\"notes\":\"Cliente preferencial | actualizado\",\"is_active\":true}" }, "description": "Admite **actualizaci\u00f3n parcial** | env\u00ede \u00fanicamente los campos que\ndesea modificar. Los campos no enviados conservan su valor actual.\n\n> **Importante:** editar un cliente **no afecta** a los comprobantes\n> ya emitidos con \u00e9l. Los datos del receptor se copian al\n> comprobante en el momento de la emisi\u00f3n y no cambian\n> retroactivamente (inmutabilidad post-emisi\u00f3n por normativa fiscal).\n\nSi cambia el `id_type` o `id_number`, el sistema verifica que la\nnueva combinaci\u00f3n no est\u00e9 en uso por otro cliente del mismo\ncontribuyente. Si ya existe, responde **HTTP 422**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101123456\",\n \"name\": \"Nombre Actualizado S.A.\",\n \"commercial_name\": \"Nuevo Nombre Comercial\",\n \"location\": {\"province\": 1, \"canton\": \"01\", \"district\": \"01\"},\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200 metros norte del parque central\",\n \"phone\": {\"country_code\": 506, \"number\": \"22001234\"},\n \"emails\": [\"facturacion@ejemplo.cr\", \"contabilidad@ejemplo.cr\"],\n \"default_activity_code\": \"6121.0\",\n \"notes\": \"Cliente preferencial | actualizado\",\n \"is_active\": true,\n \"has_location\": true,\n \"has_email\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T11:00:00-06:00\"\n },\n \"message\": \"Cliente actualizado correctamente.\",\n \"errors\": null\n}", "name": "Cliente actualizado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "Cliente no encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe un cliente con este tipo y n\u00famero de identificaci\u00f3n.\",\n \"errors\": {\"id_number\": [\"Duplicado para este contribuyente.\"]}\n}", "name": "Identificaci\u00f3n duplicada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"default_activity_code\": [\"Debe tener el formato XXXX.X (ejemplo: 6121.0).\"]}\n}", "name": "Formato de actividad econ\u00f3mica inv\u00e1lido" } ] }, { "name": "Eliminar un cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/clients\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/clients\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID del cliente." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Realiza un **soft delete** del cliente. El registro queda marcado\ncomo eliminado pero no se borra f\u00edsicamente | por eso puede:\n\n- **Crear un nuevo cliente** con la misma combinaci\u00f3n `id_type` +\n `id_number` despu\u00e9s de eliminar uno. La restricci\u00f3n de unicidad\n solo aplica a registros activos (no eliminados).\n- Los **comprobantes ya emitidos** con este cliente **no se ven\n afectados** | los datos del receptor se copiaron al comprobante\n al momento de la emisi\u00f3n (inmutabilidad post-emisi\u00f3n)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Cliente eliminado correctamente.\",\n \"errors\": null\n}", "name": "Cliente eliminado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] } ] }, { "name": "Items \/ Productos", "description": "", "item": [ { "name": "Listar productos y servicios del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/items", "query": [ { "key": "q", "value": "consultor%C3%ADa", "description": "B\u00fasqueda por descripci\u00f3n, c\u00f3digo interno o c\u00f3digo CABYS (m\u00ednimo 2 caracteres).", "disabled": false }, { "key": "cabys_code", "value": "4233201000000", "description": "Filtrar por c\u00f3digo CABYS exacto (13 d\u00edgitos).", "disabled": false }, { "key": "for_contributor_id", "value": "0b3f1c2a-0000-4000-8000-000000000000", "description": "Selector al facturar: UUID del contribuyente seleccionado. Devuelve los items de su alcance M\u00c1S el pozo general. Sin este par\u00e1metro se listan todos los items del cat\u00e1logo.", "disabled": false }, { "key": "is_active", "value": "true", "description": "Filtrar por estado. `true` = solo activos (default), `false` = solo inactivos.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100). Default: 15.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/items?q=consultor%C3%ADa&cabys_code=4233201000000&for_contributor_id=0b3f1c2a-0000-4000-8000-000000000000&is_active=true&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los items (productos\/servicios reutilizables) registrados\npor el contribuyente, con soporte para b\u00fasqueda por texto, filtro\npor c\u00f3digo CABYS exacto y filtro por estado.\n\nPor defecto, el listado incluye **solo items activos** ordenados\nalfab\u00e9ticamente por descripci\u00f3n. Para ver los inactivos use\n`is_active=false`.\n\nLa b\u00fasqueda por texto (`q`) es case-insensitive y busca en:\ndescripci\u00f3n, c\u00f3digo interno (SKU) y c\u00f3digo CABYS." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0010-7288-8ece-fd64da756010\",\n \"cabys_code\": \"4233201000000\",\n \"internal_code\": \"SKU-001\",\n \"description\": \"Servicio de consultor\u00eda profesional\",\n \"unit_of_measure\": \"Sp\",\n \"unit_of_measure_label\": \"Servicios Profesionales\",\n \"commercial_unit\": null,\n \"unit_price\": \"50000.00000\",\n \"tax\": {\n \"code\": \"01\",\n \"rate_code\": \"08\",\n \"rate\": \"13.00\",\n \"label\": \"IVA 13%\"\n },\n \"is_mercancia\": false,\n \"is_servicio\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-10T14:30:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 2, \"per_page\": 15, \"total\": 30, \"from\": 1, \"to\": 15},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": \"...\"}\n}", "name": "Listado paginado" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 0, \"from\": null, \"to\": null},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Sin resultados" } ] }, { "name": "Crear un nuevo producto o servicio", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/items", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/items" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"cabys_code\":\"4233201000000\",\"internal_code\":\"SKU-001\",\"description\":\"Servicio de consultor\u00eda profesional\",\"unit_of_measure\":\"Sp\",\"commercial_unit\":\"caja x 12\",\"unit_price\":50000,\"tax_code\":\"01\",\"tax_rate_code\":\"08\",\"tax_factor\":4326.41688,\"tax_rate\":13,\"is_active\":true}" }, "description": "Registra un item reutilizable en el cat\u00e1logo del contribuyente. Los\ndatos corresponden a los campos de una l\u00ednea de detalle del\ncomprobante.\n\n**Reglas de validaci\u00f3n:**\n\n- `cabys_code` es **obligatorio** y debe existir en el cat\u00e1logo\n CABYS vigente (13 d\u00edgitos).\n- `internal_code` es opcional, pero si se env\u00eda debe ser **\u00fanico**\n por contribuyente.\n- Si `tax_code` es `01` (IVA) o `07` (IVA c\u00e1lculo especial),\n `tax_rate_code` es obligatorio.\n- Si `tax_code` se env\u00eda, `tax_rate` tambi\u00e9n es obligatorio.\n- Si `unit_of_measure` es `Otros`, `commercial_unit` es obligatorio." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0011-7288-8ece-fd64da756011\",\n \"cabys_code\": \"4233201000000\",\n \"internal_code\": \"SKU-001\",\n \"description\": \"Servicio de consultor\u00eda profesional\",\n \"unit_of_measure\": \"Sp\",\n \"unit_of_measure_label\": \"Servicios Profesionales\",\n \"commercial_unit\": null,\n \"unit_price\": \"50000.00000\",\n \"tax\": {\n \"code\": \"01\",\n \"rate_code\": \"08\",\n \"rate\": \"13.00\",\n \"label\": \"IVA 13%\"\n },\n \"is_mercancia\": false,\n \"is_servicio\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Item creado correctamente.\",\n \"errors\": null\n}", "name": "Item creado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"internal_code\": [\"Ya existe un item con este c\u00f3digo interno.\"]}\n}", "name": "C\u00f3digo interno duplicado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"cabys_code\": [\"El c\u00f3digo CABYS no existe en el cat\u00e1logo vigente.\"]}\n}", "name": "C\u00f3digo CABYS no existe en el cat\u00e1logo" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA c\u00e1lculo especial (07).\",\n \"errors\": {\"tax_rate_code\": [\"tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA c\u00e1lculo especial (07).\"]}\n}", "name": "Falta tax_rate_code para IVA" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"commercial_unit es obligatoria cuando unit_of_measure es 'Otros'.\",\n \"errors\": {\"commercial_unit\": [\"commercial_unit es obligatoria cuando unit_of_measure es 'Otros'.\"]}\n}", "name": "Unit_of_measure 'Otros' sin commercial_unit" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan\": [\"Ha alcanzado el l\u00edmite de items de su plan. Actualice a un plan superior.\"]}\n}", "name": "L\u00edmite del plan alcanzado" } ] }, { "name": "Consultar un item por UUID", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/items\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/items\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0010-7288-8ece-fd64da756010", "description": "UUID del item." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle completo del item indicado. Solo se retornan\nitems que pertenecen a su contribuyente. Los items eliminados\n(soft delete) retornan **404** | no se pueden consultar." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0010-7288-8ece-fd64da756010\",\n \"cabys_code\": \"4233201000000\",\n \"internal_code\": \"SKU-001\",\n \"description\": \"Servicio de consultor\u00eda profesional\",\n \"unit_of_measure\": \"Sp\",\n \"unit_of_measure_label\": \"Servicios Profesionales\",\n \"commercial_unit\": null,\n \"unit_price\": \"50000.00000\",\n \"tax\": {\n \"code\": \"01\",\n \"rate_code\": \"08\",\n \"rate\": \"13.00\",\n \"label\": \"IVA 13%\"\n },\n \"is_mercancia\": false,\n \"is_servicio\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-10T14:30:00-06:00\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Item encontrado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] }, { "name": "Editar un item existente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/items\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/items\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0010-7288-8ece-fd64da756010", "description": "UUID del item." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"cabys_code\":\"4233201000000\",\"internal_code\":\"SKU-001-V2\",\"description\":\"Servicio de consultor\u00eda profesional actualizado\",\"unit_of_measure\":\"Sp\",\"commercial_unit\":\"caja x 12\",\"unit_price\":55000,\"tax_code\":\"01\",\"tax_rate_code\":\"08\",\"tax_rate\":13,\"is_active\":true}" }, "description": "Admite **actualizaci\u00f3n parcial** | env\u00ede \u00fanicamente los campos que\ndesea modificar. Los campos no enviados conservan su valor actual.\n\n> **Importante:** editar un item **no afecta** a los comprobantes\n> ya emitidos con \u00e9l. Los datos de la l\u00ednea se copian al comprobante\n> en el momento de la emisi\u00f3n y no cambian retroactivamente\n> (inmutabilidad post-emisi\u00f3n por normativa fiscal).\n\n**Validaciones cruzadas que se aplican al editar:**\n\n- Si cambia `internal_code`, se verifica que no est\u00e9 en uso por\n otro item del mismo contribuyente.\n- Si cambia `cabys_code`, se valida contra el cat\u00e1logo CABYS vigente.\n- Si `tax_code` queda en `01` o `07` pero no hay `tax_rate_code`,\n la edici\u00f3n se rechaza.\n- Si `unit_of_measure` queda en `Otros` pero no hay `commercial_unit`,\n la edici\u00f3n se rechaza." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0010-7288-8ece-fd64da756010\",\n \"cabys_code\": \"4233201000000\",\n \"internal_code\": \"SKU-001-V2\",\n \"description\": \"Servicio de consultor\u00eda profesional actualizado\",\n \"unit_of_measure\": \"Sp\",\n \"unit_of_measure_label\": \"Servicios Profesionales\",\n \"commercial_unit\": null,\n \"unit_price\": \"55000.00000\",\n \"tax\": {\n \"code\": \"01\",\n \"rate_code\": \"08\",\n \"rate\": \"13.00\",\n \"label\": \"IVA 13%\"\n },\n \"is_mercancia\": false,\n \"is_servicio\": true,\n \"is_active\": true,\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T11:00:00-06:00\"\n },\n \"message\": \"Item actualizado correctamente.\",\n \"errors\": null\n}", "name": "Item actualizado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "Item no encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe un item con el c\u00f3digo interno [SKU-001-V2].\",\n \"errors\": {\"internal_code\": [\"Duplicado para este contribuyente.\"]}\n}", "name": "C\u00f3digo interno duplicado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El c\u00f3digo CABYS [9999999999999] no existe en el cat\u00e1logo vigente.\",\n \"errors\": {\"cabys_code\": [\"C\u00f3digo CABYS no encontrado.\"]}\n}", "name": "C\u00f3digo CABYS no existe" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA c\u00e1lculo especial (07).\",\n \"errors\": {\"tax_rate_code\": [\"tax_rate_code es obligatorio cuando tax_code es IVA (01) o IVA c\u00e1lculo especial (07).\"]}\n}", "name": "Falta tax_rate_code para IVA" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"tax_rate es obligatorio cuando se especifica tax_code.\",\n \"errors\": {\"tax_rate\": [\"Env\u00ede tax_rate junto con tax_code.\"]}\n}", "name": "Falta tax_rate cuando hay tax_code" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"commercial_unit es obligatoria cuando unit_of_measure es 'Otros'.\",\n \"errors\": {\"commercial_unit\": [\"commercial_unit es obligatoria cuando unit_of_measure es 'Otros'.\"]}\n}", "name": "unit_of_measure 'Otros' sin commercial_unit" } ] }, { "name": "Eliminar un item", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/items\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/items\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0010-7288-8ece-fd64da756010", "description": "UUID del item." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Realiza un **soft delete** del item. El registro queda marcado como\neliminado pero no se borra f\u00edsicamente | por eso puede:\n\n- **Crear un nuevo item** con el mismo `internal_code` despu\u00e9s de\n eliminar uno. La restricci\u00f3n de unicidad solo aplica a items\n activos (no eliminados).\n- Los **comprobantes ya emitidos** con este item **no se ven\n afectados** | los datos de la l\u00ednea se copiaron al comprobante\n al momento de la emisi\u00f3n (inmutabilidad post-emisi\u00f3n)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Item eliminado correctamente.\",\n \"errors\": null\n}", "name": "Item eliminado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Recurso no encontrado.\",\n \"errors\": null\n}", "name": "No encontrado" } ] } ] }, { "name": "Secuencias", "description": "", "item": [ { "name": "Listar secuencias del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/sequences", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/sequences" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todas las secuencias de consecutivos (sucursal + terminal +\ntipo de comprobante) registradas por el contribuyente autenticado,\nordenadas por sucursal, terminal y tipo.\n\nCada secuencia representa un contador independiente del consecutivo de\n20 d\u00edgitos definido en la normativa (p\u00e1g. 65 Anexos): los 3 d\u00edgitos de\nsucursal (`local_code`), 5 de terminal (`terminal_code`), 2 del tipo\n(`voucher_type`) y 10 del consecutivo correlativo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"local_code\": \"001\",\n \"terminal_code\": \"00001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"voucher_type_abbr\": \"FE\",\n \"current_sequence\": 42,\n \"next_sequence\": 43,\n \"last_consecutive\": \"00100001010000000042\",\n \"next_consecutive\": \"00100001010000000043\",\n \"last_issued_at\": \"2026-04-10T14:30:00-06:00\",\n \"last_issued_key\": \"506041026...00000042\",\n \"is_active\": true,\n \"is_near_rollover\": false,\n \"display_key\": \"001-00001-01\"\n }\n ],\n \"message\": \"Secuencias del contribuyente.\",\n \"errors\": null\n}", "name": "Listado de secuencias" } ] }, { "name": "Crear una secuencia (sucursal\/terminal)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/sequences", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/sequences" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"local_code\":\"001\",\"terminal_code\":\"00001\",\"voucher_type\":\"01\",\"current_sequence\":9992}" }, "description": "Registra una nueva secuencia de consecutivos para una combinaci\u00f3n de\n**sucursal + terminal + tipo de comprobante** del contribuyente\nautenticado. \u00datil para dar de alta una nueva caja, sucursal o un tipo\nde comprobante que a\u00fan no tiene secuencia.\n\n**Reglas de validaci\u00f3n:**\n\n- `local_code` + `terminal_code` + `voucher_type` deben ser una\n combinaci\u00f3n **\u00fanica**. Duplicar responde **HTTP 422**.\n- `local_code` son 3 d\u00edgitos y no puede ser `000`.\n- `terminal_code` son 5 d\u00edgitos y no puede ser `00000`.\n- `voucher_type` debe ser uno de los 7 tipos de emisi\u00f3n directa.\n- Crear una terminal nueva consume cupo del plan\n (`max_branch_terminals`); si lo supera responde **HTTP 422**.\n\nLa secuencia se crea con `is_active=true`." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"local_code\": \"001\",\n \"terminal_code\": \"00001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"voucher_type_abbr\": \"FE\",\n \"current_sequence\": 9992,\n \"next_sequence\": 9993,\n \"last_consecutive\": \"00100001010000009992\",\n \"next_consecutive\": \"00100001010000009993\",\n \"last_issued_at\": null,\n \"last_issued_key\": null,\n \"is_active\": true,\n \"is_near_rollover\": false,\n \"display_key\": \"001-00001-01\"\n },\n \"message\": \"Secuencia creada.\",\n \"errors\": null\n}", "name": "Secuencia creada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe una secuencia para esa sucursal, terminal y tipo.\",\n \"errors\": {\"voucher_type\": [\"Secuencia duplicada.\"]}\n}", "name": "Secuencia duplicada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ha alcanzado el l\u00edmite de terminales de su plan.\",\n \"errors\": {\"terminal_code\": [\"Ha alcanzado el l\u00edmite de terminales de su plan.\"]}\n}", "name": "L\u00edmite del plan alcanzado" } ] }, { "name": "Ajustar una secuencia existente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/sequences\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/sequences\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID de la secuencia." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"current_sequence\":9992,\"is_active\":true,\"reason\":\"Migraci\u00f3n desde Alegra, \u00faltimo consecutivo tipo 01 fue 9992.\",\"password\":\"MiC0ntr4se\u00f14\"}" }, "description": "Admite **actualizaci\u00f3n parcial** del `current_sequence` y\/o del estado\n`is_active` de una secuencia del contribuyente autenticado. Solo se\npueden ajustar secuencias propias; una secuencia inexistente o de otro\ncontribuyente responde **HTTP 404**.\n\n> **Importante:** bajar `current_sequence` por debajo del \u00faltimo\n> consecutivo **ya emitido** se rechaza con 422: el pr\u00f3ximo comprobante\n> repetir\u00eda un n\u00famero existente y Hacienda lo rechazar\u00eda. S\u00ed se permite\n> ajustarlo por encima de ese piso, que es el escenario leg\u00edtimo de\n> migraci\u00f3n desde otro facturador.\n>\n> Cambiar el consecutivo exige **confirmaci\u00f3n de contrase\u00f1a** y queda\n> registrado en la bit\u00e1cora de auditor\u00eda con el valor anterior, el\n> nuevo, el motivo, el usuario y la IP (Resoluci\u00f3n MH-DGT-RES-0027-2024,\n> art. 6).\n\nEl motivo (`reason`) es **obligatorio** en toda actualizaci\u00f3n." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"local_code\": \"001\",\n \"terminal_code\": \"00001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"voucher_type_abbr\": \"FE\",\n \"current_sequence\": 9992,\n \"next_sequence\": 9993,\n \"last_consecutive\": \"00100001010000009992\",\n \"next_consecutive\": \"00100001010000009993\",\n \"last_issued_at\": \"2026-04-10T14:30:00-06:00\",\n \"last_issued_key\": \"506041026...00009992\",\n \"is_active\": true,\n \"is_near_rollover\": false,\n \"display_key\": \"001-00001-01\"\n },\n \"message\": \"Secuencia actualizada.\",\n \"errors\": null\n}", "name": "Secuencia actualizada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Secuencia no encontrada.\",\n \"errors\": null\n}", "name": "Secuencia no encontrada" } ] } ] }, { "name": "Sucursales y cajas", "description": "", "item": [ { "name": "Listar sucursales y cajas propias", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve las sucursales (branches) directas del contribuyente autenticado,\ncada una con sus cajas (terminals). La sucursal directa usa slot `00` en el\n`terminal_code` (= `00` + caja de 3 d\u00edg.); la primera caja es `00001`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019ee0-...\", \"local_code\": \"001\", \"name\": \"Casa Matriz\",\n \"is_active\": true, \"is_direct\": true,\n \"terminals\": [{ \"id\": \"019ee1-...\", \"terminal_code\": \"00001\", \"slot\": \"00\", \"box\": \"001\", \"name\": \"Caja 1\", \"is_active\": true }],\n \"created_at\": \"2026-06-19T15:00:00-06:00\"\n }\n ],\n \"message\": \"Sucursales del contribuyente.\", \"errors\": null\n}", "name": "Sucursales del contribuyente" } ] }, { "name": "Crear una sucursal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"local_code\":\"002\",\"name\":\"Sucursal Heredia\",\"box_name\":\"Caja Principal\"}" }, "description": "Crea una sucursal directa del contribuyente y, autom\u00e1ticamente, su primera\ncaja (toda sucursal nace con \u22651 caja). Consume cupo del POZO del plan\n(`max_branches`). La primera caja directa es `00001`." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": { \"id\": \"019ee0-...\", \"local_code\": \"002\", \"name\": \"Sucursal Heredia\", \"is_direct\": true, \"terminals\": [{ \"terminal_code\": \"00002\", \"name\": \"Caja Principal\", \"is_active\": true }] },\n \"message\": \"Sucursal creada.\", \"errors\": null\n}", "name": "Sucursal creada (con su primera caja)" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Esa sucursal ya existe.\", \"errors\": { \"local_code\": [\"Ya ten\u00e9s una sucursal con ese c\u00f3digo.\"] }\n}", "name": "Sucursal duplicada" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Alcanz\u00f3 el pozo de 2 sucursal(es) de su plan. Actualice su plan para agregar m\u00e1s.\", \"errors\": { \"local_code\": [\"Alcanz\u00f3 el pozo de 2 sucursal(es) de su plan. Actualice su plan para agregar m\u00e1s.\"] }\n}", "name": "Pozo del plan agotado" } ] }, { "name": "Actualizar una sucursal (nombre y\/o c\u00f3digo)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches\/:id", "variable": [ { "id": "id", "key": "id", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Casa Matriz San Jos\u00e9\",\"local_code\":\"002\",\"reason\":\"Numeraci\u00f3n heredada del sistema anterior\",\"password\":\"MiC0ntr4se\u00f14\"}" }, "description": "Cambia el nombre de la sucursal y\/o su `local_code` (posiciones 01-03 del\nNumeroConsecutivo). Cambiar el c\u00f3digo exige confirmar la contrase\u00f1a y\nmigra las secuencias existentes al c\u00f3digo nuevo (nunca las reinicia), de\nmodo que la numeraci\u00f3n contin\u00faa donde iba. Pensado para cuentas que\nmigran desde otro sistema de facturaci\u00f3n y necesitan conservar su\nnumeraci\u00f3n de sucursal (p. ej. casa matriz 002 en vez de 001)." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": { \"id\": \"019ee0-...\", \"local_code\": \"002\", \"name\": \"Casa Matriz San Jos\u00e9\" }, \"message\": \"Sucursal actualizada.\", \"errors\": null }", "name": "Sucursal actualizada" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"La sucursal no existe.\", \"errors\": null }", "name": "Sucursal inexistente" }, { "header": [], "code": 422, "body": "{ \"success\": false, \"data\": null, \"message\": \"Ya ten\u00e9s una sucursal con ese c\u00f3digo.\", \"errors\": { \"local_code\": [\"Ya ten\u00e9s una sucursal con ese c\u00f3digo.\"] } }", "name": "C\u00f3digo duplicado" } ] }, { "name": "Agregar una caja a una sucursal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches\/:id\/terminals", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches\/:id\/terminals", "variable": [ { "id": "id", "key": "id", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Caja 2\"}" }, "description": "Crea una caja (terminal) en la sucursal directa indicada. El `terminal_code`\nse asigna autom\u00e1ticamente: slot `00` + la siguiente caja libre (los c\u00f3digos\nborrados no se reutilizan). Respeta el tope de cajas por sucursal del plan." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": { \"id\": \"019ee0-...\", \"local_code\": \"001\", \"terminals\": [{ \"terminal_code\": \"00001\", \"name\": \"Caja 1\" }, { \"terminal_code\": \"00002\", \"name\": \"Caja 2\" }] },\n \"message\": \"Caja creada.\", \"errors\": null\n}", "name": "Caja creada" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"La sucursal no existe.\", \"errors\": null }", "name": "Sucursal inexistente" }, { "header": [], "code": 422, "body": "{ \"success\": false, \"data\": null, \"message\": \"Alcanz\u00f3 el tope de 3 caja(s) por sucursal de su plan.\", \"errors\": { \"name\": [\"Actualice su plan para agregar m\u00e1s cajas.\"] } }", "name": "Tope de cajas alcanzado" } ] }, { "name": "Actualizar una caja (nombre y\/o c\u00f3digo)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches\/:id\/terminals\/:tid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches\/:id\/terminals\/:tid", "variable": [ { "id": "id", "key": "id", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." }, { "id": "tid", "key": "tid", "value": "019ee1bb-cccc-dddd-eeee-ffffffffffff", "description": "UUID de la caja." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"POS Entrada\",\"terminal_code\":\"00003\",\"delegated_issuance\":true,\"reason\":\"Numeraci\u00f3n heredada del sistema anterior\",\"password\":\"MiC0ntr4se\u00f14\"}" }, "description": "Cambia el nombre de la caja y\/o su `terminal_code` (posiciones 04-08 del\nNumeroConsecutivo). Cambiar el c\u00f3digo exige confirmar la contrase\u00f1a y\nmigra las secuencias existentes al c\u00f3digo nuevo (nunca las reinicia).\nPensado para cuentas que migran desde otro sistema y necesitan conservar\nsu numeraci\u00f3n de caja (p. ej. 00003 en vez de 00001). No se permite un\nc\u00f3digo ya reservado por la terminal de un integrador que gestione (o\nhaya gestionado) esta cuenta." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": { \"id\": \"019ee0-...\", \"terminals\": [{ \"terminal_code\": \"00003\", \"name\": \"POS Entrada\" }] }, \"message\": \"Caja actualizada.\", \"errors\": null }", "name": "Caja actualizada" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"La caja no existe.\", \"errors\": null }", "name": "Caja inexistente" }, { "header": [], "code": 422, "body": "{ \"success\": false, \"data\": null, \"message\": \"Ya ten\u00e9s una caja con ese c\u00f3digo.\", \"errors\": { \"terminal_code\": [\"Ya ten\u00e9s una caja con ese c\u00f3digo.\"] } }", "name": "C\u00f3digo en uso" } ] }, { "name": "Eliminar una caja", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches\/:id\/terminals\/:tid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches\/:id\/terminals\/:tid", "variable": [ { "id": "id", "key": "id", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." }, { "id": "tid", "key": "tid", "value": "019ee1bb-cccc-dddd-eeee-ffffffffffff", "description": "UUID de la caja." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Borra (soft delete) una caja de la sucursal. No se puede eliminar la \u00faltima\ncaja activa de la sucursal (toda sucursal debe conservar \u22651 caja). El c\u00f3digo\nde la caja borrada no se reutiliza." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": null, \"message\": \"Caja eliminada.\", \"errors\": null }", "name": "Caja eliminada" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"La caja no existe.\", \"errors\": null }", "name": "Caja inexistente" }, { "header": [], "code": 409, "body": "{ \"success\": false, \"data\": null, \"message\": \"Deb\u00e9s mantener al menos una caja en la sucursal.\", \"errors\": null }", "name": "Es la \u00faltima caja de la sucursal" } ] }, { "name": "Eliminar una sucursal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/branches\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/branches\/:id", "variable": [ { "id": "id", "key": "id", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Borra (soft delete) la sucursal junto con sus cajas. No se puede eliminar la\n\u00faltima sucursal del contribuyente (siempre debe quedar \u22651)." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": null, \"message\": \"Sucursal eliminada.\", \"errors\": null }", "name": "Sucursal eliminada" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"La sucursal no existe.\", \"errors\": null }", "name": "Sucursal inexistente" }, { "header": [], "code": 409, "body": "{ \"success\": false, \"data\": null, \"message\": \"Deb\u00e9s mantener al menos una sucursal.\", \"errors\": null }", "name": "Es la \u00faltima sucursal" } ] } ] }, { "name": "Webhooks", "description": "", "item": [ { "name": "Listar webhook endpoints registrados", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks", "query": [ { "key": "is_active", "value": "1", "description": "Filtrar por estado. Sin filtro: muestra todos.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100).", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks?is_active=1&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todos los endpoints de su cuenta (activos e inactivos),\nordenados del m\u00e1s reciente al m\u00e1s antiguo. Cada endpoint incluye su\nestado de salud actual y los timestamps del \u00faltimo intento de entrega.\n\nEl campo `health_status` puede tomar los valores:\n- `healthy` | activo, sin fallos recientes.\n- `degraded` | activo pero con fallos consecutivos (entre 1 y 9).\n- `disabled` | desactivado autom\u00e1ticamente tras 10 fallos consecutivos.\n- `inactive` | desactivado manualmente.\n- `never_used` | activo, a\u00fan no se ha disparado ning\u00fan evento hacia \u00e9l." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a\",\n \"url\": \"https:\/\/api.miempresa.cr\/webhooks\/Almendro\",\n \"secret\": \"whsec_****************************ab3f\",\n \"events\": [\"voucher.accepted\", \"voucher.rejected\"],\n \"events_detail\": [\n {\"value\": \"voucher.accepted\", \"label\": \"Comprobante aceptado por Hacienda\", \"group\": \"voucher\"},\n {\"value\": \"voucher.rejected\", \"label\": \"Comprobante rechazado por Hacienda\", \"group\": \"voucher\"}\n ],\n \"description\": \"Webhook principal e-commerce\",\n \"is_active\": true,\n \"health_status\": \"healthy\",\n \"consecutive_failures\": 0,\n \"last_triggered_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_success_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_failure_at\": null,\n \"last_failure_reason\": null,\n \"created_at\": \"2026-03-20T08:00:00-06:00\",\n \"updated_at\": \"2026-03-22T10:30:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"total\": 3, \"per_page\": 15, \"last_page\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "success" } ] }, { "name": "Crear un webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/api.miempresa.cr\\\/webhooks\\\/Almendro\",\"events\":[\"voucher.accepted\",\"voucher.rejected\"],\"description\":\"Webhook principal e-commerce\",\"is_active\":true}" }, "description": "Registra una URL HTTPS que recibir\u00e1 notificaciones para los eventos\nque usted seleccione. El sistema genera autom\u00e1ticamente un **secret\n\u00fanico de 64 caracteres** que deber\u00e1 usar para verificar la firma de\ncada entrega.\n\n> **Importante:** el secret completo se devuelve **una \u00fanica vez**\n> en esta respuesta, en el campo `secret`. Almac\u00e9nelo de forma segura\n> en ese momento | en consultas posteriores (`GET \/webhooks\/{id}`) solo\n> ver\u00e1 una versi\u00f3n enmascarada (`whsec_****...ab3f`). Para obtener un\n> nuevo secret deber\u00e1 eliminar el endpoint y crear uno nuevo.\n\n**Consejos para la URL:**\n\n- Debe empezar con `https:\/\/` | no se acepta HTTP plano.\n- El certificado TLS debe ser v\u00e1lido (no auto-firmado).\n- La URL debe responder POST en menos de 15 segundos.\n- Evite URLs con query string | el path es suficiente." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a\",\n \"url\": \"https:\/\/api.miempresa.cr\/webhooks\/Almendro\",\n \"secret\": \"a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f6ab3f\",\n \"events\": [\"voucher.accepted\", \"voucher.rejected\"],\n \"events_detail\": [\n {\"value\": \"voucher.accepted\", \"label\": \"Comprobante aceptado por Hacienda\", \"group\": \"voucher\"},\n {\"value\": \"voucher.rejected\", \"label\": \"Comprobante rechazado por Hacienda\", \"group\": \"voucher\"}\n ],\n \"description\": \"Webhook principal e-commerce\",\n \"is_active\": true,\n \"health_status\": \"never_used\",\n \"consecutive_failures\": 0,\n \"last_triggered_at\": null,\n \"last_success_at\": null,\n \"last_failure_at\": null,\n \"last_failure_reason\": null,\n \"created_at\": \"2026-03-22T10:30:00-06:00\",\n \"updated_at\": \"2026-03-22T10:30:00-06:00\"\n },\n \"message\": \"Webhook endpoint creado. Almacene el secret | no se mostrar\u00e1 de nuevo.\",\n \"errors\": null\n}", "name": "created" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"url\": [\"La URL debe usar HTTPS.\"],\n \"events.0\": [\"El evento seleccionado no es v\u00e1lido.\"]\n }\n}", "name": "validation_error" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"plan\": [\"Su plan actual no incluye webhooks. Actualice su plan para usar esta funcionalidad.\"]\n }\n}", "name": "plan_restriction" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\n \"plan\": [\"Ha alcanzado el l\u00edmite de webhooks de su plan (3 endpoints).\"]\n }\n}", "name": "limit_reached" } ] }, { "name": "Consultar un webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a", "description": "UUID del webhook endpoint." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle completo de un endpoint: su URL, eventos\nsuscritos, estado de salud actual, fallos consecutivos acumulados\ny timestamps de la \u00faltima entrega (exitosa y fallida).\n\nEl campo `secret` se devuelve siempre enmascarado en este endpoint\n(`whsec_****...ab3f`), revelando solo los \u00faltimos 4 caracteres para\npermitir identificarlo visualmente. Si extravi\u00f3 el secret original,\ndeber\u00e1 eliminar el endpoint y crear uno nuevo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a\",\n \"url\": \"https:\/\/api.miempresa.cr\/webhooks\/Almendro\",\n \"secret\": \"whsec_****************************ab3f\",\n \"events\": [\"voucher.accepted\", \"voucher.rejected\"],\n \"events_detail\": [\n {\"value\": \"voucher.accepted\", \"label\": \"Comprobante aceptado por Hacienda\", \"group\": \"voucher\"}\n ],\n \"description\": \"Webhook principal e-commerce\",\n \"is_active\": true,\n \"health_status\": \"healthy\",\n \"consecutive_failures\": 0,\n \"last_triggered_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_success_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_failure_at\": null,\n \"last_failure_reason\": null,\n \"created_at\": \"2026-03-20T08:00:00-06:00\",\n \"updated_at\": \"2026-03-22T10:30:00-06:00\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "found" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El recurso solicitado no existe.\",\n \"errors\": null\n}", "name": "not_found" } ] }, { "name": "Editar un webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a", "description": "UUID del webhook endpoint." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/api.miempresa.cr\\\/webhooks\\\/v2\",\"events\":[\"voucher.accepted\",\"voucher.rejected\",\"voucher.sent\"],\"description\":\"Webhook e-commerce v2\",\"is_active\":true}" }, "description": "Admite actualizaci\u00f3n parcial | env\u00ede solo los campos que desee\nmodificar. Los campos no enviados conservan su valor actual.\n\n**Reactivaci\u00f3n de endpoints desactivados autom\u00e1ticamente:** si un\nendpoint fue desactivado por acumular 10 fallos consecutivos, puede\nreactivarlo enviando `is_active = true`. Esto reinicia el contador de\nfallos a 0 y vuelve a incluir el endpoint en futuras entregas.\nAseg\u00farese antes de corregir el problema que caus\u00f3 los fallos.\n\n**Campos editables:**\n\n- `url` | nueva URL HTTPS del receptor.\n- `events` | nueva lista de eventos a suscribir.\n- `description` | descripci\u00f3n opcional.\n- `is_active` | activar \/ desactivar el endpoint.\n\n> El secret **no es editable**. Si necesita rotarlo (por ejemplo,\n> tras una sospecha de compromiso), elimine el endpoint actual y\n> cree uno nuevo | recibir\u00e1 un secret nuevo en la respuesta." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a\",\n \"url\": \"https:\/\/api.miempresa.cr\/webhooks\/v2\",\n \"secret\": \"whsec_****************************ab3f\",\n \"events\": [\"voucher.accepted\", \"voucher.rejected\", \"voucher.sent\"],\n \"description\": \"Webhook e-commerce v2\",\n \"is_active\": true,\n \"health_status\": \"never_used\",\n \"consecutive_failures\": 0,\n \"last_triggered_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_success_at\": \"2026-03-22T10:30:00-06:00\",\n \"last_failure_at\": null,\n \"last_failure_reason\": null,\n \"created_at\": \"2026-03-20T08:00:00-06:00\",\n \"updated_at\": \"2026-03-25T15:45:00-06:00\"\n },\n \"message\": \"Webhook endpoint actualizado correctamente.\",\n \"errors\": null\n}", "name": "updated" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El recurso solicitado no existe.\",\n \"errors\": null\n}", "name": "not_found" } ] }, { "name": "Eliminar un webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks\/:id", "variable": [ { "id": "id", "key": "id", "value": "9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a", "description": "UUID del webhook endpoint." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Elimina el endpoint y deja de recibir notificaciones de todos sus\neventos. Los logs hist\u00f3ricos de entregas se conservan durante el\nper\u00edodo de retenci\u00f3n para consulta y auditor\u00eda | eliminar el\nendpoint no borra sus logs.\n\nTras la eliminaci\u00f3n, puede crear un endpoint nuevo con la misma URL\nsi lo desea. Recibir\u00e1 un secret nuevo en la respuesta de creaci\u00f3n." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Webhook endpoint eliminado correctamente.\",\n \"errors\": null\n}", "name": "deleted" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El recurso solicitado no existe.\",\n \"errors\": null\n}", "name": "not_found" } ] }, { "name": "Consultar el historial de entregas de un endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks\/:id\/logs", "query": [ { "key": "event", "value": "voucher.accepted", "description": "Filtrar por tipo de evento.", "disabled": false }, { "key": "status", "value": "failed", "description": "Filtrar por resultado: success o failed.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Resultados por p\u00e1gina (1-100).", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks\/:id\/logs?event=voucher.accepted&status=failed&per_page=25&page=1", "variable": [ { "id": "id", "key": "id", "value": "9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a", "description": "UUID del webhook endpoint." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el registro de cada intento de entrega hacia el endpoint:\nevento disparado, ID de entrega (\u00fatil para deduplicar), resultado\n(\u00e9xito o fallo), c\u00f3digo HTTP devuelto por su servidor y tiempo de\nrespuesta en milisegundos.\n\nLos logs se conservan durante **3 meses**. \u00datil para:\n\n- Verificar que un evento espec\u00edfico fue entregado.\n- Diagnosticar fallos: qu\u00e9 HTTP code devolvi\u00f3 su endpoint.\n- Medir latencia: campo `response_time_ms`.\n- Auditor\u00eda: trazabilidad completa de notificaciones enviadas.\n\nLos campos voluminosos (`payload` enviado, `response_body` recibido)\nse excluyen del listado por razones de volumen. Si necesita esa\ninformaci\u00f3n para una entrega espec\u00edfica, contacte a soporte\nindicando el `delivery_id`.\n\n**Interpretando el campo `status`:**\n\n- `success` | el endpoint respondi\u00f3 con HTTP 2xx.\n- `failed` | el endpoint respondi\u00f3 con 4xx\/5xx, o hubo timeout\/error de red.\n\nCuando una entrega tiene reintentos, cada intento queda registrado\ncomo una fila separada con el mismo `delivery_id` pero distinto\nvalor de `attempt` (1, 2, 3 o 4)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 12345,\n \"event\": \"voucher.accepted\",\n \"event_label\": \"Comprobante aceptado por Hacienda\",\n \"delivery_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"attempt\": 1,\n \"status\": \"success\",\n \"response_status\": 200,\n \"response_time_ms\": 145,\n \"response_time_formatted\": \"145ms\",\n \"error_message\": null,\n \"created_at\": \"2026-03-22T10:30:05-06:00\"\n },\n {\n \"id\": 12344,\n \"event\": \"voucher.rejected\",\n \"event_label\": \"Comprobante rechazado por Hacienda\",\n \"delivery_id\": \"660f9511-f30c-52e5-b827-557766551111\",\n \"attempt\": 2,\n \"status\": \"failed\",\n \"response_status\": 503,\n \"response_time_ms\": 15000,\n \"response_time_formatted\": \"15.00s\",\n \"error_message\": \"HTTP 503\",\n \"created_at\": \"2026-03-22T10:28:30-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"total\": 87, \"per_page\": 25, \"last_page\": 4},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": \"...\"}\n}", "name": "success" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El recurso solicitado no existe.\",\n \"errors\": null\n}", "name": "endpoint_not_found" } ] }, { "name": "Enviar un evento de prueba", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/webhooks\/:id\/test", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/webhooks\/:id\/test", "variable": [ { "id": "id", "key": "id", "value": "9c1b4e5a-3b2c-4d5e-6f7a-8b9c0d1e2f3a", "description": "UUID del webhook endpoint." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Env\u00eda S\u00cdNCRONAMENTE un payload `webhook.test` al endpoint, firmado con la\nmisma HMAC-SHA256 y los mismos headers `X-Almendro-*` que las entregas\nreales. Sirve para verificar que el receptor est\u00e1 accesible, valida la\nfirma y responde 2xx, sin tener que emitir un comprobante real.\n\nLa entrega queda registrada en el historial (`\/webhooks\/{id}\/logs`) pero\nNO afecta los contadores de salud del endpoint (no auto-desactiva ni\nresetea fallos reales)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": { \"success\": true, \"response_status\": 200, \"response_time_ms\": 142, \"error_message\": null, \"delivery_id\": \"\u2026\" },\n \"message\": \"Evento de prueba entregado correctamente.\",\n \"errors\": null\n}", "name": "delivered" } ] } ] }, { "name": "Reportes", "description": "", "item": [ { "name": "Dashboard", "description": "", "item": [ { "name": "Resumen del dashboard.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/summary", "query": [ { "key": "date_from", "value": "2026-04-01", "description": "Inicio del periodo (YYYY-MM-DD). Default: primer dia del mes actual.", "disabled": false }, { "key": "date_to", "value": "2026-04-30", "description": "Fin del periodo (YYYY-MM-DD). Default: hoy.", "disabled": false }, { "key": "voucher_type", "value": "01%2C04", "description": "CSV de tipos. `01`,`02`,`03`,`04`,`08`,`09`,`10`.", "disabled": false }, { "key": "status", "value": "accepted%2Crejected", "description": "CSV de estados. Default: `accepted`.", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "ISO 4217. Default: `CRC`.", "disabled": false }, { "key": "environment", "value": "production", "description": "`production` o `sandbox`. Default: `production`.", "disabled": false }, { "key": "receiver_id_number", "value": "3101000001", "description": "Cedula del receptor para filtrar.", "disabled": false }, { "key": "sale_condition", "value": "01%2C02", "description": "CSV de condiciones de venta.", "disabled": false }, { "key": "payment_method", "value": "01%2C02", "description": "CSV de medios de pago.", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false }, { "key": "managed_contributor_id", "value": "019d867d-0241-7288-8ece-fd64da75616d", "description": "UUID de un cliente gestionado.\n Solo para integradores. Filtra el resumen para mostrar unicamente\n los comprobantes de ese cliente. Sin este parametro se agregan todos.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/summary?date_from=2026-04-01&date_to=2026-04-30&voucher_type=01%2C04&status=accepted%2Crejected¤cy_code=CRC&environment=production&receiver_id_number=3101000001&sale_condition=01%2C02&payment_method=01%2C02&group_by=month&limit=10&managed_contributor_id=019d867d-0241-7288-8ece-fd64da75616d" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna conteos por estado Hacienda, montos agregados (venta, descuentos,\nimpuestos, total comprobante) y desglose por tipo de comprobante para\nel periodo solicitado.\n\nLos datos son base para la preparacion de la declaracion 150\n(IVA mensual) y 101\/102\/103 (utilidades).\n\n---\n\n### Modo Integrador\n\nCuando el token pertenece a un integrador, este endpoint agrega\nautomaticamente los comprobantes de **todos sus clientes gestionados**.\nLa respuesta incluye adicionalmente el campo `by_contributor` con el\ndesglose por cliente, ordenado de mayor a menor uso.\n\nPara filtrar solo un cliente especifico, use `?managed_contributor_id={uuid}`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\"date_from\": \"2026-04-01\", \"date_to\": \"2026-04-30\", \"currency_code\": \"CRC\", \"environment\": \"production\"},\n \"counts\": {\"total\": 150, \"accepted\": 140, \"rejected\": 5, \"sent\": 3, \"error\": 2, \"cancelled\": 0, \"draft\": 0, \"pending\": 0, \"acceptance_rate\": 96.55},\n \"totals\": {\n \"total_venta\": \"15000000.00000\",\n \"total_descuentos\": \"500000.00000\",\n \"total_venta_neta\": \"14500000.00000\",\n \"total_impuesto\": \"1885000.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"16385000.00000\",\n \"average_per_voucher\": \"117035.71429\"\n },\n \"by_type\": [\n {\"voucher_type\": \"01\", \"voucher_type_label\": \"Factura Electr\u00f3nica\", \"count\": 100, \"total_venta\": \"12000000.00000\", \"total_impuesto\": \"1560000.00000\", \"total_comprobante\": \"13560000.00000\"}\n ]\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Contribuyente normal" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\"date_from\": \"2026-04-01\", \"date_to\": \"2026-04-30\", \"currency_code\": \"CRC\", \"environment\": \"production\"},\n \"counts\": {\"total\": 8500, \"accepted\": 8200, \"rejected\": 180, \"sent\": 70, \"error\": 50, \"cancelled\": 0, \"draft\": 0, \"pending\": 0, \"acceptance_rate\": 97.85},\n \"totals\": {\n \"total_venta\": \"850000000.00000\",\n \"total_descuentos\": \"0.00000\",\n \"total_venta_neta\": \"850000000.00000\",\n \"total_impuesto\": \"110500000.00000\",\n \"total_otros_cargos\": \"0.00000\",\n \"total_comprobante\": \"960500000.00000\",\n \"average_per_voucher\": \"117134.14634\"\n },\n \"by_type\": [\n {\"voucher_type\": \"01\", \"voucher_type_label\": \"Factura Electr\u00f3nica\", \"count\": 7200, \"total_venta\": \"720000000.00000\", \"total_impuesto\": \"93600000.00000\", \"total_comprobante\": \"813600000.00000\"}\n ],\n \"by_contributor\": [\n {\"contributor_id\": \"019d867d-a001-7288-8ece-fd64da756a01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"count\": 5200, \"total_comprobante\": \"621000000.00000\", \"total_impuesto\": \"80730000.00000\"},\n {\"contributor_id\": \"019d867d-a002-7288-8ece-fd64da756a02\", \"legal_name\": \"Restaurante El Mango S.A.\", \"count\": 2800, \"total_comprobante\": \"280000000.00000\", \"total_impuesto\": \"21000000.00000\"},\n {\"contributor_id\": \"019d867d-a003-7288-8ece-fd64da756a03\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"count\": 500, \"total_comprobante\": \"59500000.00000\", \"total_impuesto\": \"8770000.00000\"}\n ]\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Integrador (incluye desglose por cliente)" } ] } ] }, { "name": "Ventas por per\u00edodo", "description": "", "item": [ { "name": "Ventas agrupadas por periodo.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/sales-by-period", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "4", "description": "", "disabled": false }, { "key": "status[0]", "value": "draft", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "4", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "6", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/sales-by-period?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=4&status[0]=draft¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=4&payment_method[0]=6&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna series temporales de ventas agrupadas por dia, semana o mes.\nLa agrupacion se controla con el parametro `group_by` (day, week, month)\ny se auto-detecta segun el rango de fechas si no se especifica.\n\nUtil para graficos de tendencia en el dashboard y para verificar\ndatos antes de la declaracion 150 mensual." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"currency_code\": \"CRC\",\n \"environment\": \"production\"\n },\n \"group_by\": \"week\",\n \"data\": [\n {\n \"period_start\": \"2026-03-02\",\n \"period_label\": \"Sem. 02 mar 2026\",\n \"count\": 48,\n \"total_venta\": \"3120500.00000\",\n \"total_descuentos\": \"45000.00000\",\n \"total_impuesto\": \"399815.00000\",\n \"total_comprobante\": \"3475315.00000\"\n },\n {\n \"period_start\": \"2026-03-09\",\n \"period_label\": \"Sem. 09 mar 2026\",\n \"count\": 52,\n \"total_venta\": \"3410820.50000\",\n \"total_descuentos\": \"38000.00000\",\n \"total_impuesto\": \"438846.67000\",\n \"total_comprobante\": \"3811667.17000\"\n },\n {\n \"period_start\": \"2026-03-16\",\n \"period_label\": \"Sem. 16 mar 2026\",\n \"count\": 46,\n \"total_venta\": \"2719000.00000\",\n \"total_descuentos\": \"42000.00000\",\n \"total_impuesto\": \"298880.00000\",\n \"total_comprobante\": \"2975880.00000\"\n }\n ],\n \"grand_total\": {\n \"count\": 146,\n \"total_venta\": \"9250320.50000\",\n \"total_impuesto\": \"1137541.67000\",\n \"total_comprobante\": \"10262862.17000\"\n }\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "Ventas por receptor", "description": "", "item": [ { "name": "Ranking de ventas por receptor.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/sales-by-receiver", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "9", "description": "", "disabled": false }, { "key": "status[0]", "value": "pending", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "11", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "2", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/sales-by-receiver?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=9&status[0]=pending¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=11&payment_method[0]=2&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna los receptores (clientes) con mayor monto facturado en el\nperiodo, ordenados de mayor a menor. El parametro `limit` controla\ncuantos registros retornar (default 10, maximo 100).\n\nUtil para identificar clientes principales y para conciliacion\nfiscal por cedula de receptor." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"currency_code\": \"CRC\",\n \"environment\": \"production\"\n },\n \"limit\": 10,\n \"data\": [\n {\n \"receiver_id_type\": \"02\",\n \"receiver_id_number\": \"3101123456\",\n \"receiver_name\": \"Comercializadora La Catedral S.A.\",\n \"count\": 24,\n \"total_venta\": \"2980000.00000\",\n \"total_impuesto\": \"387400.00000\",\n \"total_comprobante\": \"3367400.00000\",\n \"percentage\": 32.81\n },\n {\n \"receiver_id_type\": \"02\",\n \"receiver_id_number\": \"3101998877\",\n \"receiver_name\": \"Inversiones del Valle S.R.L.\",\n \"count\": 18,\n \"total_venta\": \"1740500.50000\",\n \"total_impuesto\": \"226265.07000\",\n \"total_comprobante\": \"1966765.57000\",\n \"percentage\": 19.16\n },\n {\n \"receiver_id_type\": \"01\",\n \"receiver_id_number\": \"108880777\",\n \"receiver_name\": \"Mar\u00eda Fernanda Rojas Alvarado\",\n \"count\": 11,\n \"total_venta\": \"845000.00000\",\n \"total_impuesto\": \"109850.00000\",\n \"total_comprobante\": \"954850.00000\",\n \"percentage\": 9.30\n }\n ],\n \"others\": {\n \"count\": 93,\n \"total_comprobante\": \"3973846.60000\",\n \"percentage\": 38.73\n },\n \"grand_total\": {\n \"count\": 146,\n \"total_comprobante\": \"10262862.17000\",\n \"unique_receivers\": 47\n }\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "Ventas por actividad", "description": "", "item": [ { "name": "Ventas agrupadas por actividad economica.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/sales-by-activity", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "8", "description": "", "disabled": false }, { "key": "status[0]", "value": "sent", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "10", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "6", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/sales-by-activity?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=8&status[0]=sent¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=10&payment_method[0]=6&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna montos y conteos agrupados por codigo de actividad economica\nCIIU del emisor. Esencial para la declaracion 150 que requiere\nreportar IVA desglosado por actividad economica." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"currency_code\": \"CRC\",\n \"environment\": \"production\"\n },\n \"data\": [\n {\n \"activity_code\": \"620100\",\n \"activity_description\": \"Actividades de programaci\u00f3n inform\u00e1tica\",\n \"count\": 86,\n \"total_venta\": \"6120000.00000\",\n \"total_impuesto\": \"795600.00000\",\n \"total_comprobante\": \"6915600.00000\",\n \"percentage\": 67.38\n },\n {\n \"activity_code\": \"702000\",\n \"activity_description\": \"Actividades de consultor\u00eda de gesti\u00f3n\",\n \"count\": 41,\n \"total_venta\": \"2380320.50000\",\n \"total_impuesto\": \"309441.67000\",\n \"total_comprobante\": \"2689762.17000\",\n \"percentage\": 26.21\n },\n {\n \"activity_code\": \"631100\",\n \"activity_description\": \"Procesamiento de datos y hospedaje\",\n \"count\": 19,\n \"total_venta\": \"750000.00000\",\n \"total_impuesto\": \"97500.00000\",\n \"total_comprobante\": \"657500.00000\",\n \"percentage\": 6.41\n }\n ],\n \"grand_total\": {\n \"count\": 146,\n \"total_comprobante\": \"10262862.17000\",\n \"unique_activities\": 3\n }\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "IVA | Desglose por tarifa", "description": "", "item": [ { "name": "Desglose de IVA por tarifa | datos para la declaracion 150.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/tax-summary", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "2", "description": "", "disabled": false }, { "key": "status[0]", "value": "draft", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "4", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "99", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/tax-summary?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=2&status[0]=draft¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=4&payment_method[0]=99&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna el impuesto agrupado por codigo de tarifa IVA (0%, 1%, 2%,\n4%, 13%, exento, etc.). La declaracion 150 ante Hacienda requiere\nreportar el IVA desglosado exactamente por estas tarifas." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"currency_code\": \"CRC\",\n \"environment\": \"production\"\n },\n \"by_tax_code\": [\n {\n \"tax_code\": \"01\",\n \"tax_code_label\": \"IVA\",\n \"total_monto\": \"1118041.67000\",\n \"voucher_count\": 138,\n \"breakdown_by_rate\": [\n {\n \"rate_code\": \"08\",\n \"rate_label\": \"13% General\",\n \"rate_percentage\": 13.00,\n \"total_monto\": \"1095541.67000\",\n \"voucher_count\": 132\n },\n {\n \"rate_code\": \"04\",\n \"rate_label\": \"4% Bienes y servicios especiales\",\n \"rate_percentage\": 4.00,\n \"total_monto\": \"22500.00000\",\n \"voucher_count\": 6\n }\n ]\n },\n {\n \"tax_code\": \"07\",\n \"tax_code_label\": \"Impuesto espec\u00edfico\",\n \"total_monto\": \"19500.00000\",\n \"voucher_count\": 8,\n \"breakdown_by_rate\": [\n {\n \"rate_code\": \"11\",\n \"rate_label\": \"Tarifa especial\",\n \"rate_percentage\": 0.00,\n \"total_monto\": \"19500.00000\",\n \"voucher_count\": 8\n }\n ]\n }\n ],\n \"totals\": {\n \"total_impuesto\": \"1137541.67000\",\n \"total_iva_devuelto\": \"0.00000\",\n \"voucher_count\": 146\n }\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "MensajeReceptor", "description": "", "item": [ { "name": "Resumen de confirmaciones de receptor (MensajeReceptor).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/receiver-messages", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "2", "description": "", "disabled": false }, { "key": "status[0]", "value": "accepted", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "10", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "4", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/receiver-messages?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=2&status[0]=accepted¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=10&payment_method[0]=4&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna el conteo de mensajes de receptor agrupados por estado:\nconfirmados, pendientes y vencidos. Incluye alertas de plazo segun\nel art. 15 del Reglamento (8 dias habiles para confirmar).\n\nEste endpoint solo acepta los filtros `date_from`, `date_to` y\n`environment`. Los demas filtros (voucher_type, currency_code, etc.)\nno aplican a mensajes de receptor." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"environment\": \"production\"\n },\n \"summary\": {\n \"total\": 64,\n \"by_status\": {\n \"accepted\": 58,\n \"sent\": 3,\n \"draft\": 2,\n \"error\": 1\n },\n \"by_message\": {\n \"accepted_total\": 55,\n \"accepted_partial\": 3,\n \"rejected\": 2\n }\n },\n \"deadline_alerts\": {\n \"overdue\": 2,\n \"due_soon\": 5,\n \"on_time\": 57,\n \"deadline_business_days\": 8,\n \"alert_threshold_days\": 2\n },\n \"by_issuer\": [\n {\n \"issuer_id_number\": \"3101456789\",\n \"count\": 31,\n \"total_invoice\": \"4120000.00000\",\n \"total_tax\": \"535600.00000\",\n \"accepted\": 29,\n \"rejected\": 1\n },\n {\n \"issuer_id_number\": \"3101778899\",\n \"count\": 22,\n \"total_invoice\": \"1890500.00000\",\n \"total_tax\": \"245765.00000\",\n \"accepted\": 21,\n \"rejected\": 0\n },\n {\n \"issuer_id_number\": \"108450321\",\n \"count\": 11,\n \"total_invoice\": \"612000.00000\",\n \"total_tax\": \"79560.00000\",\n \"accepted\": 8,\n \"rejected\": 1\n }\n ]\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "Estado Hacienda", "description": "", "item": [ { "name": "Comprobantes agrupados por estado Hacienda.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/vouchers-by-status", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "9", "description": "", "disabled": false }, { "key": "status[0]", "value": "error", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "14", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "99", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/vouchers-by-status?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=9&status[0]=error¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=14&payment_method[0]=99&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna conteo y montos agrupados por el estado de confirmacion de\nHacienda (aceptado, rechazado, enviado, error, pendiente). Incluye\nmetricas como tasa de aceptacion, tasa de rechazo y conteo de\ncomprobantes pendientes.\n\nA diferencia de otros reportes, este endpoint no filtra por estado\n(ya que el proposito es mostrar TODOS los estados agrupados)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"period\": {\n \"date_from\": \"2026-03-01\",\n \"date_to\": \"2026-03-31\",\n \"currency_code\": \"CRC\",\n \"environment\": \"production\"\n },\n \"data\": [\n {\n \"status\": \"accepted\",\n \"status_label\": \"Aceptado\",\n \"count\": 138,\n \"total_venta\": \"8920320.50000\",\n \"total_impuesto\": \"1118041.67000\",\n \"total_comprobante\": \"9912362.17000\",\n \"percentage_count\": 94.52,\n \"percentage_amount\": 96.58\n },\n {\n \"status\": \"rejected\",\n \"status_label\": \"Rechazado\",\n \"count\": 4,\n \"total_venta\": \"210000.00000\",\n \"total_impuesto\": \"16000.00000\",\n \"total_comprobante\": \"275500.00000\",\n \"percentage_count\": 2.74,\n \"percentage_amount\": 2.68\n },\n {\n \"status\": \"pending\",\n \"status_label\": \"Pendiente\",\n \"count\": 3,\n \"total_venta\": \"108000.00000\",\n \"total_impuesto\": \"3500.00000\",\n \"total_comprobante\": \"62500.00000\",\n \"percentage_count\": 2.05,\n \"percentage_amount\": 0.61\n },\n {\n \"status\": \"error\",\n \"status_label\": \"Error\",\n \"count\": 1,\n \"total_venta\": \"12000.00000\",\n \"total_impuesto\": \"0.00000\",\n \"total_comprobante\": \"12500.00000\",\n \"percentage_count\": 0.68,\n \"percentage_amount\": 0.12\n }\n ],\n \"grand_total\": {\n \"count\": 146,\n \"total_comprobante\": \"10262862.17000\"\n },\n \"metrics\": {\n \"acceptance_rate\": 94.52,\n \"rejection_rate\": 2.74,\n \"pending_count\": 3,\n \"error_count\": 1,\n \"avg_processing_time_hours\": 1.4\n }\n },\n \"message\": \"\",\n \"errors\": null\n}\n", "name": "" } ] } ] }, { "name": "IVA | Auxiliar D-150", "description": "", "item": [ { "name": "Auxiliar del IVA (D-150): ventas y compras por tarifa.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/iva-auxiliary", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "1", "description": "", "disabled": false }, { "key": "status[0]", "value": "accepted", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "10", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "6", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/iva-auxiliary?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=1&status[0]=accepted¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=10&payment_method[0]=6&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Produce los dos auxiliares de la declaracion autoliquidativa 150 de\nTRIBU-CR: ventas generales por tarifa (base + impuesto), ventas sin\nIVA, compras por tarifa (importe + impuesto soportado), y el detalle\npor cliente y por proveedor. Solo comprobantes ACEPTADOS; las notas\nde credito restan." }, "response": [] }, { "name": "Exporta el auxiliar del IVA (D-150) en CSV o PDF.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/iva-auxiliary\/export", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "9", "description": "", "disabled": false }, { "key": "status[0]", "value": "rejected", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "9", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "6", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/iva-auxiliary\/export?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=9&status[0]=rejected¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=9&payment_method[0]=6&group_by=month&limit=10" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "format=csv§ion=sales|purchases descarga el auxiliar pedido en CSV;\nformat=pdf descarga el documento completo (ventas + compras) listo\npara imprimir o adjuntar al expediente del periodo." }, "response": [] } ] }, { "name": "Export", "description": "", "item": [ { "name": "Exporta un reporte del portal en CSV o PDF.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/:report\/export", "query": [ { "key": "date_from", "value": "2026-08-01", "description": "Inicio del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: primer d\u00eda del mes actual. Must be a valid date in the format Y-m-d.", "disabled": false }, { "key": "date_to", "value": "2026-08-11", "description": "Fin del rango de fecha de emisi\u00f3n (YYYY-MM-DD). Default: hoy. Debe ser >= date_from. Must be a valid date in the format Y-m-d. El campo value debe ser una fecha posterior o igual a date_from.", "disabled": false }, { "key": "voucher_type[0]", "value": "3", "description": "", "disabled": false }, { "key": "status[0]", "value": "sent", "description": "", "disabled": false }, { "key": "currency_code", "value": "CRC", "description": "Moneda ISO 4217 (3 letras). Default: CRC (150 en colones). Must match the regex \/^[A-Z]{3}$\/. El campo value debe tener 3 caracteres.", "disabled": false }, { "key": "environment", "value": "production", "description": "Ambiente: sandbox o production. Default: production (solo comprobantes con validez fiscal).", "disabled": false }, { "key": "receiver_id_number", "value": "3101234567", "description": "C\u00e9dula del receptor (9-12 d\u00edgitos). Art. 13.10 criterio 1. Must match the regex \/^\\d{9,12}$\/.", "disabled": false }, { "key": "sale_condition[0]", "value": "11", "description": "", "disabled": false }, { "key": "payment_method[0]", "value": "4", "description": "", "disabled": false }, { "key": "group_by", "value": "month", "description": "Agrupaci\u00f3n temporal (solo sales-by-period). Valores: day, week, month. Auto-detectado seg\u00fan rango.", "disabled": false }, { "key": "limit", "value": "10", "description": "Cantidad de registros top (solo sales-by-receiver). Default: 10, m\u00e1ximo: 100. El campo value debe ser al menos 1. El campo value no puede ser mayor a 100.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/:report\/export?date_from=2026-08-01&date_to=2026-08-11&voucher_type[0]=3&status[0]=sent¤cy_code=CRC&environment=production&receiver_id_number=3101234567&sale_condition[0]=11&payment_method[0]=4&group_by=month&limit=10", "variable": [ { "id": "report", "key": "report", "value": "sales-by-period%7Csales-by-receiver%7Csales-by-activity", "description": "The report." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Reportes: sales-by-period, sales-by-receiver, sales-by-activity.\nformat=csv descarga la tabla; format=pdf el documento membretado." }, "response": [] } ] }, { "name": "Filtros", "description": "", "item": [ { "name": "Facets para los filtros de reportes.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reports\/filters", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/reports\/filters" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] } ] } ] }, { "name": "Cat\u00e1logos", "description": "", "item": [ { "name": "Buscar en el catalogo CABYS (Bienes y Servicios).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/catalogs\/cabys", "query": [ { "key": "q", "value": "arroz", "description": "Texto libre o prefijo numerico del codigo CABYS. Minimo 2 caracteres.", "disabled": false }, { "key": "per_page", "value": "10", "description": "Resultados por pagina (1-100). Default: 25.", "disabled": false }, { "key": "page", "value": "1", "description": "Pagina actual.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/catalogs\/cabys?q=arroz&per_page=10&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Busqueda paginada en el catalogo oficial de bienes y servicios\nde Hacienda (~20,501 codigos). El codigo CABYS es obligatorio\nen todos los comprobantes electronicos (tipos 01-09).\n\nSi `q` contiene solo digitos, busca por prefijo de codigo. Si\ncontiene texto, busca por descripcion. Sin `q`, retorna todos\nlos codigos activos ordenados por codigo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"code\": \"0111101000100\",\n \"description\": \"Arroz con c\u00e1scara (arroz paddy)\",\n \"tax_rate\": \"01\",\n \"tax_code\": \"08\",\n \"is_merchandise\": true,\n \"is_medicine\": false\n },\n {\n \"code\": \"0111101000200\",\n \"description\": \"Arroz descascarillado (arroz cargo o arroz pardo)\",\n \"tax_rate\": \"01\",\n \"tax_code\": \"08\",\n \"is_merchandise\": true,\n \"is_medicine\": false\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"per_page\": 25, \"has_more\": true},\n \"links\": {\"prev\": null, \"next\": \"\/api\/v1\/public\/catalogs\/cabys?q=arroz&page=2\"}\n}", "name": "Busqueda por texto" } ] }, { "name": "Buscar actividad economica (CIIU).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/catalogs\/activities", "query": [ { "key": "q", "value": "desarrollo+software", "description": "Texto libre o prefijo numerico. Minimo 2 caracteres.", "disabled": false }, { "key": "per_page", "value": "10", "description": "Resultados por pagina (1-100). Default: 25.", "disabled": false }, { "key": "page", "value": "1", "description": "Pagina actual.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/catalogs\/activities?q=desarrollo+software&per_page=10&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Busqueda paginada en el catalogo de actividades economicas CIIU 4\n(~800 codigos). El codigo de actividad es obligatorio en el campo\n`CodigoActividadEmisor` de todos los comprobantes electronicos.\n\nSi `q` contiene solo digitos, busca por prefijo de codigo CIIU.\nSi contiene texto, busca por descripcion de la actividad." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\"code\": \"6201.0\", \"description\": \"Actividades de programaci\u00f3n inform\u00e1tica\"},\n {\"code\": \"6202.0\", \"description\": \"Actividades de consultor\u00eda inform\u00e1tica y gesti\u00f3n de instalaciones inform\u00e1ticas\"}\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 25, \"total\": 2},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Busqueda por texto" } ] }, { "name": "Consultar ubicaciones (provincia, canton, distrito).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/catalogs\/locations", "query": [ { "key": "province", "value": "1", "description": "Codigo de provincia (1-7) para obtener sus cantones.", "disabled": false }, { "key": "canton", "value": "01", "description": "Codigo de canton (01-20) para obtener sus distritos. Requiere `province`.", "disabled": false }, { "key": "q", "value": "escazu", "description": "Busqueda por nombre de ubicacion. Minimo 2 caracteres.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/catalogs\/locations?province=1&canton=01&q=escazu" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Consulta jerarquica de la division territorial de Costa Rica, necesaria\npara construir el nodo `Ubicacion` del emisor y receptor en el XML\ndel comprobante.\n\n**Comportamiento jerarquico:**\n- Sin parametros \u2192 retorna las 7 provincias\n- `?province=1` \u2192 cantones de San Jose\n- `?province=1&canton=01` \u2192 distritos de San Jose central\n- `?q=escazu` \u2192 busqueda por nombre en cualquier nivel\n\nNo usa paginacion: el resultado maximo es de aproximadamente 16\nregistros (distritos de un canton)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\"level\": \"province\", \"province_code\": 1, \"canton_code\": null, \"district_code\": null, \"name\": \"San Jos\u00e9\"},\n {\"level\": \"province\", \"province_code\": 2, \"canton_code\": null, \"district_code\": null, \"name\": \"Alajuela\"},\n {\"level\": \"province\", \"province_code\": 3, \"canton_code\": null, \"district_code\": null, \"name\": \"Cartago\"},\n {\"level\": \"province\", \"province_code\": 4, \"canton_code\": null, \"district_code\": null, \"name\": \"Heredia\"},\n {\"level\": \"province\", \"province_code\": 5, \"canton_code\": null, \"district_code\": null, \"name\": \"Guanacaste\"},\n {\"level\": \"province\", \"province_code\": 6, \"canton_code\": null, \"district_code\": null, \"name\": \"Puntarenas\"},\n {\"level\": \"province\", \"province_code\": 7, \"canton_code\": null, \"district_code\": null, \"name\": \"Lim\u00f3n\"}\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"count\": 7}\n}", "name": "7 provincias (sin parametros)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\"level\": \"canton\", \"province_code\": 1, \"canton_code\": 1, \"district_code\": null, \"name\": \"San Jos\u00e9\"},\n {\"level\": \"canton\", \"province_code\": 1, \"canton_code\": 2, \"district_code\": null, \"name\": \"Escaz\u00fa\"},\n {\"level\": \"canton\", \"province_code\": 1, \"canton_code\": 3, \"district_code\": null, \"name\": \"Desamparados\"}\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"count\": 20}\n}", "name": "Cantones de una provincia" } ] }, { "name": "Cat\u00e1logo de monedas activas (ISO 4217) para el selector de moneda en la\nemisi\u00f3n de comprobantes.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/catalogs\/currencies", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/catalogs\/currencies" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Las m\u00e1s usadas en Costa Rica (CRC, USD, EUR) se devuelven primero; el\nresto en orden alfab\u00e9tico por c\u00f3digo. `bccr_rate` trae el tipo de cambio\nde referencia del BCCR cuando aplica (USD), para prellenar el campo de\ntipo de cambio en la UI; si es null, el usuario lo ingresa a mano." }, "response": [] } ] }, { "name": "Consulta de Contribuyentes", "description": "", "item": [ { "name": "Consultar identificacion por numero.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/taxpayer\/:id_number", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/taxpayer\/:id_number", "variable": [ { "id": "id_number", "key": "id_number", "value": "3101234567", "description": "N\u00famero de identificaci\u00f3n (9-12 d\u00edgitos)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Busca primero en cache (24 horas), luego en el API publico de Hacienda.\nPara cedulas fisicas de 9 digitos no encontradas en Hacienda, y planes\nque incluyen consulta de padron, intenta el Padron Electoral TSE como\nfuente alternativa de nombre verificado." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id_number\": \"101230456\",\n \"id_type\": \"01\",\n \"id_type_label\": \"C\u00e9dula F\u00edsica\",\n \"name\": \"JUAN P\u00c9REZ SOL\u00cdS\",\n \"hacienda_registered\": true,\n \"regime\": { \"code\": \"02\", \"description\": \"Simplificado\" },\n \"situation\": { \"status\": \"Activo\", \"morphs_fijo\": true },\n \"activities\": [\n { \"code\": \"620100\", \"status\": \"A\", \"description\": \"Actividades de consultor\u00eda inform\u00e1tica\" }\n ],\n \"cached\": false,\n \"cached_at\": \"2026-04-08T10:30:00-06:00\",\n \"tse\": {\n \"found\": true,\n \"nombre_completo\": \"JUAN P\u00c9REZ SOL\u00cdS\",\n \"nombre\": \"JUAN\",\n \"apellido1\": \"P\u00c9REZ\",\n \"apellido2\": \"SOL\u00cdS\",\n \"cedula_vence\": \"2028-05-14\",\n \"cedula_vigente\": true,\n \"provincia\": \"San Jos\u00e9\",\n \"canton\": \"Escaz\u00fa\",\n \"distrito_codigo\": \"003\",\n \"padron_version\": \"2026-04-01\",\n \"nota\": \"Datos del Padr\u00f3n Electoral TSE (C\u00f3digo Electoral Art. 105).\",\n \"cached\": false\n }\n },\n \"message\": \"Contribuyente encontrado.\",\n \"errors\": null\n}", "name": "Caso A | Contribuyente en Hacienda con TSE (plan business|integrator)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id_number\": \"101230456\",\n \"id_type\": \"01\",\n \"id_type_label\": \"C\u00e9dula F\u00edsica\",\n \"name\": \"JUAN P\u00c9REZ SOL\u00cdS\",\n \"hacienda_registered\": false,\n \"regime\": null,\n \"situation\": null,\n \"activities\": [],\n \"cached\": false,\n \"cached_at\": \"2026-04-08T10:30:00-06:00\",\n \"tse\": {\n \"found\": true,\n \"nombre_completo\": \"JUAN P\u00c9REZ SOL\u00cdS\",\n \"nombre\": \"JUAN\",\n \"apellido1\": \"P\u00c9REZ\",\n \"apellido2\": \"SOL\u00cdS\",\n \"cedula_vence\": \"2028-05-14\",\n \"cedula_vigente\": true,\n \"provincia\": \"San Jos\u00e9\",\n \"canton\": \"Escaz\u00fa\",\n \"distrito_codigo\": \"003\",\n \"padron_version\": \"2026-04-01\",\n \"nota\": \"Datos del Padr\u00f3n Electoral TSE (C\u00f3digo Electoral Art. 105).\",\n \"cached\": false\n }\n },\n \"message\": \"Identificaci\u00f3n verificada en Padr\u00f3n Electoral TSE. No inscrita como contribuyente ante Hacienda.\",\n \"errors\": null\n}", "name": "Caso B | Consumidor final: no en Hacienda pero s\u00ed en padr\u00f3n TSE (plan business|integrator)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id_number\": \"3101234567\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"name\": \"EMPRESA EJEMPLO S.A.\",\n \"hacienda_registered\": true,\n \"regime\": { \"code\": \"01\", \"description\": \"Tradicional\" },\n \"situation\": { \"status\": \"Activo\", \"morphs_fijo\": true },\n \"activities\": [\n { \"code\": \"620100\", \"status\": \"A\", \"description\": \"Actividades de consultor\u00eda inform\u00e1tica\" }\n ],\n \"cached\": false,\n \"cached_at\": \"2026-04-08T10:30:00-06:00\"\n },\n \"message\": \"Contribuyente encontrado.\",\n \"errors\": null\n}", "name": "C\u00e9dula jur\u00eddica o plan sin consulta de padr\u00f3n (solo Hacienda)" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se encontr\u00f3 la identificaci\u00f3n '999999999' en el registro de Hacienda ni en el Padr\u00f3n Electoral TSE.\",\n \"errors\": null\n}", "name": "Caso C | No encontrado en Hacienda ni en padr\u00f3n TSE" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El API p\u00fablico de Hacienda retorn\u00f3 un error interno. Intente nuevamente m\u00e1s tarde.\",\n \"errors\": null\n}", "name": "Hacienda no disponible" }, { "header": [], "code": 504, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El API p\u00fablico de Hacienda no respondi\u00f3 dentro del tiempo l\u00edmite. Intente nuevamente.\",\n \"errors\": null\n}", "name": "Timeout Hacienda" } ] } ] }, { "name": "Confirmaci\u00f3n del Receptor", "description": "", "item": [ { "name": "Confirmar o rechazar comprobante recibido.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/receiver\/confirm", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/receiver\/confirm" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "Identificador \u00fanico de ESTA confirmaci\u00f3n, generado por usted. Es" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_key\":\"50619032600310199999900100001010000000001112345678\",\"issuer_id_number\":\"3101999999\",\"doc_issued_at\":\"2026-03-18T10:00:00-06:00\",\"message\":\"1\",\"message_detail\":\"Comprobante aceptado conforme.\",\"total_tax\":6500,\"activity_code\":\"6201.0\",\"tax_condition\":\"01\",\"tax_creditable_amount\":6500,\"expense_applicable_amount\":50000,\"total_invoice\":56500}" }, "description": "Genera y envia un MensajeReceptor a Hacienda para aceptar (total o\nparcial) o rechazar un comprobante electronico recibido de un proveedor.\n\n**Valores del campo `message`:**\n- `1` = Aceptado \u2192 consecutivo tipo 05\n- `2` = Aceptado Parcialmente \u2192 consecutivo tipo 06\n- `3` = Rechazado \u2192 consecutivo tipo 07\n\n**Plazo:** 8 dias habiles desde la emision del documento (art. 15\nReglamento). Vencido el plazo se considera aceptacion tacita y no\nse puede enviar MensajeReceptor." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0030-7288-8ece-fd64da756030\",\n \"voucher_key\": \"50619032600310199999900100001010000000001112345678\",\n \"voucher_id\": \"019d867d-0031-7288-8ece-fd64da756031\",\n \"issuer_id_number\": \"3101999999\",\n \"doc_issued_at\": \"2026-03-26T08:00:00-06:00\",\n \"message\": \"1\",\n \"message_label\": \"Aceptado\",\n \"message_detail\": null,\n \"total_tax\": \"130000.00000\",\n \"activity_code\": \"620100\",\n \"tax_condition\": \"01\",\n \"tax_condition_label\": \"Genera cr\u00e9dito IVA\",\n \"tax_creditable_amount\": \"130000.00000\",\n \"expense_applicable_amount\": null,\n \"total_invoice\": \"1130000.00000\",\n \"receiver_id_number\": \"3101999999\",\n \"receiver_consecutive\": \"00100001050000000001\",\n \"status\": \"draft\",\n \"has_xml\": true,\n \"is_signed\": true,\n \"environment\": \"production\",\n \"deadline\": {\n \"business_days_elapsed\": 2,\n \"business_days_remaining\": 6,\n \"deadline_date\": \"2026-04-07\",\n \"is_within_deadline\": true,\n \"is_near_deadline\": false,\n \"is_overdue\": false\n },\n \"hacienda\": {\n \"status\": null,\n \"message\": null,\n \"sent_at\": null,\n \"processed_at\": null\n },\n \"issued_by\": \"019d867d-0032-7288-8ece-fd64da756032\",\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Aceptado del comprobante [506...001] generada y validada correctamente. Pendiente de env\u00edo a Hacienda.\",\n \"errors\": null\n}", "name": "Aceptaci\u00f3n enviada exitosamente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El plazo de 8 d\u00edas h\u00e1biles para confirmar\/rechazar el comprobante ha vencido.\",\n \"errors\": {\"voucher_key\": [\"El plazo de 8 d\u00edas h\u00e1biles ha vencido.\"]}\n}", "name": "Plazo de 8 d\u00edas h\u00e1biles vencido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe una confirmaci\u00f3n\/rechazo para este comprobante.\",\n \"errors\": {\"voucher_key\": [\"Ya existe una confirmaci\u00f3n\/rechazo para este comprobante.\"]}\n}", "name": "Ya existe confirmaci\u00f3n para este comprobante" } ] } ] }, { "name": "Buz\u00f3n de Recibidos", "description": "", "item": [ { "name": "Listar comprobantes del buz\u00f3n de recibidos", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox", "query": [ { "key": "search", "value": "3101123456", "description": "Filtra por clave, nombre del emisor o n\u00famero de identificaci\u00f3n del emisor.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Resultados por p\u00e1gina (1-100). Default: 20.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox?search=3101123456&per_page=20&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve, paginados, los comprobantes que el contribuyente ha\n**recibido** como receptor: tanto los emitidos por otros usuarios de\nAlmendro como los cargados manualmente (XML de otro facturador). Es un\nlistado de **solo lectura** | la aceptaci\u00f3n o rechazo se hace por el\nflujo de `POST \/receiver\/confirm` (MensajeReceptor).\n\nCada fila expone solo la informaci\u00f3n p\u00fablica del documento (Art. 16):\nemisor, clave, tipo, fecha, moneda y totales, junto al plazo de\nrespuesta (8 d\u00edas h\u00e1biles), el estado de respuesta del receptor y el\norigen del comprobante en el buz\u00f3n.\n\nLa b\u00fasqueda por texto (`search`) filtra por clave, nombre del emisor o\nn\u00famero de identificaci\u00f3n del emisor." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"voucher_key\": \"50601012600310112345600100001010000000001199999999\",\n \"consecutive_number\": \"00100001010000000001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"issued_at\": \"2026-06-01T10:00:00-06:00\",\n \"currency_code\": \"CRC\",\n \"emisor\": {\"name\": \"PROVEEDOR EJEMPLO S.A.\", \"id_number\": \"3101123456\"},\n \"alias\": \"Hosting junio\",\n \"notes\": \"Pagado con tarjeta corporativa\",\n \"xsd_valid\": null,\n \"totals\": {\"total_impuesto\": \"1300.00000\", \"total_comprobante\": \"11300.00000\"},\n \"deadline\": {\"deadline_at\": \"2026-06-11\", \"remaining_business_days\": 5, \"overdue\": false},\n \"status\": \"accepted\",\n \"environment\": \"prod\",\n \"source\": \"almendro\",\n \"source_label\": \"Emitido en Almendro\",\n \"response_status\": \"pending\",\n \"response_status_label\": \"Pendiente\",\n \"is_automatic\": false,\n \"confirmation\": {\"confirmed\": false, \"message\": null, \"message_label\": null, \"status\": null},\n \"line_items\": null\n }\n ],\n \"message\": \"Comprobantes recibidos (buz\u00f3n).\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 3, \"per_page\": 20, \"total\": 45, \"from\": 1, \"to\": 20},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": \"...\"}\n}", "name": "Listado paginado" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"Comprobantes recibidos (buz\u00f3n).\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 20, \"total\": 0, \"from\": null, \"to\": null},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Buz\u00f3n vac\u00edo" } ] }, { "name": "Cargar un comprobante externo al buz\u00f3n", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/upload", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/upload" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"xml\":\"...<\\\/FacturaElectronica>\",\"source\":\"api_upload\",\"target_contributor_id\":\"a4855dc5-0acb-33c3-b921-f4291f719ca0\"}" }, "description": "Sube el XML firmado de un comprobante (generado por **cualquier\nfacturador**, dentro o fuera de Almendro) al buz\u00f3n del receptor. El\nsistema parsea el XML, valida que el **receptor** del documento sea el\ncontribuyente autenticado (la c\u00e9dula del receptor debe coincidir con la\ndel certificado `.p12`) y consulta su estado en Hacienda.\n\nSi el comprobante ya estaba en el buz\u00f3n, la carga **refresca** su\nestado en vez de duplicarlo.\n\nEnv\u00ede el XML de **una** de estas dos formas (al menos una es\nobligatoria):\n\n- `xml_file`: el archivo `.xml` (multipart\/form-data).\n- `xml`: el contenido del XML como string (JSON o form)." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"voucher_key\": \"50601012600310112345600100001010000000001199999999\",\n \"consecutive_number\": \"00100001010000000001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"issued_at\": \"2026-06-01T10:00:00-06:00\",\n \"currency_code\": \"CRC\",\n \"emisor\": {\"name\": \"PROVEEDOR EJEMPLO S.A.\", \"id_number\": \"3101123456\"},\n \"alias\": null,\n \"notes\": null,\n \"xsd_valid\": true,\n \"totals\": {\"total_impuesto\": \"1300.00000\", \"total_comprobante\": \"11300.00000\"},\n \"deadline\": {\"deadline_at\": \"2026-06-11\", \"remaining_business_days\": 5, \"overdue\": false},\n \"status\": \"accepted\",\n \"environment\": \"prod\",\n \"source\": \"api_upload\",\n \"source_label\": \"Cargado por API\",\n \"response_status\": \"pending\",\n \"response_status_label\": \"Pendiente\",\n \"is_automatic\": false,\n \"confirmation\": {\"confirmed\": false, \"message\": null, \"message_label\": null, \"status\": null},\n \"line_items\": null\n },\n \"message\": \"Comprobante cargado en el buz\u00f3n.\",\n \"errors\": null\n}", "name": "Comprobante cargado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"xml\": [\"Debe enviar el comprobante en el campo \\\"xml\\\" (string) o \\\"xml_file\\\" (archivo).\"]}\n}", "name": "Falta el XML" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El comprobante no est\u00e1 a nombre de su contribuyente.\",\n \"errors\": {\"xml\": [\"El comprobante no est\u00e1 a nombre de su contribuyente.\"]}\n}", "name": "No est\u00e1 a nombre del contribuyente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo procesar el XML del comprobante.\",\n \"errors\": {\"xml\": [\"No se pudo procesar el XML del comprobante.\"]}\n}", "name": "XML inv\u00e1lido o no respondible" } ] }, { "name": "Cargar comprobantes externos en lote", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/upload-batch", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/upload-batch" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"source\":\"api_upload\"}" }, "description": "Carga masiva al buz\u00f3n: procesa cada comprobante de forma\n**independiente**, de modo que un XML inv\u00e1lido o ajeno **no aborta el\nlote** | el resultado se reporta por \u00edtem.\n\nEnv\u00ede el lote de una o ambas de estas formas (al menos una es\nobligatoria):\n\n- `files[]`: varios archivos `.xml` (multipart\/form-data), m\u00e1ximo 50.\n- `zip`: un archivo `.zip` cuyas entradas `.xml` se procesan una a una.\n\nEl total de comprobantes procesados se limita a 50 (archivos sueltos +\nentradas del ZIP). Siempre responde **HTTP 200** con el detalle por\n\u00edtem y un resumen, aunque algunos o todos hayan fallado." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"results\": [\n {\"name\": \"factura-001.xml\", \"status\": \"ok\", \"voucher_key\": \"50601012600310112345600100001010000000001199999999\", \"message\": null},\n {\"name\": \"factura-002.xml\", \"status\": \"error\", \"voucher_key\": null, \"message\": \"El comprobante no est\u00e1 a nombre de su contribuyente.\"}\n ],\n \"summary\": {\"total\": 2, \"ok\": 1, \"failed\": 1}\n },\n \"message\": \"Lote procesado: 1 de 2 comprobante(s) cargado(s).\",\n \"errors\": null\n}", "name": "Lote procesado (con un fallo)" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"files\": [\"Debe enviar al menos un archivo en \\\"files[]\\\" o un \\\"zip\\\" con comprobantes.\"]}\n}", "name": "Lote vac\u00edo" } ] }, { "name": "Validar una clave contra Hacienda", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/lookup\/:clave", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/lookup\/:clave", "variable": [ { "id": "clave", "key": "clave", "value": "50601012600310112345600100001010000000001199999999", "description": "Clave de 50 d\u00edgitos a consultar en Hacienda." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Consulta directamente en Hacienda el estado de una **clave** (aceptado\n\/ rechazado), incluso de comprobantes emitidos por **otros\nfacturadores** y que no est\u00e9n en su buz\u00f3n. Sirve para validar la\nfactura de un proveedor antes de aceptarla.\n\nLa consulta usa el **certificado activo** del contribuyente para el\nambiente en curso. Si no hay certificado activo para ese ambiente,\nresponde **HTTP 422**. Si Hacienda no responde, responde **HTTP 502**.\n\nEl campo `in_inbox` indica si esa clave ya figura como recibida por el\ncontribuyente (su c\u00e9dula es la del receptor del comprobante)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"clave\": \"50601012600310112345600100001010000000001199999999\",\n \"found\": true,\n \"ind_estado\": \"aceptado\",\n \"detail\": \"Comprobante aceptado por Hacienda.\",\n \"in_inbox\": false\n },\n \"message\": \"Estado consultado en Hacienda.\",\n \"errors\": null\n}", "name": "Clave encontrada en Hacienda" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"clave\": \"50601012600310112345600100001010000000001199999999\",\n \"found\": false,\n \"ind_estado\": null,\n \"detail\": null,\n \"in_inbox\": false\n },\n \"message\": \"Hacienda no tiene registro de esta clave.\",\n \"errors\": null\n}", "name": "Clave no registrada en Hacienda" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No hay un certificado activo para consultar a Hacienda en este ambiente.\",\n \"errors\": {\"certificate\": [\"Falta el certificado de sandbox.\"]}\n}", "name": "Sin certificado activo" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo consultar a Hacienda: Connection timed out.\",\n \"errors\": null\n}", "name": "Hacienda no disponible" } ] }, { "name": "Consultar un comprobante del buz\u00f3n por clave", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/:key", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/:key", "variable": [ { "id": "key", "key": "key", "value": "50601012600310112345600100001010000000001199999999", "description": "Clave de 50 d\u00edgitos del comprobante recibido." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle de un comprobante recibido, identificado por su\n**clave** (50 d\u00edgitos). A diferencia del listado, el detalle incluye\nadem\u00e1s las **l\u00edneas** del comprobante (`line_items`): provienen del\ncomprobante interno cuando el emisor es de Almendro, o del snapshot\nparseado del XML cuando es un comprobante externo.\n\nSolo se retornan comprobantes que est\u00e1n en el buz\u00f3n del contribuyente\nautenticado. Si la clave no est\u00e1 en su buz\u00f3n, responde **HTTP 404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"voucher_key\": \"50601012600310112345600100001010000000001199999999\",\n \"consecutive_number\": \"00100001010000000001\",\n \"voucher_type\": \"01\",\n \"voucher_type_label\": \"Factura Electr\u00f3nica\",\n \"issued_at\": \"2026-06-01T10:00:00-06:00\",\n \"currency_code\": \"CRC\",\n \"emisor\": {\"name\": \"PROVEEDOR EJEMPLO S.A.\", \"id_number\": \"3101123456\"},\n \"alias\": \"Hosting junio\",\n \"notes\": \"Pagado con tarjeta corporativa\",\n \"xsd_valid\": null,\n \"totals\": {\"total_impuesto\": \"1300.00000\", \"total_comprobante\": \"11300.00000\"},\n \"deadline\": {\"deadline_at\": \"2026-06-11\", \"remaining_business_days\": 5, \"overdue\": false},\n \"status\": \"accepted\",\n \"environment\": \"prod\",\n \"source\": \"almendro\",\n \"source_label\": \"Emitido en Almendro\",\n \"response_status\": \"pending\",\n \"response_status_label\": \"Pendiente\",\n \"is_automatic\": false,\n \"confirmation\": {\"confirmed\": false, \"message\": null, \"message_label\": null, \"status\": null},\n \"line_items\": [\n {\"line_number\": 1, \"detail\": \"Servicio de hosting mensual\", \"quantity\": \"1.00000\", \"unit_price\": \"10000.00000\", \"total_line_amount\": \"10000.00000\"}\n ]\n },\n \"message\": \"Detalle del comprobante recibido.\",\n \"errors\": null\n}", "name": "Comprobante encontrado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El comprobante no est\u00e1 en su buz\u00f3n.\",\n \"errors\": null\n}", "name": "No est\u00e1 en el buz\u00f3n" } ] } ] }, { "name": "Clientes del Integrador", "description": "", "item": [ { "name": "Listar clientes gestionados por el integrador", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors", "query": [ { "key": "search", "value": "cliente", "description": "B\u00fasqueda por raz\u00f3n social o n\u00famero de identificaci\u00f3n (m\u00ednimo 2 caracteres).", "disabled": false }, { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100). Default: 15.", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors?search=cliente&per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los **contribuyentes-cliente** que el integrador\nautenticado gestiona actualmente, con b\u00fasqueda por texto y\npaginaci\u00f3n. Ordenado por fecha de creaci\u00f3n descendente (los m\u00e1s\nrecientes primero).\n\nSolo los clientes con v\u00ednculo **activo** se incluyen. Si un cliente\nfue desvinculado, no aparece en este listado aunque su cuenta siga\nexistiendo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-c001-7288-8ece-fd64da756c01\",\n \"legal_name\": \"CLIENTE DEL INTEGRADOR S.A.\",\n \"trade_name\": \"Cliente Shop\",\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101123456\",\n \"primary_email\": \"juan@cliente.cr\",\n \"is_active\": true,\n \"can_emit_from_portal\": true,\n \"plan_code\": \"free\",\n \"plan_name\": \"Gratis\",\n \"integrators_count\": 1,\n \"created_at\": \"2026-04-10T09:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1, \"from\": 1, \"to\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Listado paginado de clientes gestionados (cliente exclusivo)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-c001-7288-8ece-fd64da756c02\",\n \"legal_name\": \"CLIENTE COMPARTIDO S.A.\",\n \"trade_name\": null,\n \"id_type\": \"02\",\n \"id_type_label\": \"C\u00e9dula Jur\u00eddica\",\n \"id_number\": \"3101999999\",\n \"primary_email\": \"contacto@compartido.cr\",\n \"is_active\": true,\n \"can_emit_from_portal\": true,\n \"plan_code\": \"pyme\",\n \"plan_name\": \"Pyme\",\n \"integrators_count\": 3,\n \"created_at\": \"2026-03-15T12:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1, \"from\": 1, \"to\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Cliente compartido con otros integradores (N:N)" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 0, \"from\": null, \"to\": null},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Sin clientes gestionados" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" } ] }, { "name": "Crear un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"legal_name\":\"CLIENTE DEL INTEGRADOR S.A.\",\"trade_name\":\"Cliente Shop\",\"id_type\":\"02\",\"id_number\":\"3101123456\",\"email\":\"contacto@cliente.cr\",\"phone\":\"22001234\",\"economic_activities\":[\"6201.0\"],\"province\":1,\"canton\":1,\"district\":1,\"neighborhood\":\"San Pedro\",\"address\":\"200m norte del parque central\",\"owner_name\":\"Juan Cliente\",\"owner_email\":\"juan@cliente.cr\",\"phone_country_code\":506,\"emails\":[\"contacto@cliente.cr\"]}" }, "description": "Crea un nuevo contribuyente-cliente en el sistema y establece un\nv\u00ednculo de gesti\u00f3n con el integrador autenticado. El cliente recibe\nun **magic link** en el correo indicado para activar su cuenta.\n\n**El cliente queda con:**\n\n- Plan **Gratis** (el cliente o el integrador pueden actualizarlo\n despu\u00e9s).\n- Una cuenta de usuario administrador (`owner`) lista para recibir\n el magic link.\n- Un v\u00ednculo de gesti\u00f3n activo con este integrador.\n\n**El cliente NO queda con:**\n\n- Ning\u00fan certificado digital (debe subirlo despu\u00e9s con\n `POST \/my-contributors\/{id}\/certificates`).\n- Ning\u00fan grant activo para que el integrador firme por \u00e9l. Para\n eso, debe solicitar un grant desde el grupo\n `Certificados de terceros`.\n\n**Tras crear:**\n\n1. El cliente recibe un email con el magic link.\n2. El cliente debe activar la cuenta en \u2264 72 horas.\n3. Si quiere firmar por \u00e9l, solicite un grant con\n `POST \/access-requests`." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-c001-7288-8ece-fd64da756c01\",\n \"id_type\": \"02\",\n \"id_number\": \"3101123456\",\n \"legal_name\": \"CLIENTE DEL INTEGRADOR S.A.\",\n \"commercial_name\": \"Cliente Shop\",\n \"emails\": [\"juan@cliente.cr\"],\n \"economic_activities\": [\"6201.0\"],\n \"province\": 1,\n \"canton\": 1,\n \"district\": 1,\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200m norte del parque central\",\n \"phone\": \"22001234\",\n \"phone_country_code\": 506,\n \"is_active\": true,\n \"plan\": {\n \"code\": \"free\",\n \"name\": \"Gratis\"\n },\n \"has_active_grant\": false,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"updated_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Cliente creado correctamente. Se envi\u00f3 email de bienvenida.\",\n \"errors\": null\n}", "name": "Cliente creado y magic link enviado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ha alcanzado el m\u00e1ximo de clientes gestionados de su plan.\",\n \"errors\": {\"managed_contributors\": [\"Ha alcanzado el m\u00e1ximo de clientes gestionados de su plan.\"]}\n}", "name": "L\u00edmite del plan alcanzado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"owner_email\": [\"Este correo ya est\u00e1 registrado en el sistema.\"]}\n}", "name": "Correo del propietario ya registrado" } ] }, { "name": "Consultar un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle completo del cliente indicado. Solo se retornan\nclientes con v\u00ednculo **activo** con el integrador autenticado. Si\nel UUID no corresponde a un cliente gestionado actualmente por usted,\nretorna HTTP 404." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-c001-7288-8ece-fd64da756c01\",\n \"id_type\": \"02\",\n \"id_number\": \"3101123456\",\n \"legal_name\": \"CLIENTE DEL INTEGRADOR S.A.\",\n \"commercial_name\": \"Cliente Shop\",\n \"emails\": [\"juan@cliente.cr\"],\n \"economic_activities\": [\"6201.0\"],\n \"province\": 1,\n \"canton\": 1,\n \"district\": 1,\n \"neighborhood\": \"San Pedro\",\n \"address\": \"200m norte del parque central\",\n \"phone\": \"22001234\",\n \"phone_country_code\": 506,\n \"is_active\": true,\n \"plan\": {\n \"code\": \"free\",\n \"name\": \"Gratis\"\n },\n \"has_active_grant\": true,\n \"active_grant_environment\": \"sandbox\",\n \"created_at\": \"2026-04-10T09:00:00-06:00\",\n \"updated_at\": \"2026-04-10T09:00:00-06:00\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Cliente encontrado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Cliente no encontrado.\",\n \"errors\": null\n}", "name": "Cliente no encontrado o desvinculado" } ] }, { "name": "Actualizar relaci\u00f3n con el cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"default_pdf_template_id\":3,\"identifier_color\":\"#fEEeDb\"}" }, "description": "Permite modificar \u00fanicamente campos de la **relaci\u00f3n de gesti\u00f3n**\nentre el integrador y el cliente. Los datos propios del cliente\n(raz\u00f3n social, direcci\u00f3n, tel\u00e9fono, etc.) **no pueden ser\nmodificados por el integrador** | solo el cliente puede editarlos\ndesde su propio portal o API (Art. 16 Reglamento).\n\n**Campo editable:**\n\n- `default_pdf_template_id` | la plantilla PDF que este integrador\n usar\u00e1 por defecto al emitir por este cliente. Per-integrador:\n no afecta a otros integradores del mismo cliente.\n\n**Campos bloqueados (retornan 403):**\n\n- `legal_name`, `trade_name`, `emails`, `economic_activities`,\n `province`, `canton`, `district`, `neighborhood`, `address`,\n `phone`, `phone_country_code`" }, "response": [ { "header": [], "code": 200, "body": "", "name": "Relaci\u00f3n actualizada" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El integrador no puede modificar los datos del cliente. Solo el cliente puede editar su informaci\u00f3n desde su propio portal o API. Campos bloqueados: legal_name, trade_name.\",\n \"errors\": null\n}", "name": "Intento de modificar datos del cliente" } ] }, { "name": "Desvincular al integrador del cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente a desvincular." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "**Rompe \u00fanicamente la relaci\u00f3n de gesti\u00f3n** entre usted y este\ncliente. El cliente conserva:\n\n- Su cuenta y sus datos.\n- Sus certificados digitales.\n- Sus comprobantes emitidos.\n- Los v\u00ednculos con otros integradores (si los tiene).\n\n**Efectos inmediatos de la desvinculaci\u00f3n:**\n\n1. La relaci\u00f3n de gesti\u00f3n queda marcada como desvinculada.\n2. Todos los grants activos de este cliente hacia usted\n se **revocan autom\u00e1ticamente** (no podr\u00e1 seguir firmando\n por \u00e9l).\n3. Este cliente desaparecer\u00e1 del listado\n `GET \/my-contributors`.\n\n**No se puede** usar este endpoint para desvincularse a s\u00ed mismo\n(es decir, pasar su propio UUID de integrador) | retorna HTTP 403.\n\n> **Usos t\u00edpicos:** finalizaci\u00f3n de contrato con el cliente,\n> transferencia del cliente a otro integrador, limpieza de\n> clientes inactivos." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Cliente desvinculado correctamente. Se revocaron los accesos asociados.\",\n \"errors\": null\n}", "name": "Cliente desvinculado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No puede desvincularse a s\u00ed mismo desde este endpoint.\",\n \"errors\": null\n}", "name": "Intento de auto-desvinculaci\u00f3n" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Cliente no encontrado.\",\n \"errors\": null\n}", "name": "Cliente no encontrado o ya desvinculado" } ] }, { "name": "Listar los certificados digitales de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/certificates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/certificates", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el historial completo de certificados del cliente\n(activo + desactivados), ordenados por fecha de creaci\u00f3n\ndescendente. Los datos sensibles (contenido del `.p12`, contrase\u00f1as,\nPIN de Hacienda) **nunca se incluyen** en la respuesta.\n\nLa estructura es id\u00e9ntica a `GET \/api\/v1\/public\/certificates`\n(grupo **Certificados Digitales**), pero opera sobre el cliente\nindicado en la URL." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-1111-7288-8ece-fd64da756001\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 120,\n \"valid_from\": \"2024-01-01T00:00:00-06:00\",\n \"valid_until\": \"2026-08-15T23:59:59-06:00\",\n \"certificate_subject\": \"CN=CLIENTE DEL INTEGRADOR S.A., serialNumber=3101123456\",\n \"certificate_serial\": \"0A1B2C3D4E5F\",\n \"created_at\": \"2026-04-09T10:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Listado de certificados del cliente" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Cliente sin certificados" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Cliente no encontrado o no pertenece a este integrador.\",\n \"errors\": null\n}", "name": "Cliente no encontrado o desvinculado" } ] }, { "name": "Eliminar un certificado del cliente (siempre denegado)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/certificates\/:certId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/certificates\/:certId", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "certId", "key": "certId", "value": "019d867d-1111-7288-8ece-fd64da756001", "description": "UUID del certificado (no relevante, siempre 403)." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Este endpoint **siempre retorna HTTP 403** y no realiza ning\u00fan\ncambio. El integrador **no puede eliminar** certificados del\ncliente | el certificado es **propiedad del contribuyente emisor**\ny solo \u00e9l puede desactivarlo desde su propio portal.\n\n**Si quiere dejar de usar el certificado del cliente:**\n\n- Revoque su propio grant de acceso al certificado desde\n el grupo **Certificados de terceros** (`DELETE \/my-access\/{grantId}`).\n- Deje de emitir por ese cliente.\n- Desvinc\u00falese del cliente con `DELETE \/my-contributors\/{id}` si\n ya no desea gestionarlo." }, "response": [ { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El integrador no puede eliminar certificados del cliente. El certificado es propiedad del contribuyente emisor. Si desea dejar de usar este certificado, revoque su acceso desde DELETE \/api\/v1\/public\/my-access\/{grantId}.\",\n \"errors\": null\n}", "name": "Operaci\u00f3n siempre denegada" } ] }, { "name": "Subir un certificado digital para el cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/certificates", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/certificates", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "p12_password", "value": "ContrasenaDelP12", "type": "text", "description": "Contrase\u00f1a que protege el archivo `.p12` (la que el cliente defini\u00f3 al generarlo)." }, { "key": "hacienda_pin", "value": "1234", "type": "text", "description": "PIN de Hacienda del cliente (asignado por ATV al registrarse como emisor)." }, { "key": "environment", "value": "sandbox", "type": "text", "description": "Ambiente al que se asigna el certificado. Valores: `sandbox` o `production`." }, { "key": "p12_file", "src": [], "type": "file" } ] }, "description": "Carga el archivo `.p12` del cliente desde la cuenta del integrador.\nEl certificado queda **vinculado al cliente** (no al integrador):\nel integrador administra el `.p12` en nombre del cliente pero el\ncertificado pertenece al cliente.\n\nEste endpoint es equivalente a\n`POST \/api\/v1\/public\/certificates` del grupo\n**Certificados Digitales**, pero opera sobre el cliente\ngestionado indicado en la URL. Consulte la gu\u00eda de ese grupo\npara entender el formato del `.p12`, el PIN de Hacienda, etc.\n\n**Request:** `multipart\/form-data` (no JSON).\n\n**Ejemplo con `curl`:**\n\n```bash\ncurl -X POST \"https:\/\/api.almendro.cr\/api\/v1\/public\/my-contributors\/{id}\/certificates\" \\\n -H \"Authorization: Bearer {su_token_api}\" \\\n -F \"p12_file=@\/ruta\/cert-del-cliente.p12\" \\\n -F \"p12_password=contrasena-del-p12\" \\\n -F \"hacienda_pin=1234\" \\\n -F \"environment=sandbox\"\n```\n\n> **Recuerde:** cargar el certificado del cliente **no le da**\n> autom\u00e1ticamente permiso de firmar por \u00e9l. Necesita adem\u00e1s un\n> grant activo (ver grupo **Certificados de terceros**)." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-3333-7288-8ece-fd64da756c03\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 730,\n \"valid_from\": \"2026-01-01T00:00:00-06:00\",\n \"valid_until\": \"2028-01-01T00:00:00-06:00\",\n \"certificate_subject\": \"CN=CLIENTE DEL INTEGRADOR S.A., serialNumber=3101123456\",\n \"certificate_serial\": \"0A1B2C3D4E5F\",\n \"created_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Certificado del cliente registrado y activado correctamente.\",\n \"errors\": null\n}", "name": "Certificado del cliente registrado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Cliente no encontrado.\",\n \"errors\": null\n}", "name": "Cliente no encontrado o desvinculado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo leer el certificado .p12. Verifique que la contrase\u00f1a sea correcta y que el archivo sea un certificado digital v\u00e1lido.\",\n \"errors\": {\"p12_file\": [\"No se pudo leer el certificado .p12. Verifique que la contrase\u00f1a sea correcta y que el archivo sea un certificado digital v\u00e1lido.\"]}\n}", "name": "Contrase\u00f1a del .p12 incorrecta" } ] }, { "name": "Reenviar el magic link al cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/resend-magic-link", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/resend-magic-link", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Genera un nuevo token de magic link y env\u00eda un correo de bienvenida\nal usuario propietario del cliente. \u00datil cuando el magic link\noriginal expir\u00f3 (TTL 72 horas) y el cliente a\u00fan no activ\u00f3 su cuenta.\n\n**Restricciones:**\n\n- Solo se puede reenviar si el usuario del cliente tiene\n `must_change_password = true` (es decir, a\u00fan no estableci\u00f3 su\n contrase\u00f1a definitiva).\n- Si el cliente ya activ\u00f3 su cuenta, este endpoint retorna 422." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Magic link reenviado al correo del cliente.\",\n \"errors\": null\n}", "name": "Magic link reenviado" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Cliente no encontrado.\",\n \"errors\": null\n}", "name": "Cliente no encontrado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El cliente ya estableci\u00f3 su contrase\u00f1a. No se puede reenviar el magic link.\",\n \"errors\": null\n}", "name": "Cliente ya activ\u00f3 su cuenta" } ] }, { "name": "Listar las secuencias de consecutivos del cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/sequences", "query": [ { "key": "include_all_terminals", "value": "", "description": "Si `true`, incluye secuencias de TODAS las terminales del cliente (diagn\u00f3stico). Default: `false`.", "disabled": true }, { "key": "terminal_code", "value": "01001", "description": "Filtra por una caja espec\u00edfica (5 d\u00edg., modelo nuevo).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/sequences?include_all_terminals=&terminal_code=01001", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todas las secuencias (`voucher_sequences`) del cliente\ngestionado **filtradas por la terminal asignada a este integrador**.\nCada secuencia corresponde a un tipo de comprobante (01\u201310).\n\n**\u00bfPara qu\u00e9 sirve?**\n\nAl migrar un cliente desde otro facturador (Alegra, Gosocket, etc.),\nAlmendro no tiene historial de los consecutivos previos. Si se\nemite desde la secuencia 1, Hacienda rechaza por \"consecutivo\nduplicado\". Este endpoint permite verificar en qu\u00e9 n\u00famero va cada\ntipo antes de emitir, y el endpoint `PUT` permite ajustarlo.\n\n**Tipos de comprobante (01\u201310):**\n\n| C\u00f3digo | Tipo | Abrev. |\n|--------|------------------------------------|--------|\n| 01 | Factura Electr\u00f3nica | FE |\n| 02 | Nota de D\u00e9bito Electr\u00f3nica | ND |\n| 03 | Nota de Cr\u00e9dito Electr\u00f3nica | NC |\n| 04 | Tiquete Electr\u00f3nico | TE |\n| 05 | Confirmaci\u00f3n Aceptaci\u00f3n Total | CA |\n| 06 | Confirmaci\u00f3n Aceptaci\u00f3n Parcial | CP |\n| 07 | Confirmaci\u00f3n Rechazo | CR |\n| 08 | Factura Electr\u00f3nica de Compra | FEC |\n| 09 | Factura Electr\u00f3nica de Exportaci\u00f3n | FEE |\n| 10 | Recibo Electr\u00f3nico de Pago | REP |\n\nLas secuencias se crean **autom\u00e1ticamente** al emitir el primer\ncomprobante de cada tipo. Si nunca se ha emitido una FEC (tipo 08),\nno existir\u00e1 secuencia para ella | eso es normal." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [{\"id\":42,\"local_code\":\"001\",\"terminal_code\":\"00002\",\"voucher_type\":\"01\",\"voucher_type_label\":\"Factura Electr\u00f3nica\",\"voucher_type_abbr\":\"FE\",\"current_sequence\":9992,\"next_sequence\":9993,\"last_consecutive\":\"00100002010000009992\",\"next_consecutive\":\"00100002010000009993\",\"last_issued_at\":\"2026-04-20T14:30:00-06:00\",\"last_issued_key\":null,\"is_active\":true,\"is_near_rollover\":false,\"display_key\":\"001-00002-01\"}],\n \"message\": \"\",\n \"errors\": null,\n \"terminal\": \"00002\"\n}", "name": "Secuencias de la terminal del integrador" }, { "header": [], "code": 200, "body": "{\n \"success\": true, \"data\": [], \"message\": \"No hay secuencias creadas a\u00fan para la terminal 00002.\", \"errors\": null, \"terminal\": \"00002\"\n}", "name": "Sin secuencias (cliente reci\u00e9n integrado)" }, { "header": [], "code": 403, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\", \"errors\": null\n}", "name": "Plan no es Integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Cliente no encontrado.\", \"errors\": null\n}", "name": "Cliente no encontrado" } ] }, { "name": "Inicializar consecutivo para un tipo de comprobante", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/sequences", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/sequences", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_type\":\"01\",\"terminal_code\":\"01001\",\"current_sequence\":8475,\"reason\":\"Migraci\u00f3n desde Alegra | \u00faltimo consecutivo tipo 01 fue 8475.\",\"password\":\"mi_contrase\u00f1a\"}" }, "description": "Crea una secuencia con un valor inicial para un tipo de comprobante\nque a\u00fan no tiene secuencia en la terminal del integrador. **Cr\u00edtico\npara migraci\u00f3n desde otro facturador.**\n\n**Caso de uso:** el cliente usaba Alegra y su \u00faltima FE fue la 8475.\nSi Almendro emite desde 1, Hacienda rechaza por \"consecutivo\nduplicado\". Con este endpoint, setee `current_sequence=8475` para\nel tipo `01` \u2192 el pr\u00f3ximo comprobante usar\u00e1 8476.\n\n**Importante:** si la secuencia ya existe (porque ya se emiti\u00f3 al\nmenos un comprobante de ese tipo), use `PUT \/sequences\/{seqId}`\npara ajustarla.\n\n**Seguridad:** Requiere confirmaci\u00f3n de contrase\u00f1a." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\"id\":100,\"local_code\":\"001\",\"terminal_code\":\"00002\",\"voucher_type\":\"01\",\"voucher_type_label\":\"Factura Electr\u00f3nica\",\"voucher_type_abbr\":\"FE\",\"current_sequence\":8475,\"next_sequence\":8476,\"last_consecutive\":\"00100002010000008475\",\"next_consecutive\":\"00100002010000008476\",\"last_issued_at\":null,\"last_issued_key\":null,\"is_active\":true,\"is_near_rollover\":false,\"display_key\":\"001-00002-01\"},\n \"message\": \"Secuencia tipo 01 (FE) inicializada en 8475. Pr\u00f3ximo comprobante usar\u00e1 8476.\",\n \"errors\": null\n}", "name": "Secuencia inicializada" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Ya existe una secuencia para el tipo 01 en la terminal 00002. Use PUT para ajustarla.\", \"errors\": {\"voucher_type\": [\"Ya existe. Use PUT \/sequences\/{id} para ajustar.\"]}\n}", "name": "Secuencia ya existe" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"La contrase\u00f1a es incorrecta.\", \"errors\": {\"password\": [\"La contrase\u00f1a proporcionada no coincide con la del usuario autenticado.\"]}\n}", "name": "Contrase\u00f1a incorrecta" } ] }, { "name": "Ajustar el consecutivo de una secuencia del cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/sequences\/:seqId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/sequences\/:seqId", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "seqId", "key": "seqId", "value": "42", "description": "ID de la secuencia (del listado)." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"current_sequence\":9992,\"reason\":\"Migraci\u00f3n desde Alegra | \u00faltimo consecutivo tipo 01 fue 9992.\",\"password\":\"mi_contrase\u00f1a\"}" }, "description": "Cambia manualmente el `current_sequence` de una secuencia. **El\npr\u00f3ximo comprobante emitido usar\u00e1 `current_sequence + 1`.**\n\n**Cu\u00e1ndo usar:**\n- Migraci\u00f3n de facturador: el cliente usaba Alegra y su \u00faltima FE\n fue la 9992. Setee `current_sequence=9992` \u2192 Almendro\n contin\u00faa desde 9993.\n- Correcci\u00f3n post-contingencia: ajustar al valor real.\n\n**Seguridad:** Requiere confirmaci\u00f3n de contrase\u00f1a.\n\n> \u26a0\ufe0f Setear un valor **menor** al actual puede generar\n> consecutivos duplicados que Hacienda rechazar\u00e1. Se permite\n> pero se registra advertencia en la bit\u00e1cora." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"id\":42,\"local_code\":\"001\",\"terminal_code\":\"00002\",\"voucher_type\":\"01\",\"voucher_type_label\":\"Factura Electr\u00f3nica\",\"voucher_type_abbr\":\"FE\",\"current_sequence\":9992,\"next_sequence\":9993,\"last_consecutive\":\"00100002010000009992\",\"next_consecutive\":\"00100002010000009993\",\"last_issued_at\":null,\"last_issued_key\":null,\"is_active\":true,\"is_near_rollover\":false,\"display_key\":\"001-00002-01\"},\n \"message\": \"Consecutivo ajustado: tipo 01 (FE) actualizado de 0 a 9992. Pr\u00f3ximo comprobante usar\u00e1 9993.\",\n \"errors\": null\n}", "name": "Secuencia ajustada" }, { "header": [], "code": 403, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Solo puede ajustar secuencias de su propia terminal (00002).\", \"errors\": null\n}", "name": "Secuencia de otra terminal" }, { "header": [], "code": 404, "body": "{\n \"success\": false, \"data\": null, \"message\": \"Secuencia no encontrada para este cliente.\", \"errors\": null\n}", "name": "Secuencia no encontrada" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"La contrase\u00f1a es incorrecta.\", \"errors\": {\"password\": [\"La contrase\u00f1a proporcionada no coincide con la del usuario autenticado.\"]}\n}", "name": "Contrase\u00f1a incorrecta" } ] }, { "name": "Listar sucursales y cajas de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del contribuyente-cliente gestionado." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve las sucursales (branches) + cajas (terminals) que ESTE integrador\ncre\u00f3 para el cliente. Las cajas usan el slot del integrador en el\n`terminal_code` (= [slot 2 d\u00edg.][caja 3 d\u00edg.])." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [{ \"id\": \"019ee0-...\", \"local_code\": \"001\", \"name\": \"Casa Matriz\", \"is_direct\": false, \"terminals\": [{ \"terminal_code\": \"01001\", \"slot\": \"01\", \"box\": \"001\", \"name\": \"Caja 1\" }] }],\n \"message\": \"Sucursales del cliente gestionado.\", \"errors\": null\n}", "name": "Sucursales del cliente" }, { "header": [], "code": 404, "body": "{ \"success\": false, \"data\": null, \"message\": \"Cliente no encontrado.\", \"errors\": null }", "name": "Cliente no gestionado" } ] }, { "name": "Crear una sucursal para un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"local_code\":\"001\",\"name\":\"Casa Matriz\",\"box_name\":\"Caja 1\"}" }, "description": "Crea una sucursal del cliente gestionada por el integrador y su primera caja\n(en el slot del integrador). Consume cupo del POZO del plan del INTEGRADOR\n(`max_branches`), repartido entre todos sus clientes." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": { \"id\": \"019ee0-...\", \"local_code\": \"001\", \"name\": \"Casa Matriz\", \"is_direct\": false, \"terminals\": [{ \"terminal_code\": \"01001\", \"slot\": \"01\", \"name\": \"Caja 1\" }] },\n \"message\": \"Sucursal creada.\", \"errors\": null\n}", "name": "Sucursal creada (con su primera caja en el slot)" }, { "header": [], "code": 422, "body": "{ \"success\": false, \"data\": null, \"message\": \"Alcanz\u00f3 el pozo de 50 sucursal(es) de su plan. Actualice su plan para agregar m\u00e1s.\", \"errors\": { \"local_code\": [\"...\"] } }", "name": "Pozo del integrador agotado" } ] }, { "name": "Renombrar una sucursal de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches\/:branchId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches\/:branchId", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "branchId", "key": "branchId", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Sucursal Heredia\"}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": { \"id\": \"019ee0-...\", \"name\": \"Sucursal Heredia\" }, \"message\": \"Sucursal actualizada.\", \"errors\": null }", "name": "Sucursal renombrada" } ] }, { "name": "Agregar una caja a una sucursal de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "branchId", "key": "branchId", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Caja 2\"}" }, "description": "Crea una caja en la sucursal del cliente, en el slot del integrador\n(`terminal_code` = [slot][caja]). Respeta el tope de cajas por sucursal del\nplan del integrador." }, "response": [ { "header": [], "code": 201, "body": "{ \"success\": true, \"data\": { \"id\": \"019ee0-...\", \"terminals\": [{ \"terminal_code\": \"01002\", \"name\": \"Caja 2\" }] }, \"message\": \"Caja creada.\", \"errors\": null }", "name": "Caja creada" }, { "header": [], "code": 422, "body": "{ \"success\": false, \"data\": null, \"message\": \"Alcanz\u00f3 el tope de 20 caja(s) por sucursal de su plan.\", \"errors\": { \"name\": [\"...\"] } }", "name": "Tope de cajas alcanzado" } ] }, { "name": "Renombrar una caja de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals\/:tid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals\/:tid", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "branchId", "key": "branchId", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." }, { "id": "tid", "key": "tid", "value": "019ee1bb-cccc-dddd-eeee-ffffffffffff", "description": "UUID de la caja." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"POS 2\"}" }, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": { \"id\": \"019ee0-...\", \"terminals\": [{ \"terminal_code\": \"01001\", \"name\": \"POS 2\" }] }, \"message\": \"Caja actualizada.\", \"errors\": null }", "name": "Caja renombrada" } ] }, { "name": "Eliminar una caja de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals\/:tid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches\/:branchId\/terminals\/:tid", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "branchId", "key": "branchId", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." }, { "id": "tid", "key": "tid", "value": "019ee1bb-cccc-dddd-eeee-ffffffffffff", "description": "UUID de la caja." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "No se puede eliminar la \u00faltima caja activa de la sucursal." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": null, \"message\": \"Caja eliminada.\", \"errors\": null }", "name": "Caja eliminada" }, { "header": [], "code": 409, "body": "{ \"success\": false, \"data\": null, \"message\": \"Deb\u00e9s mantener al menos una caja en la sucursal.\", \"errors\": null }", "name": "Es la \u00faltima caja de la sucursal" } ] }, { "name": "Eliminar una sucursal de un cliente gestionado", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/branches\/:branchId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/branches\/:branchId", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." }, { "id": "branchId", "key": "branchId", "value": "019ee0aa-bbbb-cccc-dddd-eeeeeeeeeeee", "description": "UUID de la sucursal." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Borra la sucursal junto con sus cajas. No se puede eliminar la \u00faltima\nsucursal que el integrador tiene para ese cliente." }, "response": [ { "header": [], "code": 200, "body": "{ \"success\": true, \"data\": null, \"message\": \"Sucursal eliminada.\", \"errors\": null }", "name": "Sucursal eliminada" }, { "header": [], "code": 409, "body": "{ \"success\": false, \"data\": null, \"message\": \"Deb\u00e9s mantener al menos una sucursal para este cliente.\", \"errors\": null }", "name": "Es la \u00faltima sucursal del cliente" } ] }, { "name": "Cambiar la terminal asignada al integrador para este cliente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/terminal", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/terminal", "variable": [ { "id": "id", "key": "id", "value": "019d867d-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"assigned_terminal\":\"00003\",\"local_code\":\"001\",\"migrate_sequences\":true,\"reason\":\"Terminal 00002 comprometida con otro facturador.\",\"password\":\"mi_contrase\u00f1a\"}" }, "description": "Modifica la `assigned_terminal` en la relaci\u00f3n de gesti\u00f3n. La\nterminal ocupa la posici\u00f3n 04-08 del NumeroConsecutivo (20 d\u00edgitos).\n\n**Cu\u00e1ndo usar:**\n- Migraci\u00f3n: la terminal 00002 ya estaba comprometida \u2192 cambiar a 00003.\n- Reorganizaci\u00f3n operativa de terminales.\n\n**`migrate_sequences`:**\n- `false` (default): nueva terminal arranca limpia (secuencias en 0).\n- `true`: copia `current_sequence` de cada tipo desde la terminal\n anterior a la nueva.\n\n**Seguridad:** Requiere confirmaci\u00f3n de contrase\u00f1a.\n\n> Las secuencias de la terminal anterior NO se eliminan | los\n> vouchers ya emitidos las referencian." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"previous_terminal\":\"00002\",\"new_terminal\":\"00003\",\"sequences_migrated\":3,\"sequences\":[{\"id\":100,\"local_code\":\"001\",\"terminal_code\":\"00003\",\"voucher_type\":\"01\",\"voucher_type_label\":\"Factura Electr\u00f3nica\",\"voucher_type_abbr\":\"FE\",\"current_sequence\":9992,\"next_sequence\":9993,\"last_consecutive\":\"00100003010000009992\",\"next_consecutive\":\"00100003010000009993\",\"last_issued_at\":null,\"last_issued_key\":null,\"is_active\":true,\"is_near_rollover\":false,\"display_key\":\"001-00003-01\"}]},\n \"message\": \"Terminal cambiada de 00002 a 00003. Se migraron 3 secuencias.\",\n \"errors\": null\n}", "name": "Terminal cambiada con migraci\u00f3n" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"previous_terminal\":\"00002\",\"new_terminal\":\"00003\",\"sequences_migrated\":0,\"sequences\":[]},\n \"message\": \"Terminal cambiada de 00002 a 00003. Las secuencias se crear\u00e1n al emitir.\",\n \"errors\": null\n}", "name": "Terminal cambiada sin migraci\u00f3n" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"La terminal 00003 ya est\u00e1 asignada a otro integrador de este cliente.\", \"errors\": {\"assigned_terminal\": [\"La terminal 00003 ya est\u00e1 asignada a otro integrador de este cliente.\"]}\n}", "name": "Terminal colisiona con otro integrador" }, { "header": [], "code": 422, "body": "{\n \"success\": false, \"data\": null, \"message\": \"La contrase\u00f1a es incorrecta.\", \"errors\": {\"password\": [\"La contrase\u00f1a proporcionada no coincide con la del usuario autenticado.\"]}\n}", "name": "Contrase\u00f1a incorrecta" } ] } ] }, { "name": "Mis Integradores", "description": "", "item": [ { "name": "Listar los integradores que actualmente gestionan al contribuyente autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-integrators", "query": [ { "key": "per_page", "value": "15", "description": "Resultados por p\u00e1gina (1-100, default 15).", "disabled": false }, { "key": "page", "value": "1", "description": "N\u00famero de p\u00e1gina.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/my-integrators?per_page=15&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve las relaciones managed ACTIVAS (unlinked_at IS NULL)\ndonde el tenant autenticado es el client_contributor_id. Cada\nentrada incluye el integrador, terminal asignada, grants activos\npor ambiente, retention_months_override y plantilla PDF default." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"relationship_id\": \"019d870a-0001-7288-8ece-fd64da75a001\",\n \"integrator\": {\"id\": \"019d865a-1234-7000-a000-abcdef123456\", \"legal_name\": \"Sistemas Integrados S.A.\", \"id_number\": \"3101999999\"},\n \"assigned_terminal\": \"00002\",\n \"linked_at\": \"2026-04-10T09:00:00-06:00\",\n \"grants\": [{\"environment\": \"sandbox\", \"is_active\": true}]\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1}\n}", "name": "Integradores activos" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 0}\n}", "name": "Sin integradores" } ] }, { "name": "Consultar detalle de un integrador espec\u00edfico que gestiona al cliente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-integrators\/:integratorContributorId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-integrators\/:integratorContributorId", "variable": [ { "id": "integratorContributorId", "key": "integratorContributorId", "value": "9c1b4e5a-...", "description": "UUID del integrador." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"relationship_id\": \"019d870a-0001-7288-8ece-fd64da75a001\",\n \"integrator\": {\"id\": \"019d865a-1234-7000-a000-abcdef123456\", \"legal_name\": \"Sistemas Integrados S.A.\", \"id_number\": \"3101999999\", \"id_type\": \"02\", \"emails\": [\"soporte@integrador.cr\"]},\n \"assigned_terminal\": \"00002\",\n \"retention_months_override\": null,\n \"default_pdf_template\": null,\n \"linked_at\": \"2026-04-10T09:00:00-06:00\",\n \"grants\": [{\"id\": \"019d870b-0001-7288-8ece-fd64da75b001\", \"environment\": \"sandbox\", \"is_active\": true, \"certificate\": {\"environment\": \"sandbox\", \"is_active\": true, \"valid_until\": \"2028-01-01T00:00:00-06:00\"}}]\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Detalle del integrador" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Integrador no encontrado.\",\n \"errors\": null\n}", "name": "Integrador no encontrado" } ] }, { "name": "Liberarse de un integrador espec\u00edfico.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-integrators\/:integratorContributorId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-integrators\/:integratorContributorId", "variable": [ { "id": "integratorContributorId", "key": "integratorContributorId", "value": "9c1b4e5a-...", "description": "UUID del integrador del que se libera." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"Cambio de proveedor tecnol\u00f3gico.\"}" }, "description": "El cliente rompe el v\u00ednculo managed con un integrador concreto.\nEfectos (ver UnlinkManagedRelationshipAction):\n\n \u00b7 ManagedRelationship.unlinked_at = now() con metadata de auditor\u00eda.\n \u00b7 Cascade revoke de TODOS los grants activos del integrador sobre\n los .p12 del cliente (v\u00eda RevokeGrantAction, escenario\n GrantAutoRevoked \u2192 notifica al integrador).\n \u00b7 Otros integradores del cliente NO se afectan (modelo N:N).\n \u00b7 El contributor del cliente permanece intacto | NO se soft-deletea.\n\nIrreversible: si ambas partes quieren retomar, el integrador debe\niniciar una nueva IntegratorAccessRequest desde cero. La nueva\nrelaci\u00f3n recibir\u00e1 una terminal distinta." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Se liber\u00f3 del integrador. Los accesos asociados fueron revocados.\",\n \"errors\": null\n}", "name": "Integrador desvinculado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Integrador no encontrado.\",\n \"errors\": null\n}", "name": "Integrador no encontrado" } ] }, { "name": "Cambiar el ROL de un gestor sobre el cliente autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-integrators\/:integratorContributorId\/role", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-integrators\/:integratorContributorId\/role", "variable": [ { "id": "integratorContributorId", "key": "integratorContributorId", "value": "e507fb2b94-c9e62d073743f8140a658fd5f", "description": "" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"role\":\"architecto\"}" }, "description": "La informaci\u00f3n del cliente es del cliente: \u00e9l decide qu\u00e9 ve cada gestor.\n \u00b7 accountant (contador) \u2192 ve la facturaci\u00f3n completa + recibidos.\n \u00b7 integrator \u2192 solo ve las facturas que \u00e9l mismo emiti\u00f3.\n\nAl pasar a `integrator` se retira el puente GUI (switch-contributor):\nlos usuarios del gestor dejan de poder operar al cliente por la interfaz." }, "response": [] } ] }, { "name": "Solicitudes de Acceso", "description": "", "item": [ { "name": "Crear una solicitud de acceso hacia un cliente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"client_id_number\":\"3101000050\",\"environments\":[\"sandbox\"],\"message\":\"Hola, somos su proveedor tecnol\u00f3gico y gustar\u00eda gestionar su facturaci\u00f3n.\"}" }, "description": "El integrador envia la cedula del cliente y los ambientes a los\nque desea acceder. Se crea una solicitud en estado `pending` y se\nnotifica al cliente por email y notificacion en el portal para\nque acepte o rechace." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"status\": \"pending\",\n \"status_label\": \"Pendiente\",\n \"status_color\": \"warning\",\n \"is_pending\": true,\n \"is_final\": false,\n \"resulted_in_grants\": false,\n \"was_fully_accepted\": false,\n \"can_be_responded\": true,\n \"can_be_cancelled\": true,\n \"requested_environments\": [\"sandbox\", \"production\"],\n \"accepted_environments\": null,\n \"message\": \"Solicitamos acceso para integrar su facturaci\u00f3n con nuestro POS.\",\n \"rejection_reason\": null,\n \"client\": {\n \"id\": \"019d867d-c001-7288-8ece-fd64da756c01\",\n \"legal_name\": \"Hotel Las Palmas S.A.\",\n \"commercial_name\": \"Las Palmas\",\n \"id_type\": \"02\",\n \"id_number\": \"3101456789\",\n \"display_name\": \"Las Palmas\"\n },\n \"integrator\": {\n \"id\": \"019d867d-0241-7288-8ece-fd64da75616d\",\n \"legal_name\": \"SistemasPOS de Costa Rica S.A.\",\n \"commercial_name\": \"SistemasPOS\",\n \"id_type\": \"02\",\n \"id_number\": \"3101999888\",\n \"display_name\": \"SistemasPOS\"\n },\n \"requested_at\": \"2026-04-16T10:00:00-06:00\",\n \"responded_at\": null,\n \"created_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Solicitud de acceso creada. El cliente recibir\u00e1 un email y notificaci\u00f3n en su portal.\",\n \"errors\": null\n}", "name": "Solicitud creada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ya existe una solicitud pendiente para este cliente.\",\n \"errors\": null\n}", "name": "Error de validaci\u00f3n" } ] }, { "name": "Listar solicitudes de acceso enviadas por el integrador.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests\/sent", "query": [ { "key": "status", "value": "", "description": "Filtrar por estado: `pending`, `accepted`, `partially_accepted`, `rejected`, `cancelled`.", "disabled": true }, { "key": "per_page", "value": "16", "description": "Resultados por pagina (1-100). Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests\/sent?status=&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna el historial completo de solicitudes enviadas por el\nintegrador autenticado, incluyendo todos los estados (pendientes,\naceptadas, rechazadas, canceladas). Paginacion de 15 por pagina." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 1,\n \"status\": \"accepted\",\n \"status_label\": \"Aceptada\",\n \"status_color\": \"success\",\n \"is_pending\": false,\n \"is_final\": true,\n \"resulted_in_grants\": true,\n \"was_fully_accepted\": true,\n \"can_be_responded\": false,\n \"can_be_cancelled\": false,\n \"requested_environments\": [\"sandbox\", \"production\"],\n \"accepted_environments\": [\"sandbox\", \"production\"],\n \"message\": \"Solicitamos acceso para integrar su facturaci\u00f3n.\",\n \"rejection_reason\": null,\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"display_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\", \"commercial_name\": \"Las Palmas\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"display_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"commercial_name\": \"SistemasPOS\"},\n \"requested_at\": \"2026-04-10T10:00:00-06:00\",\n \"responded_at\": \"2026-04-11T08:00:00-06:00\",\n \"created_at\": \"2026-04-10T10:00:00-06:00\",\n \"grants_count\": 2\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Solicitudes enviadas por el integrador" } ] }, { "name": "Listar solicitudes de acceso recibidas por el cliente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests\/received", "query": [ { "key": "status", "value": "", "description": "Filtrar por estado.", "disabled": true }, { "key": "per_page", "value": "16", "description": "Resultados por pagina (1-100). Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests\/received?status=&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "El cliente ve que integradores le han solicitado acceso a sus\ncertificados digitales. Las solicitudes pendientes aparecen primero." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 2,\n \"status\": \"pending\",\n \"status_label\": \"Pendiente\",\n \"status_color\": \"warning\",\n \"is_pending\": true,\n \"is_final\": false,\n \"resulted_in_grants\": false,\n \"was_fully_accepted\": false,\n \"can_be_responded\": true,\n \"can_be_cancelled\": false,\n \"requested_environments\": [\"sandbox\"],\n \"accepted_environments\": null,\n \"message\": \"Necesitamos acceso para pruebas de integraci\u00f3n.\",\n \"rejection_reason\": null,\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"display_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\", \"commercial_name\": \"Las Palmas\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"display_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"commercial_name\": \"SistemasPOS\"},\n \"requested_at\": \"2026-04-15T14:00:00-06:00\",\n \"responded_at\": null,\n \"created_at\": \"2026-04-15T14:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Solicitudes recibidas por el cliente" } ] }, { "name": "Aceptar una solicitud de acceso (total o parcialmente).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests\/:id\/accept", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests\/:id\/accept", "variable": [ { "id": "id", "key": "id", "value": "16", "description": "ID de la solicitud a aceptar." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"rejection_reason\":\"Ya tenemos un proveedor asignado para esta tarea.\",\"accepted_environments\":[\"sandbox\"]}" }, "description": "El cliente elige que ambientes autoriza. Se crean los accesos\ncorrespondientes con terminal asignada. El integrador recibe\nnotificacion por email y en su portal." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"status\": \"accepted\",\n \"status_label\": \"Aceptada\",\n \"status_color\": \"success\",\n \"is_pending\": false,\n \"is_final\": true,\n \"resulted_in_grants\": true,\n \"was_fully_accepted\": true,\n \"can_be_responded\": false,\n \"can_be_cancelled\": false,\n \"requested_environments\": [\"sandbox\", \"production\"],\n \"accepted_environments\": [\"sandbox\", \"production\"],\n \"message\": \"Solicitamos acceso para integrar su facturaci\u00f3n.\",\n \"rejection_reason\": null,\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"display_name\": \"Las Palmas\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"display_name\": \"SistemasPOS\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\"},\n \"requested_at\": \"2026-04-10T10:00:00-06:00\",\n \"responded_at\": \"2026-04-16T11:00:00-06:00\",\n \"created_at\": \"2026-04-10T10:00:00-06:00\",\n \"grants_count\": 2\n },\n \"message\": \"Solicitud aceptada correctamente. El integrador recibir\u00e1 notificaci\u00f3n y email.\",\n \"errors\": null\n}", "name": "Solicitud aceptada completamente" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Solo se pueden responder solicitudes en estado pendiente.\",\n \"errors\": null\n}", "name": "Error de validaci\u00f3n" } ] }, { "name": "Rechazar una solicitud de acceso.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests\/:id\/reject", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests\/:id\/reject", "variable": [ { "id": "id", "key": "id", "value": "16", "description": "ID de la solicitud a rechazar." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"rejection_reason\":\"Ya tenemos un proveedor asignado para esta tarea.\",\"accepted_environments\":[\"sandbox\"]}" }, "description": "No se crean accesos. El integrador recibe notificacion con el\nmotivo opcional del rechazo." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 3,\n \"status\": \"rejected\",\n \"status_label\": \"Rechazada\",\n \"status_color\": \"danger\",\n \"is_pending\": false,\n \"is_final\": true,\n \"resulted_in_grants\": false,\n \"was_fully_accepted\": false,\n \"can_be_responded\": false,\n \"can_be_cancelled\": false,\n \"requested_environments\": [\"sandbox\", \"production\"],\n \"accepted_environments\": null,\n \"message\": \"Solicitamos acceso para integrar su facturaci\u00f3n.\",\n \"rejection_reason\": \"Ya contamos con otro proveedor de integraci\u00f3n.\",\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"display_name\": \"Las Palmas\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"display_name\": \"SistemasPOS\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\"},\n \"requested_at\": \"2026-04-10T10:00:00-06:00\",\n \"responded_at\": \"2026-04-16T12:00:00-06:00\",\n \"created_at\": \"2026-04-10T10:00:00-06:00\"\n },\n \"message\": \"Solicitud rechazada. El integrador recibir\u00e1 notificaci\u00f3n.\",\n \"errors\": null\n}", "name": "Solicitud rechazada" } ] }, { "name": "Cancelar una solicitud de acceso antes de que el cliente responda.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/access-requests\/:id\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/access-requests\/:id\/cancel", "variable": [ { "id": "id", "key": "id", "value": "16", "description": "ID de la solicitud a cancelar." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Solo se puede cancelar si la solicitud esta en estado `pending`.\nEl cliente recibe una notificacion informativa." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 4,\n \"status\": \"cancelled\",\n \"status_label\": \"Cancelada\",\n \"status_color\": \"secondary\",\n \"is_pending\": false,\n \"is_final\": true,\n \"resulted_in_grants\": false,\n \"was_fully_accepted\": false,\n \"can_be_responded\": false,\n \"can_be_cancelled\": false,\n \"requested_environments\": [\"sandbox\"],\n \"accepted_environments\": null,\n \"message\": null,\n \"rejection_reason\": null,\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"display_name\": \"Las Palmas\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"display_name\": \"SistemasPOS\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\"},\n \"requested_at\": \"2026-04-14T09:00:00-06:00\",\n \"responded_at\": \"2026-04-16T13:00:00-06:00\",\n \"created_at\": \"2026-04-14T09:00:00-06:00\"\n },\n \"message\": \"Solicitud cancelada correctamente.\",\n \"errors\": null\n}", "name": "Solicitud cancelada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Solicitud no encontrada.\",\n \"errors\": null\n}", "name": "No encontrada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"La solicitud no puede cancelarse en su estado actual (accepted). Solo se pueden cancelar solicitudes pendientes.\",\n \"errors\": null\n}", "name": "Estado no permite cancelaci\u00f3n" } ] } ] }, { "name": "Grants de Certificados", "description": "", "item": [ { "name": "Listar los accesos otorgados sobre los certificados del cliente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificate-grants", "query": [ { "key": "active", "value": "", "description": "Filtrar: `true` = solo activos, `false` = solo revocados. Omitir para ver todos.", "disabled": true }, { "key": "environment", "value": "", "description": "Filtrar por ambiente: `sandbox` o `production`.", "disabled": true }, { "key": "per_page", "value": "16", "description": "Resultados por pagina (1-100). Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/certificate-grants?active=&environment=&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "El cliente ve que integradores tienen permiso de firmar con sus\ncertificados digitales y en que ambiente. Incluye accesos activos\ny revocados (historial completo). Los activos se muestran primero." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 1,\n \"assigned_terminal\": \"00002\",\n \"is_active\": true,\n \"is_revoked\": false,\n \"certificate\": {\n \"id\": \"019d867d-d001-7288-8ece-fd64da756d01\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 1440,\n \"valid_from\": \"2026-01-01T00:00:00-06:00\",\n \"valid_until\": \"2030-01-01T00:00:00-06:00\"\n },\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\", \"display_name\": \"Las Palmas\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"display_name\": \"SistemasPOS\"},\n \"access_request_id\": 1,\n \"granted_at\": \"2026-04-11T08:00:00-06:00\",\n \"revoked_at\": null,\n \"revoke_reason\": null,\n \"revoked_by\": null,\n \"created_at\": \"2026-04-11T08:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Accesos del cliente" } ] }, { "name": "Revocar el acceso de un integrador a un certificado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/certificate-grants\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/certificate-grants\/:id", "variable": [ { "id": "id", "key": "id", "value": "16", "description": "ID del grant a revocar." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"architecto\"}" }, "description": "El integrador pierde la capacidad de firmar comprobantes con este\ncertificado. Los comprobantes previamente emitidos siguen siendo\nvalidos. El integrador recibe notificacion de la revocacion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 1,\n \"assigned_terminal\": \"00002\",\n \"is_active\": false,\n \"is_revoked\": true,\n \"certificate\": {\n \"id\": \"019d867d-d001-7288-8ece-fd64da756d01\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 1440,\n \"valid_from\": \"2026-01-01T00:00:00-06:00\",\n \"valid_until\": \"2030-01-01T00:00:00-06:00\"\n },\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\", \"display_name\": \"Las Palmas\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"display_name\": \"SistemasPOS\"},\n \"access_request_id\": 1,\n \"granted_at\": \"2026-04-11T08:00:00-06:00\",\n \"revoked_at\": \"2026-04-16T14:00:00-06:00\",\n \"revoke_reason\": \"Cambio de proveedor de integraci\u00f3n.\",\n \"revoked_by\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"display_name\": \"Las Palmas\"},\n \"created_at\": \"2026-04-11T08:00:00-06:00\"\n },\n \"message\": \"Acceso revocado correctamente. El integrador ya no puede emitir con este certificado.\",\n \"errors\": null\n}", "name": "Acceso revocado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Este acceso ya fue revocado anteriormente.\",\n \"errors\": null\n}", "name": "Grant ya revocado" } ] }, { "name": "Listar los accesos recibidos por el integrador autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-access", "query": [ { "key": "client_id", "value": "", "description": "UUID del cliente managed para filtrar grants hacia ese cliente.", "disabled": true }, { "key": "active", "value": "", "description": "Filtrar: `true` = solo activos, `false` = solo revocados. Omitir para ver todos.", "disabled": true }, { "key": "environment", "value": "", "description": "Filtrar por ambiente: `sandbox` o `production`.", "disabled": true }, { "key": "per_page", "value": "16", "description": "Resultados por pagina (1-100). Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/my-access?client_id=&active=&environment=&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "El integrador ve sobre que certificados de que clientes tiene\nacceso activo (o revocado, seg\u00fan filtro). Cada grant incluye el\ncert, el cliente, la terminal asignada y el ambiente.\n\nOpcionalmente filtrable por `client_id` para obtener los grants\ndel integrador sobre un cliente espec\u00edfico | \u00fatil en el perfil\ndel managed client para mostrar la secci\u00f3n \"Mi acceso\".\n\n Requiere plan INTEGRATOR. Retorna 403 para cualquier otro plan.\n Espeja la sem\u00e1ntica de PublicManagedContributorController." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 1,\n \"assigned_terminal\": \"00002\",\n \"is_active\": true,\n \"is_revoked\": false,\n \"certificate\": {\n \"id\": \"019d867d-d001-7288-8ece-fd64da756d01\",\n \"environment\": \"sandbox\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 1440,\n \"valid_from\": \"2026-01-01T00:00:00-06:00\",\n \"valid_until\": \"2030-01-01T00:00:00-06:00\"\n },\n \"client\": {\"id\": \"019d867d-c001-7288-8ece-fd64da756c01\", \"legal_name\": \"Hotel Las Palmas S.A.\", \"commercial_name\": \"Las Palmas\", \"id_type\": \"02\", \"id_number\": \"3101456789\", \"display_name\": \"Las Palmas\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"display_name\": \"SistemasPOS\"},\n \"access_request_id\": 1,\n \"granted_at\": \"2026-04-11T08:00:00-06:00\",\n \"revoked_at\": null,\n \"revoke_reason\": null,\n \"revoked_by\": null,\n \"created_at\": \"2026-04-11T08:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Accesos del integrador" }, { "header": [], "code": 403, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su plan no permite gestionar clientes. Actualice a Contadores o Integrador para gestionar la cartera de clientes.\",\n \"errors\": null\n}", "name": "Plan no permite gestionar clientes" } ] }, { "name": "El integrador renuncia voluntariamente a un acceso que recibio.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-access\/:grantId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-access\/:grantId", "variable": [ { "id": "grantId", "key": "grantId", "value": "16", "description": "ID del grant al que renuncia." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"reason\":\"architecto\"}" }, "description": "Util cuando el integrador deja de gestionar al cliente y quiere\nlimpiar su listado de accesos activos. El cliente es notificado\nde la renuncia." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 3,\n \"assigned_terminal\": \"00003\",\n \"is_active\": false,\n \"is_revoked\": true,\n \"certificate\": {\n \"id\": \"019d867d-d003-7288-8ece-fd64da756d03\",\n \"environment\": \"production\",\n \"is_active\": true,\n \"is_expired\": false,\n \"days_remaining\": 1200,\n \"valid_from\": \"2025-06-01T00:00:00-06:00\",\n \"valid_until\": \"2029-08-01T00:00:00-06:00\"\n },\n \"client\": {\"id\": \"019d867d-c002-7288-8ece-fd64da756c02\", \"legal_name\": \"Restaurante El Mango S.A.\", \"commercial_name\": \"El Mango\", \"id_type\": \"02\", \"id_number\": \"3101789012\", \"display_name\": \"El Mango\"},\n \"integrator\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"commercial_name\": \"SistemasPOS\", \"id_type\": \"02\", \"id_number\": \"3101999888\", \"display_name\": \"SistemasPOS\"},\n \"access_request_id\": 2,\n \"granted_at\": \"2026-03-15T10:00:00-06:00\",\n \"revoked_at\": \"2026-04-16T15:00:00-06:00\",\n \"revoke_reason\": \"Fin de contrato de servicio.\",\n \"revoked_by\": {\"id\": \"019d867d-0241-7288-8ece-fd64da75616d\", \"legal_name\": \"SistemasPOS de Costa Rica S.A.\", \"display_name\": \"SistemasPOS\"},\n \"created_at\": \"2026-03-15T10:00:00-06:00\"\n },\n \"message\": \"Ha renunciado al acceso correctamente. El cliente ser\u00e1 notificado.\",\n \"errors\": null\n}", "name": "Renuncia exitosa" } ] } ] }, { "name": "Notificaciones", "description": "", "item": [ { "name": "Listar notificaciones del usuario autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/notifications", "query": [ { "key": "unread_only", "value": "", "description": "Solo retornar notificaciones no leidas. Default: false.", "disabled": true }, { "key": "type", "value": "", "description": "Filtrar por tipo de notificacion (ej: `access_request_received`).", "disabled": true }, { "key": "per_page", "value": "16", "description": "Resultados por pagina (1-50). Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/public\/notifications?unread_only=&type=&per_page=16" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retorna las notificaciones personales del usuario y las notificaciones\ngenerales (broadcasts) del contribuyente. Las no leidas aparecen\nprimero, luego por fecha descendente. No incluye notificaciones\nexpiradas.\n\nLa respuesta incluye `unread_count` fuera del array `data` para\nactualizar el badge de notificaciones sin una consulta adicional." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": 42,\n \"type\": \"access_request_received\",\n \"type_label\": \"Solicitud de acceso recibida\",\n \"type_color\": \"info\",\n \"type_icon\": \"key\",\n \"type_category\": \"access_control\",\n \"title\": \"Nueva solicitud de acceso\",\n \"message\": \"SistemasPOS de Costa Rica S.A. solicita acceso a sus certificados digitales.\",\n \"action_url\": \"\/portal\/access-requests\/1\",\n \"action_label\": \"Revisar solicitud\",\n \"has_action\": true,\n \"metadata\": {\"access_request_id\": 1, \"integrator_name\": \"SistemasPOS\"},\n \"is_read\": false,\n \"is_unread\": true,\n \"read_at\": null,\n \"requires_action\": true,\n \"is_broadcast\": false,\n \"is_expired\": false,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"expires_at\": null\n }\n ],\n \"message\": \"\",\n \"errors\": null,\n \"unread_count\": 3,\n \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 5},\n \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}\n}", "name": "Lista con notificaciones" } ] }, { "name": "Marcar todas las notificaciones no leidas como leidas.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/notifications\/read-all", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/notifications\/read-all" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Operacion en lote que marca todas las notificaciones pendientes\ndel usuario como leidas. Retorna la cantidad de notificaciones\nque fueron marcadas (0 si ya estaban todas leidas)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"marked_count\": 5,\n \"unread_count\": 0\n },\n \"message\": \"5 notificaciones marcadas como le\u00eddas.\",\n \"errors\": null\n}", "name": "Notificaciones marcadas" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"marked_count\": 0,\n \"unread_count\": 0\n },\n \"message\": \"No hay notificaciones pendientes.\",\n \"errors\": null\n}", "name": "Sin notificaciones pendientes" } ] }, { "name": "Marcar una notificacion como leida.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/notifications\/:id\/read", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/notifications\/:id\/read", "variable": [ { "id": "id", "key": "id", "value": "16", "description": "ID de la notificacion a marcar." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Operacion idempotente: si la notificacion ya estaba leida, retorna\n200 con el mismo estado sin error. La respuesta incluye la\nnotificacion actualizada y el nuevo `unread_count`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"notification\": {\n \"id\": 42,\n \"type\": \"access_request_received\",\n \"type_label\": \"Solicitud de acceso recibida\",\n \"type_color\": \"info\",\n \"type_icon\": \"key\",\n \"type_category\": \"access_control\",\n \"title\": \"Nueva solicitud de acceso\",\n \"message\": \"SistemasPOS solicita acceso a sus certificados.\",\n \"action_url\": \"\/portal\/access-requests\/1\",\n \"action_label\": \"Revisar solicitud\",\n \"has_action\": true,\n \"metadata\": {\"access_request_id\": 1},\n \"is_read\": true,\n \"is_unread\": false,\n \"read_at\": \"2026-04-16T11:00:00-06:00\",\n \"requires_action\": true,\n \"is_broadcast\": false,\n \"is_expired\": false,\n \"created_at\": \"2026-04-16T10:00:00-06:00\",\n \"expires_at\": null\n },\n \"unread_count\": 2\n },\n \"message\": \"Notificaci\u00f3n marcada como le\u00edda.\",\n \"errors\": null\n}", "name": "Notificaci\u00f3n marcada como le\u00edda" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Notificaci\u00f3n no encontrada.\",\n \"errors\": null\n}", "name": "No encontrada" } ] } ] }, { "name": "Suscripci\u00f3n y Facturaci\u00f3n", "description": "", "item": [ { "name": "Consultar el estado de la suscripci\u00f3n", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el estado completo de billing del contribuyente autenticado:\nel plan vigente, los datos de la suscripci\u00f3n (ciclo y per\u00edodo pagado),\nel consumo de comprobantes del mes en curso, el cat\u00e1logo de planes\ndisponibles para cambiar y, si existe, la baja de plan programada.\n\nEl **consumo del mes** (`usage`) se calcula sobre los comprobantes de\nproducci\u00f3n emitidos por el contribuyente y se compara contra el l\u00edmite\nmensual del plan (`vouchers_limit` puede ser `null` = ilimitado).\n\nEl bloque `scheduled_downgrade` solo est\u00e1 presente (no `null`) cuando\nel contribuyente program\u00f3 una baja de plan que se aplicar\u00e1 al fin del\nper\u00edodo pagado (ver `POST \/subscription\/downgrade`)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"plan\": {\n \"code\": \"pyme\",\n \"name\": \"Pyme\",\n \"is_free\": false,\n \"monthly_price_usd\": \"29.00\",\n \"annual_price_usd\": \"290.00\",\n \"monthly_voucher_limit\": 1000,\n \"tier\": 3,\n \"max_clients\": 300,\n \"max_items\": 1000,\n \"max_users\": 5,\n \"max_managed_contributors\": 0,\n \"max_branches\": 3,\n \"max_terminals_per_branch\": 5,\n \"has_api\": true\n },\n \"subscription\": {\n \"status\": \"active\",\n \"billing_cycle\": \"monthly\",\n \"current_period_start\": \"2026-06-01T00:00:00-06:00\",\n \"current_period_end\": \"2026-07-01T00:00:00-06:00\",\n \"days_remaining\": 8,\n \"is_past_due\": false,\n \"is_recurring\": true\n },\n \"usage\": {\n \"vouchers_used\": 142,\n \"vouchers_limit\": 1000\n },\n \"available_plans\": [\n {\n \"code\": \"free\",\n \"name\": \"Gratis\",\n \"is_free\": true,\n \"monthly_price_usd\": \"0.00\",\n \"annual_price_usd\": \"0.00\",\n \"monthly_voucher_limit\": 10,\n \"tier\": 1,\n \"max_clients\": 5,\n \"max_items\": 10,\n \"max_users\": 1,\n \"max_managed_contributors\": 0,\n \"max_branches\": 1,\n \"max_terminals_per_branch\": 1,\n \"has_api\": false\n }\n ],\n \"scheduled_downgrade\": null\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Estado de la suscripci\u00f3n" } ] }, { "name": "Listar el historial de pagos", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/payments", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/payments" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve hasta los **100 pagos m\u00e1s recientes** del contribuyente\n(mensualidades y cargos de suscripci\u00f3n), ordenados del m\u00e1s nuevo al\nm\u00e1s antiguo. Cada pago incluye, si existe, la **factura electr\u00f3nica**\nemitida por Almendro al cobrar.\n\nEl campo `data` es un **arreglo plano** de pagos (sin paginaci\u00f3n). El\nbloque `invoice` es `null` mientras el comprobante de la mensualidad\na\u00fan no se ha emitido o vinculado." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0009-7288-8ece-fd64da756009\",\n \"date\": \"2026-06-01T08:30:00-06:00\",\n \"type\": \"subscription\",\n \"status\": \"paid\",\n \"amount_usd\": \"29.00\",\n \"currency\": \"USD\",\n \"amount_local\": \"15080.00\",\n \"description\": \"Suscripci\u00f3n Pyme (monthly)\",\n \"period_start\": \"2026-06-01\",\n \"period_end\": \"2026-07-01\",\n \"gateway\": \"tilopay\",\n \"invoice\": {\n \"voucher_key\": \"50601062600310112345600100001010000000001100000001\",\n \"status\": \"accepted\",\n \"hacienda_status\": \"aceptado\"\n }\n },\n {\n \"id\": \"019d867d-0008-7288-8ece-fd64da756008\",\n \"date\": \"2026-05-01T08:30:00-06:00\",\n \"type\": \"subscription\",\n \"status\": \"paid\",\n \"amount_usd\": \"29.00\",\n \"currency\": \"USD\",\n \"amount_local\": \"15010.00\",\n \"description\": \"Suscripci\u00f3n Pyme (monthly)\",\n \"period_start\": \"2026-05-01\",\n \"period_end\": \"2026-06-01\",\n \"gateway\": \"tilopay\",\n \"invoice\": null\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Historial de pagos" } ] }, { "name": "Cancelar una baja de plan programada", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/scheduled-downgrade", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/scheduled-downgrade" }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"password\":\"mi-contrasena-secreta\"}" }, "description": "Revierte una **baja de plan programada** (downgrade o cancelaci\u00f3n de\nsuscripci\u00f3n a\u00fan no ejecutada) y conserva el plan actual sin cambios ni\ncobros nuevos. Solo tiene efecto mientras la baja no se haya aplicado.\n\nPor seguridad exige la **contrase\u00f1a** del usuario autenticado. Requiere\nque exista una baja programada; si no, responde **404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Baja de plan cancelada. Manten\u00e9s tu plan actual.\",\n \"errors\": null\n}", "name": "Baja cancelada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No hay una baja de plan programada.\",\n \"errors\": null\n}", "name": "Sin baja programada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"password\": [\"La contrase\u00f1a es incorrecta.\"]}\n}", "name": "Contrase\u00f1a incorrecta" } ] }, { "name": "Iniciar el pago \u00fanico de un plan (checkout)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/checkout", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/checkout" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan_code\":\"pyme\",\"billing_cycle\":\"monthly\"}" }, "description": "Inicia el **checkout de Tilopay** para contratar un plan de pago por un\n\u00fanico per\u00edodo (mensual o anual). Crea una sesi\u00f3n de pago en Tilopay,\nregistra un pago **PENDIENTE** y devuelve la `redirect_url` a la que su\nbackend debe **redirigir** al cliente para completar el pago.\n\nLa activaci\u00f3n del plan **no** ocurre en esta respuesta: sucede en el\nretorno firmado de Tilopay una vez que el pago se confirma.\n\nPagar **no** exige contrase\u00f1a (el cliente entrega dinero, no hay riesgo).\nEl plan **gratis** no puede contratarse por esta v\u00eda." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"redirect_url\": \"https:\/\/app.tilopay.com\/checkout\/abc123\",\n \"order\": \"TPAY-019d867d-0001\"\n },\n \"message\": \"Redirigiendo a la pasarela de pago.\",\n \"errors\": null\n}", "name": "Sesi\u00f3n de pago creada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"El plan solicitado no existe o no est\u00e1 disponible.\"]}\n}", "name": "Plan no disponible" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"El plan gratuito no requiere pago.\"]}\n}", "name": "Plan gratuito" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"billing_cycle\": [\"El plan no tiene precio para el ciclo seleccionado.\"]}\n}", "name": "Sin precio para el ciclo" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo iniciar el pago con Tilopay. Intente de nuevo en unos minutos.\",\n \"errors\": null\n}", "name": "Fallo de la pasarela" } ] }, { "name": "Iniciar la suscripci\u00f3n recurrente de un plan", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/subscribe", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/subscribe" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan_code\":\"pyme\",\"billing_cycle\":\"monthly\"}" }, "description": "Inicia una **suscripci\u00f3n recurrente** (cobro autom\u00e1tico peri\u00f3dico) de un\nplan de pago en Tilopay. Genera la URL de registro de la suscripci\u00f3n con\nel correo del contribuyente pre-cargado y devuelve la `redirect_url` a la\nque su backend debe **redirigir** al cliente.\n\nEl plan se activa cuando llega el **webhook** de suscripci\u00f3n\/cobro de\nTilopay, no en esta respuesta. Si el contribuyente ya estaba registrado,\nse devuelve la URL de renovaci\u00f3n.\n\nRequiere que exista un **plan de pasarela** configurado para la\ncombinaci\u00f3n plan + ciclo, y que la cuenta tenga al menos un correo\nregistrado. El plan **gratis** no admite suscripci\u00f3n." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"redirect_url\": \"https:\/\/app.tilopay.com\/subscribe\/register\/xyz789\"\n },\n \"message\": \"Redirigiendo al registro de la suscripci\u00f3n.\",\n \"errors\": null\n}", "name": "Registro de suscripci\u00f3n creado" }, { "header": [], "code": 409, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"La suscripci\u00f3n recurrente para este plan a\u00fan no est\u00e1 disponible. Contacte a soporte.\",\n \"errors\": null\n}", "name": "Suscripci\u00f3n recurrente no disponible para el plan" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"El plan solicitado no existe, no est\u00e1 disponible o es gratuito.\"]}\n}", "name": "Plan no disponible o gratuito" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Su cuenta no tiene un correo registrado para la suscripci\u00f3n.\",\n \"errors\": null\n}", "name": "Sin correo registrado" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo iniciar la suscripci\u00f3n con Tilopay. Intente m\u00e1s tarde.\",\n \"errors\": null\n}", "name": "Fallo de la pasarela" } ] }, { "name": "Cancelar la suscripci\u00f3n recurrente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/cancel-recurring", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/cancel-recurring" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"password\":\"mi-contrasena-secreta\",\"reason\":\"Cancelo la suscripcion porque por ahora estoy facturando muy poco y prefiero volver al plan gratuito mientras crece mi negocio.\"}" }, "description": "Cancela el **cobro autom\u00e1tico** de la suscripci\u00f3n recurrente en Tilopay\ny programa la baja al plan **gratis** al fin del per\u00edodo pagado. El\ncontribuyente conserva su plan actual hasta entonces y **no hay\nreembolso**.\n\nPor tratarse de un cambio de plan (no un pago), exige la **contrase\u00f1a**\ndel usuario autenticado y un **motivo** de al menos 100 caracteres\n(retenci\u00f3n y anal\u00edtica). Requiere una suscripci\u00f3n recurrente activa en\nTilopay." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Suscripci\u00f3n cancelada. Manten\u00e9s el plan hasta el fin del per\u00edodo pagado.\",\n \"errors\": null\n}", "name": "Suscripci\u00f3n cancelada" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No hay una suscripci\u00f3n recurrente activa para cancelar.\",\n \"errors\": null\n}", "name": "Sin suscripci\u00f3n recurrente activa" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"password\": [\"La contrase\u00f1a es incorrecta.\"]}\n}", "name": "Contrase\u00f1a incorrecta" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"reason\": [\"El motivo debe tener al menos 100 caracteres.\"]}\n}", "name": "Motivo demasiado corto" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo cancelar la suscripci\u00f3n con Tilopay. Intente m\u00e1s tarde.\",\n \"errors\": null\n}", "name": "Fallo de la pasarela" } ] }, { "name": "Programar una baja de plan (downgrade)", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/downgrade", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/downgrade" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan_code\":\"emprendedor\",\"password\":\"mi-contrasena-secreta\",\"reason\":\"Bajo de plan porque mi volumen de facturacion disminuyo bastante este trimestre y el plan inferior cubre de sobra mis necesidades actuales.\"}" }, "description": "Programa una **baja a un plan inferior** que se aplicar\u00e1 al fin del\nper\u00edodo pagado. Si existe una suscripci\u00f3n recurrente en Tilopay, se\ncancela el cobro autom\u00e1tico para que no haya cargos futuros del plan\nsuperior. El contribuyente conserva su plan actual hasta que venza el\nper\u00edodo pagado y entonces pasa al plan destino. **No hay reembolso**.\n\nPor tratarse de un cambio de plan (no un pago), exige la **contrase\u00f1a**\ndel usuario y un **motivo** de al menos 100 caracteres.\n\nEl plan destino debe ser de **menor rango** (`tier`\/`display_order`) que\nel actual y no puede ser el plan que ya tiene activo. Para **subir** de\nplan use la suscripci\u00f3n (`POST \/subscription\/subscribe`)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Baja de plan programada. Manten\u00e9s tu plan actual hasta el fin del per\u00edodo pagado.\",\n \"errors\": null\n}", "name": "Baja programada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"password\": [\"La contrase\u00f1a es incorrecta.\"]}\n}", "name": "Contrase\u00f1a incorrecta" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"reason\": [\"El motivo debe tener al menos 100 caracteres.\"]}\n}", "name": "Motivo demasiado corto" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"El plan solicitado no existe o no est\u00e1 disponible.\"]}\n}", "name": "Plan no disponible" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"Ya ten\u00e9s este plan activo.\"]}\n}", "name": "Ya tiene este plan" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"plan_code\": [\"Para subir de plan, us\u00e1 la suscripci\u00f3n (cobro autom\u00e1tico).\"]}\n}", "name": "No es una baja real" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo procesar la baja con Tilopay. Intente m\u00e1s tarde.\",\n \"errors\": null\n}", "name": "Fallo de la pasarela" } ] } ] }, { "name": "Soporte", "description": "", "item": [ { "name": "Listar conversaciones de soporte", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support\/conversations", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support\/conversations" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve todas las conversaciones de soporte abiertas por el\ncontribuyente autenticado, ordenadas con las m\u00e1s recientes primero\n(por \u00faltima actividad). Cada conversaci\u00f3n incluye el conteo de\nmensajes, pero **no** el hilo completo | para ver los mensajes use\n`GET \/support\/conversations\/{id}`.\n\nLas conversaciones son tipo chat in-app entre el cliente y el equipo\nde soporte, dentro de la plataforma (sin correos). El alcance est\u00e1\nlimitado al contribuyente del token (multi-tenant)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"subject\": \"No me llega el correo al cliente\",\n \"status\": \"open\",\n \"priority\": \"normal\",\n \"unread_for_client\": false,\n \"messages_count\": 3,\n \"last_message_at\": \"2026-06-23T10:00:00-06:00\",\n \"created_at\": \"2026-06-22T09:00:00-06:00\"\n }\n ],\n \"message\": \"Conversaciones de soporte.\",\n \"errors\": null\n}", "name": "Listado de conversaciones" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"Conversaciones de soporte.\",\n \"errors\": null\n}", "name": "Sin conversaciones" } ] }, { "name": "Abrir una conversaci\u00f3n de soporte", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support\/conversations", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support\/conversations" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"subject\":\"No me llega el correo al cliente\",\"message\":\"Hola, emit\u00ed una factura pero el cliente dice que no le lleg\u00f3 el correo.\"}" }, "description": "Crea una nueva conversaci\u00f3n de soporte con su **primer mensaje**. La\nconversaci\u00f3n nace en estado `open` y con la prioridad correspondiente\nal plan del contribuyente (`priority` si tiene soporte prioritario,\n`normal` en caso contrario).\n\nAl crearla se env\u00eda un correo de acuse al cliente, pero el hilo sigue\nsiendo in-app.\n\n**L\u00edmite:** el cliente solo puede enviar **un mensaje de soporte por\nhora**. Si el \u00faltimo mensaje del cliente (en cualquiera de sus\nconversaciones) tiene menos de una hora y el equipo a\u00fan no lo\nrespondi\u00f3, la API responde **HTTP 429** con el tiempo restante." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"subject\": \"No me llega el correo al cliente\",\n \"status\": \"open\",\n \"priority\": \"normal\",\n \"unread_for_client\": false,\n \"messages_count\": 1,\n \"last_message_at\": \"2026-06-23T10:00:00-06:00\",\n \"created_at\": \"2026-06-23T10:00:00-06:00\",\n \"client_can_write\": false,\n \"cooldown_seconds\": 3600,\n \"messages\": [\n {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"sender_type\": \"client\",\n \"body\": \"Hola, emit\u00ed una factura pero el cliente dice que no le lleg\u00f3 el correo.\",\n \"created_at\": \"2026-06-23T10:00:00-06:00\"\n }\n ]\n },\n \"message\": \"Conversaci\u00f3n creada.\",\n \"errors\": null\n}", "name": "Conversaci\u00f3n creada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"message\": [\"El campo message es obligatorio.\"]}\n}", "name": "Mensaje requerido" }, { "header": [], "code": 429, "body": "{\n \"success\": false,\n \"data\": {\"cooldown_seconds\": 2400},\n \"message\": \"Solo puedes enviar un mensaje de soporte cada hora. Podr\u00e1s escribir de nuevo en 40 min, o cuando el equipo responda.\",\n \"errors\": null\n}", "name": "L\u00edmite de un mensaje por hora" } ] }, { "name": "Consultar una conversaci\u00f3n de soporte", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support\/conversations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support\/conversations\/:id", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID de la conversaci\u00f3n." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el detalle de una conversaci\u00f3n con su **hilo completo de\nmensajes** ordenados cronol\u00f3gicamente. Solo se retornan conversaciones\nque pertenecen al contribuyente autenticado.\n\nAl consultar el detalle, la conversaci\u00f3n se marca como **le\u00edda por el\ncliente** (`unread_for_client` pasa a `false`).\n\nLa respuesta incluye adem\u00e1s `client_can_write` y `cooldown_seconds`,\nque reflejan el l\u00edmite de un mensaje por hora para que el frontend\nhabilite o deshabilite el cuadro de respuesta." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"subject\": \"No me llega el correo al cliente\",\n \"status\": \"open\",\n \"priority\": \"normal\",\n \"unread_for_client\": false,\n \"messages_count\": 2,\n \"last_message_at\": \"2026-06-23T11:00:00-06:00\",\n \"created_at\": \"2026-06-23T10:00:00-06:00\",\n \"client_can_write\": true,\n \"cooldown_seconds\": 0,\n \"messages\": [\n {\n \"id\": \"019d867d-0002-7288-8ece-fd64da756002\",\n \"sender_type\": \"client\",\n \"body\": \"Hola, emit\u00ed una factura pero el cliente dice que no le lleg\u00f3 el correo.\",\n \"created_at\": \"2026-06-23T10:00:00-06:00\"\n },\n {\n \"id\": \"019d867d-0003-7288-8ece-fd64da756003\",\n \"sender_type\": \"admin\",\n \"body\": \"Hola, ya revisamos y el correo sali\u00f3 correctamente. P\u00eddale al cliente revisar spam.\",\n \"created_at\": \"2026-06-23T11:00:00-06:00\"\n }\n ]\n },\n \"message\": \"Detalle de la conversaci\u00f3n.\",\n \"errors\": null\n}", "name": "Detalle con hilo de mensajes" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Conversaci\u00f3n no encontrada.\",\n \"errors\": null\n}", "name": "No encontrada" } ] }, { "name": "Responder en una conversaci\u00f3n de soporte", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support\/conversations\/:id\/reply", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support\/conversations\/:id\/reply", "variable": [ { "id": "id", "key": "id", "value": "019d867d-0001-7288-8ece-fd64da756001", "description": "UUID de la conversaci\u00f3n." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"message\":\"Listo, el cliente lo encontr\u00f3 en spam. Muchas gracias.\"}" }, "description": "A\u00f1ade un nuevo mensaje del cliente al hilo de una conversaci\u00f3n\nexistente. Si la conversaci\u00f3n estaba resuelta o cerrada, se **reabre**\nautom\u00e1ticamente (`status` vuelve a `open`) y se notifica al equipo.\n\nDevuelve la conversaci\u00f3n con el hilo completo de mensajes actualizado.\n\n**L\u00edmite:** aplica el mismo l\u00edmite de **un mensaje por hora** que al\nabrir una conversaci\u00f3n. Si el \u00faltimo mensaje del cliente tiene menos\nde una hora y el equipo a\u00fan no respondi\u00f3, la API responde **HTTP 429**\ncon el tiempo restante." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"subject\": \"No me llega el correo al cliente\",\n \"status\": \"open\",\n \"priority\": \"normal\",\n \"unread_for_client\": false,\n \"messages_count\": 3,\n \"last_message_at\": \"2026-06-23T11:30:00-06:00\",\n \"created_at\": \"2026-06-23T10:00:00-06:00\",\n \"client_can_write\": false,\n \"cooldown_seconds\": 3600,\n \"messages\": [\n {\n \"id\": \"019d867d-0004-7288-8ece-fd64da756004\",\n \"sender_type\": \"client\",\n \"body\": \"Listo, el cliente lo encontr\u00f3 en spam. Muchas gracias.\",\n \"created_at\": \"2026-06-23T11:30:00-06:00\"\n }\n ]\n },\n \"message\": \"Mensaje enviado.\",\n \"errors\": null\n}", "name": "Mensaje enviado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Conversaci\u00f3n no encontrada.\",\n \"errors\": null\n}", "name": "No encontrada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"message\": [\"El campo message es obligatorio.\"]}\n}", "name": "Mensaje requerido" }, { "header": [], "code": 429, "body": "{\n \"success\": false,\n \"data\": {\"cooldown_seconds\": 1800},\n \"message\": \"Solo puedes enviar un mensaje de soporte cada hora. Podr\u00e1s escribir de nuevo en 30 min, o cuando el equipo responda.\",\n \"errors\": null\n}", "name": "L\u00edmite de un mensaje por hora" } ] } ] }, { "name": "Soporte Prioritario", "description": "", "item": [ { "name": "Consultar el estado del soporte prioritario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support-tier", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support-tier" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el tier de soporte actual del contribuyente, si tiene una\nsuscripci\u00f3n recurrente activa, los precios vigentes de cada tier y la\ndisponibilidad de cada uno para contrataci\u00f3n en l\u00ednea.\n\nLos precios provienen de la configuraci\u00f3n del sistema y est\u00e1n\nexpresados en d\u00f3lares estadounidenses (USD). La disponibilidad\ndepende de que exista un plan de pasarela (Tilopay) configurado para\nel addon correspondiente con ciclo mensual." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"current_tier\": \"standard\",\n \"has_subscription\": false,\n \"premium_usd\": 500,\n \"premium_247_usd\": 2400,\n \"premium_available\": true,\n \"premium_247_available\": true\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Estado del soporte" } ] }, { "name": "Contratar soporte prioritario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support-tier\/subscribe", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support-tier\/subscribe" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"tier\":\"premium\"}" }, "description": "Inicia la suscripci\u00f3n recurrente del tier elegido y devuelve una\n**URL de redirecci\u00f3n** a la pasarela Tilopay, donde el contribuyente\nregistra su medio de pago para el cobro mensual.\n\nEl tier solo se activa de forma efectiva cuando la pasarela confirma\nel registro mediante sus webhooks recurrentes | esta llamada solo\ninicia el proceso.\n\n**Requisitos:**\n\n- El tier solicitado (`premium` o `premium_247`) debe estar\n **disponible** para contrataci\u00f3n en l\u00ednea (vea `premium_available`\n y `premium_247_available` en `GET \/support-tier`). Si no hay plan de\n pasarela configurado, responde **HTTP 409**.\n- El contribuyente debe tener al menos un **correo** en su perfil. Si\n no lo tiene, responde **HTTP 422**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"redirect_url\": \"https:\/\/app.tilopay.com\/recurrent\/register\/abc123\"\n },\n \"message\": \"Redirigiendo a la pasarela de pago.\",\n \"errors\": null\n}", "name": "Redirecci\u00f3n a la pasarela" }, { "header": [], "code": 409, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"El soporte prioritario a\u00fan no est\u00e1 disponible para contratar en l\u00ednea. Escr\u00edbenos y lo activamos.\",\n \"errors\": null\n}", "name": "Tier no disponible para contratar en l\u00ednea" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Necesitas un correo en tu perfil para contratar el soporte.\",\n \"errors\": null\n}", "name": "Sin correo en el perfil" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"tier\": [\"El tier seleccionado no es v\u00e1lido.\"]}\n}", "name": "Tier inv\u00e1lido" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo iniciar la suscripci\u00f3n. Intenta de nuevo en unos minutos.\",\n \"errors\": null\n}", "name": "Error al iniciar la suscripci\u00f3n en la pasarela" } ] }, { "name": "Cancelar soporte prioritario", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/support-tier\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/support-tier\/cancel" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Cancela la suscripci\u00f3n recurrente de soporte: elimina el suscriptor en\nla pasarela Tilopay y devuelve al contribuyente al tier `standard`,\nlimpiando su identificador de suscripci\u00f3n.\n\nSi el contribuyente **no tiene** una suscripci\u00f3n de soporte activa,\nresponde **HTTP 404**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"Soporte prioritario cancelado.\",\n \"errors\": null\n}", "name": "Soporte cancelado" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No tienes una suscripci\u00f3n de soporte activa para cancelar.\",\n \"errors\": null\n}", "name": "Sin suscripci\u00f3n activa" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo cancelar la suscripci\u00f3n. Intenta de nuevo.\",\n \"errors\": null\n}", "name": "Error al cancelar en la pasarela" } ] } ] }, { "name": "Onboarding", "description": "", "item": [ { "name": "Estado del onboarding del contribuyente", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/onboarding", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/onboarding" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve un resumen del onboarding del contribuyente autenticado: sus\ncr\u00e9ditos disponibles (gratuito anual + comprados), si puede autoagendar\nen este momento, el precio vigente de la hora y la pr\u00f3xima cita futura\nagendada (si existe).\n\nEl campo `can_schedule` es `true` solo cuando hay al menos un cr\u00e9dito\ndisponible **y** hay agentes activos en la agenda. \u00daselo para habilitar\no deshabilitar el bot\u00f3n de agendar en el portal.\n\nEl bloque `appointment` es `null` cuando no hay una cita de onboarding o\npagada futura con estado agendado; de lo contrario trae los datos de la\npr\u00f3xima sesi\u00f3n." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"credits\": {\"free\": 1, \"purchased\": 0, \"total\": 1},\n \"can_schedule\": true,\n \"price_usd\": 100,\n \"appointment\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"starts_at\": \"2026-07-01T09:00:00-06:00\",\n \"ends_at\": \"2026-07-01T09:50:00-06:00\",\n \"agent_name\": \"Ana Soporte\",\n \"meeting_url\": \"https:\/\/meet.google.com\/abc-defg-hij\",\n \"status\": \"scheduled\"\n }\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Con cr\u00e9dito y cita agendada" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"credits\": {\"free\": 0, \"purchased\": 0, \"total\": 0},\n \"can_schedule\": false,\n \"price_usd\": 100,\n \"appointment\": null\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Sin cr\u00e9ditos ni cita" } ] }, { "name": "Huecos disponibles para autoagendar", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/onboarding\/slots", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/onboarding\/slots" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve los horarios libres en los que el contribuyente puede agendar\nsu sesi\u00f3n de onboarding, calculados a partir de las agendas de los\nagentes activos. La ventana de b\u00fasqueda va desde ahora hasta **120\nd\u00edas** hacia adelante y respeta la antelaci\u00f3n m\u00ednima configurada.\n\nPor privacidad, la respuesta **no incluye el agente** de cada hueco;\nsolo el inicio y fin del horario. El agente se asigna internamente al\nconfirmar la cita en `POST \/onboarding\/appointments`.\n\nUse el valor `starts_at` de un hueco tal cual al agendar." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"slots\": [\n {\"starts_at\": \"2026-07-01T09:00:00-06:00\", \"ends_at\": \"2026-07-01T09:50:00-06:00\"},\n {\"starts_at\": \"2026-07-01T10:00:00-06:00\", \"ends_at\": \"2026-07-01T10:50:00-06:00\"}\n ]\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Huecos disponibles" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\"slots\": []},\n \"message\": \"\",\n \"errors\": null\n}", "name": "Sin huecos disponibles" } ] }, { "name": "Agendar la sesi\u00f3n de onboarding", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/onboarding\/appointments", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/onboarding\/appointments" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"starts_at\":\"2026-07-01T09:00:00-06:00\"}" }, "description": "Reserva un hueco para la sesi\u00f3n de onboarding y **consume 1 cr\u00e9dito**\ndisponible (se usa primero el cr\u00e9dito gratuito anual; si no hay, se usa\nuno comprado). El `starts_at` enviado debe coincidir exactamente con un\nhueco devuelto por `GET \/onboarding\/slots`.\n\nAntes de crear la cita, el sistema **reconfirma la disponibilidad** del\nhorario contra la agenda actual. Si el hueco ya fue tomado o el agente\ntiene un conflicto, responde **HTTP 422** y debe elegir otro horario.\nSi no tiene cr\u00e9ditos disponibles, tambi\u00e9n responde **422**.\n\nAl agendar correctamente se crea el evento (y enlace de Google Meet, si\nla integraci\u00f3n est\u00e1 activa) y se env\u00eda un correo de confirmaci\u00f3n al\ncontribuyente cuando tiene un email registrado." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-0001-7288-8ece-fd64da756001\",\n \"starts_at\": \"2026-07-01T09:00:00-06:00\",\n \"ends_at\": \"2026-07-01T09:50:00-06:00\",\n \"agent_name\": \"Ana Soporte\",\n \"meeting_url\": \"https:\/\/meet.google.com\/abc-defg-hij\",\n \"status\": \"scheduled\"\n },\n \"message\": \"Cita de onboarding agendada.\",\n \"errors\": null\n}", "name": "Cita agendada" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"credit\": [\"No tienes cr\u00e9ditos de onboarding disponibles.\"]}\n}", "name": "Sin cr\u00e9ditos disponibles" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"starts_at\": [\"Ese horario ya no est\u00e1 disponible. Elige otro.\"]}\n}", "name": "Horario ya no disponible" } ] }, { "name": "Comprar una hora de onboarding", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/onboarding\/purchase", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/onboarding\/purchase" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Inicia el checkout de Tilopay para comprar **1 hora de onboarding** a la\ntarifa vigente (USD). Disponible para todos los planes. Devuelve la URL\nde redirecci\u00f3n a la pasarela de pago y el n\u00famero de orden.\n\n> **Importante:** el cr\u00e9dito **no se otorga en este endpoint**. Solo se\n> inicia el cobro y se registra un pago en estado pendiente. El cr\u00e9dito\n> `purchased` se crea cuando el pago se confirma mediante el retorno\n> firmado de Tilopay (procesado por el webhook de retorno).\n\nSi la pasarela falla al iniciar el checkout, responde **HTTP 502**." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"redirect_url\": \"https:\/\/app.tilopay.com\/checkout\/abc123\",\n \"order\": \"TPAY-0001\"\n },\n \"message\": \"Redirigiendo a la pasarela de pago.\",\n \"errors\": null\n}", "name": "Checkout iniciado" }, { "header": [], "code": 502, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se pudo iniciar el pago con Tilopay. Intente de nuevo en unos minutos.\",\n \"errors\": null\n}", "name": "Pasarela no disponible" } ] } ] }, { "name": "Token API", "description": "", "item": [ { "name": "Consultar metadatos del token API de integraci\u00f3n", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/tokens\/current", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/tokens\/current" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve informaci\u00f3n del token API actualmente activo del contribuyente\n(fecha de creaci\u00f3n, \u00faltimo uso, permisos) **sin exponer el valor del\ntoken**. Si a\u00fan no ha generado un token API, retorna `data: null`.\n\n\u00datil para:\n\n- Verificar en el portal cu\u00e1ndo fue el \u00faltimo uso del token (si\n lleva mucho sin usarse, quiz\u00e1 la integraci\u00f3n est\u00e9 ca\u00edda).\n- Detectar si ya existe un token antes de regenerar.\n\nRecuerde: este endpoint solo muestra **metadatos**. El valor del\ntoken solo se devuelve una vez, en la respuesta de\n`POST \/public\/tokens`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"name\": \"api-integration\",\n \"created_at\": \"2026-04-01T10:00:00-06:00\",\n \"last_used_at\": \"2026-04-16T14:30:00-06:00\",\n \"abilities\": [\"*\"],\n \"token_hint\": \"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\"\n },\n \"message\": \"\",\n \"errors\": null\n}", "name": "Token API existente" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": null,\n \"message\": \"No tiene un token API generado a\u00fan.\",\n \"errors\": null\n}", "name": "Sin token API generado a\u00fan" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Unauthenticated.\",\n \"errors\": null\n}", "name": "No autenticado" } ] }, { "name": "Generar o regenerar el token API Bearer", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/tokens", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/tokens" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Crea un nuevo token API permanente para uso desde sistemas externos\n(POS, ERP, e-commerce, CRM). Si el contribuyente ya ten\u00eda un token\nAPI, el anterior **se revoca autom\u00e1ticamente** al crear el nuevo.\n\n> **Importante:** el valor del token se devuelve en texto plano\n> **una \u00fanica vez** en esta respuesta, en el campo `bearer_token`.\n> Gu\u00e1rdelo inmediatamente | no hay forma de recuperarlo despu\u00e9s.\n> Para saber si ya existe un token (sin exponerlo), use\n> `GET \/public\/tokens\/current`.\n\n**Aislamiento de sesiones:** regenerar el token API **no afecta** a\nsu sesi\u00f3n actual del portal. Puede regenerar el token sin cerrar\nla ventana del navegador.\n\n**Impacto en sistemas productivos:** al regenerar, el token anterior\ndeja de funcionar inmediatamente. Todas sus integraciones que\nusaban el token viejo empezar\u00e1n a recibir HTTP 401 hasta que\nactualice la configuraci\u00f3n con el nuevo token." }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"bearer_token\": \"3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0\",\n \"created_at\": \"2026-04-16T15:00:00-06:00\"\n },\n \"message\": \"Token generado. Gu\u00e1rdelo ahora | no se mostrar\u00e1 nuevamente.\",\n \"errors\": null\n}", "name": "Token generado exitosamente" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Unauthenticated.\",\n \"errors\": null\n}", "name": "No autenticado" } ] } ] }, { "name": "Solicitud de Upgrade", "description": "", "item": [ { "name": "Solicitar upgrade al plan Integrador.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/upgrade-request", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/upgrade-request" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Envia un correo al usuario con las instrucciones de pago y notifica\nal equipo de Almendro para procesar la solicitud. No requiere\ncuerpo en el request | la identidad del contribuyente se obtiene\ndel token de autenticacion.\n\nSi el contribuyente ya tiene el plan Integrador activo, retorna 422.\n\nEste endpoint tiene rate limit de 1 solicitud por hora para evitar\nenvios duplicados." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"email_sent_to\": \"usuario@empresa.cr\"\n },\n \"message\": \"Solicitud enviada. Revis\u00e1 tu correo para las instrucciones de pago.\",\n \"errors\": null\n}", "name": "Solicitud enviada exitosamente" }, { "header": [], "code": 404, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"No se encontr\u00f3 un contribuyente asociado a esta cuenta.\",\n \"errors\": null\n}", "name": "Sin contribuyente asociado" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Tu cuenta ya tiene el plan Integrador activo.\",\n \"errors\": null\n}", "name": "Ya tiene plan Integrador" } ] } ] }, { "name": "Otros", "description": "", "item": [ { "name": "POST api\/v1\/public\/item-shares", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"to_contributor_id\":\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",\"item_ids\":[\"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\"],\"message\":\"m\"}" }, "description": "" }, "response": [] }, { "name": "GET api\/v1\/public\/item-shares\/sent", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/sent", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/sent" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "GET api\/v1\/public\/item-shares\/received", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/received", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/received" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "GET api\/v1\/public\/item-shares\/{id}", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/:id", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the item share." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "GET api\/v1\/public\/item-shares\/{id}\/accept-preview", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/:id\/accept-preview", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/:id\/accept-preview", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the item share." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/item-shares\/{id}\/accept", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/:id\/accept", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/:id\/accept", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the item share." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"lines\":[{\"line_id\":16,\"action\":\"architecto\",\"internal_code\":\"ngzmiyvdljnikhwa\"}]}" }, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/item-shares\/{id}\/reject", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/:id\/reject", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/:id\/reject", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the item share." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/item-shares\/{id}\/cancel", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/item-shares\/:id\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/item-shares\/:id\/cancel", "variable": [ { "id": "id", "key": "id", "value": "architecto", "description": "The ID of the item share." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Lista los contribuyentes cuyo buz\u00f3n puede ver\/operar el autenticado:\n\u00e9l mismo m\u00e1s los clientes sobre los que tiene un grant de certificado\nactivo. Alimenta el selector de contribuyente del buz\u00f3n y de la carga.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/accessible-contributors", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/accessible-contributors" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Estado de la recepci\u00f3n autom\u00e1tica de facturas por correo (F2).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/email-reception", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/email-reception" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "`enabled`: si los XML dirigidos a su c\u00e9dula que llegan a\nfacturas@almendro.cr se cargan solos a su buz\u00f3n. `quarantined`: cu\u00e1ntos\ncomprobantes esperan en cuarentena (72 horas) por tener la recepci\u00f3n\napagada; se cargan si la reactiva a tiempo." }, "response": [] }, { "name": "Enciende o apaga la recepci\u00f3n autom\u00e1tica de facturas por correo (F2).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/email-reception", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/email-reception" }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"enabled\":true}" }, "description": "Al APAGARLA, los comprobantes que lleguen dirigidos a su c\u00e9dula quedan\nen cuarentena 72 horas en lugar de cargarse (no consumen su pozo). Al\nENCENDERLA, lo que est\u00e9 en cuarentena vigente se carga autom\u00e1ticamente." }, "response": [] }, { "name": "PATCH api\/v1\/public\/inbox\/{key}\/annotation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/inbox\/:key\/annotation", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/inbox\/:key\/annotation", "variable": [ { "id": "key", "key": "key", "value": "56425593142326822820492192294472586671521743076933", "description": "" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"alias\":\"b\",\"notes\":\"n\"}" }, "description": "" }, "response": [] }, { "name": "\"No mostrar m\u00e1s\" | posponer un recordatorio de puesta a punto por 6 meses.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/reminders\/:type\/snooze", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/reminders\/:type\/snooze", "variable": [ { "id": "type", "key": "type", "value": "architecto", "description": "" } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Solo disponible para integradores que gestionan al menos un contribuyente\ncon certificado de producci\u00f3n vigente (facturan por sus clientes y no\nnecesitan su propio .p12\/perfil). Para el resto responde 422." }, "response": [] }, { "name": "Descarga el PDF de la factura (FE) asociada a un pago.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/payments\/:id\/pdf", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/payments\/:id\/pdf", "variable": [ { "id": "id", "key": "id", "value": "e507fb2b94-c9e62d073743f8140a658fd5f", "description": "The ID of the payment." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Descarga el XML firmado de la factura (FE) asociada a un pago.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/payments\/:id\/xml", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/payments\/:id\/xml", "variable": [ { "id": "id", "key": "id", "value": "e507fb2b94-c9e62d073743f8140a658fd5f", "description": "The ID of the payment." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "La FE la emite Almendro HACIA el contribuyente, as\u00ed que el voucher es del\nemisor; se autoriza por el PAGO (que s\u00ed es del contribuyente)." }, "response": [] }, { "name": "POST api\/v1\/public\/discount-codes\/validate", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/discount-codes\/validate", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/discount-codes\/validate" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"code\":\"b\",\"plan_code\":\"architecto\",\"billing_cycle\":\"architecto\"}" }, "description": "" }, "response": [] }, { "name": "Combinaciones plan\/ciclo que tienen una promoci\u00f3n activa para este\ncontribuyente. El checkout muestra el campo de descuento solo ah\u00ed.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/discount-codes\/availability", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/discount-codes\/availability" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Suscribirse \/ subir de plan COBRANDO la tarjeta tokenizada (server-to-server).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/subscribe-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/subscribe-tokenized" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"plan_code\":\"architecto\",\"billing_cycle\":\"architecto\",\"discount_code\":\"n\"}" }, "description": "Requiere tarjeta guardada (si no, el front manda primero a \"agregar tarjeta\").\nSi el contribuyente ya est\u00e1 en un plan de pago vigente del mismo ciclo, cobra\nsolo la **diferencia prorrateada** por lo que resta del per\u00edodo y MANTIENE la\nfecha de aniversario; si viene de Gratis\/sin plan, cobra el precio completo y\narranca el per\u00edodo desde hoy. Las renovaciones siguen con `subscription:charge-due`.\n\nSolo SUBIDAS: para bajar de plan se usa la baja programada (`downgrade`)." }, "response": [] }, { "name": "Sesi\u00f3n para el SDK V2 (alta de tarjeta embebida).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/card-session", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/card-session" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el token del SDK (`loginSdk`) y los par\u00e1metros para inicializar\n`Tilopay.InitTokenize()` en el frontend. El token de la tarjeta vuelve del\nlado cliente y se guarda con `saveCard()`. El email es el del contribuyente:\nel cobro posterior se hace con ese mismo par email + token." }, "response": [] }, { "name": "Guarda el token de la tarjeta tokenizada por el SDK contra el contribuyente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/save-card", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/save-card" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"token\":\"b\",\"last4\":\"ngzm\",\"brand\":\"iyvdljnikhwaykcm\"}" }, "description": "El email almacenado es el mismo que us\u00f3 cardSession() (Tilopay rutea el cobro\npor email + token)." }, "response": [] }, { "name": "Sesi\u00f3n de PAGO con el SDK (cobro \u00fanico que guarda la tarjeta, `Init({subscription:1})`).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/sdk-pay-session", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/sdk-pay-session" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"purpose\":\"architecto\",\"plan_code\":\"architecto\",\"billing_cycle\":\"architecto\",\"discount_code\":\"n\",\"beneficiary_contributor_id\":\"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\",\"tier_code\":\"miyvdl\"}" }, "description": "Se usa cuando el contribuyente NO tiene tarjeta guardada: el primer pago cobra\ny guarda la tarjeta en un solo cargo (modelo Uber). Crea un Payment pendiente\ncon la intenci\u00f3n (suscribirse o retenci\u00f3n) y devuelve los params del SDK." }, "response": [] }, { "name": "Confirma un pago hecho con el SDK: verifica con `consult`, guarda la tarjeta y\nejecuta la compra (activar plan o crear la extensi\u00f3n de retenci\u00f3n). No cobra de\nnuevo (el SDK ya cobr\u00f3).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/sdk-pay-confirm", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/sdk-pay-confirm" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"order\":\"b\",\"token\":\"n\",\"last4\":\"gzmi\",\"brand\":\"yvdljnikhwaykcmy\"}" }, "description": "" }, "response": [] }, { "name": "Elimina la tarjeta guardada. Intenta el `card-remove` en Tilopay (si el\ncomercio tuviera el permiso) y, pase o no, suelta el token de nuestro lado:\nsin token no se cobra m\u00e1s.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/subscription\/card", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/subscription\/card" }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Compra la hora de onboarding COBRANDO la tarjeta guardada (sin salir del\nportal). Mismo patr\u00f3n que la retenci\u00f3n tokenizada: chargeToken + cr\u00e9dito\ninmediato + FE. Sin tarjeta guardada responde 409 (el front abre el SDK).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/onboarding\/purchase-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/onboarding\/purchase-tokenized" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Inicia el checkout de la retenci\u00f3n para el contribuyente autenticado.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/retention-extension\/purchase", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/retention-extension\/purchase" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "El contribuyente cobra su propia retenci\u00f3n con la tarjeta guardada.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/retention-extension\/charge-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/retention-extension\/charge-tokenized" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Desactiva la auto-renovaci\u00f3n: la retenci\u00f3n sigue ACTIVA hasta el fin de su\nper\u00edodo y luego no se renueva (charge-due la omite).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/retention-extension\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/retention-extension\/cancel" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Reactiva la auto-renovaci\u00f3n de una retenci\u00f3n cancelada pero a\u00fan vigente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/retention-extension\/resume", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/retention-extension\/resume" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/api-access\/purchase", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/api-access\/purchase", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/api-access\/purchase" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/api-access\/charge-tokenized", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/api-access\/charge-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/api-access\/charge-tokenized" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Desactiva la auto-renovaci\u00f3n: el acceso sigue ACTIVO hasta el fin del\nper\u00edodo pagado y luego no se renueva (charge-due lo omite).", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/api-access\/cancel", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/api-access\/cancel" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Reactiva la auto-renovaci\u00f3n de un add-on cancelado pero a\u00fan vigente.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/api-access\/resume", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/api-access\/resume" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "GET \/distributor\/info", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/distributor\/info", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/distributor\/info" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Estado del programa para la secci\u00f3n de Mi Plan: inscripci\u00f3n, niveles\na la venta con el precio aplicable (reposici\u00f3n incluida si califica),\ny el resumen de pozos propios si ya es distribuidor." }, "response": [] }, { "name": "POST api\/v1\/public\/distributor\/purchase", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/distributor\/purchase", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/distributor\/purchase" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"tier_code\":\"bngzmi\"}" }, "description": "" }, "response": [] }, { "name": "POST api\/v1\/public\/distributor\/charge-tokenized", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/distributor\/charge-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/distributor\/charge-tokenized" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"tier_code\":\"bngzmi\"}" }, "description": "" }, "response": [] }, { "name": "GET api\/v1\/public\/managed-sales", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/managed-sales", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/managed-sales" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Registro PRIVADO de la venta del gestor (lo que \u00e9l cobra a su\ncliente): monto, moneda y modo de pago. El admin nunca lo ve.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/managed-sales\/:activationId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/managed-sales\/:activationId", "variable": [ { "id": "activationId", "key": "activationId", "value": "564", "description": "" } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"sale_amount\":1,\"sale_currency\":\"USD\",\"sale_payment_method\":\"architecto\"}" }, "description": "" }, "response": [] }, { "name": "Inicia el checkout de la retenci\u00f3n que un gestor paga para un cliente\ngestionado. El gestor autenticado paga; el cliente es el beneficiario.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/retention-extension", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/retention-extension", "variable": [ { "id": "id", "key": "id", "value": "e507fb2b94-c9e62d073743f8140a658fd5f", "description": "The ID of the my contributor." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] }, { "name": "Un gestor cobra la retenci\u00f3n de un cliente gestionado con SU tarjeta guardada.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/my-contributors\/:id\/retention-extension\/charge-tokenized", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/retention-extension\/charge-tokenized", "variable": [ { "id": "id", "key": "id", "value": "e507fb2b94-c9e62d073743f8140a658fd5f", "description": "The ID of the my contributor." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [] } ] }, { "name": "Perfil del contribuyente", "description": "", "item": [ { "name": "Entitlement del plan", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/public\/entitlement", "query": [], "raw": "{{baseUrl}}\/api\/v1\/public\/entitlement" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Devuelve el plan vigente del contribuyente autenticado con TODOS sus\nl\u00edmites resueltos (override por contribuyente > valor del plan;\n`null` = sin tope). Pensado para que integraciones (POS, canal\ne-commerce) lo cacheen y apliquen los l\u00edmites localmente." }, "response": [ { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": {\n \"plan\": { \"code\": \"professional\", \"name\": \"Profesional\", \"billing_mode\": \"annual_or_monthly\" },\n \"features\": [\"api_access\", \"receiver_module\", \"webhooks\"],\n \"limits\": {\n \"monthly_voucher_limit\": 500, \"max_users\": 5, \"max_clients\": 1500,\n \"max_items\": 3000, \"max_branches\": 5, \"max_terminals_per_branch\": 5,\n \"max_pos_items\": 15000, \"max_pos_cashiers_per_terminal\": 10,\n \"max_channel_pages\": 15\n }\n },\n \"message\": \"Entitlement del plan (l\u00edmites resueltos con overrides).\", \"errors\": null\n}", "name": "Entitlement resuelto" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }