Astranexo Hacienda API

openapi: 3.2.0
info:
  title: Astranexo Com Hacienda API
  version: '1.0'
  contact:
    name: Soporte de Aster
    url: https://astranexo.com/soporte
    email: app@astranexo.com
  description: 'Operations tagged Hacienda across 2 of this provider''s published API definitions: aster-openapi.yaml, fe-api-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://aster.astranexo.com/api/v1
  description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
security:
- ApiKey: []
tags:
- name: Hacienda
  description: Estado de Hacienda, consultas de comprobantes y registro de contribuyentes.
paths:
  /hacienda/status:
    get:
      operationId: getHaciendaStatus
      tags:
      - Hacienda
      summary: Disponibilidad de Hacienda y configuración
      description: Disponibilidad de los servicios de Hacienda (staging y producción, según el monitoreo de Aster) y si la organización tiene certificado y credenciales en cada ambiente.
      x-required-ability: hacienda:query
      responses:
        '200':
          description: Estado.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/HaciendaStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /hacienda/query/{clave}:
    parameters:
    - name: clave
      in: path
      required: true
      description: Clave numérica de 50 caracteres.
      schema:
        type: string
        pattern: ^[0-9A-Z]{50}$
    get:
      operationId: queryHaciendaDocument
      tags:
      - Hacienda
      summary: Consultar un comprobante en Hacienda
      description: Consulta directamente a Hacienda el estado de un comprobante, con las credenciales ATV de la organización en el ambiente de la clave. Los errores de Hacienda se devuelven con su código HTTP (o `502`).
      x-required-ability: hacienda:query
      responses:
        '200':
          description: Estado del comprobante en Hacienda.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/HaciendaQueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: Hacienda no respondió.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /hacienda/validate:
    post:
      operationId: validateDocumentDraft
      tags:
      - Hacienda
      summary: Revisión básica de un borrador
      description: 'Revisión estructural mínima de un borrador, sin firmar ni enviar: exige

        `document_type`, emisor con `name`, `identification_type` e

        `identification_number`, al menos una línea y totales, y advierte si falta el

        receptor. **No** aplica las reglas FE 4.4; para eso use `POST /electronic-documents`

        con una clave de prueba.'
      x-required-ability: hacienda:validate
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DraftValidationRequest'
            example:
              document_type: '01'
              issuer:
                name: Servicios Ejemplo S.A.
                identification_type: '02'
                identification_number: '3101123456'
              items:
              - description: Servicio de instalación
              totals:
                total: 28250
      responses:
        '200':
          description: Resultado de la revisión.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/DraftValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /hacienda/resolution:
    get:
      operationId: getDocumentResolution
      tags:
      - Hacienda
      summary: Resolución registrada de un documento
      description: Estado y mensaje de Hacienda registrados en Aster para un documento de la organización (sin consultar a Hacienda).
      x-required-ability: hacienda:query
      parameters:
      - name: clave
        in: query
        required: true
        description: Clave numérica de 50 caracteres.
        schema:
          type: string
          pattern: ^[0-9A-Z]{50}$
      responses:
        '200':
          description: Resolución.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/DocumentResolution'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /hacienda/taxpayers:
    get:
      operationId: searchTaxpayers
      tags:
      - Hacienda
      summary: Buscar contribuyentes
      description: 'Búsqueda pública en el registro de contribuyentes de Hacienda, por cédula o por

        nombre. La respuesta agrupa los resultados en `cedulas_fisicas` (solo personas

        físicas), `cedulas_juridicas` (solo personas jurídicas) o `taxpayers` (mezcla o

        ningún resultado). Limitado a 60 solicitudes por minuto por IP.'
      security: []
      parameters:
      - name: cedula
        in: query
        description: Identificación (alias `id`, `identification`). Se ignoran guiones y espacios.
        schema:
          type: string
      - name: nombre
        in: query
        description: Nombre o razón social (mínimo 2 caracteres; obligatorio si no hay cédula).
        schema:
          type: string
          minLength: 2
      - name: apellidos
        in: query
        description: Apellidos (personas físicas).
        schema:
          type: string
      - name: tipo
        in: query
        description: '`F` persona física o `J` persona jurídica.'
        schema:
          type: string
          enum:
          - F
          - J
      - name: exact_match
        in: query
        description: '`true` para coincidencia exacta.'
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Resultados.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/TaxpayerSearchResult'
              example:
                success: true
                message: 1 taxpayer(s) found.
                data:
                  cedulas_juridicas:
                  - cedula: '3101123456'
                    id_raw: '3101123456'
                    tipo: J
                    tipo_texto: Cédula Jurídica
                    class: Cédula Jurídica
                    razon_social: SERVICIOS EJEMPLO SOCIEDAD ANONIMA
                timestamp: '2026-10-08T16:00:00Z'
                api_version: '1.0'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /hacienda/exonerations/{number}:
    get:
      operationId: getExoneration
      tags:
      - Hacienda
      summary: Consultar una exoneración en EXONET
      description: 'Una autorización de exoneración de EXONET («AL-00020402-24») tal como la tiene Hacienda:

        titular, puntos de IVA exonerados, fechas de emisión y vencimiento y los CABYS que cubre

        (`covers_all_cabys` es `true` cuando no está limitada por CABYS). `in_force` indica si está

        vigente hoy (hora de Costa Rica).


        Las respuestas se guardan en caché (un día; «no existe», una hora); `?refresh=1` consulta

        a Hacienda de nuevo, por ejemplo cuando el cliente acaba de renovar la autorización. Es la

        misma consulta que se hace antes de firmar cada documento con una exoneración «AL-».

        Limitado a 60 solicitudes por minuto por IP.'
      security: []
      parameters:
      - name: number
        in: path
        required: true
        description: Número de autorización, `AL-` + 8 dígitos + `-` + año de 2 dígitos.
        schema:
          type: string
          pattern: ^AL-\d{8}-\d{2}$
      - name: refresh
        in: query
        description: '`1` para no usar la caché.'
        schema:
          type: string
          enum:
          - '1'
          - 'true'
      responses:
        '200':
          description: La autorización.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ExonetAuthorization'
              example:
                success: true
                data:
                  number: AL-00020402-24
                  holder_id: '3004061893'
                  points: 12
                  issued_on: '2024-06-10'
                  expires_on: '2030-06-10'
                  covers_all_cabys: false
                  cabys:
                  - '0113200000000'
                  - '1201000009900'
                  authorization_type: tarifa reducida
                  document_type: '04'
                  document_type_description: Exenciones Dirección General de Hacienda
                  institution_code: '01'
                  institution_name: Ministerio de Hacienda
                  in_force: true
                timestamp: '2026-10-12T16:00:00Z'
                api_version: '1.0'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          description: '`exoneration_not_found`: EXONET no tiene esa autorización.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: '`exonet_unreachable`: no se pudo consultar a Hacienda; intente de nuevo.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
