{"openapi":"3.1.0","info":{"title":"Factumel API","version":"1.6.0","description":"API REST de Factumel para integrar facturación electrónica uruguaya. La creación, la firma, el envío y la aceptación por DGI son etapas distintas. La API key determina el ambiente y, opcionalmente, una única empresa. Las claves anteriores siguen siendo organizacionales; enviar a DGI en producción requiere habilitación fiscal real.","contact":{"email":"info@zuomy.uy"}},"servers":[{"url":"https://factumel.com","description":"Factumel. El ambiente lo determina la API key."}],"tags":[{"name":"Empresas","description":"Empresas de la organización, filtradas a la compañía de la API key si está restringida."},{"name":"Comprobantes","description":"Ciclo de vida de comprobantes electrónicos."},{"name":"DGI Uruguay","description":"Consultas a emisores electrónicos de DGI."},{"name":"Recibidos","description":"CFE recibidos por las empresas autorizadas de la organización y ambiente de la clave."},{"name":"Administración de webhooks","description":"Sólo claves de alcance organizacional con permiso webhooks:manage."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key fmk_test_, fmk_hom_ o fmk_live_ generada en /dashboard/api. Seleccionar explícitamente empresa o alcance organizacional. Claves antiguas permanecen organizacionales. Nunca incluir secretos en navegadores."}},"schemas":{"CaeRange":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"series":{"type":"string"},"authorization":{"type":["string","null"]},"numberFrom":{"type":"string"},"numberTo":{"type":"string"},"nextNumber":{"type":"string"},"remaining":{"type":"string"},"available":{"type":"boolean"},"signatureVerified":{"type":"boolean"},"active":{"type":"boolean"},"validUntil":{"type":["string","null"],"format":"date"}}},"IssuanceReadiness":{"type":"object","properties":{"companyId":{"type":"string"},"environment":{"type":"string"},"documentType":{"type":"string"},"canAttemptIssuance":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object"}},"blocked":{"type":"array","items":{"type":"object"}},"cae":{"type":"object"},"checkedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["error"]},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"legalName":{"type":["string","null"]},"taxId":{"type":"string"},"countryCode":{"type":"string"},"status":{"type":"string"},"environment":{"type":"string","enum":["TEST","HOMOLOGATION","PRODUCTION"]},"fiscalProfileConfigured":{"type":"boolean"},"providers":{"type":"array","items":{"type":"string"}}}},"Item":{"type":"object","additionalProperties":false,"required":["description","quantity","unitPrice","taxRate"],"properties":{"description":{"type":"string","minLength":1,"maxLength":500},"quantity":{"type":"number","exclusiveMinimum":0},"unitPrice":{"type":"number"},"taxRate":{"type":"number","minimum":0,"maximum":100},"unitMeasure":{"type":"string","minLength":1,"maxLength":10},"fiscalIndicator":{"type":"integer","minimum":1,"maximum":17},"agentResponsibleIndicator":{"type":"string","enum":["R","A"]},"discountPercent":{"type":"number","minimum":0,"maximum":100},"discountAmount":{"type":"number","minimum":0},"surchargePercent":{"type":"number","minimum":0,"maximum":999.999},"surchargeAmount":{"type":"number","minimum":0}}},"PaymentMethod":{"type":"object","additionalProperties":false,"required":["description","amount"],"properties":{"code":{"type":"string","maxLength":20},"description":{"type":"string","minLength":1,"maxLength":50},"printOrder":{"type":"integer","minimum":0,"maximum":99},"amount":{"type":"number","exclusiveMinimum":0}}},"DocumentReference":{"type":"object","additionalProperties":false,"properties":{"globalReference":{"type":"boolean"},"sourceDocumentId":{"type":"string","minLength":1},"documentType":{"type":"string","maxLength":10},"series":{"type":"string","maxLength":10},"number":{"type":"string","pattern":"^\\d+$"},"reason":{"type":"string","maxLength":200},"referencedAt":{"type":"string","format":"date"},"amount":{"type":"number","exclusiveMinimum":0},"currencyCode":{"type":"string","minLength":3,"maxLength":3},"exchangeRate":{"type":"number","exclusiveMinimum":0}},"description":"La validez fiscal de las referencias se comprueba según el tipo de CFE. Usar sourceDocumentId cuando el documento original está registrado en Factumel."},"GlobalAdjustment":{"type":"object","additionalProperties":false,"required":["movement","valueType","inputValue","description","fiscalIndicator"],"properties":{"movement":{"type":"string","enum":["D","R"]},"valueType":{"type":"integer","enum":[1,2]},"inputValue":{"oneOf":[{"type":"string"},{"type":"number"}]},"amount":{"oneOf":[{"type":"string"},{"type":"number"}]},"code":{"type":"string","pattern":"^\\d{1,3}$"},"description":{"type":"string","minLength":1,"maxLength":100},"fiscalIndicator":{"type":"integer","minimum":1,"maximum":17}},"description":"Zona D: está sujeta a las barreras fiscales de cada ambiente; no implica autorización de envío."},"Retention":{"type":"object","additionalProperties":false,"required":["code","subjectAmount","value"],"properties":{"code":{"type":"string","pattern":"^\\d{4}[-/]?\\d{3}$"},"rate":{"type":"number","minimum":0,"maximum":100},"subjectAmount":{"type":"number","exclusiveMinimum":0},"additionalInfo":{"type":"string","maxLength":150},"value":{"type":"number","exclusiveMinimum":0}}},"RetentionLine":{"type":"object","additionalProperties":false,"required":["retentions"],"properties":{"detailLine":{"type":"integer","minimum":1,"maximum":200},"adjustment":{"type":"boolean"},"retentions":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/Retention"}}}},"DocumentCreate":{"type":"object","additionalProperties":false,"required":["companyId","documentType","currencyCode"],"description":"El servidor valida todas las reglas fiscales adicionales antes de persistir. externalId sigue siendo opcional a nivel HTTP por compatibilidad, pero es fuertemente recomendado para conciliar timeouts; los SDKs oficiales lo exigen.","properties":{"companyId":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1,"maxLength":120,"description":"Único por empresa y ambiente; se utiliza para idempotencia y recuperación."},"documentType":{"type":"string","minLength":1,"maxLength":10,"example":"111"},"issuedAt":{"type":"string","format":"date-time"},"dueDate":{"type":"string","format":"date"},"valueDate":{"type":"string","format":"date"},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"example":"UYU"},"exchangeRate":{"type":"number","exclusiveMinimum":0,"maximum":9999.999},"paymentForm":{"type":"integer","enum":[1,2]},"grossAmountIndicator":{"type":"integer","enum":[1,2,3]},"foreignCurrencyPurchaseIndicator":{"type":"integer","enum":[1,2]},"transferType":{"type":"integer","enum":[1,2]},"goodsOwnerDocumentType":{"type":"integer","minimum":2,"maximum":7},"goodsOwnerCountryCode":{"type":"string","minLength":2,"maxLength":2},"goodsOwnerDocument":{"type":"string","maxLength":20},"goodsOwnerForeignDocument":{"type":"string","maxLength":20},"goodsOwnerName":{"type":"string","maxLength":150},"customerDocumentType":{"type":"integer","minimum":1,"maximum":7},"customerTaxId":{"type":"string","maxLength":40},"customerName":{"type":"string","maxLength":200},"customerAddress":{"type":"string","maxLength":200},"customerCity":{"type":"string","maxLength":100},"customerDepartment":{"type":"string","maxLength":100},"customerCountryCode":{"type":"string","minLength":2,"maxLength":2},"customerCountryName":{"type":"string","maxLength":100},"customerForeignDocument":{"type":"string","maxLength":20},"exportSaleClause":{"type":"string","minLength":1,"maxLength":3},"exportSaleMode":{"type":"integer","enum":[1,2,3,4,90,91,99]},"exportTransportMode":{"type":"integer","enum":[1,2,3,8,9]},"customerEmail":{"type":"string","format":"email","maxLength":254},"customerInterchangeUrl":{"type":"string","format":"uri","maxLength":500},"mandateDocumentType":{"type":"integer","minimum":1,"maximum":7},"mandateCountryCode":{"type":"string","minLength":2,"maxLength":2},"mandateDocument":{"type":"string","maxLength":20},"mandateName":{"type":"string","maxLength":150},"customerDeliveryEmail":{"type":"string","format":"email","maxLength":254},"customerElectronicDeliveryAuthorizedAt":{"type":"string","format":"date-time"},"customerElectronicDeliveryAuthorizationRef":{"type":"string","maxLength":300},"adendaText":{"type":"string","maxLength":10000},"workstationCode":{"type":"string","minLength":1,"maxLength":80},"paymentMethods":{"type":"array","maxItems":40,"items":{"$ref":"#/components/schemas/PaymentMethod"}},"globalAdjustments":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/GlobalAdjustment"}},"retentionLines":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/RetentionLine"}},"references":{"type":"array","maxItems":40,"items":{"$ref":"#/components/schemas/DocumentReference"}},"items":{"type":"array","maxItems":700,"default":[],"items":{"$ref":"#/components/schemas/Item"}}}},"Document":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"environment":{"type":"string"},"externalId":{"type":["string","null"]},"documentType":{"type":"string"},"status":{"type":"string","enum":["DRAFT","QUEUED","SIGNED","SENT","ACCEPTED","OBSERVED","REJECTED","CANCELLED","CONTINGENCY"]},"series":{"type":["string","null"]},"number":{"type":["string","null"]},"total":{"type":"string"},"xsd":{"type":"object"},"envelope":{"type":["object","null"]}}},"OneShotDocumentCreate":{"allOf":[{"$ref":"#/components/schemas/DocumentCreate"},{"type":"object","required":["externalId"]}],"description":"Requiere externalId estable; se crea borrador y se intenta enviar a DGI. No significa aceptación."},"ReceivedCfe":{"type":"object","description":"Resumen de un CFE recibido. Nunca incluye rawXml ni secretos de transporte.","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"environment":{"type":"string","enum":["TEST","HOMOLOGATION","PRODUCTION"]},"source":{"type":"string"},"senderTaxId":{"type":"string"},"receiverTaxId":{"type":["string","null"]},"senderName":{"type":["string","null"]},"documentType":{"type":"string"},"series":{"type":"string"},"number":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"currencyCode":{"type":"string"},"total":{"type":"string"},"signatureValid":{"type":["boolean","null"]},"validationStatus":{"type":"string"},"commercialStatus":{"type":"string"},"responseDeliveryStatus":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"responseDueAt":{"type":"string","format":"date-time"},"respondedAt":{"type":["string","null"],"format":"date-time"},"responseReasonCode":{"type":["string","null"]},"responseReason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookDocument":{"type":"object","additionalProperties":true,"required":["id","environment","status"],"properties":{"id":{"type":"string"},"externalId":{"type":["string","null"]},"environment":{"type":"string","enum":["TEST","HOMOLOGATION","PRODUCTION"]},"countryCode":{"type":"string"},"documentType":{"type":"string"},"series":{"type":["string","null"]},"number":{"type":["string","null"]},"currencyCode":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"total":{"type":"string"},"status":{"type":"string"},"authorityTrack":{"type":["string","null"]},"xsdValidationOk":{"type":["boolean","null"]}}},"ManagedWebhookEndpoint":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"consecutiveFailures":{"type":"integer"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastFailureAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEndpointCreate":{"type":"object","additionalProperties":false,"required":["url","events"],"properties":{"url":{"type":"string","format":"uri","maxLength":2000,"description":"HTTPS público, con DNS/IP aprobados por la protección contra SSRF."},"events":{"type":"array","minItems":1,"maxItems":50,"uniqueItems":true,"items":{"type":"string"},"description":"Eventos admitidos: *, document.* o nombres específicos documentados en /desarrolladores/webhooks."}}},"WebhookEndpointUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","format":"uri","maxLength":2000},"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"active":{"type":"boolean"}}},"WebhookEvent":{"type":"object","additionalProperties":false,"required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","description":"ID estable; puede repetirse en reintentos. Deduplícalo por organización/destino."},"type":{"type":"string","description":"Evento fiscal, por ejemplo document.accepted o dgi.transport_unknown."},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","required":["event","document"],"properties":{"event":{"type":"object","properties":{"sourceType":{"type":"string"},"status":{"type":["string","null"]},"message":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true}}},"document":{"$ref":"#/components/schemas/WebhookDocument"}}}}}},"responses":{"RateLimited":{"description":"Cuota por API key y tipo de operación superada. Respetar Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooLarge":{"description":"Payload JSON mayor a 1 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API key ausente o no válida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Scope insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Invalid":{"description":"Parámetros o payload no válidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":{"DocumentId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"WebhookId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"}}}},"paths":{"/api/v1/companies":{"get":{"tags":["Empresas"],"summary":"Listar empresas de la organización y ambiente","description":"Sólo retorna empresas de la organización autenticada. fiscalProfileConfigured indica configuración activa, no autorización fiscal ni preparación completa.","x-required-scope":"documents:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Empresas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/companies/{id}/cae":{"get":{"tags":["Empresas"],"summary":"Rangos CAE y numeración disponibles en DGI","x-required-scope":"documents:read","description":"Rangos propios de la empresa, filtrados por la organización y ambiente de la API key. La disponibilidad informativa no reserva numeración ni garantiza la autorización fiscal.","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"name":"documentType","in":"query","schema":{"type":"string","pattern":"^\\d{3}$"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Rangos CAE y disponibilidad","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CaeRange"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"environment":{"type":"string"},"fiscalDay":{"type":"string","format":"date"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/companies/{id}/issuance-readiness":{"get":{"tags":["Empresas"],"summary":"Prechequeo fiscal sin efectos secundarios","x-required-scope":"documents:read","description":"Diagnóstico por tipo CFE, empresa y ambiente. No sustituye homologación, conectividad SOAP ni aceptación de DGI.","parameters":[{"$ref":"#/components/parameters/DocumentId"},{"name":"documentType","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{3}$"}}],"responses":{"200":{"description":"Chequeo informativo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuanceReadiness"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents":{"get":{"tags":["Comprobantes"],"summary":"Listar comprobantes","x-required-scope":"documents:read","parameters":[{"name":"companyId","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Página de comprobantes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Comprobantes"],"summary":"Crear un borrador fiscal","x-required-scope":"documents:write","description":"No firma, no consume CAE y no envía a DGI. Usar externalId para idempotencia por empresa.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreate"}}}},"responses":{"200":{"description":"Repetición idempotente","content":{"application/json":{"schema":{"type":"object"}}}},"201":{"description":"Borrador creado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"idempotent":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Invalid"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/issue-and-submit":{"post":{"tags":["Comprobantes"],"summary":"Crear, firmar e intentar transmitir en una sola solicitud","x-required-scopes":["documents:write","documents:submit"],"description":"Operación con efectos fiscales. Reutiliza el contrato de creación y los guards del envío existente. externalId es obligatorio para idempotencia y recuperación. En PRODUCTION está deshabilitado salvo API_ONE_SHOT_LIVE_ENABLED=true en el servidor. HTTP 202 significa pendiente; ni HTTP 200 ni submitted=true garantizan ACCEPTED. Con timeout/errores, consultar primero GET /documents/lookup. NO reintentar con otro externalId.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneShotDocumentCreate"}}}},"responses":{"200":{"description":"Se obtuvo un estado final; inspeccionar data.status (ACCEPTED, REJECTED u OBSERVED).","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Creado o reusado; transmisión y aceptación DGI pueden estar pendientes. Incluye documentId y Location.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Invalid"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Invalid"},"503":{"description":"Desconocido si DGI recibió: recuperar con documentId y conciliar sin reenvío automático."}}}},"/api/v1/documents/lookup":{"get":{"tags":["Comprobantes"],"summary":"Recuperar por externalId","x-required-scope":"documents:read","description":"Busca por companyId y externalId dentro de la organización y ambiente autenticados. Útil al recuperar un timeout sin generar un CFE duplicado.","parameters":[{"name":"companyId","in":"query","required":true,"schema":{"type":"string"}},{"name":"externalId","in":"query","required":true,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Comprobante existente","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}":{"get":{"tags":["Comprobantes"],"summary":"Consultar comprobante","x-required-scope":"documents:read","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Comprobante, historial y estado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}/issue":{"post":{"tags":["Comprobantes"],"summary":"Preparar, numerar y firmar","x-required-scope":"documents:issue","description":"Valida y firma usando CAE. Todavía no significa enviado ni aceptado por DGI.","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Estado de emisión","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"idempotent":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"409":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}/submit":{"post":{"tags":["Comprobantes"],"summary":"Transmitir a DGI","x-required-scope":"documents:submit","description":"Puede preparar y firmar si aún está en borrador. submitted señala transmisión, nunca aceptación definitiva. Consultar luego.","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Resultado de envío","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"submitted":{"type":"boolean"},"idempotent":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}/status":{"post":{"tags":["Comprobantes"],"summary":"Actualizar estado contra DGI","x-required-scope":"documents:status","description":"Consultar estado asíncrono del CFE en su sobre, o devolver estado final almacenado. No emitir ni reenviar.","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Estado final o transitorio","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"},"dgiStatus":{"type":["string","null"]},"finalStatus":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}/pdf":{"get":{"tags":["Comprobantes"],"summary":"Descargar PDF fiscal generado con el mismo renderer del panel","x-required-scope":"documents:read","description":"Requiere XML firmado, XSD válido y CAE documentado. El PDF de TEST/HOMOLOGATION lleva marca SIN VALOR FISCAL.","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"PDF fiscal","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"409":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/documents/{id}/xml":{"get":{"tags":["Comprobantes"],"summary":"Descargar XML firmado validado","x-required-scope":"documents:read","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"XML firmado","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"409":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/received-documents":{"get":{"tags":["Recibidos"],"summary":"Listar CFE recibidos","x-required-scope":"received:read","description":"Filtros de organización y ambiente obligatorios; una API key restringida a una empresa sólo devuelve esa empresa. No incluye el XML original para evitar transferirlo en listados.","parameters":[{"name":"companyId","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Página de CFE recibidos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedCfe"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/received-documents/{id}":{"get":{"tags":["Recibidos"],"summary":"Consultar CFE recibido","x-required-scope":"received:read","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Comprobante recibido","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReceivedCfe"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/received-documents/{id}/xml":{"get":{"tags":["Recibidos"],"summary":"Descargar XML original de CFE recibido","description":"Devuelve el XML originalmente recibido, sin afirmar validación de firma DGI; revisar signatureValid y validationStatus por separado.","x-required-scope":"received:read","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"XML recibido original","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks":{"get":{"tags":["Administración de webhooks"],"summary":"Listar destinos webhook de la organización","description":"Exige webhooks:manage y API key de alcance organizacional; nunca expone secretos ni sus hashes.","x-required-scope":"webhooks:manage","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Lista paginada de endpoints sin secretos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ManagedWebhookEndpoint"}},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Administración de webhooks"],"summary":"Crear destino HTTPS y generar secreto HMAC una sola vez","description":"Sólo claves organizacionales con webhooks:manage; valida DNS/SSRF. El secreto se entrega una sola vez.","x-required-scope":"webhooks:manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Destino creado, incluye secret solamente en esta respuesta","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedWebhookEndpoint"},"secret":{"type":"string","writeOnly":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks/{id}":{"get":{"tags":["Administración de webhooks"],"summary":"Consultar destino sin revelar su secreto","x-required-scope":"webhooks:manage","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedWebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Administración de webhooks"],"summary":"Actualizar URL, eventos y activación","x-required-scope":"webhooks:manage","description":"Al reactivar se reinicia el cursor de nuevos eventos. El destino HTTPS vuelve a validarse.","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"Endpoint actualizado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedWebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/Invalid"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Administración de webhooks"],"summary":"Archivar destino y cancelar pendientes","x-required-scope":"webhooks:manage","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"204":{"description":"Archivado sin body"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks/{id}/rotate-secret":{"post":{"tags":["Administración de webhooks"],"summary":"Rotar secreto HMAC","x-required-scope":"webhooks:manage","description":"Invalida el secreto anterior para futuras entregas; el nuevo valor aparece únicamente en esta respuesta.","parameters":[{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Secreto nuevo mostrado una sola vez","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"secret":{"type":"string","writeOnly":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/uy/electronic-issuers":{"get":{"tags":["DGI Uruguay"],"summary":"Consultar directorio de emisores electrónicos","x-required-scope":"documents:read","parameters":[{"name":"companyId","in":"query","required":true,"schema":{"type":"string"}},{"name":"rut","in":"query","required":true,"schema":{"type":"string"}},{"name":"force","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Información del directorio y contraparte de intercambio","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"webhooks":{"fiscalEvent":{"post":{"tags":["Comprobantes"],"summary":"Entrega HTTP saliente de eventos de Factumel","description":"Esta operación describe un callback realizado por Factumel hacia la URL HTTPS configurada desde el dashboard. No es un endpoint público para crear eventos. Entrega at-least-once: verificar HMAC, evitar replay y deduplicar id.","security":[],"parameters":[{"name":"x-factumel-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Segundos Unix UTC; rechazar fuera de una ventana de tiempo pequeña."},{"name":"x-factumel-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1=[0-9a-f]{64}$"},"description":"HMAC SHA256 hex del timestamp + punto + cuerpo JSON literal, usando secreto del webhook."},{"name":"x-factumel-event","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-factumel-event-id","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"El integrador confirmó la recepción duradera del evento. Cualquier 2xx se acepta."},"400":{"description":"Firma inválida u otro error del receptor; Factumel considera la entrega fallida."}}}}}}