{ "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": "81ff3494-c42c-41b7-a8fb-47c4b3e397c4", "description": "Almendro Factura Electr\u00f3nica \u2014 API REST v1 \u2014 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": "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-c001-7288-8ece-fd64da756c01", "description": "UUID del cliente gestionado cuyos comprobantes se consultan. Solo para plan Integrador con relaci\u00f3n managed activa. Sin este filtro, retorna comprobantes propios. validation.uuid.", "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&environment=production¤cy_code=CRC&contributor_id=019d867d-c001-7288-8ece-fd64da756c01&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": "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": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"voucher_type\":\"01\",\"situation\":\"1\",\"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\",\"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\":\"b\",\"emails\":[\"architecto\"],\"province\":2,\"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\",\"monto\":\"1300.00000\",\"monto_exportacion\":50,\"exoneracion\":{\"tipoDocumento\":\"kc\",\"numeroDocumento\":\"m\",\"nombreInstitucion\":\"y\",\"fechaEmision\":\"2026-04-29T10:12:07\",\"tarifaExonerada\":72,\"montoExoneracion\":61}}],\"impuesto_neto\":\"1300.00000\",\"total_line_amount\":\"11300.00000\",\"medicine_registration\":\"p\",\"pharma_form_code\":\"564\",\"commercial_codes\":[{\"tipo\":2,\"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** \u2014 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) \u2014 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": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Ha alcanzado el l\u00edmite mensual de comprobantes de su plan.\",\n \"errors\": {\"plan\": [\"Actualice a un plan superior o active overage para continuar emitiendo.\"]}\n}", "name": "Cupo mensual agotado" } ] }, { "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 \u2014 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": "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) \u2014 ...\",\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": "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 \u2014 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 \u2014 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 \u2014 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": "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_today\": 12,\n \"emails_limit\": 75,\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_today\": 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\": \"3101000000\",\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_daily_emails\": 75,\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\":\"3101000000\",\"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 \u2014 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\": \"3101000000\",\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": "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`) \u2014 \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 {\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=EMPRESA EJEMPLO S.A., serialNumber=3101000001\",\n \"certificate_serial\": \"0A1B2C3D4E5F\",\n \"created_at\": \"2026-04-09T10:00:00-06:00\"\n },\n {\n \"id\": \"019d867d-2222-7288-8ece-fd64da756002\",\n \"environment\": \"sandbox\",\n \"is_active\": false,\n \"is_expired\": true,\n \"days_remaining\": 0,\n \"valid_from\": \"2022-01-01T00:00:00-06:00\",\n \"valid_until\": \"2024-01-01T00:00:00-06:00\",\n \"certificate_subject\": \"CN=EMPRESA EJEMPLO S.A., serialNumber=3101000001\",\n \"certificate_serial\": \"AA11BB22CC33\",\n \"created_at\": \"2024-01-10T08:00:00-06:00\"\n }\n ],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Listado con activo e hist\u00f3rico" }, { "header": [], "code": 200, "body": "{\n \"success\": true,\n \"data\": [],\n \"message\": \"\",\n \"errors\": null\n}", "name": "Sin certificados cargados" }, { "header": [], "code": 401, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Unauthenticated.\",\n \"errors\": null\n}", "name": "No autenticado" } ] }, { "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": "MiContrasenaDelP12", "type": "text", "description": "Contrase\u00f1a que protege el archivo `.p12` (la que usted defini\u00f3 al generarlo)." }, { "key": "hacienda_pin", "value": "1234", "type": "text", "description": "PIN asignado por Hacienda al registrarse como emisor en ATV (normalmente 4 d\u00edgitos)." }, { "key": "environment", "value": "sandbox", "type": "text", "description": "Ambiente al que se asigna este certificado. Valores: `sandbox` o `production`." }, { "key": "p12_file", "src": [], "type": "file" } ] }, "description": "Sube un archivo `.p12` (PKCS#12) con su contrase\u00f1a y el PIN de\nHacienda, y lo activa como certificado para firmar comprobantes\nen el ambiente indicado.\n\nEste request **debe enviarse como `multipart\/form-data`** (no JSON),\nporque incluye un archivo binario.\n\n**Proceso interno al subir:**\n\n1. Se valida que el archivo sea un `.p12` leg\u00edtimo y que la\n contrase\u00f1a lo abra correctamente.\n2. Se extraen los metadatos del certificado X.509 (vigencia,\n subject, n\u00famero de serie).\n3. Si ya exist\u00eda un certificado activo del mismo ambiente, se\n **desactiva autom\u00e1ticamente** (queda en el hist\u00f3rico).\n4. El nuevo certificado queda activo y listo para firmar.\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=contrasena-del-p12\" \\\n -F \"hacienda_pin=1234\" \\\n -F \"environment=sandbox\"\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('p12_file', fs.createReadStream('certificado.p12'))\nform.append('p12_password', 'contrasena-del-p12')\nform.append('hacienda_pin', '1234')\nform.append('environment', 'sandbox')\n\nconst response = await axios.post(\n 'https:\/\/api.almendro.cr\/api\/v1\/public\/certificates',\n form,\n { headers: { ...form.getHeaders(), Authorization: `Bearer ${token}` } },\n)\n```" }, "response": [ { "header": [], "code": 201, "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"019d867d-3333-7288-8ece-fd64da756003\",\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=EMPRESA EJEMPLO S.A., serialNumber=3101000001\",\n \"certificate_serial\": \"0A1B2C3D4E5F\",\n \"created_at\": \"2026-04-16T10:00:00-06:00\"\n },\n \"message\": \"Certificado registrado y activado correctamente.\",\n \"errors\": null\n}", "name": "Certificado registrado y activado" }, { "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 incorrecta del .p12" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"p12_file\": [\"El archivo debe tener extensi\u00f3n .p12 o .pfx.\"]}\n}", "name": "Archivo no es un .p12 v\u00e1lido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"environment\": [\"El ambiente seleccionado no es v\u00e1lido. Use sandbox o production.\"]}\n}", "name": "Ambiente inv\u00e1lido" }, { "header": [], "code": 422, "body": "{\n \"success\": false,\n \"data\": null,\n \"message\": \"Los datos proporcionados no son v\u00e1lidos.\",\n \"errors\": {\"hacienda_pin\": [\"El PIN de Hacienda es obligatorio.\"]}\n}", "name": "Falta el PIN de Hacienda" } ] }, { "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 nuevo certificado pero quiere dejar el ambiente\n> sin firma temporalmente (caso raro).\n> - Migraci\u00f3n de un contribuyente a otra plataforma.\n\nNo necesita desactivar el certificado anterior antes de subir uno\nnuevo \u2014 el `POST \/certificates` ya lo hace autom\u00e1ticamente al\nregistrar el nuevo." }, "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** \u2014 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_title\": 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_title\": 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_title\":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 \u2014 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_title\": 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\"},\"fonts\":{\"family\":\"Helvetica\",\"size_header\":2,\"size_body\":9,\"size_footer\":3,\"size_title\":14},\"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\":false,\"show_payment_methods\":true,\"show_references\":false,\"show_other_charges\":false},\"qr\":{\"size\":100,\"position\":\"bottom-right\"},\"margins\":{\"top\":22,\"right\":24,\"bottom\":18,\"left\":8},\"style\":\"modern\",\"footer_text\":\"m\"}}" }, "description": "Admite **actualizaci\u00f3n parcial** \u2014 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_title\": 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** \u2014 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 \u2014 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} \u2014 {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} \u2014 {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} \u2014 {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** \u2014 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 \u2014 actualizado\",\"is_active\":true}" }, "description": "Admite **actualizaci\u00f3n parcial** \u2014 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 \u2014 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 \u2014 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** \u2014 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": "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&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_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** \u2014 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** \u2014 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 \u2014 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** \u2014 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": "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` \u2014 activo, sin fallos recientes.\n- `degraded` \u2014 activo pero con fallos consecutivos (entre 1 y 9).\n- `disabled` \u2014 desactivado autom\u00e1ticamente tras 10 fallos consecutivos.\n- `inactive` \u2014 desactivado manualmente.\n- `never_used` \u2014 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\/almendrofec\",\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\\\/almendrofec\",\"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 \u2014 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:\/\/` \u2014 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 \u2014 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\/almendrofec\",\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 \u2014 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\/almendrofec\",\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 \u2014 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` \u2014 nueva URL HTTPS del receptor.\n- `events` \u2014 nueva lista de eventos a suscribir.\n- `description` \u2014 descripci\u00f3n opcional.\n- `is_active` \u2014 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 \u2014 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 \u2014 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` \u2014 el endpoint respondi\u00f3 con HTTP 2xx.\n- `failed` \u2014 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": "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. validation.min validation.max.", "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 D-104\n(IVA mensual) y D-101 (renta anual).\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": "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": "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 \u2014 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 \u2014 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 \u2014 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": "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\": \"3101000000\",\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": "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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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}" }, "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** \u2014 solo el cliente puede editarlos\ndesde su propio portal o API (Art. 16 Reglamento).\n\n**Campo editable:**\n\n- `default_pdf_template_id` \u2014 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) \u2014 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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 \u2014 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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 } ], "raw": "{{baseUrl}}\/api\/v1\/public\/my-contributors\/:id\/sequences?include_all_terminals=", "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.),\nAlmendroFEC 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 \u2014 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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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\",\"current_sequence\":8475,\"reason\":\"Migraci\u00f3n desde Alegra \u2014 \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 AlmendroFEC 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 \u2014 \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 AlmendroFEC\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": "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 \u2014 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 \u2014 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": "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-50). 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-50). 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-50). 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-50). 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 \u2014 \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\": \"Este endpoint solo est\u00e1 disponible para el plan Integrador. Actualice su plan para gestionar 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": "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 \u2014 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 \u2014 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 AlmendroFEC para procesar la solicitud. No requiere\ncuerpo en el request \u2014 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" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }