{"components":{"headers":{"Aster-Simulated":{"description":"`true` cuando el veredicto de Hacienda será simulado (sandbox).","schema":{"enum":["true"],"type":"string"}},"Content-Disposition":{"description":"Nombre del archivo descargado, por ejemplo `attachment; filename=\"\u003cclave\u003e.xml\"`.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"`true` cuando la respuesta es la guardada para la misma `X-Idempotency-Key`.","schema":{"enum":["true"],"type":"string"}},"Retry-After":{"description":"Segundos que faltan para poder reintentar.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Solicitudes permitidas en la ventana actual.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana actual.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fin de la ventana actual (segundos Unix).","schema":{"format":"int64","type":"integer"}}},"parameters":{"CantonCode":{"description":"Código del cantón (dos dígitos).","in":"path","name":"canton","required":true,"schema":{"example":"01","type":"string"}},"DocumentKey":{"description":"Clave numérica (50 caracteres), consecutivo (20 dígitos) o id del documento.","in":"path","name":"key","required":true,"schema":{"example":"50608102600310112345600100001010000000042112345678","type":"string"}},"IdempotencyKey":{"description":"Clave única de la operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve la respuesta guardada durante 24 horas.","in":"header","name":"X-Idempotency-Key","required":false,"schema":{"example":"7f3c1e2a-pedido-1042","maxLength":255,"type":"string"}},"OrganizationId":{"description":"Id (UUID) de la organización.","in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},"Page":{"description":"Página (desde 1).","in":"query","name":"page","schema":{"default":1,"minimum":1,"type":"integer"}},"PdfLang":{"description":"Idioma del PDF. Por defecto se toma de `Accept-Language` (`en`) o español.","in":"query","name":"lang","schema":{"enum":["es","en"],"type":"string"}},"PerPage":{"description":"Elementos por página (1–100).","in":"query","name":"per_page","schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},"ProvinceCode":{"description":"Código de la provincia (1–7).","in":"path","name":"province","required":true,"schema":{"example":"1","type":"string"}},"WebhookEventHeader":{"description":"Nombre del evento, por ejemplo `document.accepted`.","in":"header","name":"X-Webhook-Event","required":true,"schema":{"type":"string"}},"WebhookId":{"description":"Id numérico del webhook.","in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}},"WebhookIdHeader":{"description":"Id único (UUID) de la entrega. Se repite en los reintentos de la misma entrega; úselo para descartar duplicados.","in":"header","name":"X-Webhook-ID","required":true,"schema":{"format":"uuid","type":"string"}},"WebhookSignatureHeader":{"description":"`sha256=` + HMAC-SHA256 en hexadecimal del cuerpo exacto, con el secreto del webhook. Se omite si no hay secreto.","in":"header","name":"X-Webhook-Signature","required":false,"schema":{"example":"sha256=5d41402abc4b2a76b9719d911017c592ae2f8d3c2f5b4d8e0a1b2c3d4e5f6a7b","type":"string"}},"WebhookSignatureV2Header":{"description":"`t=\u003ctimestamp\u003e,v1=\u003chex\u003e`, donde `v1` es el HMAC-SHA256 de `\"\u003ctimestamp\u003e.\u003ccuerpo\u003e\"` con el secreto del webhook. Verifique también que `t` sea reciente para rechazar repeticiones.","in":"header","name":"X-Webhook-Signature-V2","required":false,"schema":{"example":"t=1791476102,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","type":"string"}},"WebhookTimestampHeader":{"description":"Momento del envío (segundos Unix).","in":"header","name":"X-Webhook-Timestamp","required":true,"schema":{"format":"int64","type":"integer"}}},"responses":{"AccountForbidden":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"account_key_required","message":"This endpoint manages an account: use an account API key."},"message":"This endpoint manages an account: use an account API key.","success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Sin permiso: `account_key_required` (se usó una clave de organización), `forbidden`, `live_key_required`, `organization_limit_reached`."},"BadRequest":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"invalid_json","message":"Invalid JSON in request body: unexpected EOF"},"success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"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."},"Conflict":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"duplicate_consecutive","message":"El consecutivo 00100001010000000042 ya fue utilizado en el documento 50608102600310112345600100001010000000042112345678 (entorno staging). Hacienda rechazará documentos con consecutivo duplicado."},"success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Conflicto: `idempotency_in_progress`, `duplicate_clave`, `duplicate_consecutive`, `already_voided`, `organization_exists`."},"Forbidden":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"forbidden","message":"This action is unauthorized."},"message":"This action is unauthorized.","success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Sin permiso: `forbidden` (falta la habilidad), `organization_key_required`, `live_key_required`, `no_tenant`, `tenant_inactive`, `tenant_deleted`."},"NotFound":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"not_found","message":"Document not found."},"success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"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`)."},"PaymentRequired":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Se requiere un plan pagado: `plan_required` (claves de producción sin plan activo) o `subscription_expired`."},"QuotaExceeded":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"quota_exceeded","message":"This period's 500 documents are used. Upgrade the plan or add a pack to keep issuing.","pack_url":"https://aster.astranexo.com/app/billing#packs","upgrade_url":"https://aster.astranexo.com/app/billing","usage":{"active_organizations":1,"in_flight":2,"included_docs":500,"pack_remaining":0,"period_end":"2026-11-01T00:00:00Z","period_start":"2026-10-01T00:00:00Z","plan":"inicial","remaining":1.5,"status":"active","used":498.5}},"message":"This period's 500 documents are used. Upgrade the plan or add a pack to keep issuing.","success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/QuotaError"}}},"description":"Envío de producción sin cuota disponible: `quota_exceeded` (con `upgrade_url`,\n`pack_url` y `usage`), `plan_required` o `payment_required` (pago fallido hace más\nde 7 días). También `subscription_expired`.\n"},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Servicio no disponible temporalmente: `billing_unavailable`, `service_unavailable`, `auth_unavailable`."},"TooManyRequests":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"rate_limited","message":"Rate limit exceeded. Try again in 12 seconds."},"message":"Rate limit exceeded. Try again in 12 seconds.","success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"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"}}},"Unauthorized":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"unauthenticated","message":"Unauthenticated."},"message":"Unauthenticated.","success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Clave ausente, desconocida, vencida o revocada: `unauthenticated`, `token_expired`, `key_revoked`, `tenant_unresolved`."},"Unprocessable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Regla de negocio incumplida; `error.code` indica cuál."},"ValidationFailed":{"content":{"application/json":{"example":{"api_version":"1.0","error":{"code":"validation_error","errors":{"email":["A valid email is required."]},"message":"A valid email is required."},"success":false,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/ErrorEnvelope"}]}}},"description":"Validación fallida (`validation_error`, con mensajes por campo en `error.errors`) u otra regla de negocio con su propio código."}},"schemas":{"Account":{"properties":{"billing_email":{"format":"email","type":"string"},"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"plan":{"example":"inicial","type":"string"},"status":{"description":"`sandbox`: sin plan pagado (solo claves de prueba).","enum":["sandbox","active","past_due","canceled"],"type":"string"}},"type":"object"},"Address":{"description":"Ubicación según los catálogos de Hacienda (alias del bloque `location`).","properties":{"canton":{"example":"01","type":"string"},"details":{"description":"Otras señas.","type":"string"},"district":{"example":"01","type":"string"},"neighborhood":{"type":"string"},"other_signs":{"description":"Alias de `details`.","type":"string"},"province":{"example":"1","type":"string"}},"type":"object"},"AddressSearchResult":{"properties":{"canton":{"oneOf":[{"$ref":"#/components/schemas/LocationUnit"},{"type":"null"}]},"district":{"oneOf":[{"$ref":"#/components/schemas/LocationUnit"},{"type":"null"}]},"id":{"format":"int64","type":"integer"},"neighborhood":{"oneOf":[{"$ref":"#/components/schemas/LocationUnit"},{"type":"null"}]},"primary_text":{"type":"string"},"province":{"$ref":"#/components/schemas/Province"},"secondary_text":{"type":"string"},"type":{"enum":["neighborhood","district","canton","province"],"type":"string"}},"type":"object"},"ApiConfig":{"properties":{"callback_url":{"description":"Igual que `callback_url` en la raíz.","format":"uri","type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"language":{"description":"Idioma de los mensajes de validación.","enum":["es","en"],"type":"string"},"simulate":{"description":"Pide un veredicto simulado (solo claves de prueba; `422 simulation_not_available` con claves de producción).","enum":["accepted","rejected"],"type":"string"}},"type":"object"},"ApiKey":{"properties":{"abilities":{"items":{"type":"string"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","type":["string","null"]},"id":{"format":"uuid","type":"string"},"last_used_at":{"format":"date-time","type":["string","null"]},"mode":{"enum":["test","live"],"type":"string"},"name":{"type":"string"},"organization_id":{"description":"Organización de la clave; ausente en las claves de cuenta.","format":"uuid","type":"string"},"prefix":{"description":"Inicio de la clave, para reconocerla.","example":"aster_test_8Kq3vT0b","type":"string"},"revoked_at":{"format":"date-time","type":["string","null"]}},"type":"object"},"ApiKeyCreated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"properties":{"secret":{"description":"La clave completa. Solo se muestra en esta respuesta.","example":"aster_test_8Kq3vT0bX2mN7pQ9rS4tU6wY1zA3cE5gH7jK9lM0","type":"string"}},"required":["secret"],"type":"object"}]},"ApiKeyInput":{"properties":{"abilities":{"description":"Habilidades de la clave. Por defecto, todas las disponibles para su tipo. De\norganización: `invoices:read`, `invoices:write`, `invoices:sign`,\n`invoices:void`, `credit-notes:read|write|sign`, `debit-notes:read|write|sign`,\n`tickets:read|write|sign`, `recipients:read`, `recipients:write`,\n`hacienda:query`, `hacienda:validate`, `settings:read`, `settings:manage`,\n`webhooks:read`, `webhooks:write`, `webhooks:manage`, `reference:read`,\n`documents:export`. De cuenta: `account:manage`.\n","items":{"type":"string"},"type":"array"},"expires_at":{"description":"Vencimiento (futuro).","format":"date-time","type":"string"},"mode":{"enum":["test","live"],"type":"string"},"name":{"maxLength":100,"type":"string"},"organization_id":{"description":"Organización de la clave. Omítalo para una clave de cuenta.","format":"uuid","type":"string"}},"required":["name","mode"],"type":"object"},"ArchiveExport":{"properties":{"created_at":{"format":"date-time","type":"string"},"documents":{"type":["integer","null"]},"environment":{"$ref":"#/components/schemas/Environment"},"error":{"type":["string","null"]},"expires_at":{"format":"date-time","type":["string","null"]},"finished_at":{"format":"date-time","type":["string","null"]},"from":{"format":"date","type":"string"},"id":{"format":"uuid","type":"string"},"size_bytes":{"type":["integer","null"]},"status":{"enum":["pending","running","ready","failed","expired"],"type":"string"},"to":{"format":"date","type":"string"}},"type":"object"},"ArchiveExportRequest":{"properties":{"environment":{"$ref":"#/components/schemas/Environment"},"from":{"format":"date","type":"string"},"to":{"format":"date","type":"string"}},"required":["from","to"],"type":"object"},"Branding":{"properties":{"color":{"example":"#0057FF","type":"string"},"email_reply_to":{"type":"string"},"email_sender_name":{"type":"string"},"footer":{"type":"string"},"has_logo":{"type":"boolean"}},"type":"object"},"BrandingInput":{"properties":{"color":{"description":"Color hexadecimal; vacío lo borra.","pattern":"^(#[0-9A-Fa-f]{6})?$","type":"string"},"email_reply_to":{"maxLength":255,"type":"string"},"email_sender_name":{"maxLength":100,"type":"string"},"footer":{"maxLength":300,"type":"string"},"logo":{"contentEncoding":"base64","description":"PNG o JPEG en base64 (máximo 512 KB); vacío lo borra.","type":"string"}},"type":"object"},"CabysCode":{"properties":{"category_1":{"type":["string","null"]},"category_2":{"type":["string","null"]},"category_3":{"type":["string","null"]},"code":{"type":"string"},"description_1":{"type":["string","null"]},"description_2":{"type":["string","null"]},"description_3":{"type":["string","null"]},"description_9":{"description":"Descripción del bien o servicio.","type":["string","null"]},"id":{"format":"int64","type":"integer"},"rank":{"description":"Relevancia (solo en búsquedas).","type":"number"},"tax_rate":{"description":"Tarifa de IVA sugerida.","type":["string","null"]}},"type":"object"},"CabysCodeDetail":{"additionalProperties":{"type":["string","null"]},"description":"Código CABYS con sus nueve niveles (`category_1`…`category_9`, `description_1`…`description_9`).","properties":{"category_1":{"type":["string","null"]},"category_9":{"type":["string","null"]},"code":{"type":"string"},"description_1":{"type":["string","null"]},"description_9":{"type":["string","null"]},"excludes_note":{"type":["string","null"]},"id":{"format":"int64","type":"integer"},"includes_note":{"type":["string","null"]},"tax_rate":{"type":["string","null"]}},"type":"object"},"CallbackReceivedEvent":{"additionalProperties":true,"description":"Evento reservado; su contenido no está definido.","type":"object"},"CertificateEnvironmentStatus":{"properties":{"has_certificate":{"type":"boolean"},"has_credentials":{"type":"boolean"}},"type":"object"},"CertificateInfo":{"properties":{"expiry_date":{"format":"date","type":"string"},"is_expired":{"type":"boolean"},"serial_number":{"type":"string"},"subject":{"type":"string"}},"type":["object","null"]},"CertificateStatus":{"properties":{"default_environment":{"$ref":"#/components/schemas/Environment"},"production":{"$ref":"#/components/schemas/CertificateEnvironmentStatus"},"staging":{"$ref":"#/components/schemas/CertificateEnvironmentStatus"}},"type":"object"},"CertificateUpload":{"properties":{"atv_password":{"description":"Contraseña ATV.","type":"string"},"atv_user":{"description":"Usuario ATV de Hacienda (correo de comprobantes electrónicos).","type":"string"},"certificate":{"contentEncoding":"base64","description":"Archivo `.p12` de la llave criptográfica, en base64.","type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"pin":{"description":"PIN de la llave.","type":"string"}},"required":["certificate","pin","atv_user","atv_password"],"type":"object"},"CodeBatch":{"properties":{"codes":{"items":{"type":"string"},"maxItems":50,"type":"array"}},"required":["codes"],"type":"object"},"CodeEntry":{"properties":{"code":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"note":{"type":"string"}},"type":"object"},"CommercialCode":{"properties":{"code":{"type":"string"},"type":{"example":"04","type":"string"}},"type":"object"},"CommercialInfo":{"properties":{"credit_terms":{"description":"Plazo del crédito (alias `credit_days`).","type":["string","number"]},"currency":{"description":"Moneda ISO 4217.","example":"CRC","type":"string"},"exchange_rate":{"description":"Tipo de cambio; obligatorio si la moneda no es `CRC`.","type":["number","string"]},"payment_method":{"description":"Medio de pago (Nota 6, `01`–`07`, `99`) o nombre (`cash`, `card`, `check`, `transfer`, `sinpe`, `digital`, `other`).","example":"01","type":"string"},"payment_method_other":{"description":"Obligatorio con `payment_method` `99`.","type":"string"},"sale_condition":{"description":"Condición de venta (Nota 5, `01`–`15`, `99`) o nombre (`cash`, `credit`, `consignment`…).","example":"01","type":"string"},"sale_condition_other":{"description":"Obligatorio con `sale_condition` `99`.","type":"string"}},"required":["currency","sale_condition","payment_method"],"type":"object"},"Counter":{"properties":{"branch":{"example":"001","type":"string"},"document_type":{"example":"01","type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"next_value":{"example":1501,"format":"int64","type":"integer"},"terminal":{"example":"00001","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"},"CounterInput":{"properties":{"branch":{"description":"Sucursal (hasta 3 dígitos).","pattern":"^\\d{1,3}$","type":"string"},"document_type":{"enum":["01","02","03","04","05","06","07","08","09","10"],"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"next_value":{"format":"int64","maximum":9999999999,"minimum":1,"type":"integer"},"terminal":{"description":"Terminal o punto de venta (hasta 5 dígitos).","pattern":"^\\d{1,5}$","type":"string"}},"required":["branch","terminal","document_type","next_value"],"type":"object"},"CurrentKey":{"properties":{"abilities":{"items":{"type":"string"},"type":"array"},"account":{"properties":{"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"status":{"type":"string"}},"type":"object"},"key":{"properties":{"id":{"format":"uuid","type":"string"},"mode":{"enum":["test","live"],"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"}},"type":"object"},"organization":{"properties":{"environment":{"$ref":"#/components/schemas/Environment"},"id":{"format":"uuid","type":"string"},"identification_number":{"type":"string"},"identification_type":{"type":"string"},"name":{"type":"string"}},"type":"object"}},"type":"object"},"Delivery":{"properties":{"email":{"description":"Envía el documento por correo cuando Hacienda lo acepte.","type":"boolean"},"recipients":{"description":"Destinatarios; por defecto, el correo del receptor.","items":{"format":"email","type":"string"},"maxItems":5,"type":"array"}},"type":"object"},"Discount":{"properties":{"amount":{"type":"number"},"code":{"description":"Código de descuento.","type":"string"},"other_code":{"description":"Alias `other_discount_code`.","type":"string"},"reason":{"description":"Naturaleza del descuento (alias `nature`).","type":"string"}},"required":["amount"],"type":"object"},"Document":{"properties":{"consecutive_number":{"type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"currency":{"type":"string"},"document_key":{"type":["string","null"]},"document_type":{"type":"string"},"document_type_name":{"type":["string","null"]},"emisor_identification":{"type":["string","null"]},"emisor_name":{"type":["string","null"]},"environment":{"$ref":"#/components/schemas/Environment"},"exchange_rate":{"type":["number","null"]},"hacienda_message":{"type":["string","null"]},"hacienda_response_at":{"format":"date-time","type":"string"},"hacienda_status":{"type":["string","null"]},"id":{"format":"int64","type":"integer"},"net_amount":{"type":"number"},"pdf_path":{"type":["string","null"]},"processing_time_ms":{"type":["integer","null"]},"receptor_identification":{"type":["string","null"]},"receptor_name":{"type":["string","null"]},"rejections":{"description":"Errores y advertencias de Hacienda, si los hay.","items":{"$ref":"#/components/schemas/Rejection"},"type":"array"},"response_xml":{"description":"XML de respuesta de Hacienda, si ya existe.","type":"string"},"signed_xml":{"description":"XML firmado.","type":"string"},"status":{"$ref":"#/components/schemas/DocumentStatus"},"tax_amount":{"type":"number"},"total_amount":{"type":"number"},"transaction_id":{"type":"string"},"updated_at":{"format":"date-time","type":"string"},"xml_path":{"type":["string","null"]}},"type":"object"},"DocumentBlock":{"properties":{"activity_code":{"description":"Código de actividad económica del emisor (por ejemplo `620100` o `9511.0`). Obligatorio salvo en facturas de compra.","type":"string"},"branch":{"description":"Sucursal (alias `sucursal`). Por defecto `001`.","type":"string"},"clave":{"description":"Clave numérica propia (alias `key`). Debe enviarse con `consecutive_number`.","pattern":"^[0-9A-Z]{50}$","type":"string"},"consecutive_number":{"description":"Consecutivo propio de 20 dígitos (alias `consecutive`).","pattern":"^\\d{20}$","type":"string"},"date":{"description":"Fecha de emisión (ISO 8601 con zona horaria). No puede ser futura.","format":"date-time","type":"string"},"document_type":{"description":"`01` factura, `02` nota de débito, `03` nota de crédito, `04` tiquete, `08` factura de compra, `09` factura de exportación, `10` recibo electrónico de pago.","enum":["01","02","03","04","08","09","10"],"type":"string"},"provider_system_id":{"description":"Identificación del proveedor de sistemas. Opcional con claves de organización (por defecto, AstraNexo).","type":"string"},"situation":{"description":"`1` normal, `2` contingencia, `3` sin internet.","enum":["1","2","3"],"type":"string"},"terminal":{"description":"Terminal (alias `punto_venta`). Por defecto `00001`.","type":"string"}},"required":["document_type","date","situation"],"type":"object"},"DocumentListItem":{"properties":{"consecutive_number":{"type":["string","null"]},"created_at":{"format":"date-time","type":"string"},"currency":{"type":"string"},"document_key":{"type":["string","null"]},"document_type":{"description":"Tipo (`01`–`10`, o `RC` para mensajes receptor).","type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"hacienda_response_at":{"format":"date-time","type":["string","null"]},"hacienda_status":{"type":["string","null"]},"id":{"description":"Id del documento (también sirve como cursor).","type":"string"},"receptor_identification":{"type":["string","null"]},"receptor_name":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/DocumentStatus"},"total":{"type":"number"}},"type":"object"},"DocumentListResponse":{"properties":{"api_version":{"type":"string"},"data":{"items":{"$ref":"#/components/schemas/DocumentListItem"},"type":"array"},"next_cursor":{"description":"Cursor de la página siguiente; `null` si no hay más.","type":["string","null"]},"success":{"const":true,"type":"boolean"},"timestamp":{"format":"date-time","type":"string"}},"required":["success","data","timestamp","api_version"],"type":"object"},"DocumentQueuedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEventPayload"},{"properties":{"document_key":{"type":"string"},"hacienda_status":{"const":"queued","type":"string"},"signed_xml_path":{"type":"string"},"status":{"const":"queued","type":"string"}},"required":["document_key","status"],"type":"object"}]},"DocumentResolution":{"properties":{"clave":{"type":"string"},"hacienda_message":{"type":["string","null"]},"hacienda_response_at":{"format":"date-time","type":"string"},"hacienda_status":{"type":["string","null"]},"status":{"type":["string","null"]}},"type":"object"},"DocumentSignedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEventPayload"},{"properties":{"consecutive_number":{"type":"string"},"document_key":{"type":"string"},"document_type":{"description":"Tipo del documento, o `RC` para mensajes receptor.","type":"string"},"document_type_name":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"signed_xml_path":{"type":"string"}},"required":["document_key","document_type","environment"],"type":"object"}]},"DocumentStatus":{"description":"Estado del documento en Aster: `processing` (firmado, enviándose), `sent`, `queued` (Hacienda no disponible; se reintenta), `accepted`, `rejected`, `error` (nunca llegó a Hacienda).","enum":["processing","sent","queued","accepted","rejected","error"],"type":"string"},"DocumentSubmitted":{"properties":{"consecutive_number":{"description":"Consecutivo de 20 dígitos.","type":"string"},"document_key":{"description":"Clave numérica de 50 caracteres.","type":"string"},"document_type":{"type":"string"},"document_type_name":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"id":{"format":"int64","type":"integer"},"queued_at":{"format":"date-time","type":"string"},"signed_xml_path":{"description":"Ruta interna del XML firmado (descárguelo con `GET /documents/{key}/xml`).","type":"string"},"simulated":{"description":"Presente y `true` cuando el veredicto será simulado.","type":"boolean"},"status":{"const":"processing","type":"string"},"storage_status":{"enum":["cloud","local_fallback"],"type":"string"},"tenant_uuid":{"format":"uuid","type":"string"}},"type":"object"},"DocumentVerdictEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEventPayload"},{"properties":{"document_key":{"type":"string"},"document_type":{"description":"Tipo del documento, o `RC` para mensajes receptor.","type":"string"},"hacienda_message":{"description":"Detalle del mensaje de Hacienda.","type":"string"},"hacienda_status":{"enum":["accepted","rejected"],"type":"string"},"response_xml_path":{"type":"string"},"signed_xml_path":{"type":"string"},"status":{"enum":["accepted","rejected"],"type":"string"}},"required":["document_key","document_type","status"],"type":"object"}]},"DocumentVoidedEvent":{"allOf":[{"$ref":"#/components/schemas/WebhookEventPayload"},{"properties":{"credit_note_key":{"description":"Clave de la nota de crédito que lo anula.","type":"string"},"document_key":{"description":"Clave del documento anulado.","type":"string"},"hacienda_message":{"type":"string"},"hacienda_status":{"const":"accepted","type":"string"}},"required":["document_key","credit_note_key"],"type":"object"}]},"DraftValidationRequest":{"properties":{"document_type":{"type":"string"},"issuer":{"additionalProperties":true,"properties":{"identification_number":{"type":"string"},"identification_type":{"type":"string"},"name":{"type":"string"}},"type":"object"},"items":{"items":{},"type":"array"},"receiver":{"additionalProperties":true,"type":"object"},"totals":{"additionalProperties":true,"type":"object"}},"type":"object"},"DraftValidationResult":{"properties":{"errors":{"items":{"type":"string"},"type":["array","null"]},"valid":{"type":"boolean"},"warnings":{"items":{"type":"string"},"type":["array","null"]}},"type":"object"},"ElectronicDocumentRequest":{"properties":{"api_config":{"$ref":"#/components/schemas/ApiConfig"},"callback_url":{"description":"URL adicional que recibe los webhooks de este documento (firmados con el secreto del primer webhook activo, si existe).","format":"uri","type":"string"},"commercial_info":{"$ref":"#/components/schemas/CommercialInfo"},"delivery":{"$ref":"#/components/schemas/Delivery"},"document":{"$ref":"#/components/schemas/DocumentBlock"},"environment":{"$ref":"#/components/schemas/Environment"},"issuer":{"$ref":"#/components/schemas/Party"},"items":{"items":{"$ref":"#/components/schemas/Item"},"minItems":1,"type":"array"},"other_charges":{"items":{"$ref":"#/components/schemas/OtherCharge"},"type":"array"},"receiver":{"$ref":"#/components/schemas/Receiver"},"reference":{"$ref":"#/components/schemas/Reference"},"totals":{"$ref":"#/components/schemas/Totals"}},"required":["document","commercial_info","issuer","items"],"type":"object"},"EmailRequest":{"properties":{"recipients":{"items":{"format":"email","type":"string"},"maxItems":5,"minItems":1,"type":"array"}},"required":["recipients"],"type":"object"},"Envelope":{"description":"Envoltura de las respuestas exitosas.","properties":{"api_version":{"example":"1.0","type":"string"},"data":{"description":"Contenido de la respuesta."},"message":{"description":"Mensaje legible (en inglés) de algunas operaciones.","type":"string"},"success":{"const":true,"type":"boolean"},"timestamp":{"format":"date-time","type":"string"}},"required":["success","timestamp","api_version"],"type":"object"},"Environment":{"description":"Ambiente de Hacienda. Con claves de Aster lo decide la clave.","enum":["staging","production"],"type":"string"},"ErrorEnvelope":{"description":"Envoltura de los errores.","properties":{"api_version":{"example":"1.0","type":"string"},"error":{"$ref":"#/components/schemas/ErrorPayload"},"message":{"description":"Repite `error.message` en los errores de autenticación, permisos, límites, idempotencia y cuota.","type":"string"},"success":{"const":false,"type":"boolean"},"timestamp":{"format":"date-time","type":"string"}},"required":["success","error","timestamp","api_version"],"type":"object"},"ErrorPayload":{"properties":{"code":{"description":"Código estable del error, para usar en el código del cliente.","example":"validation_error","type":"string"},"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Mensajes por campo (ruta con puntos, por ejemplo `items.0.cabys_code`).","type":"object"},"message":{"description":"Descripción legible.","type":"string"}},"required":["code","message"],"type":"object"},"ExchangeRate":{"properties":{"buy":{"type":"number"},"date":{"format":"date","type":"string"},"entity":{"type":"string"},"note":{"description":"Motivo cuando el tipo de cambio no está disponible.","type":"string"},"sell":{"type":"number"},"source":{"description":"Origen del tipo de cambio — `hacienda` o `bccr` (referencia), `ventanilla` (tasa de una entidad autorizada), `mercado` (otras monedas) o `unavailable`.","type":"string"}},"type":"object"},"ExchangeRateEntity":{"properties":{"buy":{"type":"number"},"date":{"format":"date","type":"string"},"entity":{"example":"Banco BAC San José S.A.","type":"string"},"provider":{"type":"string"},"sell":{"type":"number"}},"type":"object"},"ExchangeRatePair":{"properties":{"buy":{"type":"number"},"date":{"format":"date","type":"string"},"entity":{"type":"string"},"fallback":{"description":"Se pidió una entidad que no estaba disponible y respondió la cadena de referencia.","type":"boolean"},"from":{"type":"string"},"note":{"type":"string"},"rate":{"description":"Igual a `sell`.","type":"number"},"sell":{"type":"number"},"source":{"type":"string"},"stale":{"description":"Se usó el último valor guardado.","type":"boolean"},"to":{"type":"string"}},"type":"object"},"Exoneration":{"properties":{"amount":{"description":"Monto exonerado (alias `exonerated_amount`).","type":"number"},"article":{"type":["string","integer"]},"document_number":{"type":"string"},"document_type":{"description":"Tipo de documento de exoneración (alias `type`).","type":"string"},"emission_date":{"format":"date-time","type":"string"},"inciso":{"type":["string","integer"]},"institution":{"description":"Código de la institución que emite la exoneración.","type":"string"},"institution_name":{"type":"string"},"percentage":{"description":"Puntos porcentuales exonerados (alias `exonerated_rate`).","type":"number"},"type_other":{"type":"string"}},"required":["document_type","document_number","institution","emission_date"],"type":"object"},"HaciendaEnvironmentStatus":{"properties":{"available":{"type":"boolean"},"has_certificate":{"type":"boolean"},"has_credentials":{"type":"boolean"},"last_check":{"format":"date-time","type":"string"},"response_time_ms":{"type":"number"}},"type":"object"},"HaciendaQueryResult":{"properties":{"clave":{"type":"string"},"details":{"type":"string"},"error_codes":{"items":{"type":"string"},"type":["array","null"]},"ind_estado":{"example":"aceptado","type":"string"},"message":{"type":"string"},"status":{"example":"aceptado","type":"string"}},"type":"object"},"HaciendaStatus":{"properties":{"checked_at":{"format":"date-time","type":"string"},"default_environment":{"$ref":"#/components/schemas/Environment"},"production":{"$ref":"#/components/schemas/HaciendaEnvironmentStatus"},"staging":{"$ref":"#/components/schemas/HaciendaEnvironmentStatus"}},"type":"object"},"IdentificationType":{"description":"Tipo de identificación: `01` física, `02` jurídica, `03` DIMEX, `04` NITE.","enum":["01","02","03","04"],"type":"string"},"ImportResult":{"properties":{"imported":{"type":"integer"},"problems":{"items":{"properties":{"file":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"type":"array"},"skipped":{"type":"integer"}},"type":"object"},"Item":{"properties":{"cabys_code":{"description":"Código CABYS de 13 dígitos. Debe existir.","type":"string"},"commercial_codes":{"items":{"$ref":"#/components/schemas/CommercialCode"},"type":"array"},"description":{"maxLength":200,"type":"string"},"discount":{"description":"Descuentos.","items":{"$ref":"#/components/schemas/Discount"},"type":"array"},"discounts":{"description":"Alias de `discount`.","items":{"$ref":"#/components/schemas/Discount"},"type":"array"},"exoneration":{"$ref":"#/components/schemas/Exoneration"},"export_amount":{"type":"number"},"is_service":{"description":"Solo se usa si el CABYS falta o no es numérico.","type":"boolean"},"line_number":{"description":"Número de línea (se asigna si se omite).","type":"integer"},"medication_registry":{"description":"Registro de medicamentos.","type":"string"},"net_tax":{"description":"Se recalcula a partir de los impuestos.","type":"number"},"pharmaceutical_form":{"description":"Forma farmacéutica.","type":"string"},"price":{"description":"Precio unitario.","minimum":0,"type":"number"},"quantity":{"exclusiveMinimum":0,"type":"number"},"subtotal":{"description":"Se calcula si se omite.","type":"number"},"surtido_items":{"description":"Componentes de un surtido o combo.","items":{"$ref":"#/components/schemas/SurtidoItem"},"type":"array"},"tariff_code":{"description":"Partida arancelaria (facturas de exportación).","type":"string"},"tax":{"description":"Impuestos de la línea; acepta un objeto o un arreglo.","oneOf":[{"items":{"$ref":"#/components/schemas/Tax"},"type":"array"},{"$ref":"#/components/schemas/Tax"}]},"total":{"description":"Se recalcula a partir de los impuestos.","type":"number"},"transaction_type":{"description":"Tipo de transacción (FE 4.4).","type":"string"},"unit":{"description":"Unidad de medida. Las de servicio (`Sp`, `Os`, `Spe`, `St`, `Al`…) requieren un CABYS de servicio (5–9) y las de bienes uno de bienes (0–4).","example":"Unid","type":"string"},"unit_price":{"description":"Alias de `price`.","minimum":0,"type":"number"}},"required":["cabys_code","quantity","unit","description"],"type":"object"},"LocationUnit":{"properties":{"code":{"type":"string"},"full_code":{"type":"string"},"id":{"format":"int64","type":"integer"},"name":{"type":"string"}},"type":"object"},"Organization":{"properties":{"certificate_live":{"description":"Tiene llave criptográfica de producción.","type":"boolean"},"certificate_test":{"description":"Tiene llave criptográfica de staging.","type":"boolean"},"created_at":{"format":"date-time","type":"string"},"economic_activities":{"items":{"type":"string"},"type":"array"},"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"identification_number":{"type":"string"},"identification_type":{"$ref":"#/components/schemas/IdentificationType"},"legal_name":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"}},"type":"object"},"OrganizationInput":{"properties":{"economic_activities":{"description":"Códigos de actividad económica (4 a 6 caracteres).","items":{"maxLength":6,"minLength":4,"type":"string"},"type":"array"},"email":{"format":"email","maxLength":160,"type":"string"},"identification_number":{"description":"Identificación del contribuyente (las jurídicas pueden contener letras mayúsculas).","type":"string"},"identification_type":{"$ref":"#/components/schemas/IdentificationType"},"legal_name":{"description":"Razón social; por defecto, `name`.","type":"string"},"name":{"maxLength":100,"type":"string"},"phone":{"maxLength":20,"type":"string"}},"required":["name","identification_type","identification_number","email"],"type":"object"},"OrganizationProfile":{"properties":{"created_at":{"format":"date-time","type":"string"},"default_environment":{"$ref":"#/components/schemas/Environment"},"economic_activities":{"items":{"type":"string"},"type":["array","null"]},"email":{"type":["string","null"]},"id":{"description":"Id interno.","format":"int64","type":"integer"},"identification_number":{"type":["string","null"]},"identification_type":{"type":["string","null"]},"is_active":{"type":"boolean"},"legal_name":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"logo_width":{"type":["integer","null"]},"name":{"type":"string"},"phone":{"type":["string","null"]},"plan":{"type":"string"},"rate_limits":{"properties":{"per_day":{"type":"integer"},"per_minute":{"type":"integer"}},"type":"object"},"uuid":{"format":"uuid","type":"string"}},"type":"object"},"OrganizationProfileUpdate":{"description":"Campos a cambiar.","properties":{"default_environment":{"$ref":"#/components/schemas/Environment"},"economic_activities":{"items":{"type":"string"},"type":"array"},"email":{"format":"email","type":"string"},"identification_number":{"type":"string"},"identification_type":{"$ref":"#/components/schemas/IdentificationType"},"legal_name":{"type":"string"},"logo_url":{"type":"string"},"logo_width":{"type":"integer"},"name":{"type":"string"},"phone":{"type":"string"}},"type":"object"},"OrganizationUpdate":{"description":"Campos a cambiar. La identificación no se puede cambiar.","properties":{"economic_activities":{"items":{"maxLength":6,"minLength":4,"type":"string"},"type":"array"},"email":{"format":"email","maxLength":160,"type":"string"},"legal_name":{"type":"string"},"name":{"maxLength":100,"type":"string"},"phone":{"maxLength":20,"type":"string"}},"type":"object"},"OtherCharge":{"properties":{"amount":{"type":"number"},"detail":{"type":"string"},"document_type":{"description":"Tipo de otro cargo (Nota 16), por ejemplo `06` impuesto de servicio 10 %.","type":"string"},"id_number":{"description":"Identificación del tercero.","type":"string"},"name":{"description":"Nombre del tercero.","type":"string"},"percentage":{"type":"number"}},"required":["document_type","amount"],"type":"object"},"Pack":{"properties":{"code":{"example":"pack_500","type":"string"},"docs":{"example":500,"type":"integer"},"price_cents":{"description":"Precio en centavos de USD, sin IVA.","example":2000,"type":"integer"}},"type":"object"},"PaginationMeta":{"properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"format":"int64","type":"integer"}},"type":"object"},"Party":{"description":"Emisor o receptor.","properties":{"address":{"$ref":"#/components/schemas/Address"},"commercial_name":{"type":"string"},"email":{"format":"email","type":"string"},"foreign_address":{"description":"Dirección en el extranjero (facturas de exportación).","type":"string"},"id":{"description":"Número de identificación.","type":"string"},"location":{"$ref":"#/components/schemas/Address"},"name":{"type":"string"},"phone":{"$ref":"#/components/schemas/Phone"},"type":{"description":"Tipo de identificación: `01` física, `02` jurídica, `03` DIMEX, `04` NITE, `05` extranjero no domiciliado, `06` no contribuyente; o nombre (`fisica`, `juridica`, `dimex`, `nite`, `extranjero`).","example":"02","type":"string"}},"required":["type","id","name"],"type":"object"},"Phone":{"description":"Teléfono como texto (`\"22223333\"`, código de país 506) u objeto.","oneOf":[{"type":"string"},{"properties":{"country_code":{"example":"506","type":"string"},"number":{"example":"22223333","type":"string"}},"type":"object"}]},"Plan":{"properties":{"active_org_cents":{"description":"Cargo por organización activa en el período, en centavos de USD.","type":"integer"},"archive_included":{"description":"Si el plan incluye Archeion (Escala y Plataforma).","type":"boolean"},"code":{"example":"crecimiento","type":"string"},"included_docs":{"description":"Documentos incluidos por período.","example":3000,"type":"integer"},"live_allowed":{"description":"Si el plan permite documentos de producción.","type":"boolean"},"max_organizations":{"description":"Organizaciones permitidas (0 = sin límite).","example":10,"type":"integer"},"monthly_price_cents":{"description":"Precio mensual en centavos de USD, sin IVA.","example":4900,"type":"integer"},"name":{"example":"Crecimiento","type":"string"},"yearly_price_cents":{"description":"Precio anual en centavos de USD, sin IVA.","example":49000,"type":"integer"}},"type":"object"},"PriceList":{"properties":{"currency":{"const":"USD","type":"string"},"iva_rate":{"example":0.13,"type":"number"},"packs":{"items":{"$ref":"#/components/schemas/Pack"},"type":"array"},"plans":{"items":{"$ref":"#/components/schemas/Plan"},"type":"array"}},"type":"object"},"Province":{"properties":{"code":{"type":"string"},"id":{"format":"int64","type":"integer"},"name":{"type":"string"}},"type":"object"},"QuotaError":{"description":"Error 402 de cuota o plan.","properties":{"api_version":{"example":"1.0","type":"string"},"error":{"properties":{"code":{"enum":["quota_exceeded","plan_required","payment_required","subscription_expired"],"type":"string"},"message":{"type":"string"},"pack_url":{"description":"Dónde comprar un paquete de documentos.","format":"uri","type":"string"},"upgrade_url":{"description":"Dónde cambiar de plan.","format":"uri","type":"string"},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["code","message"],"type":"object"},"message":{"type":"string"},"success":{"const":false,"type":"boolean"},"timestamp":{"format":"date-time","type":"string"}},"required":["success","error","timestamp","api_version"],"type":"object"},"Receiver":{"allOf":[{"$ref":"#/components/schemas/Party"},{"properties":{"activity_code":{"description":"Actividad económica del receptor.","type":"string"}},"type":"object"}],"description":"Receptor. Obligatorio salvo en tiquetes."},"ReceptorMessageRequest":{"properties":{"activity_code":{"description":"Actividad económica del receptor (alias `codigo_actividad`).","pattern":"^(\\d{6}|\\d{2,4}\\.\\d{1,2})$","type":"string"},"callback_url":{"format":"uri","type":"string"},"clave":{"description":"Clave del comprobante recibido (alias `key`).","pattern":"^[0-9A-Z]{50}$","type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"issue_date":{"description":"Fecha de emisión del comprobante (alias `fecha_emision`, `date`).","type":"string"},"issuer_id":{"description":"Identificación del emisor del comprobante (alias `emisor_id`, `cedula_emisor`).","pattern":"^[0-9A-Z]+$","type":"string"},"issuer_id_type":{"description":"Tipo de identificación del emisor (alias `emisor_id_type`, `tipo_emisor`).","type":"string"},"language":{"enum":["es","en"],"type":"string"},"message":{"description":"`1` aceptación, `2` aceptación parcial, `3` rechazo (alias `mensaje`). Acepta número o texto.","oneOf":[{"enum":[1,2,3],"type":"integer"},{"enum":["1","2","3"],"type":"string"}]},"message_detail":{"description":"Detalle; obligatorio en la aceptación parcial (alias `detalle_mensaje`, `detail`).","maxLength":160,"type":"string"},"original_doc_type":{"default":"01","description":"Tipo del comprobante recibido (alias `tipo_documento_original`).","type":"string"},"receiver_id":{"description":"Identificación de la organización receptora (alias `receptor_id`, `cedula_receptor`).","pattern":"^[0-9A-Z]+$","type":"string"},"receiver_id_type":{"description":"Tipo de identificación del receptor (alias `receptor_id_type`, `tipo_receptor`).","type":"string"},"tax_condition":{"description":"Condición del impuesto (alias `condicion_impuesto`).","enum":["01","02","03","04","05"],"type":"string"},"total":{"description":"Total del comprobante (alias `total_factura`).","exclusiveMinimum":0,"type":"number"},"total_applicable_expense":{"description":"Gasto aplicable (alias `monto_total_gasto_aplicable`).","type":"number"},"total_tax":{"description":"Impuesto total del comprobante (alias `total_impuesto`, `monto_total_impuesto`).","type":"number"},"total_tax_credit":{"description":"Impuesto a acreditar (alias `monto_total_impuesto_acreditar`).","type":"number"}},"required":["clave","message","issuer_id","issuer_id_type","receiver_id","receiver_id_type","issue_date","total"],"type":"object"},"Recipient":{"properties":{"canton":{"type":["string","null"]},"commercial_name":{"type":["string","null"]},"country_code":{"type":["string","null"]},"created_at":{"format":"date-time","type":["string","null"]},"district":{"type":["string","null"]},"email":{"type":["string","null"]},"fax":{"type":["string","null"]},"id":{"format":"int64","type":"integer"},"identification_number":{"type":"string"},"identification_type":{"type":"string"},"is_foreign":{"type":"boolean"},"name":{"type":"string"},"neighborhood":{"type":["string","null"]},"notes":{"type":["string","null"]},"other_address":{"type":["string","null"]},"phone":{"type":["string","null"]},"province":{"type":["string","null"]},"updated_at":{"format":"date-time","type":["string","null"]}},"type":"object"},"RecipientInput":{"properties":{"canton":{"type":"string"},"commercial_name":{"type":"string"},"country_code":{"type":"string"},"district":{"type":"string"},"email":{"format":"email","type":"string"},"fax":{"type":"string"},"identification_number":{"type":"string"},"identification_type":{"$ref":"#/components/schemas/IdentificationType"},"is_foreign":{"type":"boolean"},"name":{"type":"string"},"neighborhood":{"type":"string"},"notes":{"type":"string"},"other_address":{"type":"string"},"phone":{"type":"string"},"province":{"type":"string"}},"required":["name","identification_type","identification_number"],"type":"object"},"RecipientSummary":{"properties":{"email":{"type":["string","null"]},"id":{"format":"int64","type":"integer"},"identification_number":{"type":"string"},"identification_type":{"type":"string"},"name":{"type":"string"},"phone":{"type":["string","null"]}},"type":"object"},"Reference":{"description":"Documento de referencia (notas de crédito y débito, sustituciones, recibos de pago).","properties":{"code":{"description":"Motivo (Nota 9, `01`–`17`, `99`).","type":"string"},"code_other_description":{"description":"Obligatorio con `code` `99`.","type":"string"},"date":{"description":"Fecha del documento referido.","type":"string"},"document_type":{"description":"Tipo de documento referido (Nota 10, `01`–`20`, `99`; alias `type`).","type":"string"},"number":{"description":"Clave (50 caracteres) o número del documento referido.","type":"string"},"reason":{"description":"Explicación.","type":"string"},"type_other":{"description":"Obligatorio con `document_type` `99`.","type":"string"}},"required":["document_type","date"],"type":"object"},"Rejection":{"properties":{"col":{"type":"integer"},"description":{"type":"string"},"element_name":{"type":"string"},"error_code":{"example":"-53","type":"string"},"friendly_message":{"type":"string"},"location":{"type":"string"},"message":{"type":"string"},"row":{"type":"integer"}},"type":"object"},"Retention":{"properties":{"class":{"enum":["standard","archive","internal"],"type":"string"},"description":{"type":"string"}},"type":"object"},"ServiceCheck":{"properties":{"available":{"type":"boolean"},"message":{"type":"string"},"response_time_ms":{"type":"number"}},"type":"object"},"ServiceStatus":{"properties":{"database":{"enum":["connected","disconnected"],"type":"string"},"hacienda":{"additionalProperties":{"properties":{"api":{"$ref":"#/components/schemas/ServiceCheck"},"available":{"type":"boolean"},"checked_at":{"format":"date-time","type":"string"},"message":{"enum":["ok","token_unavailable","api_unavailable","down"],"type":"string"},"response_time_ms":{"type":"number"},"token":{"$ref":"#/components/schemas/ServiceCheck"}},"type":"object"},"description":"Disponibilidad de Hacienda por ambiente (`staging`, `production`).","type":"object"},"status":{"description":"`degraded` (con HTTP 503) cuando la API no puede atender solicitudes.","enum":["ok","degraded"],"type":"string"},"timestamp":{"format":"date-time","type":"string"},"version":{"example":"1.0","type":"string"}},"type":"object"},"SurtidoItem":{"properties":{"cabys_code":{"type":"string"},"description":{"type":"string"},"discount":{"items":{"properties":{"amount":{"type":"number"},"code":{"type":"string"}},"type":"object"},"type":"array"},"price":{"type":"number"},"quantity":{"type":"number"},"subtotal":{"type":"number"},"tax":{"items":{"properties":{"amount":{"type":"number"},"rate":{"type":"number"},"rate_type":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":"array"},"total":{"type":"number"},"unit":{"type":"string"}},"type":"object"},"TariffCode":{"properties":{"chapter":{"type":["string","null"]},"code":{"type":"string"},"description":{"type":"string"},"heading":{"type":["string","null"]},"id":{"format":"int64","type":"integer"},"is_leaf":{"description":"Partida final, utilizable en un comprobante.","type":"boolean"},"level":{"type":"integer"},"rank":{"description":"Relevancia (solo en búsquedas).","type":"number"}},"type":"object"},"TariffCodeDetail":{"allOf":[{"$ref":"#/components/schemas/TariffCode"},{"properties":{"children":{"items":{"$ref":"#/components/schemas/TariffCode"},"type":"array"},"parent_code":{"type":["string","null"]}},"type":"object"}]},"Tax":{"properties":{"amount":{"description":"Monto del impuesto; se calcula si se omite.","type":"number"},"assumed_tax_amount":{"description":"Impuesto asumido por el emisor.","type":"number"},"exoneration_amount":{"description":"Monto exonerado; se calcula a partir de la exoneración de la línea.","type":"number"},"rate":{"description":"Tarifa en porcentaje.","example":13,"type":"number"},"rate_code":{"description":"Código de tarifa IVA (alias `rate_type`): `01` 0 %, `02` 1 %, `03` 2 %, `04` 4 %, `05` transitorio 0 %, `06` transitorio 4 %, `07` transitorio 8 %, `08` general 13 %, `09` reducida 0,5 %, `10` exenta, `11` 0 % sin derecho a crédito.","enum":["01","02","03","04","05","06","07","08","09","10","11"],"type":"string"},"taxable_base":{"description":"Base imponible especial.","type":"number"},"type":{"description":"Código de impuesto: `01` IVA, `02` selectivo de consumo, … `99` otros.","example":"01","type":"string"}},"required":["type"],"type":"object"},"TaxRateEntry":{"properties":{"code":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"rate":{"type":["number","null"]}},"type":"object"},"Taxpayer":{"properties":{"apellidos":{"type":"string"},"cedula":{"type":"string"},"class":{"type":"string"},"id_raw":{"type":"string"},"nombre":{"description":"Nombre completo (personas físicas).","type":"string"},"primer_apellido":{"type":"string"},"primer_nombre":{"type":"string"},"razon_social":{"description":"Razón social (personas jurídicas).","type":"string"},"segundo_apellido":{"type":"string"},"segundo_nombre":{"type":"string"},"tipo":{"enum":["F","J"],"type":"string"},"tipo_texto":{"type":"string"}},"type":"object"},"TaxpayerSearchResult":{"description":"Solo una de las listas está presente.","properties":{"cedulas_fisicas":{"items":{"$ref":"#/components/schemas/Taxpayer"},"type":"array"},"cedulas_juridicas":{"items":{"$ref":"#/components/schemas/Taxpayer"},"type":"array"},"query":{"description":"Término buscado (solo cuando no hay resultados).","type":"string"},"taxpayers":{"items":{"$ref":"#/components/schemas/Taxpayer"},"type":"array"}},"type":"object"},"Totals":{"description":"Resumen del comprobante. El servidor lo recalcula a partir de las líneas; solo `total_other_charges` y `total_iva_returned` se toman de la solicitud. Acepta también los alias `sales`, `discounts`, `net_sales`, `taxes`, `other_charges` y un bloque `breakdown`.","properties":{"total":{"type":"number"},"total_assumed_tax":{"type":"number"},"total_discount":{"type":"number"},"total_exempt_goods":{"type":"number"},"total_exempt_services":{"type":"number"},"total_exonerated_goods":{"type":"number"},"total_exonerated_services":{"type":"number"},"total_iva_returned":{"description":"IVA devuelto (servicios de salud pagados con tarjeta).","type":"number"},"total_net_sales":{"type":"number"},"total_no_sujeta_goods":{"type":"number"},"total_no_sujeto_services":{"type":"number"},"total_other_charges":{"type":"number"},"total_sales":{"type":"number"},"total_taxed_goods":{"type":"number"},"total_taxed_services":{"type":"number"},"total_taxes":{"type":"number"}},"type":"object"},"Usage":{"properties":{"active_organizations":{"description":"Organizaciones con al menos un documento de producción en el período.","type":"integer"},"in_flight":{"description":"Documentos de producción esperando el veredicto de Hacienda (cuentan contra la cuota).","type":"integer"},"included_docs":{"type":"integer"},"pack_remaining":{"description":"Documentos restantes de paquetes.","type":"number"},"period_end":{"format":"date-time","type":"string"},"period_start":{"format":"date-time","type":"string"},"plan":{"type":"string"},"remaining":{"description":"Documentos que aún pueden enviarse en el período (plan + paquetes).","type":"number"},"status":{"enum":["sandbox","active","past_due","canceled"],"type":"string"},"used":{"description":"Documentos consumidos (1 por documento, 0,5 por mensaje receptor).","type":"number"}},"type":"object"},"ValidationError":{"allOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"properties":{"error":{"properties":{"code":{"const":"validation_error","type":"string"},"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},"message":{"description":"Resumen de todos los mensajes, separados por ` | `.","type":"string"}},"required":["code","message","errors"],"type":"object"}},"type":"object"}],"description":"Error `422 validation_error` con los mensajes por campo."},"VoidRequest":{"properties":{"branch":{"description":"Sucursal de la nota de crédito (por defecto, la del original).","type":"string"},"reason":{"description":"Motivo de la anulación. Por defecto «Anula documento de referencia».","maxLength":180,"type":"string"},"terminal":{"description":"Terminal de la nota de crédito (por defecto, la del original).","type":"string"}},"type":"object"},"VoidSubmitted":{"allOf":[{"$ref":"#/components/schemas/DocumentSubmitted"},{"properties":{"voids":{"description":"Clave del documento que se anula.","type":"string"}},"type":"object"}]},"Webhook":{"properties":{"created_at":{"format":"date-time","type":"string"},"disabled_at":{"format":"date-time","type":["string","null"]},"disabled_reason":{"type":["string","null"]},"events":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"failure_count":{"description":"Entregas fallidas consecutivas; a las 10 el webhook se desactiva.","type":"integer"},"id":{"format":"int64","type":"integer"},"is_active":{"type":"boolean"},"last_triggered_at":{"format":"date-time","type":["string","null"]},"max_retries":{"type":"integer"},"name":{"type":"string"},"timeout_seconds":{"type":"integer"},"updated_at":{"format":"date-time","type":"string"},"url":{"format":"uri","type":"string"},"uuid":{"format":"uuid","type":"string"}},"type":"object"},"WebhookCreated":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"properties":{"secret":{"description":"Secreto para verificar las firmas. Solo se muestra al crear o regenerar.","type":"string"}},"required":["secret"],"type":"object"}]},"WebhookDelivery":{"properties":{"attempt":{"description":"Número de intento dentro de la entrega.","type":"integer"},"delivered_at":{"format":"date-time","type":["string","null"]},"error":{"type":["string","null"]},"event":{"type":"string"},"id":{"description":"Id del intento (para reenviarlo).","format":"int64","type":"integer"},"response_status":{"type":["integer","null"]},"response_time_ms":{"type":["number","null"]},"successful":{"type":"boolean"}},"type":"object"},"WebhookEvent":{"description":"Eventos suscribibles. `document.created`, `document.error` y `callback.received` se aceptan pero actualmente no se emiten.","enum":["document.signed","document.queued","document.accepted","document.rejected","document.voided","document.created","document.error","callback.received"],"type":"string"},"WebhookEventPayload":{"description":"Base de los cuerpos de los eventos de documento. El cuerpo es el objeto del evento,\nsin envoltura; el nombre del evento viaja en `X-Webhook-Event`. Las entregas se\nreintentan hasta `1 + max_retries` veces (máximo 7) a los 5 s, 30 s, 2 min, 10 min,\n1 h y 6 h; cualquier 2xx es éxito. Tras 10 entregas fallidas consecutivas el\nwebhook se desactiva. Una entrega reintentada conserva su `X-Webhook-ID`.\n","properties":{"document_key":{"description":"Clave numérica del documento.","type":"string"}},"required":["document_key"],"type":"object"},"WebhookInput":{"properties":{"events":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"minItems":1,"type":"array"},"is_active":{"default":true,"type":"boolean"},"max_retries":{"default":3,"description":"Reintentos tras el primer intento (fuera de rango se usa 3; como máximo se hacen 7 intentos en total).","maximum":10,"minimum":0,"type":"integer"},"name":{"type":"string"},"timeout_seconds":{"default":30,"description":"Tiempo de espera por intento (fuera de rango se usa 30).","maximum":60,"minimum":5,"type":"integer"},"url":{"description":"`https://`, host público, sin credenciales.","format":"uri","type":"string"}},"required":["name","url","events"],"type":"object"},"WebhookSecret":{"properties":{"id":{"format":"int64","type":"integer"},"secret":{"type":"string"}},"type":"object"},"WebhookTestResult":{"properties":{"delivery":{"properties":{"response_time_ms":{"type":"number"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"event":{"const":"test","type":"string"},"payload":{"properties":{"message":{"type":"string"},"timestamp":{"format":"date-time","type":"string"},"webhook_id":{"format":"uuid","type":"string"}},"type":"object"}},"type":"object"},"WebhookUpdate":{"properties":{"events":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"is_active":{"type":"boolean"},"max_retries":{"type":"integer"},"name":{"type":"string"},"timeout_seconds":{"type":"integer"},"url":{"format":"uri","type":"string"}},"type":"object"}},"securitySchemes":{"ApiKey":{"description":"Tu llave de API en el encabezado `Authorization: Bearer \u003cllave\u003e`: `aster_test_…` (pruebas) o `aster_live_…` (producción).","scheme":"bearer","type":"http"}}},"info":{"contact":{"email":"app@astranexo.com","name":"Soporte de Aster","url":"https://astranexo.com/soporte"},"description":"API de **Aster** para emitir y recibir comprobantes electrónicos de Costa Rica\nconforme a la versión 4.4 de Hacienda: factura (01), nota de débito (02),\nnota de crédito (03), tiquete (04), factura de compra (08), factura de\nexportación (09) y recibo electrónico de pago (10), además de los mensajes\nreceptor (aceptación, aceptación parcial y rechazo de comprobantes recibidos).\n\n*English: REST API to issue and receive Costa Rica electronic invoices (Hacienda FE 4.4).*\n\n## Autenticación\n\nTodas las rutas, salvo las marcadas como públicas, usan una clave en el\nencabezado `Authorization: Bearer \u003cclave\u003e`:\n\n- **Clave de organización de prueba** (`aster_test_…`): actúa sobre un\n  contribuyente en el ambiente de staging (sandbox).\n- **Clave de organización de producción** (`aster_live_…`): actúa sobre un\n  contribuyente en producción.\n- **Clave de cuenta** (`aster_test_…` o `aster_live_…` sin organización): administra\n  la cuenta, sus organizaciones y sus claves.\n\n- **La clave decide el ambiente.** Omita `environment` en las solicitudes; enviar el\n  otro ambiente responde `422 environment_mismatch`. Una clave de prueba solo ve\n  documentos de staging y una de producción solo los de producción.\n- Las rutas de cuenta (`/account`, `/organizations`, `/api-keys`) requieren una clave\n  de cuenta (`403 account_key_required`); las demás requieren una clave de\n  organización (`403 organization_key_required`).\n- Cada clave tiene habilidades (*abilities*). La que exige cada operación aparece en\n  `x-required-ability`; sin ella la respuesta es `403 forbidden`.\n- Las claves de producción requieren un plan pagado activo (`402 plan_required`).\n\n## Formato de respuesta\n\nRespuestas exitosas: `{\"success\": true, \"message\"?, \"data\"?, \"timestamp\", \"api_version\"}`.\nErrores: `{\"success\": false, \"message\"?, \"error\": {\"code\", \"message\", \"errors\"?}, \"timestamp\", \"api_version\"}`.\nLos errores de validación (`422 validation_error`) listan en `error.errors` los mensajes por campo.\nLas validaciones de comprobantes responden en español por defecto; envíe\n`api_config.language: \"en\"` o `Accept-Language: en` para recibirlas en inglés.\n\n## Idempotencia\n\nLas solicitudes `POST`, `PUT`, `PATCH` y `DELETE` autenticadas aceptan\n`X-Idempotency-Key` (máximo 255 caracteres). Repetir la misma solicitud con la misma\nclave devuelve la respuesta guardada con `Idempotent-Replayed: true` durante 24 horas.\nMisma clave en curso: `409 idempotency_in_progress`; misma clave con otro cuerpo o\nruta: `422 idempotency_key_reused`. Las respuestas 5xx no se guardan.\n\n## Límites de uso\n\nLas rutas de organización se limitan por organización, por minuto y por día\n(calendario de Costa Rica) según el plan. Las rutas públicas y las de cuenta se\nlimitan por IP y por minuto. Las respuestas incluyen `X-RateLimit-Limit`,\n`X-RateLimit-Remaining` y `X-RateLimit-Reset`; al exceder el límite se responde\n`429 rate_limited` con `Retry-After` (segundos).\n\n## Cuotas\n\nCada documento de producción con veredicto de Hacienda consume 1 documento del\nperíodo (un mensaje receptor consume 0,5). Cuando se agotan los documentos del plan y\nde los paquetes, los envíos de producción responden `402 quota_exceeded` antes de\nfirmar nada, con `error.upgrade_url`, `error.pack_url` y `error.usage`. Los documentos\nde prueba no consumen cuota.\n\n## Sandbox\n\nCon una clave de prueba, una organización sin credenciales de staging (o una\nsolicitud con `api_config.simulate`) recibe un veredicto **simulado**: el documento se\nvalida, se firma con un certificado de sandbox y se registra, pero nunca se envía a\nHacienda. Unos dos segundos después queda `accepted` (o `rejected` con\n`\"simulate\": \"rejected\"`) y se envían los webhooks habituales. La respuesta del envío\ntrae `\"simulated\": true` y el encabezado `Aster-Simulated: true`.\n","summary":"Facturación electrónica de Costa Rica (Hacienda, FE 4.4).","title":"Aster API","version":"1.0"},"openapi":"3.1.0","paths":{"/account":{"get":{"description":"Cuenta, plan y estado de facturación. Requiere una clave de cuenta.","operationId":"getAccount","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Account"}},"type":"object"}]}}},"description":"La cuenta."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver la cuenta","tags":["Cuenta y uso"],"x-required-ability":"account:manage"}},"/account/archive":{"post":{"description":"Agrega o quita el complemento Archeion (US$5 por organización al mes) de la suscripción.\nRequiere una llave de cuenta live y un plan pagado. Escala y Plataforma ya lo incluyen\n(`422 archive_included`). Al desactivarlo, los archivos se conservan 90 días más para\nexportarlos.\n","operationId":"setAccountArchive","requestBody":{"content":{"application/json":{"example":{"enabled":true},"schema":{"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Cambio solicitado; se refleja cuando se confirma en la suscripción."},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Activar o desactivar Archeion","tags":["Cuenta y uso"],"x-required-ability":"account:manage"}},"/account/usage":{"get":{"description":"Período de facturación actual, documentos incluidos, consumidos (1 por documento de\nproducción con veredicto de Hacienda, 0,5 por mensaje receptor), documentos en espera\nde Hacienda, saldo de paquetes, documentos restantes y organizaciones con documentos\nde producción en el período. Los documentos de prueba son gratuitos.\n","operationId":"getAccountUsage","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Usage"}},"type":"object"}]}}},"description":"Consumo del período."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Consumo del período","tags":["Cuenta y uso"],"x-required-ability":"account:manage"}},"/api-keys":{"get":{"description":"Claves de la cuenta (de cuenta y de organización), de la más reciente a la más antigua, incluidas las revocadas. Nunca incluye el secreto.","operationId":"listApiKeys","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array"}},"type":"object"}]}}},"description":"Claves."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar claves","tags":["Claves API"],"x-required-ability":"account:manage"},"post":{"description":"Crea una clave de cuenta (sin `organization_id`) o de organización. El secreto se\ndevuelve **una sola vez**. Las claves de producción requieren un plan pagado\nactivo (`402 plan_required`) y solo una clave de cuenta de producción puede\ncrearlas (`403 live_key_required`). Sin `abilities`, una clave de organización\nrecibe todas las habilidades de organización y una de cuenta `account:manage`.\n","operationId":"createApiKey","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"mode":"test","name":"Integración ERP","organization_id":"6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44"},"schema":{"$ref":"#/components/schemas/ApiKeyInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ApiKeyCreated"}},"type":"object"}]}}},"description":"Clave creada. Guarde el secreto ahora; no se vuelve a mostrar."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/AccountForbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Crear una clave","tags":["Claves API"],"x-required-ability":"account:manage"}},"/api-keys/{key}":{"delete":{"description":"Revoca una clave de la cuenta. Una clave no puede revocarse a sí misma\n(`422 cannot_revoke_current_key`) y solo una clave de cuenta de producción puede\nrevocar claves de producción (`403 live_key_required`).\n","operationId":"revokeApiKey","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Clave revocada."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Revocar una clave","tags":["Claves API"],"x-required-ability":"account:manage"},"parameters":[{"description":"Id (UUID) de la clave.","in":"path","name":"key","required":true,"schema":{"format":"uuid","type":"string"}}]},"/archive":{"get":{"description":"Clase de retención de los archivos de la organización: `standard` (90 días después de la\nrespuesta de Hacienda) o `archive` (Archeion: 5 años desde la emisión).\n","operationId":"getArchive","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Retention"}},"type":"object"}]}}},"description":"Retención."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Retención de la organización","tags":["Archivo"],"x-required-ability":"documents:export"}},"/archive/exports":{"get":{"operationId":"listArchiveExports","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/ArchiveExport"},"type":"array"}},"type":"object"}]}}},"description":"Las últimas 50 exportaciones del ambiente de la llave."},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"Exportaciones recientes","tags":["Archivo"],"x-required-ability":"documents:export"},"post":{"description":"Arma en segundo plano un ZIP con los XML firmados y las respuestas de Hacienda de los\ndocumentos emitidos en el rango (días de Costa Rica, inclusive), hasta 3 000 documentos.\nConsultá el estado con `GET /archive/exports/{id}`; queda disponible 7 días.\n","operationId":"createArchiveExport","requestBody":{"content":{"application/json":{"example":{"from":"2026-09-01","to":"2026-09-30"},"schema":{"$ref":"#/components/schemas/ArchiveExportRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ArchiveExport"}},"type":"object"}]}}},"description":"Exportación en cola."},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationFailed"}},"summary":"Exportar un rango a ZIP","tags":["Archivo"],"x-required-ability":"documents:export"}},"/archive/exports/{id}":{"get":{"operationId":"getArchiveExport","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ArchiveExport"}},"type":"object"}]}}},"description":"Exportación."},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Estado de una exportación","tags":["Archivo"],"x-required-ability":"documents:export"},"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}]},"/archive/exports/{id}/download":{"get":{"operationId":"downloadArchiveExport","responses":{"200":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}}},"description":"El ZIP."},"404":{"$ref":"#/components/responses/NotFound"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"La exportación aún no está lista (`export_not_ready`)."}},"summary":"Descargar el ZIP","tags":["Archivo"],"x-required-ability":"documents:export"},"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}]},"/archive/import":{"post":{"description":"Un ZIP (hasta 50 MB, 5 000 archivos) con XML firmados de un proveedor anterior y, si los\ntenés, las respuestas de Hacienda (`MensajeHacienda`). Requiere Archeion y una llave live.\nCada documento debe ser de la organización (emisor, o receptor en una FEC); las claves ya\nregistradas se omiten. Los consecutivos importados no se pueden reutilizar.\n","operationId":"importArchive","requestBody":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}},"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ImportResult"}},"type":"object"}]}}},"description":"Resultado de la importación."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Archeion no está activo (`archeion_required`)."},"422":{"$ref":"#/components/responses/ValidationFailed"}},"summary":"Importar comprobantes de otro proveedor","tags":["Archivo"],"x-required-ability":"invoices:write"}},"/auth/me":{"get":{"description":"Identifica la clave de organización con que se llama, su cuenta, su organización y sus habilidades. Útil para verificar una integración.","operationId":"getCurrentKey","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CurrentKey"}},"type":"object"}]}}},"description":"La clave actual."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Clave actual","tags":["Claves API"],"x-required-ability":"ninguna"}},"/company":{"get":{"description":"Alias de `GET /organizations/me`.","operationId":"getCompany","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/OrganizationProfile"}},"type":"object"}]}}},"description":"Perfil de la organización."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver el perfil (alias)","tags":["Organizaciones"],"x-alias-of":"/organizations/me","x-required-ability":"settings:read"},"put":{"description":"Alias de `PUT /organizations/me`.","operationId":"updateCompany","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationProfileUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Perfil actualizado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Actualizar el perfil (alias)","tags":["Organizaciones"],"x-alias-of":"/organizations/me","x-required-ability":"settings:manage"}},"/company/certificate":{"delete":{"description":"Alias de `DELETE /organizations/me/certificate`.","operationId":"deleteCompanyCertificate","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"description":"Ambiente (solo necesario con tokens heredados).","in":"query","name":"environment","required":false,"schema":{"$ref":"#/components/schemas/Environment"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Certificado eliminado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Eliminar el certificado (alias)","tags":["Organizaciones"],"x-alias-of":"/organizations/me/certificate","x-required-ability":"settings:manage"},"get":{"description":"Alias de `GET /organizations/me/certificate`.","operationId":"getCompanyCertificate","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CertificateStatus"}},"type":"object"}]}}},"description":"Estado del certificado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Estado del certificado (alias)","tags":["Organizaciones"],"x-alias-of":"/organizations/me/certificate","x-required-ability":"settings:read"},"post":{"description":"Alias de `POST /organizations/me/certificate`.","operationId":"uploadCompanyCertificate","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateUpload"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CertificateInfo"}},"type":"object"}]}}},"description":"Certificado guardado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Subir el certificado (alias)","tags":["Organizaciones"],"x-alias-of":"/organizations/me/certificate","x-required-ability":"settings:manage"}},"/documents":{"get":{"description":"Documentos de la organización en el ambiente de la clave, del más reciente al más\nantiguo, con paginación por cursor: pase el `next_cursor` de la respuesta como\n`cursor` para obtener la página siguiente (`null` cuando no hay más).\n`direction=received` lista los mensajes receptor emitidos sobre comprobantes recibidos.\n","operationId":"listDocuments","parameters":[{"description":"`issued` (por defecto): comprobantes emitidos; `received`: mensajes receptor.","in":"query","name":"direction","schema":{"default":"issued","enum":["issued","received"],"type":"string"}},{"description":"Tipo de documento (`01`–`10`, o `RC` para mensajes receptor).","in":"query","name":"type","schema":{"pattern":"^(0[1-9]|10|RC)$","type":"string"}},{"description":"Estado del documento.","in":"query","name":"status","schema":{"$ref":"#/components/schemas/DocumentStatus"}},{"description":"Desde esta fecha de creación (inclusive, hora de Costa Rica).","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Hasta esta fecha de creación (inclusive, hora de Costa Rica).","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"description":"Clave, consecutivo o identificación exactos del receptor, o parte de su nombre.","in":"query","name":"search","schema":{"type":"string"}},{"description":"Cursor de la página siguiente (`next_cursor`).","in":"query","name":"cursor","schema":{"type":"string"}},{"description":"Documentos por página (1–200).","in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}},"description":"Página de documentos."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar documentos","tags":["Documentos"],"x-required-ability":"invoices:read"}},"/documents/export":{"get":{"description":"Descarga en un ZIP todos los XML firmados y de respuesta de Hacienda de la\norganización en el ambiente de la clave, organizados como\n`emitidos/{tipo}/{clave}/…` y `recibidos/{tipo}/{clave}/…`. El archivo se transmite\npor partes, sin límite de cantidad de documentos.\n","operationId":"exportDocuments","parameters":[{"description":"Tipo de documento (`01`, `02`…).","in":"query","name":"document_type","schema":{"type":"string"}},{"description":"Estado (`accepted`, `rejected`…).","in":"query","name":"status","schema":{"$ref":"#/components/schemas/DocumentStatus"}},{"description":"Fecha de creación inicial (ISO 8601).","in":"query","name":"from_date","schema":{"example":"2026-01-01","type":"string"}},{"description":"Fecha de creación final (ISO 8601).","in":"query","name":"to_date","schema":{"example":"2026-03-31","type":"string"}}],"responses":{"200":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}}},"description":"Archivo ZIP.","headers":{"Content-Disposition":{"$ref":"#/components/headers/Content-Disposition"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Exportar XML en ZIP","tags":["Documentos"],"x-required-ability":"documents:export"}},"/documents/{key}/email":{"parameters":[{"$ref":"#/components/parameters/DocumentKey"}],"post":{"description":"Envía el XML firmado, la respuesta de Hacienda y el PDF a hasta 5 destinatarios. Si\nHacienda aún no ha aceptado el documento, el correo sale en cuanto lo acepte. Los\ndocumentos rechazados (`422 document_rejected`) y los mensajes receptor\n(`422 not_emailable`) no se envían.\n","operationId":"emailDocument","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"recipients":["cliente@example.com"]},"schema":{"$ref":"#/components/schemas/EmailRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"api_version":"1.0","message":"The email will be sent now.","success":true,"timestamp":"2026-10-08T16:20:00Z"},"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Correo programado."},"400":{"$ref":"#/components/responses/BadRequest"},"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"}},"summary":"Enviar el documento por correo","tags":["Documentos"],"x-required-ability":"invoices:write"}},"/documents/{key}/pdf":{"get":{"description":"Representación impresa del comprobante con la marca de la organización. Los mensajes receptor no tienen PDF (`404 pdf_not_available`).","operationId":"downloadDocumentPdf","parameters":[{"$ref":"#/components/parameters/PdfLang"}],"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"PDF.","headers":{"Content-Disposition":{"$ref":"#/components/headers/Content-Disposition"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Descargar el PDF","tags":["Documentos"],"x-required-ability":"invoices:read"},"parameters":[{"$ref":"#/components/parameters/DocumentKey"}]},"/documents/{key}/response-xml":{"get":{"description":"Mensaje de Hacienda con el veredicto. `404 response_not_available` mientras Hacienda no haya respondido.","operationId":"downloadDocumentResponseXml","responses":{"200":{"content":{"application/xml":{"schema":{"format":"binary","type":"string"}}},"description":"XML de respuesta de Hacienda.","headers":{"Content-Disposition":{"$ref":"#/components/headers/Content-Disposition"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Descargar el XML de respuesta de Hacienda","tags":["Documentos"],"x-required-ability":"invoices:read"},"parameters":[{"$ref":"#/components/parameters/DocumentKey"}]},"/documents/{key}/void":{"parameters":[{"$ref":"#/components/parameters/DocumentKey"}],"post":{"description":"En Costa Rica un comprobante aceptado se anula con una nota de crédito. Este\nendpoint emite una nota de crédito (`03`) por el total, con código de referencia `01`\n(anula documento de referencia), construida línea por línea a partir del XML firmado\ndel original. Se procesa como `POST /electronic-documents` (misma clave, ambiente,\ncuota y validación) y responde lo mismo, con `data.voids` = clave anulada.\n\nSolo se anulan facturas, notas de débito, tiquetes y facturas de exportación\naceptadas por Hacienda (`422 not_voidable`); un documento ya anulado responde\n`409 already_voided`. Cuando Hacienda acepta la nota de crédito se envía el webhook\n`document.voided`.\n","operationId":"voidDocument","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"reason":"Factura emitida por error"},"schema":{"$ref":"#/components/schemas/VoidRequest"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/VoidSubmitted"}},"type":"object"}]}}},"description":"Nota de crédito emitida; el original queda anulado cuando Hacienda la acepte.","headers":{"Aster-Simulated":{"$ref":"#/components/headers/Aster-Simulated"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Anular un documento","tags":["Documentos"],"x-required-ability":"invoices:void"}},"/documents/{key}/xml":{"get":{"description":"XML del comprobante firmado tal como se envió a Hacienda.","operationId":"downloadDocumentXml","responses":{"200":{"content":{"application/xml":{"schema":{"format":"binary","type":"string"}}},"description":"XML firmado.","headers":{"Content-Disposition":{"$ref":"#/components/headers/Content-Disposition"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Descargar el XML firmado","tags":["Documentos"],"x-required-ability":"invoices:read"},"parameters":[{"$ref":"#/components/parameters/DocumentKey"}]},"/documents/{key}/zip":{"get":{"description":"ZIP con el XML firmado, el XML de respuesta de Hacienda (si ya existe) y el PDF.","operationId":"downloadDocumentZip","parameters":[{"$ref":"#/components/parameters/PdfLang"}],"responses":{"200":{"content":{"application/zip":{"schema":{"format":"binary","type":"string"}}},"description":"Archivo ZIP.","headers":{"Content-Disposition":{"$ref":"#/components/headers/Content-Disposition"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Descargar XML, respuesta y PDF en ZIP","tags":["Documentos"],"x-required-ability":"invoices:read"},"parameters":[{"$ref":"#/components/parameters/DocumentKey"}]},"/electronic-documents":{"post":{"description":"Valida, firma (XAdES-EPES) y envía a Hacienda cualquier comprobante FE 4.4:\n`01` factura, `02` nota de débito, `03` nota de crédito, `04` tiquete,\n`08` factura de compra, `09` factura de exportación y `10` recibo electrónico de pago.\n\nEl documento se firma de forma síncrona y se envía a Hacienda en segundo plano: la\nrespuesta `201` trae `status: \"processing\"` y el veredicto llega por webhook\n(`document.accepted` / `document.rejected`) o consultando\n`GET /electronic-documents/{key}`.\n\nAntes de firmar se aplican las reglas de Hacienda: campos obligatorios, tablas de\ncondiciones por tipo de documento, formatos del XSD, cálculos (errores -107, -109,\n-111, -190, -290, -476, -487), existencia de las cédulas y de los códigos CABYS,\ny, para notas de crédito y débito, que el documento referido exista, haya sido\naceptado y coincida el receptor. Cualquier fallo responde `422 validation_error`\ncon los mensajes por campo.\n\nReglas para claves de organización:\n- El emisor (en una factura de compra `08`, el receptor) debe ser la organización\n  de la clave (`422 organization_mismatch`).\n- `document.provider_system_id` es opcional; por defecto es el registro de AstraNexo\n  como proveedor de sistemas.\n- Sin `clave`/`consecutive_number`, Aster numera el documento por ambiente,\n  sucursal, terminal y tipo. Si se envían, deben ir juntos, la fecha de la clave debe\n  coincidir con `document.date` y ningún consecutivo puede reutilizarse\n  (`409 duplicate_clave` / `409 duplicate_consecutive`).\n- Los totales (`totals`) y los montos derivados de cada línea se recalculan a partir\n  de las líneas; solo `total_other_charges` y `total_iva_returned` se toman del\n  cuerpo.\n\nLos nombres legibles se convierten a códigos: `sale_condition` (`cash`, `credit`…),\n`payment_method` (`cash`, `card`, `transfer`, `sinpe`…) y el tipo de identificación\n(`fisica`, `juridica`, `dimex`, `nite`, `extranjero`).\n","operationId":"submitElectronicDocument","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"description":"`en` devuelve los mensajes de validación en inglés (si no se envía `api_config.language`).","in":"header","name":"Accept-Language","required":false,"schema":{"example":"es","type":"string"}}],"requestBody":{"content":{"application/json":{"examples":{"exonerada":{"summary":"Línea con exoneración parcial (totales calculados por el servidor)","value":{"commercial_info":{"currency":"CRC","payment_method":"transfer","sale_condition":"cash"},"document":{"activity_code":"620100","date":"2026-10-08T11:00:00-06:00","document_type":"01","situation":"1"},"issuer":{"address":{"canton":"01","details":"100 m norte del parque central","district":"01","province":"1"},"email":"facturacion@ejemplo.cr","id":"3101123456","name":"Servicios Ejemplo S.A.","type":"02"},"items":[{"cabys_code":"8713000000000","description":"Servicio exonerado parcialmente","exoneration":{"article":"2","document_number":"AL-00012345-26","document_type":"03","emission_date":"2026-09-01T00:00:00-06:00","inciso":"1","institution":"01","percentage":5},"quantity":1,"tax":{"rate":13,"rate_code":"08","type":"01"},"unit":"Sp","unit_price":25000}],"receiver":{"email":"compras@asociacion.example.com","id":"3002654321","name":"Asociación Ejemplo","type":"02"},"totals":{}}},"factura":{"summary":"Factura electrónica (01) con descuento, dos líneas y correo al receptor","value":{"api_config":{"language":"es","simulate":"accepted"},"commercial_info":{"currency":"CRC","exchange_rate":1,"payment_method":"04","sale_condition":"01"},"delivery":{"email":true,"recipients":["maria.rodriguez@example.com"]},"document":{"activity_code":"620100","branch":"001","date":"2026-10-08T10:15:00-06:00","document_type":"01","situation":"1","terminal":"00001"},"issuer":{"address":{"canton":"01","details":"100 m norte del parque central","district":"01","province":"1"},"commercial_name":"Ejemplo","email":"facturacion@ejemplo.cr","id":"3101123456","name":"Servicios Ejemplo S.A.","phone":{"country_code":"506","number":"22223333"},"type":"02"},"items":[{"cabys_code":"4529000000000","commercial_codes":[{"code":"SKU-0042","type":"04"}],"description":"Repuesto de equipo","discount":[{"amount":3600,"code":"04","reason":"Descuento comercial"}],"line_number":1,"price":20000,"quantity":2,"tax":[{"rate":13,"rate_code":"08","type":"01"}],"unit":"Unid"},{"cabys_code":"8713000000000","description":"Servicio de instalación","line_number":2,"price":25000,"quantity":1,"tax":[{"rate":13,"rate_code":"08","type":"01"}],"unit":"Sp"}],"receiver":{"address":{"canton":"03","details":"Residencial Las Palmas, casa 12","district":"01","province":"2"},"email":"maria.rodriguez@example.com","id":"109870654","name":"María Rodríguez Solís","phone":"88887777","type":"01"},"totals":{"total":69382,"total_discount":3600,"total_net_sales":61400,"total_sales":65000,"total_taxed_goods":40000,"total_taxed_services":25000,"total_taxes":7982}}},"nota_credito":{"summary":"Nota de crédito (03) que corrige el monto de una factura aceptada","value":{"commercial_info":{"currency":"CRC","payment_method":"04","sale_condition":"01"},"document":{"activity_code":"620100","date":"2026-10-09T09:00:00-06:00","document_type":"03","situation":"1"},"issuer":{"address":{"canton":"01","details":"100 m norte del parque central","district":"01","province":"1"},"email":"facturacion@ejemplo.cr","id":"3101123456","name":"Servicios Ejemplo S.A.","type":"02"},"items":[{"cabys_code":"8713000000000","description":"Ajuste de servicio de instalación","price":5000,"quantity":1,"tax":[{"rate":13,"rate_code":"08","type":"01"}],"unit":"Sp"}],"receiver":{"email":"maria.rodriguez@example.com","id":"109870654","name":"María Rodríguez Solís","type":"01"},"reference":{"code":"02","date":"2026-10-08T10:15:00-06:00","document_type":"01","number":"50608102600310112345600100001010000000042112345678","reason":"Corrige monto"},"totals":{}}}},"schema":{"$ref":"#/components/schemas/ElectronicDocumentRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"api_version":"1.0","data":{"consecutive_number":"00100001010000000042","document_key":"50608102600310112345600100001010000000042112345678","document_type":"01","document_type_name":"Factura Electrónica","environment":"staging","id":4182,"queued_at":"2026-10-08T16:15:02Z","signed_xml_path":"aster/6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44/staging/2026/10/emitidos/FE/50608102600310112345600100001010000000042112345678/FacturaElectronica_00100001010000000042.xml","simulated":true,"status":"processing","storage_status":"cloud","tenant_uuid":"6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44"},"message":"Document submitted for processing.","success":true,"timestamp":"2026-10-08T16:15:02Z"},"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/DocumentSubmitted"}},"type":"object"}]}}},"description":"Documento firmado y en proceso de envío a Hacienda.","headers":{"Aster-Simulated":{"$ref":"#/components/headers/Aster-Simulated"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"content":{"application/json":{"examples":{"organizacion":{"summary":"Emisor distinto a la organización","value":{"api_version":"1.0","error":{"code":"organization_mismatch","message":"issuer.id (3101999999) is not this organization's identification (3101123456). Use the key of the organization that issues the document."},"success":false,"timestamp":"2026-10-08T16:15:02Z"}},"validacion":{"summary":"Error de validación","value":{"api_version":"1.0","error":{"code":"validation_error","errors":{"items.0.cabys_code":["El código CABYS es requerido."]},"message":"El código CABYS es requerido."},"success":false,"timestamp":"2026-10-08T16:15:02Z"}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/ErrorEnvelope"}]}}},"description":"Validación fallida (`validation_error`, con `error.errors` por campo) u otra regla\nde negocio: `environment_mismatch`, `organization_mismatch`,\n`simulation_not_available`, `invalid_clave_consecutive`, `invalid_clave_format`,\n`invalid_consecutive_format`, `fec_clave_id_mismatch`, `clave_date_mismatch`,\n`missing_credentials`, `missing_certificate`, `certificate_expired`,\n`invalid_document_type`.\n"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Emitir un comprobante electrónico","tags":["Documentos"],"x-required-ability":["invoices:write","invoices:sign"],"x-required-ability-match":"any"}},"/electronic-documents/{key}":{"get":{"description":"Documento completo con su estado ante Hacienda, el XML firmado, el XML de respuesta (si ya hay) y los errores de rechazo detallados. Una clave solo ve documentos de su ambiente.","operationId":"getElectronicDocument","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Document"}},"type":"object"}]}}},"description":"El documento."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver un documento","tags":["Documentos"],"x-required-ability":"invoices:read"},"parameters":[{"$ref":"#/components/parameters/DocumentKey"}]},"/exchange-rates":{"get":{"description":"Tipo de cambio de referencia vigente (compra y venta). Si ninguna fuente responde, `buy`/`sell` son `0` y `note` explica el motivo (HTTP 200).","operationId":"getExchangeRate","responses":{"200":{"content":{"application/json":{"example":{"api_version":"1.0","data":{"buy":505.12,"date":"2026-10-08","entity":"BCCR","sell":511.43,"source":"hacienda"},"success":true,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ExchangeRate"}},"type":"object"}]}}},"description":"Tipo de cambio."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Tipo de cambio actual USD/CRC","tags":["Tipo de cambio"],"x-required-ability":"reference:read"}},"/exchange-rates/entities":{"get":{"description":"Tipo de cambio USD/CRC de ventanilla de cada entidad autorizada. Guarde `entity` tal cual para usarlo en `GET /exchange-rates/pair`. Lista vacía si el servicio no está disponible.","operationId":"listExchangeRateEntities","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/ExchangeRateEntity"},"type":"array"}},"type":"object"}]}}},"description":"Entidades."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Tipo de cambio por entidad financiera","tags":["Tipo de cambio"],"x-required-ability":"reference:read"}},"/exchange-rates/historical":{"get":{"description":"Tipo de cambio USD/CRC del BCCR para una fecha pasada. Fines de semana y feriados toman el del día hábil anterior. Si no se puede resolver, `buy`/`sell` son `0` con `note`.","operationId":"getHistoricalExchangeRate","parameters":[{"description":"Fecha (`YYYY-MM-DD`), no futura.","in":"query","name":"date","required":true,"schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ExchangeRate"}},"type":"object"}]}}},"description":"Tipo de cambio de la fecha."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Tipo de cambio histórico","tags":["Tipo de cambio"],"x-required-ability":"reference:read"}},"/exchange-rates/pair":{"get":{"description":"Tipo de cambio entre dos monedas ISO 4217. Con `entity` (solo USD/CRC) devuelve el\ntipo de ventanilla de esa entidad financiera; si no está disponible responde con la\ncadena de referencia y `fallback: true`. `stale: true` indica que se usó el último\nvalor guardado porque la fuente en vivo no respondió.\n","operationId":"getExchangeRatePair","parameters":[{"description":"Moneda de origen (ISO 4217).","in":"query","name":"from","required":true,"schema":{"example":"USD","maxLength":3,"minLength":3,"type":"string"}},{"description":"Moneda de destino (ISO 4217).","in":"query","name":"to","required":true,"schema":{"example":"CRC","maxLength":3,"minLength":3,"type":"string"}},{"description":"Nombre de la entidad, tal como lo devuelve `GET /exchange-rates/entities`.","in":"query","name":"entity","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ExchangeRatePair"}},"type":"object"}]}}},"description":"Tipo de cambio del par."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Tipo de cambio de un par de monedas","tags":["Tipo de cambio"],"x-required-ability":"reference:read"}},"/hacienda/query/{clave}":{"get":{"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`).","operationId":"queryHaciendaDocument","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/HaciendaQueryResult"}},"type":"object"}]}}},"description":"Estado del comprobante en Hacienda."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Hacienda no respondió."}},"summary":"Consultar un comprobante en Hacienda","tags":["Hacienda"],"x-required-ability":"hacienda:query"},"parameters":[{"description":"Clave numérica de 50 caracteres.","in":"path","name":"clave","required":true,"schema":{"pattern":"^[0-9A-Z]{50}$","type":"string"}}]},"/hacienda/resolution":{"get":{"description":"Estado y mensaje de Hacienda registrados en Aster para un documento de la organización (sin consultar a Hacienda).","operationId":"getDocumentResolution","parameters":[{"description":"Clave numérica de 50 caracteres.","in":"query","name":"clave","required":true,"schema":{"pattern":"^[0-9A-Z]{50}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/DocumentResolution"}},"type":"object"}]}}},"description":"Resolución."},"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"}},"summary":"Resolución registrada de un documento","tags":["Hacienda"],"x-required-ability":"hacienda:query"}},"/hacienda/status":{"get":{"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.","operationId":"getHaciendaStatus","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/HaciendaStatus"}},"type":"object"}]}}},"description":"Estado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Disponibilidad de Hacienda y configuración","tags":["Hacienda"],"x-required-ability":"hacienda:query"}},"/hacienda/taxpayers":{"get":{"description":"Búsqueda pública en el registro de contribuyentes de Hacienda, por cédula o por\nnombre. La respuesta agrupa los resultados en `cedulas_fisicas` (solo personas\nfísicas), `cedulas_juridicas` (solo personas jurídicas) o `taxpayers` (mezcla o\nningún resultado). Limitado a 60 solicitudes por minuto por IP.\n","operationId":"searchTaxpayers","parameters":[{"description":"Identificación (alias `id`, `identification`). Se ignoran guiones y espacios.","in":"query","name":"cedula","schema":{"type":"string"}},{"description":"Nombre o razón social (mínimo 2 caracteres; obligatorio si no hay cédula).","in":"query","name":"nombre","schema":{"minLength":2,"type":"string"}},{"description":"Apellidos (personas físicas).","in":"query","name":"apellidos","schema":{"type":"string"}},{"description":"`F` persona física o `J` persona jurídica.","in":"query","name":"tipo","schema":{"enum":["F","J"],"type":"string"}},{"description":"`true` para coincidencia exacta.","in":"query","name":"exact_match","schema":{"enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"api_version":"1.0","data":{"cedulas_juridicas":[{"cedula":"3101123456","class":"Cédula Jurídica","id_raw":"3101123456","razon_social":"SERVICIOS EJEMPLO SOCIEDAD ANONIMA","tipo":"J","tipo_texto":"Cédula Jurídica"}]},"message":"1 taxpayer(s) found.","success":true,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/TaxpayerSearchResult"}},"type":"object"}]}}},"description":"Resultados."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Buscar contribuyentes","tags":["Hacienda"]}},"/hacienda/validate":{"post":{"description":"Revisión estructural mínima de un borrador, sin firmar ni enviar: exige\n`document_type`, emisor con `name`, `identification_type` e\n`identification_number`, al menos una línea y totales, y advierte si falta el\nreceptor. **No** aplica las reglas FE 4.4; para eso use `POST /electronic-documents`\ncon una clave de prueba.\n","operationId":"validateDocumentDraft","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"document_type":"01","issuer":{"identification_number":"3101123456","identification_type":"02","name":"Servicios Ejemplo S.A."},"items":[{"description":"Servicio de instalación"}],"totals":{"total":28250}},"schema":{"$ref":"#/components/schemas/DraftValidationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/DraftValidationResult"}},"type":"object"}]}}},"description":"Resultado de la revisión."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Revisión básica de un borrador","tags":["Hacienda"],"x-required-ability":"hacienda:validate"}},"/organizations":{"get":{"description":"Contribuyentes de la cuenta, del más antiguo al más reciente. Requiere una clave de cuenta.","operationId":"listOrganizations","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Organization"},"type":"array"}},"type":"object"}]}}},"description":"Organizaciones."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar organizaciones","tags":["Organizaciones"],"x-required-ability":"account:manage"},"post":{"description":"Agrega un contribuyente a la cuenta. La identificación no puede cambiarse después.\nEl plan limita la cantidad de organizaciones (`403 organization_limit_reached`); una\nidentificación repetida en la cuenta responde `409 organization_exists`.\n","operationId":"createOrganization","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"economic_activities":["475201"],"email":"facturacion@laesquina.cr","identification_number":"3101123456","identification_type":"02","legal_name":"Ferretería La Esquina S.A.","name":"Ferretería La Esquina","phone":"22223333"},"schema":{"$ref":"#/components/schemas/OrganizationInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Organization"}},"type":"object"}]}}},"description":"Organización creada."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Crear una organización","tags":["Organizaciones"],"x-required-ability":"account:manage"}},"/organizations/me":{"get":{"description":"Perfil fiscal de la organización de la clave, su plan y sus límites de uso.","operationId":"getMyOrganization","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/OrganizationProfile"}},"type":"object"}]}}},"description":"Perfil de la organización."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver el perfil de la organización","tags":["Organizaciones"],"x-required-ability":"settings:read"},"put":{"description":"Cambia los campos enviados; los omitidos no cambian. En una cuenta con plan pagado\nrequiere una clave de producción (`403 live_key_required`).\n","operationId":"updateMyOrganization","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"email":"facturacion@laesquina.cr","phone":"22223333"},"schema":{"$ref":"#/components/schemas/OrganizationProfileUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Perfil actualizado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Actualizar el perfil de la organización","tags":["Organizaciones"],"x-required-ability":"settings:manage"}},"/organizations/me/branding":{"get":{"description":"Color, pie de página, logo y remitente que se usan en el PDF y en los correos de los documentos.","operationId":"getMyBranding","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Branding"}},"type":"object"}]}}},"description":"Marca de la organización."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver la marca","tags":["Organizaciones"],"x-required-ability":"settings:read"},"put":{"description":"Cambia los campos enviados; los omitidos no cambian y una cadena vacía borra el\nvalor. `logo` es un PNG o JPEG en base64 de hasta 512 KB. En una cuenta con plan\npagado requiere una clave de producción (`403 live_key_required`).\n","operationId":"updateMyBranding","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"color":"#0057FF","email_reply_to":"ventas@laesquina.cr","email_sender_name":"Ferretería La Esquina","footer":"Gracias por su compra."},"schema":{"$ref":"#/components/schemas/BrandingInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Branding"}},"type":"object"}]}}},"description":"Marca actualizada."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Actualizar la marca","tags":["Organizaciones"],"x-required-ability":"settings:manage"}},"/organizations/me/certificate":{"delete":{"description":"Elimina la llave criptográfica y las credenciales ATV del ambiente de la clave. El ambiente puede indicarse en la consulta o en el cuerpo (`{\"environment\": \"staging\"}`); con claves de Aster se toma de la clave.","operationId":"deleteMyCertificate","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"description":"Ambiente (solo necesario con tokens heredados).","in":"query","name":"environment","required":false,"schema":{"$ref":"#/components/schemas/Environment"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Certificado eliminado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Eliminar el certificado","tags":["Organizaciones"],"x-required-ability":"settings:manage"},"get":{"description":"Indica, por ambiente, si la organización tiene llave criptográfica y credenciales ATV configuradas.","operationId":"getMyCertificate","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CertificateStatus"}},"type":"object"}]}}},"description":"Estado del certificado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Estado del certificado","tags":["Organizaciones"],"x-required-ability":"settings:read"},"post":{"description":"Guarda la llave criptográfica (`.p12` en base64), su PIN y las credenciales ATV de\nHacienda para el ambiente de la clave. El PIN y la contraseña se guardan cifrados.\nEl certificado debe pertenecer a la identificación de la organización\n(`422 certificate_mismatch`).\n","operationId":"uploadMyCertificate","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"atv_password":"contraseña-atv","atv_user":"cpj-3-101-123456@stag.comprobanteselectronicos.go.cr","certificate":"MIIKYgIBAzCCCh4GCSqGSIb3DQEHAaCCCg8EggoLMIIKBzCCBX...","pin":"1234"},"schema":{"$ref":"#/components/schemas/CertificateUpload"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CertificateInfo"}},"type":"object"}]}}},"description":"Certificado guardado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Subir el certificado","tags":["Organizaciones"],"x-required-ability":"settings:manage"}},"/organizations/me/consecutives":{"get":{"description":"Contadores de consecutivos que Aster usa para numerar los documentos de la organización, por ambiente, sucursal, terminal y tipo de documento. `next_value` es el número que recibirá el próximo documento.","operationId":"listMyConsecutives","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Counter"},"type":"array"}},"type":"object"}]}}},"description":"Contadores."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar consecutivos","tags":["Organizaciones"],"x-required-ability":"settings:read"},"put":{"description":"Fija el próximo consecutivo de una secuencia, por ejemplo cuando el contribuyente\nviene de otro proveedor y debe continuar después de su último número. Un contador\nsolo avanza: retroceder reutilizaría números que Hacienda ya vio\n(`422 consecutive_backwards`).\n","operationId":"updateMyConsecutive","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"branch":"001","document_type":"01","next_value":1501,"terminal":"00001"},"schema":{"$ref":"#/components/schemas/CounterInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Counter"}},"type":"object"}]}}},"description":"Contador actualizado."},"400":{"$ref":"#/components/responses/BadRequest"},"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"}},"summary":"Adelantar un consecutivo","tags":["Organizaciones"],"x-required-ability":"settings:manage"}},"/organizations/{org}":{"delete":{"description":"Retira la organización de la cuenta y revoca sus claves. Sus documentos se conservan\n(registros fiscales). Solo una clave de cuenta de producción puede eliminar\norganizaciones (`403 live_key_required`).\n","operationId":"deleteOrganization","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"example":{"api_version":"1.0","message":"Organization deleted. Its keys were revoked; its documents are kept.","success":true,"timestamp":"2026-10-08T16:00:00Z"},"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Organización eliminada."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Eliminar una organización","tags":["Organizaciones"],"x-required-ability":"account:manage"},"get":{"description":"Una organización de la cuenta por su id (UUID).","operationId":"getOrganization","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Organization"}},"type":"object"}]}}},"description":"La organización."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver una organización","tags":["Organizaciones"],"x-required-ability":"account:manage"},"parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"patch":{"description":"Cambia los campos enviados; los omitidos no cambian. La identificación no se puede\ncambiar (`422`). En una cuenta con plan pagado, solo una clave de cuenta de producción\npuede actualizar organizaciones (`403 live_key_required`).\n","operationId":"updateOrganization","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"economic_activities":["475201","466301"],"email":"facturas@laesquina.cr"},"schema":{"$ref":"#/components/schemas/OrganizationUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Organization"}},"type":"object"}]}}},"description":"Organización actualizada."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Actualizar una organización","tags":["Organizaciones"],"x-required-ability":"account:manage"}},"/plans":{"get":{"description":"Lista pública de planes y paquetes de documentos, con precios en centavos de USD. A cada cargo se le suma el IVA (13 %). Limitado a 120 solicitudes por minuto por IP.","operationId":"listPlans","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/PriceList"}},"type":"object"}]}}},"description":"Planes y paquetes."},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[],"summary":"Planes y paquetes","tags":["Cuenta y uso"]}},"/receptor-messages":{"post":{"description":"Emite el mensaje receptor sobre un comprobante de un proveedor: `1` aceptación\n(documento `05`), `2` aceptación parcial (`06`) y `3` rechazo (`07`). Se firma y se\nenvía a Hacienda igual que un comprobante; el veredicto llega por webhook con\n`document_type: \"RC\"`. La organización debe ser el receptor del comprobante\n(`422 organization_mismatch`). En producción consume 0,5 documentos de la cuota.\nMuchos campos aceptan alias en español (por ejemplo `mensaje`, `cedula_emisor`,\n`fecha_emision`).\n","operationId":"submitReceptorMessage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"activity_code":"620100","clave":"50607102600310198765400100001010000000283112345678","issue_date":"2026-10-07T14:30:00-06:00","issuer_id":"3101987654","issuer_id_type":"02","message":1,"original_doc_type":"01","receiver_id":"3101123456","receiver_id_type":"02","tax_condition":"01","total":113000,"total_applicable_expense":100000,"total_tax":13000,"total_tax_credit":13000},"schema":{"$ref":"#/components/schemas/ReceptorMessageRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"example":{"api_version":"1.0","data":{"consecutive_number":"00100001050000000006","document_key":"50607102600310198765400100001010000000283112345678","document_type":"05","document_type_name":"Aceptación Comprobante","environment":"staging","id":4190,"queued_at":"2026-10-08T16:30:00Z","signed_xml_path":"aster/6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44/staging/2026/10/recibidos/FE/50607102600310198765400100001010000000283112345678/ConfirmacionAceptacionComprobante_00100001050000000006.xml","status":"processing","storage_status":"cloud","tenant_uuid":"6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44"},"message":"Receptor message submitted for processing.","success":true,"timestamp":"2026-10-08T16:30:00Z"},"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/DocumentSubmitted"}},"type":"object"}]}}},"description":"Mensaje receptor firmado y en proceso."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Aceptar, aceptar parcialmente o rechazar un comprobante recibido","tags":["Mensajes receptor"],"x-required-ability":"invoices:sign"}},"/recipients":{"get":{"description":"Clientes guardados de la organización, por nombre, paginados.","operationId":"listRecipients","parameters":[{"description":"Busca en nombre, identificación y correo.","in":"query","name":"search","schema":{"type":"string"}},{"description":"Tipo de identificación.","in":"query","name":"identification_type","schema":{"$ref":"#/components/schemas/IdentificationType"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Recipient"},"type":"array"},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"type":"object"}},"type":"object"}]}}},"description":"Página de receptores."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar receptores","tags":["Receptores"],"x-required-ability":"recipients:read"},"post":{"description":"Guarda un cliente. La identificación no puede repetirse en la organización (`422`).","operationId":"createRecipient","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"canton":"03","district":"01","email":"maria.rodriguez@example.com","identification_number":"109870654","identification_type":"01","name":"María Rodríguez Solís","other_address":"Residencial Las Palmas, casa 12","phone":"88887777","province":"2"},"schema":{"$ref":"#/components/schemas/RecipientInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"format":"int64","type":"integer"},"identification_number":{"type":"string"},"identification_type":{"type":"string"},"name":{"type":"string"}},"type":"object"}},"type":"object"}]}}},"description":"Receptor creado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Crear un receptor","tags":["Receptores"],"x-required-ability":"recipients:write"}},"/recipients/lookup":{"get":{"description":"Devuelve el receptor guardado con esa identificación (`404 recipient_not_found` si no existe).","operationId":"lookupRecipient","parameters":[{"description":"Número de identificación (alias `id_number`).","in":"query","name":"identification_number","required":true,"schema":{"type":"string"}},{"description":"Tipo de identificación.","in":"query","name":"identification_type","schema":{"$ref":"#/components/schemas/IdentificationType"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/RecipientSummary"}},"type":"object"}]}}},"description":"El receptor."},"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"}},"summary":"Buscar un receptor por identificación","tags":["Receptores"],"x-required-ability":"recipients:read"}},"/recipients/{id}":{"delete":{"description":"Elimina el receptor guardado.","operationId":"deleteRecipient","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Receptor eliminado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Eliminar un receptor","tags":["Receptores"],"x-required-ability":"recipients:write"},"get":{"description":"Un receptor guardado.","operationId":"getRecipient","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Recipient"}},"type":"object"}]}}},"description":"El receptor."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver un receptor","tags":["Receptores"],"x-required-ability":"recipients:read"},"parameters":[{"description":"Id del receptor.","in":"path","name":"id","required":true,"schema":{"format":"int64","type":"integer"}}],"put":{"description":"Reemplaza los datos del receptor. `name`, `identification_type` e\n`identification_number` vacíos conservan el valor actual; los demás campos omitidos\nquedan vacíos.\n","operationId":"updateRecipient","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"id":{"format":"int64","type":"integer"}},"type":"object"}},"type":"object"}]}}},"description":"Receptor actualizado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Reemplazar un receptor","tags":["Receptores"],"x-required-ability":"recipients:write"}},"/reference/address-search":{"get":{"description":"Busca barrios, distritos, cantones y provincias por nombre (sin distinguir tildes) y devuelve la jerarquía completa de cada resultado. Menos de 2 caracteres devuelve una lista vacía.","operationId":"searchAddresses","parameters":[{"description":"Nombre o parte del nombre.","in":"query","name":"q","required":true,"schema":{"example":"escazu","minLength":2,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/AddressSearchResult"},"type":"array"}},"type":"object"}]}}},"description":"Ubicaciones."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Buscar ubicaciones","tags":["Catálogos"]}},"/reference/cabys":{"get":{"description":"Búsqueda de texto completo en el catálogo CABYS (descripción y código). Menos de 2 caracteres devuelve una lista vacía. Las rutas `/reference/*` se limitan a 300 solicitudes por minuto por IP.","operationId":"searchCabys","parameters":[{"description":"Texto o prefijo de código.","in":"query","name":"q","required":true,"schema":{"minLength":2,"type":"string"}},{"description":"Resultados (1–100).","in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"description":"`1` para coincidir con cualquiera de las palabras.","in":"query","name":"match_any","schema":{"default":"0","enum":["0","1"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CabysCode"},"type":"array"}},"type":"object"}]}}},"description":"Códigos encontrados, por relevancia."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Buscar códigos CABYS","tags":["Catálogos"]}},"/reference/cabys/batch":{"post":{"description":"Devuelve los códigos existentes de la lista (máximo 50; los demás se ignoran).","operationId":"batchCabys","requestBody":{"content":{"application/json":{"example":{"codes":["4529000000000","8713000000000"]},"schema":{"$ref":"#/components/schemas/CodeBatch"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CabysCode"},"type":"array"}},"type":"object"}]}}},"description":"Códigos encontrados."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Consultar varios códigos CABYS","tags":["Catálogos"]}},"/reference/cabys/browse":{"get":{"description":"Con solo `category_1` devuelve sus subcategorías (`category_2`, `description_2`); con `category_1` y `category_2` devuelve los códigos de esa subcategoría.","operationId":"browseCabys","parameters":[{"description":"Sección (primer nivel).","in":"query","name":"category_1","required":true,"schema":{"type":"string"}},{"description":"División (segundo nivel).","in":"query","name":"category_2","schema":{"type":"string"}},{"description":"Filtra bienes o servicios.","in":"query","name":"type","schema":{"enum":["producto","servicio"],"type":"string"}},{"description":"Códigos (1–500).","in":"query","name":"limit","schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"anyOf":[{"$ref":"#/components/schemas/CabysCode"},{"properties":{"category_2":{"type":"string"},"description_2":{"type":"string"}},"type":"object"}]},"type":"array"}},"type":"object"}]}}},"description":"Subcategorías o códigos."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Navegar el catálogo CABYS","tags":["Catálogos"]}},"/reference/cabys/categories":{"get":{"description":"Secciones del catálogo CABYS. `type=producto` (secciones 0–4) o `type=servicio` (5–9).","operationId":"listCabysCategories","parameters":[{"description":"Filtra bienes o servicios.","in":"query","name":"type","schema":{"enum":["producto","servicio"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"properties":{"category_1":{"type":"string"},"description_1":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}]}}},"description":"Categorías."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Categorías CABYS de primer nivel","tags":["Catálogos"]}},"/reference/cabys/{code}":{"get":{"description":"Código CABYS con sus nueve niveles, tarifa de IVA sugerida y notas de inclusión y exclusión.","operationId":"getCabys","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/CabysCodeDetail"}},"type":"object"}]}}},"description":"El código."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Ver un código CABYS","tags":["Catálogos"]},"parameters":[{"description":"Código CABYS de 13 dígitos.","in":"path","name":"code","required":true,"schema":{"example":"8713000000000","type":"string"}}]},"/reference/cantons/{province}":{"get":{"description":"Cantones de la provincia.","operationId":"listCantons","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationUnit"},"type":"array"}},"type":"object"}]}}},"description":"Cantones."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Cantones de una provincia","tags":["Catálogos"]},"parameters":[{"$ref":"#/components/parameters/ProvinceCode"}]},"/reference/districts/{province}/{canton}":{"get":{"description":"Distritos del cantón.","operationId":"listDistricts","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationUnit"},"type":"array"}},"type":"object"}]}}},"description":"Distritos."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Distritos de un cantón","tags":["Catálogos"]},"parameters":[{"$ref":"#/components/parameters/ProvinceCode"},{"$ref":"#/components/parameters/CantonCode"}]},"/reference/document-types":{"get":{"description":"Tipos de comprobante que se emiten con `POST /electronic-documents`.","operationId":"listDocumentTypes","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Tipos de comprobante."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Tipos de comprobante","tags":["Catálogos"]}},"/reference/economic-activities":{"get":{"description":"Lista corta de códigos de actividad económica frecuentes (no es el catálogo completo).","operationId":"listEconomicActivities","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Actividades."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Actividades económicas comunes","tags":["Catálogos"]}},"/reference/neighborhoods/{province}/{canton}/{district}":{"get":{"description":"Barrios del distrito.","operationId":"listNeighborhoods","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationUnit"},"type":"array"}},"type":"object"}]}}},"description":"Barrios."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Barrios de un distrito","tags":["Catálogos"]},"parameters":[{"$ref":"#/components/parameters/ProvinceCode"},{"$ref":"#/components/parameters/CantonCode"},{"description":"Código del distrito (dos dígitos).","in":"path","name":"district","required":true,"schema":{"example":"01","type":"string"}}]},"/reference/payment-methods":{"get":{"description":"Medios de pago (Nota 6).","operationId":"listPaymentMethods","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Medios de pago."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Medios de pago","tags":["Catálogos"]}},"/reference/provinces":{"get":{"description":"Provincias de Costa Rica con su código de Hacienda.","operationId":"listProvinces","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Province"},"type":"array"}},"type":"object"}]}}},"description":"Provincias."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Provincias","tags":["Catálogos"]}},"/reference/reference-codes":{"get":{"description":"Motivos de referencia (Nota 9), con una nota sobre su efecto en el período fiscal.","operationId":"listReferenceCodes","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Códigos de referencia."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Códigos de referencia","tags":["Catálogos"]}},"/reference/reference-doc-types":{"get":{"description":"Tipos de documento que puede referir un comprobante (Nota 10).","operationId":"listReferenceDocTypes","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Tipos de documento de referencia."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Tipos de documento de referencia","tags":["Catálogos"]}},"/reference/sale-conditions":{"get":{"description":"Condiciones de venta (Nota 5).","operationId":"listSaleConditions","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/CodeEntry"},"type":"array"}},"type":"object"}]}}},"description":"Condiciones de venta."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Condiciones de venta","tags":["Catálogos"]}},"/reference/tariff-codes":{"get":{"description":"Búsqueda en el arancel (partidas para `tariff_code`, por ejemplo en facturas de exportación). Menos de 2 caracteres devuelve una lista vacía.","operationId":"searchTariffCodes","parameters":[{"description":"Texto o prefijo de código.","in":"query","name":"q","required":true,"schema":{"minLength":2,"type":"string"}},{"description":"Resultados (1–100).","in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"description":"`1` para coincidir con cualquiera de las palabras.","in":"query","name":"match_any","schema":{"enum":["0","1"],"type":"string"}},{"description":"`1` para devolver solo partidas finales (utilizables en un comprobante).","in":"query","name":"leaf_only","schema":{"enum":["0","1"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/TariffCode"},"type":"array"}},"type":"object"}]}}},"description":"Partidas encontradas."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Buscar partidas arancelarias","tags":["Catálogos"]}},"/reference/tariff-codes/batch":{"post":{"description":"Devuelve las partidas existentes de la lista (entre 1 y 50 códigos; más de 50 responde `400 too_many_codes`).","operationId":"batchTariffCodes","requestBody":{"content":{"application/json":{"example":{"codes":["8471300000"]},"schema":{"$ref":"#/components/schemas/CodeBatch"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/TariffCode"},"type":"array"}},"type":"object"}]}}},"description":"Partidas encontradas."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Consultar varias partidas","tags":["Catálogos"]}},"/reference/tariff-codes/browse":{"get":{"description":"Hijos directos de una partida (`parent`) o las partidas de primer nivel de un capítulo (`chapter`). Se requiere uno de los dos.","operationId":"browseTariffCodes","parameters":[{"description":"Código de la partida padre.","in":"query","name":"parent","schema":{"type":"string"}},{"description":"Capítulo.","in":"query","name":"chapter","schema":{"type":"string"}},{"description":"Resultados (1–500).","in":"query","name":"limit","schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/TariffCode"},"type":"array"}},"type":"object"}]}}},"description":"Partidas."},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Navegar el arancel","tags":["Catálogos"]}},"/reference/tariff-codes/chapters":{"get":{"description":"Capítulos (primer nivel) del arancel.","operationId":"listTariffChapters","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"properties":{"code":{"type":"string"},"description":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}]}}},"description":"Capítulos."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Capítulos del arancel","tags":["Catálogos"]}},"/reference/tariff-codes/{code}":{"get":{"description":"Partida con su padre y sus hijos directos.","operationId":"getTariffCode","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/TariffCodeDetail"}},"type":"object"}]}}},"description":"La partida."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Ver una partida arancelaria","tags":["Catálogos"]},"parameters":[{"description":"Código de la partida.","in":"path","name":"code","required":true,"schema":{"type":"string"}}]},"/reference/tax-rates":{"get":{"description":"Tabla de códigos de impuesto con su tarifa.","operationId":"listTaxRates","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/TaxRateEntry"},"type":"array"}},"type":"object"}]}}},"description":"Tarifas."},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[],"summary":"Tarifas de impuestos","tags":["Catálogos"]}},"/status":{"get":{"description":"Verificación de salud pública del API y de la disponibilidad de Hacienda. Limitado a 120 solicitudes por minuto por IP.","operationId":"getStatus","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ServiceStatus"}},"type":"object"}]}}},"description":"Estado actual.","headers":{"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"}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/ServiceStatus"}},"type":"object"}]}}},"description":"El API no puede atender solicitudes (`status` = `degraded`)."}},"security":[],"summary":"Estado del servicio","tags":["Estado"]}},"/webhooks":{"get":{"description":"Webhooks de la organización en el ambiente de la clave, ordenados por nombre.","operationId":"listWebhooks","parameters":[{"description":"`true` o `1` para ver solo los activos; `false` para solo los inactivos.","in":"query","name":"active","schema":{"enum":["true","false","1","0"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array"}},"type":"object"}]}}},"description":"Webhooks."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Listar webhooks","tags":["Webhooks"],"x-required-ability":"webhooks:read"},"post":{"description":"Registra una URL que recibirá los eventos indicados del ambiente de la clave. La URL\ndebe ser `https://`, de un host público y sin credenciales. La respuesta incluye el\n`secret` para verificar las firmas; **solo se muestra aquí** (o al regenerarlo).\n","operationId":"createWebhook","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"events":["document.accepted","document.rejected","document.voided"],"max_retries":3,"name":"ERP producción","timeout_seconds":30,"url":"https://erp.example.com/webhooks/aster"},"schema":{"$ref":"#/components/schemas/WebhookInput"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookCreated"}},"type":"object"}]}}},"description":"Webhook creado."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Crear un webhook","tags":["Webhooks"],"x-required-ability":"webhooks:write"}},"/webhooks/{id}":{"delete":{"description":"Elimina el webhook; deja de recibir eventos.","operationId":"deleteWebhook","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Webhook eliminado."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Eliminar un webhook","tags":["Webhooks"],"x-required-ability":"webhooks:manage"},"get":{"description":"Un webhook de la organización (sin su secreto).","operationId":"getWebhook","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Webhook"}},"type":"object"}]}}},"description":"El webhook."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Ver un webhook","tags":["Webhooks"],"x-required-ability":"webhooks:read"},"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"put":{"description":"Cambia los campos enviados. Reactivar un webhook desactivado (`is_active: true`) borra su contador de fallos.","operationId":"updateWebhook","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"example":{"events":["document.accepted","document.rejected"],"is_active":true},"schema":{"$ref":"#/components/schemas/WebhookUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"properties":{"id":{"format":"int64","type":"integer"}},"type":"object"}},"type":"object"}]}}},"description":"Webhook actualizado."},"400":{"$ref":"#/components/responses/BadRequest"},"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"}},"summary":"Actualizar un webhook","tags":["Webhooks"],"x-required-ability":"webhooks:manage"}},"/webhooks/{id}/deliveries":{"get":{"description":"Los últimos 100 intentos de entrega del webhook, del más reciente al más antiguo.","operationId":"listWebhookDeliveries","responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookDelivery"},"type":"array"}},"type":"object"}]}}},"description":"Intentos de entrega."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Registro de entregas","tags":["Webhooks"],"x-required-ability":"webhooks:read"},"parameters":[{"$ref":"#/components/parameters/WebhookId"}]},"/webhooks/{id}/deliveries/{delivery}/redeliver":{"parameters":[{"$ref":"#/components/parameters/WebhookId"},{"description":"Id del intento de entrega (de `GET /webhooks/{id}/deliveries`).","in":"path","name":"delivery","required":true,"schema":{"format":"int64","type":"integer"}}],"post":{"description":"Pone en cola una copia nueva de una entrega anterior (mismo evento y contenido, con un nuevo presupuesto de reintentos y un nuevo `X-Webhook-ID`).","operationId":"redeliverWebhookDelivery","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"content":{"application/json":{"example":{"api_version":"1.0","message":"Redelivery queued.","success":true,"timestamp":"2026-10-08T16:40:00Z"},"schema":{"$ref":"#/components/schemas/Envelope"}}},"description":"Reenvío en cola."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Reenviar una entrega","tags":["Webhooks"],"x-required-ability":"webhooks:manage"}},"/webhooks/{id}/regenerate-secret":{"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"post":{"description":"Genera un secreto nuevo; el anterior deja de firmar de inmediato.","operationId":"regenerateWebhookSecret","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookSecret"}},"type":"object"}]}}},"description":"Secreto nuevo."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Regenerar el secreto","tags":["Webhooks"],"x-required-ability":"webhooks:manage"}},"/webhooks/{id}/test":{"parameters":[{"$ref":"#/components/parameters/WebhookId"}],"post":{"description":"Envía de inmediato una entrega de prueba (`X-Webhook-Event: test`) con los mismos\nencabezados y firmas que una entrega real, y devuelve el resultado. El cuerpo de la\nprueba es `{\"event\": \"test\", \"data\": {\"message\", \"webhook_id\", \"timestamp\"}}`.\nSi la conexión falla responde `422 delivery_failed`.\n","operationId":"testWebhook","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/WebhookTestResult"}},"type":"object"}]}}},"description":"Resultado de la entrega de prueba (exitosa o no)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Enviar una prueba","tags":["Webhooks"],"x-required-ability":"webhooks:manage"}}},"security":[{"ApiKey":[]}],"servers":[{"description":"Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.","url":"https://aster.astranexo.com/api/v1"}],"tags":[{"description":"Emisión, consulta, descarga, envío por correo y anulación de comprobantes electrónicos.","name":"Documentos"},{"description":"Aceptación, aceptación parcial o rechazo de comprobantes recibidos de proveedores.","name":"Mensajes receptor"},{"description":"Contribuyentes de la cuenta, su perfil, certificado de firma, consecutivos y marca.","name":"Organizaciones"},{"description":"Claves de cuenta y de organización.","name":"Claves API"},{"description":"Cuenta, plan, consumo del período y lista pública de precios.","name":"Cuenta y uso"},{"description":"Notificaciones firmadas de cambios de estado de los documentos.","name":"Webhooks"},{"description":"Clientes guardados de la organización.","name":"Receptores"},{"description":"Estado de Hacienda, consultas de comprobantes y registro de contribuyentes.","name":"Hacienda"},{"description":"Catálogos públicos de Hacienda (CABYS, partidas arancelarias, ubicaciones y tablas de códigos FE 4.4).","name":"Catálogos"},{"description":"Tipo de cambio de referencia, histórico y por entidad financiera.","name":"Tipo de cambio"},{"description":"Archeion, el archivo fiscal de 5 años; exportaciones e importaciones.","name":"Archivo"},{"description":"Salud del servicio.","name":"Estado"}],"webhooks":{"callback.received":{"post":{"description":"Evento reservado. Puede suscribirse, pero actualmente no se emite; use `document.accepted` y `document.rejected` para conocer el veredicto.","operationId":"onCallbackReceived","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackReceivedEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Respuesta de Hacienda recibida","tags":["Webhooks"]}},"document.accepted":{"post":{"description":"Hacienda aceptó el comprobante o mensaje receptor (`document_type: \"RC\"` en los mensajes receptor).","operationId":"onDocumentAccepted","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"example":{"document_key":"50608102600310112345600100001010000000042112345678","document_type":"01","hacienda_message":"Este comprobante fue aceptado en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios","hacienda_status":"accepted","response_xml_path":"aster/6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44/staging/2026/10/emitidos/FE/50608102600310112345600100001010000000042112345678/RespuestaFacturaElectronica_00100001010000000042.xml","signed_xml_path":"aster/6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44/staging/2026/10/emitidos/FE/50608102600310112345600100001010000000042112345678/FacturaElectronica_00100001010000000042.xml","status":"accepted"},"schema":{"$ref":"#/components/schemas/DocumentVerdictEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Documento aceptado por Hacienda","tags":["Webhooks"]}},"document.queued":{"post":{"description":"Hacienda no estaba disponible al enviar el documento; quedó en cola y se reenviará automáticamente. El veredicto llegará después con `document.accepted` o `document.rejected`.","operationId":"onDocumentQueued","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentQueuedEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Documento en cola","tags":["Webhooks"]}},"document.rejected":{"post":{"description":"Hacienda rechazó el comprobante o mensaje receptor. El detalle de los errores está en `hacienda_message` y en `GET /electronic-documents/{key}` (`rejections`). El consecutivo queda consumido; para sustituirlo emita un documento nuevo con código de referencia `16`.","operationId":"onDocumentRejected","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVerdictEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Documento rechazado por Hacienda","tags":["Webhooks"]}},"document.signed":{"post":{"description":"Se envía cuando un comprobante o mensaje receptor queda firmado, antes de enviarse a\nHacienda. Para mensajes receptor `document_type` es `RC`.\n","operationId":"onDocumentSigned","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentSignedEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega; otra respuesta o un error de conexión provoca reintentos."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Documento firmado","tags":["Webhooks"]}},"document.voided":{"post":{"description":"Hacienda aceptó la nota de crédito emitida con `POST /documents/{key}/void`; el documento original queda anulado.","operationId":"onDocumentVoided","parameters":[{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookIdHeader"},{"$ref":"#/components/parameters/WebhookTimestampHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"},{"$ref":"#/components/parameters/WebhookSignatureV2Header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVoidedEvent"}}},"required":true},"responses":{"200":{"description":"Cualquier respuesta 2xx confirma la entrega."},"500":{"description":"Error del receptor; la entrega se reintenta."}},"summary":"Documento anulado","tags":["Webhooks"]}}}}