components:
  headers:
    X-RateLimit-Reset:
      description: Fin de la ventana actual (segundos Unix).
      schema:
        type: integer
        format: int64
    Retry-After:
      description: Segundos que faltan para poder reintentar.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Solicitudes restantes en la ventana actual.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Solicitudes permitidas en la ventana actual.
      schema:
        type: integer
  responses:
    Forbidden:
      description: 'Sin permiso: `forbidden` (falta la habilidad), `organization_key_required`, `live_key_required`, `no_tenant`, `tenant_inactive`, `tenant_deleted`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: This action is unauthorized.
            error:
              code: forbidden
              message: This action is unauthorized.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    Unprocessable:
      description: Regla de negocio incumplida; `error.code` indica cuál.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: 'No existe o no pertenece a la organización ni a su ambiente: `not_found` u otro código específico (`xml_not_available`, `response_not_available`, `pdf_not_available`, `no_documents`, `recipient_not_found`, `document_not_found`, `cabys_not_found`, `tariff_not_found`, `province_not_found`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: not_found
              message: Document not found.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    ValidationFailed:
      description: Validación fallida (`validation_error`, con mensajes por campo en `error.errors`) u otra regla de negocio con su propio código.
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/ValidationError'
            - $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: validation_error
              message: A valid email is required.
              errors:
                email:
                - A valid email is required.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    TooManyRequests:
      description: Límite de solicitudes alcanzado (`rate_limited`).
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: Rate limit exceeded. Try again in 12 seconds.
            error:
              code: rate_limited
              message: Rate limit exceeded. Try again in 12 seconds.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    Unauthorized:
      description: 'Clave ausente, desconocida, vencida o revocada: `unauthenticated`, `token_expired`, `key_revoked`, `tenant_unresolved`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: Unauthenticated.
            error:
              code: unauthenticated
              message: Unauthenticated.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    BadRequest:
      description: 'Solicitud mal formada: `invalid_json`, `invalid_request`, `invalid_idempotency_key`, `invalid_body`, `missing_params`, `missing_date`, `invalid_date`, `future_date`, `invalid_currency`, `missing_category`, `missing_param`, `too_many_codes`, etc.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: invalid_json
              message: 'Invalid JSON in request body: unexpected EOF'
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
  schemas:
    ErrorPayload:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Código estable del error, para usar en el código del cliente.
          example: validation_error
        message:
          type: string
          description: Descripción legible.
        errors:
          type: object
          description: Mensajes por campo (ruta con puntos, por ejemplo `items.0.cabys_code`).
          additionalProperties:
            type: array
            items:
              type: string
    Envelope:
      type: object
      description: Envoltura de las respuestas exitosas.
      required:
      - success
      - timestamp
      - api_version
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string
          description: Mensaje legible (en inglés) de algunas operaciones.
        data:
          description: Contenido de la respuesta.
        timestamp:
          type: string
          format: date-time
        api_version:
          type: string
          example: '1.0'
    DraftValidationResult:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type:
          - array
          - 'null'
          items:
            type: string
        warnings:
          type:
          - array
          - 'null'
          items:
            type: string
    TaxpayerSearchResult:
      type: object
      description: Solo una de las listas está presente.
      properties:
        cedulas_fisicas:
          type: array
          items:
            $ref: '#/components/schemas/Taxpayer'
        cedulas_juridicas:
          type: array
          items:
            $ref: '#/components/schemas/Taxpayer'
        taxpayers:
          type: array
          items:
            $ref: '#/components/schemas/Taxpayer'
        query:
          type: string
          description: Término buscado (solo cuando no hay resultados).
    DraftValidationRequest:
      type: object
      properties:
        document_type:
          type: string
        issuer:
          type: object
          properties:
            name:
              type: string
            identification_type:
              type: string
            identification_number:
              type: string
          additionalProperties: true
        receiver:
          type: object
          additionalProperties: true
        items:
          type: array
          items: {}
        totals:
          type: object
          additionalProperties: true
    DocumentResolution:
      type: object
      properties:
        clave:
          type: string
        status:
          type:
          - string
          - 'null'
        hacienda_status:
          type:
          - string
          - 'null'
        hacienda_message:
          type:
          - string
          - 'null'
        hacienda_response_at:
          type: string
          format: date-time
    Taxpayer:
      type: object
      properties:
        cedula:
          type: string
        id_raw:
          type: string
        tipo:
          type: string
          enum:
          - F
          - J
        tipo_texto:
          type: string
        class:
          type: string
        nombre:
          type: string
          description: Nombre completo (personas físicas).
        primer_nombre:
          type: string
        segundo_nombre:
          type: string
        apellidos:
          type: string
        primer_apellido:
          type: string
        segundo_apellido:
          type: string
        razon_social:
          type: string
          description: Razón social (personas jurídicas).
    ErrorEnvelope:
      type: object
      description: Envoltura de los errores.
      required:
      - success
      - error
      - timestamp
      - api_version
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
          description: Repite `error.message` en los errores de autenticación, permisos, límites, idempotencia y cuota.
        error:
          $ref: '#/components/schemas/ErrorPayload'
        timestamp:
          type: string
          format: date-time
        api_version:
          type: string
          example: '1.0'
    ExonetAuthorization:
      type: object
      description: Autorización de exoneración de EXONET.
      properties:
        number:
          type: string
          example: AL-00020402-24
        holder_id:
          type: string
          description: Identificación del titular (comprador).
        points:
          type: number
          description: Puntos de IVA exonerados (13 = todo el 13 %). Es el tope de `exoneration.percentage` en las líneas.
        issued_on:
          type: string
          format: date
          description: Debe coincidir con `exoneration.emission_date`.
        expires_on:
          type: string
          format: date
          description: Vacío si no vence.
        covers_all_cabys:
          type: boolean
        cabys:
          type: array
          items:
            type: string
          description: CABYS cubiertos cuando `covers_all_cabys` es `false`.
        authorization_type:
          type: string
        document_type:
          type: string
          description: Tipo de documento de exoneración (FE 4.4)
          normalmente `04`.: null
        document_type_description:
          type: string
        institution_code:
          type: string
        institution_name:
          type: string
        cfia_project:
          type: integer
          description: Proyecto CFIA
          cuando la autorización es de construcción.: null
        in_force:
          type: boolean
          description: Vigente hoy (hora de Costa Rica).
    HaciendaEnvironmentStatus:
      type: object
      properties:
        available:
          type: boolean
        has_certificate:
          type: boolean
        has_credentials:
          type: boolean
        response_time_ms:
          type: number
        last_check:
          type: string
          format: date-time
    HaciendaStatus:
      type: object
      properties:
        staging:
          $ref: '#/components/schemas/HaciendaEnvironmentStatus'
        production:
          $ref: '#/components/schemas/HaciendaEnvironmentStatus'
        default_environment:
          $ref: '#/components/schemas/Environment'
        checked_at:
          type: string
          format: date-time
    HaciendaQueryResult:
      type: object
      properties:
        clave:
          type: string
        status:
          type: string
          example: aceptado
        ind_estado:
          type: string
          example: aceptado
        message:
          type: string
        details:
          type: string
        error_codes:
          type:
          - array
          - 'null'
          items:
            type: string
    Environment:
      type: string
      enum:
      - staging
      - production
      description: Ambiente de Hacienda. Con claves de Aster lo decide la clave.
    ValidationError:
      description: Error `422 validation_error` con los mensajes por campo.
      allOf:
      - $ref: '#/components/schemas/ErrorEnvelope'
      - type: object
        properties:
          error:
            type: object
            required:
            - code
            - message
            - errors
            properties:
              code:
                type: string
                const: validation_error
              message:
                type: string
                description: Resumen de todos los mensajes, separados por ` | `.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      description: Clave única de la operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve la respuesta guardada durante 24 horas.
      schema:
        type: string
        maxLength: 255
        example: 7f3c1e2a-pedido-1042
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: 'Tu llave de API en el encabezado `Authorization: Bearer <llave>`: `aster_test_…` (pruebas) o `aster_live_…` (producción).'
x-refined-from:
- aster-openapi.yaml
- fe-api-openapi.yaml