{
  "openapi": "3.0.3",
  "info": {
    "title": "API de facturación electrónica e-FacturaCR",
    "version": "v1",
    "description": "Emite comprobantes electrónicos de Costa Rica (versión 4.4 de Hacienda) desde otro sistema."
  },
  "servers": [
    {
      "url": "https://e-facturacr.com/api/v1"
    }
  ],
  "security": [
    {
      "llave": []
    }
  ],
  "paths": {
    "/documentos": {
      "post": {
        "operationId": "emitir",
        "summary": "Emitir un documento",
        "description": "Crea la factura, el tiquete, la nota o la factura de compra y lo envía a Hacienda.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentoNuevo"
              },
              "examples": {
                "factura": {
                  "value": {
                    "tipo": "FE",
                    "referencia": "INV/2026/00412",
                    "condicion_venta": "01",
                    "medio_pago": "04",
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "observaciones": "Entregar en bodega 2"
                  }
                },
                "factura_completa": {
                  "value": {
                    "tipo": "FE",
                    "referencia": "INV/2026/00413",
                    "condicion_venta": "01",
                    "medios_pago": [
                      {
                        "codigo": "01",
                        "monto": 50000
                      },
                      {
                        "codigo": "02",
                        "monto": 73100
                      }
                    ],
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example",
                      "actividad": "410001"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 10,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08",
                        "codigo": "CEM-50",
                        "codigo_tipo": "01",
                        "tipo_transaccion": "01",
                        "descuento": 5000,
                        "descuento_codigo": "04",
                        "descuento_naturaleza": "Descuento por volumen de la obra"
                      },
                      {
                        "cabys": "8314100000000",
                        "detalle": "Asesoría técnica en obra",
                        "cantidad": 2,
                        "unidad": "h",
                        "precio_unitario": 20000,
                        "tarifa_iva": "08",
                        "exoneracion": {
                          "tipo_documento": "03",
                          "numero": "LEY-9635-2026-000123",
                          "articulo": 8,
                          "inciso": 1,
                          "institucion": "01",
                          "fecha": "2026-01-15",
                          "tarifa": 13
                        }
                      }
                    ],
                    "otros_cargos": [
                      {
                        "tipo": "06",
                        "detalle": "Impuesto de servicio",
                        "monto": 4000,
                        "porcentaje": 10
                      }
                    ],
                    "otros_datos": [
                      {
                        "codigo": "OrdenCompra",
                        "texto": "OC-2026-0098"
                      }
                    ],
                    "observaciones": "Entregar en bodega 2"
                  }
                },
                "exportacion": {
                  "value": {
                    "tipo": "FEE",
                    "referencia": "EXP/2026/00027",
                    "condicion_venta": "02",
                    "plazo_credito": 30,
                    "medio_pago": "04",
                    "moneda": "USD",
                    "receptor": {
                      "tipo_identificacion": "05",
                      "identificacion": "US841234567",
                      "nombre": "Pacific Trading LLC",
                      "correo": "ap@pacifictrading.example",
                      "direccion": "1200 Harbor Blvd, Suite 400, Long Beach, CA 90802, Estados Unidos"
                    },
                    "lineas": [
                      {
                        "cabys": "8314100000000",
                        "detalle": "Servicios de desarrollo de software, octubre de 2026",
                        "cantidad": 1,
                        "unidad": "Sp",
                        "precio_unitario": 4500
                      }
                    ]
                  }
                },
                "nota_credito": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00031",
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "referencia": "INV/2026/00412",
                      "codigo": "01",
                      "razon": "Anula la factura por error en el pedido"
                    }
                  }
                },
                "nota_de_fuera": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00032",
                    "moneda": "USD",
                    "tipo_cambio": 448.37,
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "tipo_documento": "01",
                      "numero": "50601102600310198765400100001010000000045123456789",
                      "fecha": "2026-10-01",
                      "codigo": "02",
                      "razon": "Corrige el monto facturado"
                    }
                  }
                },
                "nota_financiera": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00033",
                    "lineas": [
                      {
                        "detalle": "Descuento por pronto pago",
                        "cantidad": 1,
                        "precio_unitario": 5000
                      }
                    ],
                    "documento_referencia": {
                      "referencia": "INV/2026/00412",
                      "codigo": "09",
                      "razon": "Descuento por pronto pago"
                    }
                  }
                },
                "factura_compra": {
                  "value": {
                    "tipo": "FEC",
                    "referencia": "COMPRA/2026/00007",
                    "condicion_venta": "01",
                    "medio_pago": "01",
                    "proveedor": {
                      "tipo_identificacion": "01",
                      "identificacion": "205550123",
                      "nombre": "María Fernández Rojas",
                      "correo": "maria.fernandez@correo.example",
                      "telefono": "88887777",
                      "provincia": "2",
                      "canton": "01",
                      "distrito": "01",
                      "otras_senas": "200 metros norte de la iglesia, casa esquinera"
                    },
                    "lineas": [
                      {
                        "cabys": "8314100000000",
                        "detalle": "Mantenimiento del jardín, noviembre de 2026",
                        "cantidad": 1,
                        "unidad": "Os",
                        "precio_unitario": 60000,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "tipo_documento": "14",
                      "numero": "RECIBO-0087",
                      "fecha": "2026-11-10",
                      "codigo": "04",
                      "razon": "Compra a un contribuyente del régimen simplificado"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "El documento.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Documento"
                },
                "example": {
                  "id": "doc_8Jq2mXw4Tz1RbYc6",
                  "referencia": "INV/2026/00412",
                  "tipo": "FE",
                  "consecutivo": "00100003010000002318",
                  "clave": "50613112600310198765400100003010000002318158241973",
                  "estado": "procesando",
                  "mensaje_hacienda": "",
                  "fecha_emision": "2026-11-13T10:42:07-06:00",
                  "moneda": "CRC",
                  "tipo_cambio": 1,
                  "subtotal": 150000.0,
                  "descuento": 0.0,
                  "impuesto": 19500.0,
                  "otros_cargos": 0.0,
                  "total": 169500.0,
                  "receptor": {
                    "identificacion": "3101456789",
                    "nombre": "Constructora Los Robles S.A."
                  },
                  "ambiente": "pruebas",
                  "repetida": false,
                  "archivos": {
                    "xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
                    "respuesta": null,
                    "pdf": null
                  }
                }
              }
            }
          },
          "200": {
            "description": "La referencia ya existía: es el mismo documento.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Documento"
                },
                "example": {
                  "id": "doc_8Jq2mXw4Tz1RbYc6",
                  "referencia": "INV/2026/00412",
                  "tipo": "FE",
                  "consecutivo": "00100003010000002318",
                  "clave": "50613112600310198765400100003010000002318158241973",
                  "estado": "procesando",
                  "mensaje_hacienda": "",
                  "fecha_emision": "2026-11-13T10:42:07-06:00",
                  "moneda": "CRC",
                  "tipo_cambio": 1,
                  "subtotal": 150000.0,
                  "descuento": 0.0,
                  "impuesto": 19500.0,
                  "otros_cargos": 0.0,
                  "total": 169500.0,
                  "receptor": {
                    "identificacion": "3101456789",
                    "nombre": "Constructora Los Robles S.A."
                  },
                  "ambiente": "pruebas",
                  "repetida": false,
                  "archivos": {
                    "xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
                    "respuesta": null,
                    "pdf": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "solicitud_invalida: El cuerpo no es un JSON válido o pasa del tamaño permitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sin_permiso: La llave es de solo consulta y no puede emitir. produccion_no_habilitada: El perfil todavía no está habilitado para producción. tope_adicionales: El ciclo llegó a su tope de documentos adicionales. Pida otro tope en el perfil o espere al ciclo siguiente. perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "emisor_incompleto: Al emisor le falta configuración. El mensaje dice qué. referencia_repetida: Esa referencia ya existe con otros datos. Con los mismos datos se devuelve el documento que ya existía.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validacion: Un dato no pasa la validación. El mensaje dice cuál y en qué línea. No se gasta consecutivo. no_generado: El comprobante no se pudo armar con esos datos y quedó con estado «error». Su consecutivo no se reutiliza. Corrija y envíe de nuevo con la misma referencia.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tope_diario: La llave llegó a su tope de documentos del día. demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "cuenta_morosa: La factura del plan está vencida y el API dejó de emitir. Vuelve a emitir en cuanto se registre el pago. Consultar y descargar siguen funcionando.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "api_en_pausa: El API está en pausa y no emite por el momento. Consultar y descargar siguen funcionando.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listar",
        "summary": "Listar documentos",
        "description": "Los documentos del emisor, del más reciente al más antiguo. Se filtra por referencia, estado, tipo y fechas.",
        "parameters": [
          {
            "name": "referencia",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "La referencia exacta de su sistema."
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "procesando, aceptado, rechazado o error."
          },
          {
            "name": "tipo",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "FE, TE, FEE, NC, ND o FEC."
          },
          {
            "name": "desde",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Fecha de emisión desde, AAAA-MM-DD."
          },
          {
            "name": "hasta",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Fecha de emisión hasta, AAAA-MM-DD."
          },
          {
            "name": "pagina",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Número de página, desde 1."
          },
          {
            "name": "por_pagina",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Documentos por página, hasta 100."
          }
        ],
        "responses": {
          "200": {
            "description": "La página de documentos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documentos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Documento"
                      }
                    },
                    "pagina": {
                      "type": "integer"
                    },
                    "por_pagina": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validacion: Un dato no pasa la validación. El mensaje dice cuál y en qué línea. No se gasta consecutivo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documentos/validar": {
      "post": {
        "operationId": "validar",
        "summary": "Revisar sin emitir",
        "description": "Revisa el documento como lo haría la emisión y responde si está bien, con sus totales. No guarda nada, no gasta consecutivo y no envía a Hacienda.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentoNuevo"
              },
              "examples": {
                "factura": {
                  "value": {
                    "tipo": "FE",
                    "referencia": "INV/2026/00412",
                    "condicion_venta": "01",
                    "medio_pago": "04",
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "observaciones": "Entregar en bodega 2"
                  }
                },
                "factura_completa": {
                  "value": {
                    "tipo": "FE",
                    "referencia": "INV/2026/00413",
                    "condicion_venta": "01",
                    "medios_pago": [
                      {
                        "codigo": "01",
                        "monto": 50000
                      },
                      {
                        "codigo": "02",
                        "monto": 73100
                      }
                    ],
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example",
                      "actividad": "410001"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 10,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08",
                        "codigo": "CEM-50",
                        "codigo_tipo": "01",
                        "tipo_transaccion": "01",
                        "descuento": 5000,
                        "descuento_codigo": "04",
                        "descuento_naturaleza": "Descuento por volumen de la obra"
                      },
                      {
                        "cabys": "8314100000000",
                        "detalle": "Asesoría técnica en obra",
                        "cantidad": 2,
                        "unidad": "h",
                        "precio_unitario": 20000,
                        "tarifa_iva": "08",
                        "exoneracion": {
                          "tipo_documento": "03",
                          "numero": "LEY-9635-2026-000123",
                          "articulo": 8,
                          "inciso": 1,
                          "institucion": "01",
                          "fecha": "2026-01-15",
                          "tarifa": 13
                        }
                      }
                    ],
                    "otros_cargos": [
                      {
                        "tipo": "06",
                        "detalle": "Impuesto de servicio",
                        "monto": 4000,
                        "porcentaje": 10
                      }
                    ],
                    "otros_datos": [
                      {
                        "codigo": "OrdenCompra",
                        "texto": "OC-2026-0098"
                      }
                    ],
                    "observaciones": "Entregar en bodega 2"
                  }
                },
                "exportacion": {
                  "value": {
                    "tipo": "FEE",
                    "referencia": "EXP/2026/00027",
                    "condicion_venta": "02",
                    "plazo_credito": 30,
                    "medio_pago": "04",
                    "moneda": "USD",
                    "receptor": {
                      "tipo_identificacion": "05",
                      "identificacion": "US841234567",
                      "nombre": "Pacific Trading LLC",
                      "correo": "ap@pacifictrading.example",
                      "direccion": "1200 Harbor Blvd, Suite 400, Long Beach, CA 90802, Estados Unidos"
                    },
                    "lineas": [
                      {
                        "cabys": "8314100000000",
                        "detalle": "Servicios de desarrollo de software, octubre de 2026",
                        "cantidad": 1,
                        "unidad": "Sp",
                        "precio_unitario": 4500
                      }
                    ]
                  }
                },
                "nota_credito": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00031",
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "referencia": "INV/2026/00412",
                      "codigo": "01",
                      "razon": "Anula la factura por error en el pedido"
                    }
                  }
                },
                "nota_de_fuera": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00032",
                    "moneda": "USD",
                    "tipo_cambio": 448.37,
                    "receptor": {
                      "tipo_identificacion": "02",
                      "identificacion": "3101456789",
                      "nombre": "Constructora Los Robles S.A.",
                      "correo": "compras@losrobles.example"
                    },
                    "lineas": [
                      {
                        "cabys": "3744001000100",
                        "detalle": "Cemento Portland blanco 50 kg",
                        "cantidad": 20,
                        "unidad": "Unid",
                        "precio_unitario": 7500,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "tipo_documento": "01",
                      "numero": "50601102600310198765400100001010000000045123456789",
                      "fecha": "2026-10-01",
                      "codigo": "02",
                      "razon": "Corrige el monto facturado"
                    }
                  }
                },
                "nota_financiera": {
                  "value": {
                    "tipo": "NC",
                    "referencia": "RINV/2026/00033",
                    "lineas": [
                      {
                        "detalle": "Descuento por pronto pago",
                        "cantidad": 1,
                        "precio_unitario": 5000
                      }
                    ],
                    "documento_referencia": {
                      "referencia": "INV/2026/00412",
                      "codigo": "09",
                      "razon": "Descuento por pronto pago"
                    }
                  }
                },
                "factura_compra": {
                  "value": {
                    "tipo": "FEC",
                    "referencia": "COMPRA/2026/00007",
                    "condicion_venta": "01",
                    "medio_pago": "01",
                    "proveedor": {
                      "tipo_identificacion": "01",
                      "identificacion": "205550123",
                      "nombre": "María Fernández Rojas",
                      "correo": "maria.fernandez@correo.example",
                      "telefono": "88887777",
                      "provincia": "2",
                      "canton": "01",
                      "distrito": "01",
                      "otras_senas": "200 metros norte de la iglesia, casa esquinera"
                    },
                    "lineas": [
                      {
                        "cabys": "8314100000000",
                        "detalle": "Mantenimiento del jardín, noviembre de 2026",
                        "cantidad": 1,
                        "unidad": "Os",
                        "precio_unitario": 60000,
                        "tarifa_iva": "08"
                      }
                    ],
                    "documento_referencia": {
                      "tipo_documento": "14",
                      "numero": "RECIBO-0087",
                      "fecha": "2026-11-10",
                      "codigo": "04",
                      "razon": "Compra a un contribuyente del régimen simplificado"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "El documento está bien y se puede emitir.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Revision"
                },
                "example": {
                  "valido": true,
                  "repetida": false,
                  "documento": null,
                  "tipo": "FE",
                  "referencia": "INV/2026/00412",
                  "moneda": "CRC",
                  "tipo_cambio": 1,
                  "subtotal": 150000.0,
                  "descuento": 0.0,
                  "impuesto": 19500.0,
                  "otros_cargos": 0.0,
                  "total": 169500.0,
                  "avisos": [],
                  "ambiente": "pruebas"
                }
              }
            }
          },
          "400": {
            "description": "solicitud_invalida: El cuerpo no es un JSON válido o pasa del tamaño permitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sin_permiso: La llave es de solo consulta y no puede emitir. produccion_no_habilitada: El perfil todavía no está habilitado para producción. tope_adicionales: El ciclo llegó a su tope de documentos adicionales. Pida otro tope en el perfil o espere al ciclo siguiente. perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "emisor_incompleto: Al emisor le falta configuración. El mensaje dice qué. referencia_repetida: Esa referencia ya existe con otros datos. Con los mismos datos se devuelve el documento que ya existía.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validacion: Un dato no pasa la validación. El mensaje dice cuál y en qué línea. No se gasta consecutivo. no_generado: El comprobante no se pudo armar con esos datos y quedó con estado «error». Su consecutivo no se reutiliza. Corrija y envíe de nuevo con la misma referencia.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "tope_diario: La llave llegó a su tope de documentos del día. demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "cuenta_morosa: La factura del plan está vencida y el API dejó de emitir. Vuelve a emitir en cuanto se registre el pago. Consultar y descargar siguen funcionando.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "api_en_pausa: El API está en pausa y no emite por el momento. Consultar y descargar siguen funcionando.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documentos/{id}": {
      "get": {
        "operationId": "consultar",
        "summary": "Consultar el estado",
        "description": "Devuelve el documento con su estado más reciente.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "El documento.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Documento"
                },
                "example": {
                  "id": "doc_8Jq2mXw4Tz1RbYc6",
                  "referencia": "INV/2026/00412",
                  "tipo": "FE",
                  "consecutivo": "00100003010000002318",
                  "clave": "50613112600310198765400100003010000002318158241973",
                  "estado": "procesando",
                  "mensaje_hacienda": "",
                  "fecha_emision": "2026-11-13T10:42:07-06:00",
                  "moneda": "CRC",
                  "tipo_cambio": 1,
                  "subtotal": 150000.0,
                  "descuento": 0.0,
                  "impuesto": 19500.0,
                  "otros_cargos": 0.0,
                  "total": 169500.0,
                  "receptor": {
                    "identificacion": "3101456789",
                    "nombre": "Constructora Los Robles S.A."
                  },
                  "ambiente": "pruebas",
                  "repetida": false,
                  "archivos": {
                    "xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
                    "respuesta": null,
                    "pdf": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "no_encontrado: No existe un documento con ese identificador para este emisor.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/emisor": {
      "get": {
        "operationId": "emisor",
        "summary": "Probar la llave",
        "description": "Devuelve el emisor de la llave y si ya puede emitir. Sirve para probar la conexión.",
        "responses": {
          "200": {
            "description": "El emisor de la llave. Con una llave de producción trae además «plan»: nombre (El plan del perfil); ciclo_desde (Primer día del ciclo en curso, AAAA-MM-DD); ciclo_hasta (Último día del ciclo en curso, AAAA-MM-DD); documentos_incluidos (Documentos que el plan incluye en cada ciclo); documentos_usados (Documentos emitidos en el ciclo. No cuentan los que Hacienda rechazó); adicionales (Documentos del ciclo por encima de los incluidos. Se cobran en la factura del ciclo siguiente); tope_adicionales (Cuántos adicionales admite el ciclo. Al llegar, el API deja de emitir hasta el ciclo siguiente); puede_emitir (false si el API no emitiría en este momento: pausa, factura vencida o tope alcanzado); motivo (Por qué no puede emitir. Vacío si puede)."
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documentos/{id}/xml": {
      "get": {
        "operationId": "xml",
        "summary": "Descargar el XML firmado",
        "description": "El comprobante electrónico tal como se envió a Hacienda.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "El archivo.",
            "content": {
              "application/xml": {}
            }
          },
          "404": {
            "description": "no_encontrado: No existe un documento con ese identificador para este emisor. archivo_no_disponible: Ese archivo todavía no existe. El PDF y la respuesta llegan cuando Hacienda acepta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documentos/{id}/respuesta": {
      "get": {
        "operationId": "respuesta",
        "summary": "Descargar la respuesta de Hacienda",
        "description": "El mensaje de aceptación o de rechazo.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "El archivo.",
            "content": {
              "application/xml": {}
            }
          },
          "404": {
            "description": "no_encontrado: No existe un documento con ese identificador para este emisor. archivo_no_disponible: Ese archivo todavía no existe. El PDF y la respuesta llegan cuando Hacienda acepta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/documentos/{id}/pdf": {
      "get": {
        "operationId": "pdf",
        "summary": "Descargar el PDF",
        "description": "La representación impresa. Existe cuando Hacienda acepta.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "El archivo.",
            "content": {
              "application/pdf": {}
            }
          },
          "404": {
            "description": "no_encontrado: No existe un documento con ese identificador para este emisor. archivo_no_disponible: Ese archivo todavía no existe. El PDF y la respuesta llegan cuando Hacienda acepta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "llave_invalida: Falta la llave, está mal escrita o no existe. llave_anulada: La llave fue anulada. Cree otra en el perfil.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "perfil_suspendido: El perfil está suspendido. Entre al perfil o escríbanos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "demasiadas_solicitudes: Demasiadas solicitudes en un minuto. Espere y repita.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "error_interno: Algo falló de nuestro lado. Repita con la misma referencia: no se duplica.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-webhooks": {
    "aviso": {
      "post": {
        "operationId": "aviso",
        "summary": "Aviso al sistema de origen",
        "description": "El API envía este POST a la dirección https registrada en el perfil cuando un documento llega a un estado final. Va firmado en la cabecera X-Efcr-Firma. Una respuesta 2xx lo da por entregado; si no, se reintenta 5 veces en 24 horas. Un aviso puede llegar repetido: use su «id».",
        "parameters": [
          {
            "name": "X-Efcr-Evento",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "El evento: documento.aceptado, documento.rechazado, documento.error o prueba."
          },
          {
            "name": "X-Efcr-Aviso",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "El identificador del aviso. Es el «id» del cuerpo y no cambia entre reintentos."
          },
          {
            "name": "X-Efcr-Firma",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "t=<tiempo>,v1=<firma>. El tiempo va en segundos (Unix). La firma es el HMAC-SHA256, en hexadecimal, de «<tiempo>.<cuerpo>» con la llave de firma de su perfil."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Aviso"
              },
              "example": {
                "id": "avs_Q2x8Lm4TzK1RbYc6",
                "evento": "documento.aceptado",
                "creado": "2026-11-13T10:42:12-06:00",
                "ambiente": "pruebas",
                "documento": {
                  "id": "doc_8Jq2mXw4Tz1RbYc6",
                  "referencia": "INV/2026/00412",
                  "tipo": "FE",
                  "consecutivo": "00100003010000002318",
                  "clave": "50613112600310198765400100003010000002318158241973",
                  "estado": "aceptado",
                  "mensaje_hacienda": "",
                  "fecha_emision": "2026-11-13T10:42:07-06:00",
                  "moneda": "CRC",
                  "tipo_cambio": 1,
                  "subtotal": 150000.0,
                  "descuento": 0.0,
                  "impuesto": 19500.0,
                  "otros_cargos": 0.0,
                  "total": 169500.0,
                  "receptor": {
                    "identificacion": "3101456789",
                    "nombre": "Constructora Los Robles S.A."
                  },
                  "ambiente": "pruebas",
                  "archivos": {
                    "xml": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/xml",
                    "respuesta": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/respuesta",
                    "pdf": "https://e-facturacr.com/api/v1/documentos/doc_8Jq2mXw4Tz1RbYc6/pdf"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Recibido. Cualquier otra respuesta se reintenta."
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "llave": {
        "type": "http",
        "scheme": "bearer",
        "description": "La llave del perfil, en la cabecera Authorization: Bearer <llave>."
      }
    },
    "schemas": {
      "DocumentoNuevo": {
        "type": "object",
        "required": [
          "tipo",
          "referencia",
          "lineas"
        ],
        "properties": {
          "tipo": {
            "description": "FE factura, TE tiquete, FEE factura de exportación, NC nota de crédito, ND nota de débito o FEC factura de compra.",
            "enum": [
              "FE",
              "FEC",
              "FEE",
              "NC",
              "ND",
              "TE"
            ]
          },
          "referencia": {
            "description": "El número del documento en su sistema, hasta 60 caracteres. Es único por emisor y es lo que evita los duplicados."
          },
          "receptor": {
            "description": "El cliente: tipo y número de identificación, nombre y correo. En un tiquete puede faltar. En la factura de exportación es un cliente del extranjero, con su dirección. Una nota lleva siempre el cliente del documento original: si este se emitió con el API se toma solo (si lo envía, debe ser el mismo) y si es de fuera hay que enviarlo. En la factura de compra no va: se envía «proveedor».",
            "type": "object",
            "required": [
              "tipo_identificacion",
              "identificacion",
              "nombre"
            ],
            "properties": {
              "tipo_identificacion": {
                "description": "01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE. En la factura de exportación, 05: cliente del extranjero; el tiquete también lo admite."
              },
              "identificacion": {
                "description": "El número, sin guiones ni espacios. La de un cliente del extranjero: hasta 20 letras y números."
              },
              "nombre": {
                "description": "Nombre o razón social, hasta 100 caracteres."
              },
              "correo": {
                "description": "Correo del cliente. Sale en el comprobante."
              },
              "direccion": {
                "description": "Dirección del cliente en el extranjero, de 5 a 300 caracteres. Solo con el tipo 05."
              },
              "actividad": {
                "description": "Código de la actividad económica del cliente, de 6 caracteres. En facturas y notas, cuando el cliente la pide para su crédito fiscal."
              }
            }
          },
          "proveedor": {
            "description": "Solo en la factura de compra: a quién se le compra, con su dirección y su correo.",
            "type": "object",
            "required": [
              "tipo_identificacion",
              "identificacion",
              "nombre",
              "correo",
              "provincia",
              "canton",
              "distrito",
              "otras_senas"
            ],
            "properties": {
              "tipo_identificacion": {
                "description": "01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE. 06 no contribuyente, solo con la condición de venta 13."
              },
              "identificacion": {
                "description": "El número, sin guiones ni espacios."
              },
              "nombre": {
                "description": "Nombre o razón social del proveedor, de 5 a 100 caracteres."
              },
              "correo": {
                "description": "Correo del proveedor. Sale en el comprobante."
              },
              "telefono": {
                "description": "Teléfono, de 8 a 20 dígitos."
              },
              "provincia": {
                "description": "Código de la provincia, de 1 a 7. Con el tipo 06 la dirección puede faltar, completa."
              },
              "canton": {
                "description": "Código del cantón, de dos dígitos."
              },
              "distrito": {
                "description": "Código del distrito, de dos dígitos."
              },
              "otras_senas": {
                "description": "Otras señas de la dirección, de 5 a 250 caracteres."
              },
              "actividad": {
                "description": "Código de la actividad económica del proveedor, de 6 caracteres."
              }
            }
          },
          "lineas": {
            "description": "De 1 a 200 líneas. De cada una: CABYS, detalle, cantidad, precio y tarifa de IVA. El API calcula los totales.",
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "cabys",
                "detalle",
                "cantidad",
                "precio_unitario"
              ],
              "properties": {
                "cabys": {
                  "description": "Código CABYS de 13 dígitos del bien o servicio. Puede faltar en una nota financiera, con el código de referencia 09 o 10."
                },
                "detalle": {
                  "description": "Descripción de la línea, de 3 a 200 caracteres."
                },
                "cantidad": {
                  "description": "Mayor que cero, con hasta 3 decimales."
                },
                "precio_unitario": {
                  "description": "Precio de una unidad, sin el IVA, con hasta 5 decimales."
                },
                "unidad": {
                  "description": "Unidad de medida de Hacienda. Si falta: Unid para bienes y Sp para servicios."
                },
                "tarifa_iva": {
                  "description": "Código de la tarifa. Si falta: 08, la general del 13 %. En la factura de exportación y en sus notas, si falta: 10, exento."
                },
                "descuento": {
                  "description": "Monto del descuento de la línea, con hasta 5 decimales. Menor que el monto de la línea. No se envía en una regalía o bonificación."
                },
                "descuento_codigo": {
                  "description": "Código del descuento. Si falta: 07, comercial. 01, 02 o 03 convierten la línea en una regalía o bonificación: se entrega completa y la tarifa debe llevar IVA."
                },
                "descuento_naturaleza": {
                  "description": "Explicación del descuento, de 3 a 80 caracteres."
                },
                "descuento_otro": {
                  "description": "Descripción del descuento, de 5 a 100 caracteres."
                },
                "base_imponible": {
                  "description": "Solo con el descuento 02: el valor sobre el que el cliente paga el IVA. Si falta: el monto de la línea."
                },
                "codigo": {
                  "description": "Código del producto en su sistema, hasta 20 caracteres."
                },
                "codigo_tipo": {
                  "description": "Tipo del código del producto. Si falta: 04, de uso interno."
                },
                "tipo_transaccion": {
                  "description": "Tipo de transacción de la línea. En facturas, notas y facturas de compra. Vea el catálogo."
                },
                "partida_arancelaria": {
                  "description": "Partida arancelaria, de 12 dígitos. Obligatoria en la factura de exportación y en sus notas cuando la línea es una mercancía: CABYS que empieza por 0, 1, 2, 3 o 4. En servicios no va."
                },
                "exoneracion": {
                  "description": "El documento que exonera el IVA de la línea. No se usa en la factura de exportación.",
                  "type": "object",
                  "required": [
                    "tipo_documento",
                    "numero",
                    "institucion",
                    "fecha",
                    "tarifa"
                  ],
                  "properties": {
                    "tipo_documento": {
                      "description": "Tipo del documento de exoneración. Vea el catálogo."
                    },
                    "tipo_documento_otro": {
                      "description": "Descripción del tipo, de 5 a 100 caracteres."
                    },
                    "numero": {
                      "description": "Número del documento de exoneración, de 3 a 40 caracteres."
                    },
                    "articulo": {
                      "description": "Número del artículo de la ley, entero."
                    },
                    "inciso": {
                      "description": "Número del inciso, entero, cuando el artículo lo tiene."
                    },
                    "institucion": {
                      "description": "Institución que emitió la exoneración. Vea el catálogo."
                    },
                    "institucion_otros": {
                      "description": "Nombre de la institución, de 5 a 160 caracteres."
                    },
                    "fecha": {
                      "description": "Fecha de emisión del documento de exoneración, AAAA-MM-DD."
                    },
                    "tarifa": {
                      "description": "Tarifa exonerada, en puntos del IVA: 13 exonera todo el IVA de una línea al 13 %. Si supera la tarifa de la línea se usa la de la línea."
                    }
                  }
                },
                "numero_vin": {
                  "description": "Número VIN o de serie del vehículo, de hasta 17 caracteres. Obligatorio cuando el CABYS empieza por 4911 o 4991. Un vehículo por línea."
                },
                "registro_medicamento": {
                  "description": "Registro sanitario del medicamento, hasta 100 caracteres. Solo con CABYS que empieza por 3562 a 3565."
                },
                "forma_farmaceutica": {
                  "description": "Código de la forma farmacéutica, hasta 3 caracteres. Solo con CABYS que empieza por 3562 a 3565."
                },
                "iva_devuelto": {
                  "description": "true en un servicio de salud con la tarifa reducida del 4 % (código 04) pagado con tarjeta: el IVA de la línea se devuelve y no se cobra."
                }
              }
            },
            "minItems": 1,
            "maxItems": 200
          },
          "condicion_venta": {
            "description": "Código de Hacienda. Si falta: 01, contado. Una nota toma la condición, el plazo y el medio de pago del original."
          },
          "condicion_venta_otros": {
            "description": "Descripción de la condición, de 5 a 100 caracteres."
          },
          "plazo_credito": {
            "description": "Días de plazo. Obligatorio con las condiciones 02, 08 y 10."
          },
          "medio_pago": {
            "description": "Código de Hacienda. Si falta: 01, efectivo."
          },
          "medio_pago_otros": {
            "description": "Descripción del medio de pago, de 3 a 100 caracteres."
          },
          "medios_pago": {
            "description": "En vez de «medio_pago», cuando se paga con dos a cuatro medios: cada uno con su monto. La suma debe ser el total del documento.",
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "codigo",
                "monto"
              ],
              "properties": {
                "codigo": {
                  "description": "Código del medio de pago. Vea el catálogo."
                },
                "monto": {
                  "description": "Lo pagado con ese medio, mayor que cero y con hasta 2 decimales."
                }
              }
            }
          },
          "moneda": {
            "description": "Código de la moneda. Si falta: CRC. Una nota va en la moneda y con el tipo de cambio de su documento original."
          },
          "tipo_cambio": {
            "description": "Colones por unidad de la moneda. En dólares, si falta, se usa el de venta del día. En las demás monedas es obligatorio. Una nota lleva el del documento original: si este se emitió con el API se toma solo, y si es de fuera hay que enviarlo."
          },
          "actividad": {
            "description": "Código de la actividad económica del emisor. Si falta: la principal."
          },
          "observaciones": {
            "description": "Texto libre de hasta 500 caracteres. Viaja en el XML y sale en el PDF."
          },
          "otros_datos": {
            "description": "Hasta 20 datos adicionales de uso comercial, cada uno con su nombre. Viajan en el XML y salen en el PDF.",
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "codigo",
                "texto"
              ],
              "properties": {
                "codigo": {
                  "description": "Nombre del dato, hasta 60 caracteres. Por ejemplo OrdenCompra."
                },
                "texto": {
                  "description": "Su valor, hasta 500 caracteres."
                }
              }
            }
          },
          "otros_cargos": {
            "description": "Hasta 15 cargos que se suman al total sin ser líneas: timbres, impuesto de servicio, cobros de terceros.",
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "tipo",
                "detalle",
                "monto"
              ],
              "properties": {
                "tipo": {
                  "description": "Código del cargo. Vea el catálogo."
                },
                "tipo_otros": {
                  "description": "Descripción del cargo, de 5 a 100 caracteres."
                },
                "detalle": {
                  "description": "Detalle del cargo, de 3 a 160 caracteres."
                },
                "monto": {
                  "description": "Monto del cargo, mayor que cero y con hasta 5 decimales."
                },
                "porcentaje": {
                  "description": "Porcentaje que representa el cargo, por ejemplo 10. Es informativo."
                },
                "tercero": {
                  "description": "A nombre de quién se cobra.",
                  "type": "object",
                  "required": [
                    "tipo_identificacion",
                    "identificacion",
                    "nombre"
                  ],
                  "properties": {
                    "tipo_identificacion": {
                      "description": "01 cédula física, 02 cédula jurídica, 03 DIMEX o 04 NITE."
                    },
                    "identificacion": {
                      "description": "El número, sin guiones ni espacios."
                    },
                    "nombre": {
                      "description": "Nombre o razón social del tercero, de 5 a 100 caracteres."
                    }
                  }
                }
              }
            }
          },
          "documento_referencia": {
            "description": "El documento al que este hace referencia y el motivo. En una nota, el que corrige o anula. En la factura de compra, el comprobante del proveedor. En los demás es opcional.",
            "type": "object",
            "required": [
              "razon"
            ],
            "properties": {
              "id": {
                "description": "El «id» que el API le dio al documento original."
              },
              "referencia": {
                "description": "La referencia de su sistema con que emitió el original."
              },
              "clave": {
                "description": "La clave de 50 dígitos del original."
              },
              "tipo_documento": {
                "description": "Tipo del documento al que se hace referencia, cuando no se emitió con este API. Vea el catálogo."
              },
              "tipo_documento_otros": {
                "description": "Descripción del tipo, de 5 a 100 caracteres."
              },
              "numero": {
                "description": "El número del documento de fuera, hasta 50 caracteres. Con los tipos de documento 01, 02, 03, 04, 09, 11, 12, 15, 19 y 20 es la clave de 50 caracteres del comprobante: con otro número Hacienda lo rechaza."
              },
              "fecha": {
                "description": "Fecha de emisión del documento de fuera: AAAA-MM-DD, o con la hora, AAAA-MM-DDTHH:MM:SS. No puede tener más de 10 años."
              },
              "codigo": {
                "description": "Qué hace la referencia. Si falta: 01, anula, en una nota de crédito; 02, corrige el monto, en una nota de débito; 04, referencia a otro documento, en los demás."
              },
              "codigo_otros": {
                "description": "Descripción del motivo, de 5 a 100 caracteres."
              },
              "razon": {
                "description": "El motivo, de 3 a 180 caracteres."
              }
            }
          }
        },
        "additionalProperties": false,
        "example": {
          "tipo": "FE",
          "referencia": "INV/2026/00412",
          "condicion_venta": "01",
          "medio_pago": "04",
          "receptor": {
            "tipo_identificacion": "02",
            "identificacion": "3101456789",
            "nombre": "Constructora Los Robles S.A.",
            "correo": "compras@losrobles.example"
          },
          "lineas": [
            {
              "cabys": "3744001000100",
              "detalle": "Cemento Portland blanco 50 kg",
              "cantidad": 20,
              "unidad": "Unid",
              "precio_unitario": 7500,
              "tarifa_iva": "08"
            }
          ],
          "observaciones": "Entregar en bodega 2"
        }
      },
      "Documento": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Identificador del documento en el API. Con él se consulta y se descargan sus archivos."
          },
          "referencia": {
            "description": "La referencia que envió su sistema."
          },
          "tipo": {
            "description": "FE, TE, FEE, NC, ND o FEC."
          },
          "consecutivo": {
            "description": "El consecutivo de 20 dígitos. Lo asigna el API."
          },
          "clave": {
            "description": "La clave de 50 dígitos."
          },
          "estado": {
            "description": "procesando, aceptado, rechazado o error."
          },
          "mensaje_hacienda": {
            "description": "El motivo cuando Hacienda rechaza, o por qué el documento todavía no sale o no llegó. Vacío en los demás casos."
          },
          "fecha_emision": {
            "description": "Fecha y hora de emisión, hora de Costa Rica."
          },
          "moneda": {
            "description": "El código de la moneda."
          },
          "tipo_cambio": {
            "description": "El tipo de cambio usado. 1 en colones."
          },
          "subtotal": {
            "description": "Suma de cantidad por precio de las líneas, antes de descuentos."
          },
          "descuento": {
            "description": "Suma de los descuentos."
          },
          "impuesto": {
            "description": "El IVA que paga el cliente, sin lo exonerado."
          },
          "otros_cargos": {
            "description": "Suma de los otros cargos."
          },
          "total": {
            "description": "El total del comprobante."
          },
          "receptor": {
            "description": "Identificación y nombre del cliente, o null en un tiquete sin cliente. En la factura de compra, el proveedor."
          },
          "ambiente": {
            "description": "pruebas o produccion, según la llave usada."
          },
          "repetida": {
            "description": "true cuando la referencia ya existía y se devolvió el mismo documento."
          },
          "archivos": {
            "description": "Las direcciones del XML firmado, la respuesta de Hacienda y el PDF. null mientras no existan."
          }
        }
      },
      "Revision": {
        "type": "object",
        "properties": {
          "valido": {
            "description": "true: el documento pasa todas las revisiones y se puede emitir tal cual. Si algo no pasa, la respuesta es el mismo error que daría la emisión."
          },
          "repetida": {
            "description": "true cuando esa referencia ya se emitió con los mismos datos: emitir devolvería ese documento, sin crear otro."
          },
          "documento": {
            "description": "El «id» del documento que ya existe con esa referencia, o null."
          },
          "tipo": {
            "description": "FE, TE, FEE, NC, ND o FEC."
          },
          "referencia": {
            "description": "La referencia que envió su sistema."
          },
          "moneda": {
            "description": "La moneda con que saldría el documento. En una nota, la de su documento original."
          },
          "tipo_cambio": {
            "description": "El tipo de cambio con que saldría. En una nota, el de su documento original."
          },
          "subtotal": {
            "description": "Suma de cantidad por precio de las líneas, antes de descuentos."
          },
          "descuento": {
            "description": "Suma de los descuentos."
          },
          "impuesto": {
            "description": "El IVA que pagaría el cliente, sin lo exonerado."
          },
          "otros_cargos": {
            "description": "Suma de los otros cargos."
          },
          "total": {
            "description": "El total que tendría el comprobante."
          },
          "avisos": {
            "description": "Lista de observaciones que no impiden emitir, pero conviene revisar. Vacía si no hay."
          },
          "ambiente": {
            "description": "pruebas o produccion, según la llave usada."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "codigo": {
                "type": "string",
                "enum": [
                  "api_en_pausa",
                  "archivo_no_disponible",
                  "cuenta_morosa",
                  "demasiadas_solicitudes",
                  "emisor_incompleto",
                  "error_interno",
                  "llave_anulada",
                  "llave_invalida",
                  "no_encontrado",
                  "no_generado",
                  "perfil_suspendido",
                  "produccion_no_habilitada",
                  "referencia_repetida",
                  "sin_permiso",
                  "solicitud_invalida",
                  "tope_adicionales",
                  "tope_diario",
                  "validacion"
                ]
              },
              "mensaje": {
                "type": "string"
              },
              "detalles": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "campo": {
                      "type": "string"
                    },
                    "mensaje": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Aviso": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Identificador del aviso. Si llega uno repetido, su sistema ya lo procesó."
          },
          "evento": {
            "description": "documento.aceptado, documento.rechazado, documento.error o prueba.",
            "enum": [
              "documento.aceptado",
              "documento.error",
              "documento.rechazado",
              "prueba"
            ]
          },
          "creado": {
            "description": "Fecha y hora en que se generó el aviso, hora de Costa Rica."
          },
          "ambiente": {
            "description": "pruebas o produccion."
          },
          "documento": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Documento"
              }
            ],
            "nullable": true,
            "description": "El documento, con los mismos datos de GET /documentos/{id}. null en el aviso de prueba."
          }
        }
      }
    }
  }
}