{"openapi":"3.1.0","info":{"title":"Monetae Conecta — API pública","version":"1.0.0","description":"API de integración para ERP, CRM, sistemas de facturación y cores bancarios.\n\nAutenticación: cabecera `Authorization: Bearer <llave de la integración>`.\nPaginación: por cursor (`limit`, `cursor`).\nIdempotencia: cabecera `Idempotency-Key` en las creaciones; obligatoria en salidas.\nMontos: decimales en texto con moneda explícita. Fechas: ISO 8601 en UTC.\n\nCódigos de error: unauthenticated (401), invalid_credential (401), credential_revoked (401), permission_denied (403), company_not_allowed (403), invalid_request (400), invalid_parameter (400), missing_parameter (400), invalid_cursor (400), unsupported_version (400), idempotency_key_required (400), resource_not_found (404), duplicate_reference (409), resource_conflict (409), idempotency_key_reused (409), request_in_progress (409), account_not_active (422), account_lifecycle_closed (422), insufficient_funds (422), destination_not_registered (422), beneficiary_name_mismatch (422), amount_out_of_range (422), rail_not_enabled (422), operation_not_available_via_api (422), rate_limit_exceeded (429), internal_error (500), service_unavailable (503)."},"servers":[{"url":"https://conectademo.monetae.io"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Cuentas"},{"name":"Saldos"},{"name":"Clientes"},{"name":"Recaudos"},{"name":"Salidas"},{"name":"Barridos"},{"name":"Obligaciones"},{"name":"Aplicaciones"},{"name":"Webhooks"}],"paths":{"/api/public/v1/accounts":{"get":{"operationId":"accounts-list","tags":["Cuentas"],"summary":"Listar cuentas virtuales","description":"Devuelve las cuentas virtuales de la empresa, de la más reciente a la más antigua, con paginación por cursor.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filtra por estado de la cuenta. (ACTIVE | FULFILLED | EXPIRED | SUSPENDED | CLOSED | ARCHIVED)","schema":{"type":"string"}},{"name":"external_account_reference","in":"query","required":false,"description":"Busca por la referencia que asignó el sistema del cliente. (texto)","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Solo las cuentas de ese cliente. (uuid)","schema":{"type":"string"}},{"name":"virtual_account_number","in":"query","required":false,"description":"Busca por número de cuenta virtual. (texto)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"account","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_number":"01423100000174","use":"CUSTOMER_FINAL","type":"OBLIGATION","modality":"ONE_TIME","status":"ACTIVE","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","alias":null,"customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","external_customer_reference":"ERP-CLI-0091","external_account_reference":"FAC-2026-00187","obligation_reference":"FAC-2026-00187","description":"Factura 187 de enero","expected_amount":{"amount":"1500.00","currency":"USD"},"collected_amount":{"amount":"0.00","currency":"USD"},"balance":{"amount":"0.00","currency":"USD"},"expires_at":"2026-02-28T23:59:59.000Z","created_at":"2026-01-15T14:32:01.204Z","is_primary":false,"holder_scope":"THIRD_PARTY","collection_mode":"GENERAL"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"accounts-create","tags":["Cuentas"],"summary":"Crear una cuenta virtual","description":"Crea una cuenta virtual y devuelve su número. Las cuentas CUSTOMER y OBLIGATION siempre van asociadas a un cliente (por customer_id o external_customer_reference); FUNDING puede ir sin cliente. Solo OBLIGATION lleva modalidad y referencia de obligación.","security":[{"bearerAuth":[]}],"x-scope":"accounts:write","x-scopes":["accounts:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Recomendado: repetir la misma llamada con la misma llave devuelve la cuenta original en lugar de crear otra. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","associated_entity"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"type":{"description":"Tipo de cuenta. (CUSTOMER | OBLIGATION | FUNDING)"},"modality":{"description":"Modalidad de la obligación. (ONE_TIME | INSTALLMENTS | RECURRING) Condicional: Obligatorio si type es OBLIGATION; se rechaza en CUSTOMER y FUNDING."},"associated_entity":{"description":"Entidad asociada a la cuenta (a nombre de quién opera). (texto (máx. 160))"},"customer_id":{"description":"Cliente del maestro. (uuid) Condicional: Obligatorio en CUSTOMER y OBLIGATION, salvo que envíes external_customer_reference."},"external_customer_reference":{"description":"Referencia del cliente en el sistema origen. (texto (máx. 80)) Condicional: Alternativa a customer_id; uno de los dos es obligatorio en CUSTOMER y OBLIGATION."},"obligation_reference":{"description":"Número de factura, contrato o cuota. (texto (máx. 80)) Condicional: Obligatorio si type es OBLIGATION."},"external_account_reference":{"description":"Referencia de la cuenta en el sistema origen. Única por empresa; si se omite se usa obligation_reference o el número de cliente. (texto (máx. 80))"},"alias":{"description":"Alias interno para cuentas operativas (ej. Nómina, Tesorería). (texto (máx. 60))"},"description":{"description":"Descripción libre. (texto (máx. 240))"},"expected_amount":{"description":"Monto esperado a recaudar. (decimal > 0, máx. 10.000.000)"},"expires_at":{"description":"Fecha de vencimiento de la cuenta. (fecha ISO 8601 con zona)"}}},"example":{"type":"OBLIGATION","modality":"ONE_TIME","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","external_customer_reference":"ERP-CLI-0091","obligation_reference":"FAC-2026-00187","expected_amount":1500,"expires_at":"2026-02-28T23:59:59Z"}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"account","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_number":"01423100000174","use":"CUSTOMER_FINAL","type":"OBLIGATION","modality":"ONE_TIME","status":"ACTIVE","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","alias":null,"customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","external_customer_reference":"ERP-CLI-0091","external_account_reference":"FAC-2026-00187","obligation_reference":"FAC-2026-00187","description":"Factura 187 de enero","expected_amount":{"amount":"1500.00","currency":"USD"},"collected_amount":{"amount":"0.00","currency":"USD"},"balance":{"amount":"0.00","currency":"USD"},"expires_at":"2026-02-28T23:59:59.000Z","created_at":"2026-01-15T14:32:01.204Z","is_primary":false,"holder_scope":"THIRD_PARTY","collection_mode":"GENERAL"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/accounts/{account_id}":{"get":{"operationId":"accounts-get","tags":["Cuentas"],"summary":"Consultar una cuenta virtual","description":"Devuelve una cuenta por su identificador. El número de cuenta virtual no es el identificador del recurso.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"account_id","in":"path","required":true,"description":"Identificador de la cuenta. (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"account","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_number":"01423100000174","use":"CUSTOMER_FINAL","type":"OBLIGATION","modality":"ONE_TIME","status":"ACTIVE","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","alias":null,"customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","external_customer_reference":"ERP-CLI-0091","external_account_reference":"FAC-2026-00187","obligation_reference":"FAC-2026-00187","description":"Factura 187 de enero","expected_amount":{"amount":"1500.00","currency":"USD"},"collected_amount":{"amount":"0.00","currency":"USD"},"balance":{"amount":"0.00","currency":"USD"},"expires_at":"2026-02-28T23:59:59.000Z","created_at":"2026-01-15T14:32:01.204Z","is_primary":false,"holder_scope":"THIRD_PARTY","collection_mode":"GENERAL"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"patch":{"operationId":"accounts-patch","tags":["Cuentas"],"summary":"Modificar una cuenta virtual","description":"Cambia datos de la cuenta o su estado. Enviá al menos un campo. Una cuenta cerrada o archivada no se puede modificar: reabrirla es una decisión que se toma en el portal.","security":[{"bearerAuth":[]}],"x-scope":"accounts:write","x-scopes":["accounts:write"],"parameters":[{"name":"account_id","in":"path","required":true,"description":"Identificador de la cuenta. (uuid)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"associated_entity":{"description":"Nueva entidad asociada. (texto (máx. 160))"},"alias":{"description":"Alias interno; null lo borra. (texto (máx. 60) o null)"},"description":{"description":"Descripción. (texto (máx. 240) o null)"},"external_account_reference":{"description":"Referencia externa de la cuenta. (texto (máx. 80) o null)"},"expected_amount":{"description":"Monto esperado. (decimal > 0 o null)"},"expires_at":{"description":"Vencimiento. (fecha ISO 8601 con zona o null)"},"status":{"description":"Nuevo estado. Cumplida y vencida las determina la plataforma. (ACTIVE | SUSPENDED | CLOSED)"}}},"example":{"alias":"Nómina","status":"SUSPENDED"}}}},"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"account","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_number":"01423100000174","use":"CUSTOMER_FINAL","type":"OBLIGATION","modality":"ONE_TIME","status":"SUSPENDED","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","alias":null,"customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","external_customer_reference":"ERP-CLI-0091","external_account_reference":"FAC-2026-00187","obligation_reference":"FAC-2026-00187","description":"Factura 187 de enero","expected_amount":{"amount":"1500.00","currency":"USD"},"collected_amount":{"amount":"0.00","currency":"USD"},"balance":{"amount":"0.00","currency":"USD"},"expires_at":"2026-02-28T23:59:59.000Z","created_at":"2026-01-15T14:32:01.204Z","is_primary":false,"holder_scope":"THIRD_PARTY","collection_mode":"GENERAL"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/accounts/{account_id}/balance":{"get":{"operationId":"accounts-balance","tags":["Saldos"],"summary":"Saldo de una cuenta virtual","description":"Saldo disponible de la cuenta según el libro contable de la plataforma.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"account_id","in":"path","required":true,"description":"Identificador de la cuenta. (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"balance","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","available":{"amount":"1500.00","currency":"USD"},"as_of":"2026-01-18T16:40:00.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/accounts/{account_id}/movements":{"get":{"operationId":"accounts-movements","tags":["Saldos"],"summary":"Movimientos de una cuenta virtual","description":"Entradas y salidas de la cuenta, de la más reciente a la más antigua. Este listado avanza con `before`, no con `cursor`.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"account_id","in":"path","required":true,"description":"Identificador de la cuenta. (uuid)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Trae los movimientos anteriores a ese momento: usá el `next_cursor` de la página previa. (fecha ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"account_movement","movement_id":"5c4b3a29-1817-4655-9243-0a1b2c3d4e5f","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","direction":"CREDIT","operation":"PAYIN","amount":{"amount":"1500.00","currency":"USD"},"source_reference":"PI-2026-00018492","description":"Recaudo acreditado","occurred_at":"2026-01-18T15:22:10.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/balances/master":{"get":{"operationId":"balances-master","tags":["Saldos"],"summary":"Posición de la cuenta madre","description":"Posición agregada de la empresa: total, fondos de terceros segregados y fondos propios disponibles para salidas.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"master_balance","company_id":"a1111111-0000-4000-8000-000000000001","total":{"amount":"125430.18","currency":"USD"},"third_party":{"amount":"98120.44","currency":"USD"},"own":{"amount":"27309.74","currency":"USD"},"as_of":"2026-01-18T16:40:00.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/customers":{"get":{"operationId":"customers-list","tags":["Clientes"],"summary":"Listar clientes","description":"Clientes del maestro de la empresa, con paginación por cursor.","security":[{"bearerAuth":[]}],"x-scope":"customers:read","x-scopes":["customers:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"external_customer_reference","in":"query","required":false,"description":"Referencia del cliente en el sistema origen. (texto)","schema":{"type":"string"}},{"name":"customer_code","in":"query","required":false,"description":"Número de cliente de Conecta (CLI-######). (texto)","schema":{"type":"string"}},{"name":"document_number","in":"query","required":false,"description":"Documento del cliente. (texto)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"customer","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","company_id":"a1111111-0000-4000-8000-000000000001","customer_code":"CLI-000091","name":"Distribuidora La Ceiba, S.A. de C.V.","person_type":"LEGAL","document_type":"NIT","document_number":"0614-010190-101-1","email":"pagos@laceiba.com.sv","phone":"+503 2222-2222","contract":"CTR-2026-014","external_customer_reference":"ERP-CLI-0091","status":"ACTIVE","created_at":"2026-01-10T18:04:55.100Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"customers-create","tags":["Clientes"],"summary":"Crear un cliente","description":"Da de alta un cliente en el maestro. Si no declarás el nombre del titular, es obligatorio enviar external_customer_reference: el cliente queda registrado como no declarado.","security":[{"bearerAuth":[]}],"x-scope":"customers:write","x-scopes":["customers:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Recomendado para no duplicar clientes ante reintentos. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"name":{"description":"Nombre o razón social. (texto (máx. 160)) Condicional: Obligatorio salvo que envíes external_customer_reference."},"external_customer_reference":{"description":"Referencia del cliente en el sistema origen. Única por empresa. (texto (máx. 80)) Condicional: Obligatorio si no declarás name."},"person_type":{"description":"Persona natural o jurídica (LEGAL por defecto). (NATURAL | LEGAL)"},"document_type":{"description":"Tipo de documento (NIT, DUI, pasaporte…). (texto (máx. 20))"},"document_number":{"description":"Número de documento. (texto (máx. 40))"},"email":{"description":"Correo de contacto. (correo (máx. 160))"},"phone":{"description":"Teléfono de contacto. (texto (máx. 40))"},"contract":{"description":"Número de contrato. (texto (máx. 80))"},"customer_code":{"description":"Número de cliente propio. Si se omite, Conecta lo genera. (texto (máx. 40))"},"primary_account":{"description":"Si lo enviás, se crea en la misma operación la cuenta virtual principal del cliente. Admite alias, external_account_reference y description. Si falla la cuenta, no se crea el cliente. (objeto)"}}},"example":{"name":"Distribuidora La Ceiba, S.A. de C.V.","person_type":"LEGAL","document_type":"NIT","document_number":"0614-010190-101-1","external_customer_reference":"ERP-CLI-0091","primary_account":{"alias":"Cuenta principal","external_account_reference":"ERP-CTA-0091"}}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"customer","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","company_id":"a1111111-0000-4000-8000-000000000001","customer_code":"CLI-000091","name":"Distribuidora La Ceiba, S.A. de C.V.","person_type":"LEGAL","document_type":"NIT","document_number":"0614-010190-101-1","email":"pagos@laceiba.com.sv","phone":"+503 2222-2222","contract":"CTR-2026-014","external_customer_reference":"ERP-CLI-0091","status":"ACTIVE","created_at":"2026-01-10T18:04:55.100Z","primary_account":{"virtual_account_number":"01423300000144"}}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/customers/{customer_id}":{"get":{"operationId":"customers-get","tags":["Clientes"],"summary":"Consultar un cliente","description":"Devuelve un cliente por su identificador.","security":[{"bearerAuth":[]}],"x-scope":"customers:read","x-scopes":["customers:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"description":"Identificador del cliente. (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"customer","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","company_id":"a1111111-0000-4000-8000-000000000001","customer_code":"CLI-000091","name":"Distribuidora La Ceiba, S.A. de C.V.","person_type":"LEGAL","document_type":"NIT","document_number":"0614-010190-101-1","email":"pagos@laceiba.com.sv","phone":"+503 2222-2222","contract":"CTR-2026-014","external_customer_reference":"ERP-CLI-0091","status":"ACTIVE","created_at":"2026-01-10T18:04:55.100Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"patch":{"operationId":"customers-patch","tags":["Clientes"],"summary":"Modificar un cliente","description":"Actualiza datos de contacto, documento, referencias o estado. Enviá al menos un campo.","security":[{"bearerAuth":[]}],"x-scope":"customers:write","x-scopes":["customers:write"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Identificador del cliente. (uuid)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"name":{"description":"Nombre o razón social. (texto (máx. 160))"},"document_type":{"description":"Tipo de documento. (texto (máx. 20) o null)"},"document_number":{"description":"Número de documento. (texto (máx. 40) o null)"},"email":{"description":"Correo. (correo (máx. 160) o null)"},"phone":{"description":"Teléfono. (texto (máx. 40) o null)"},"contract":{"description":"Contrato. (texto (máx. 80) o null)"},"external_customer_reference":{"description":"Referencia externa. Única por empresa. (texto (máx. 80) o null)"},"status":{"description":"Estado del cliente. (ACTIVE | SUSPENDED | INACTIVE)"}}},"example":{"phone":"+503 2222-2222","status":"SUSPENDED"}}}},"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"customer","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","company_id":"a1111111-0000-4000-8000-000000000001","customer_code":"CLI-000091","name":"Distribuidora La Ceiba, S.A. de C.V.","person_type":"LEGAL","document_type":"NIT","document_number":"0614-010190-101-1","email":"pagos@laceiba.com.sv","phone":"+503 2222-2222","contract":"CTR-2026-014","external_customer_reference":"ERP-CLI-0091","status":"SUSPENDED","created_at":"2026-01-10T18:04:55.100Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/customers/{customer_id}/accounts":{"get":{"operationId":"customers-accounts","tags":["Clientes"],"summary":"Listar las cuentas virtuales de un cliente","description":"Cuentas virtuales asociadas al cliente. La cuenta principal se identifica con is_primary = true.","security":[{"bearerAuth":[]}],"x-scope":"accounts:read","x-scopes":["accounts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"description":"Identificador del cliente. (uuid)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filtra por estado de la cuenta (ACTIVE, SUSPENDED, FULFILLED, EXPIRED, CLOSED). (texto)","schema":{"type":"string"}},{"name":"is_primary","in":"query","required":false,"description":"Filtra solo la cuenta principal o solo las adicionales. (true | false)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"account","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_number":"01423100000174","use":"CUSTOMER_FINAL","type":"OBLIGATION","modality":"ONE_TIME","status":"ACTIVE","associated_entity":"Distribuidora La Ceiba, S.A. de C.V.","alias":null,"customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","external_customer_reference":"ERP-CLI-0091","external_account_reference":"FAC-2026-00187","obligation_reference":"FAC-2026-00187","description":"Factura 187 de enero","expected_amount":{"amount":"1500.00","currency":"USD"},"collected_amount":{"amount":"0.00","currency":"USD"},"balance":{"amount":"0.00","currency":"USD"},"expires_at":"2026-02-28T23:59:59.000Z","created_at":"2026-01-15T14:32:01.204Z","is_primary":false,"holder_scope":"THIRD_PARTY","collection_mode":"GENERAL"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/customers/{customer_id}/obligations":{"get":{"operationId":"customers-obligations","tags":["Clientes"],"summary":"Listar las obligaciones de un cliente","description":"Obligaciones del cliente agregadas a través de todas sus cuentas virtuales.","security":[{"bearerAuth":[]}],"x-scope":"obligations:read","x-scopes":["obligations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"description":"Identificador del cliente. (uuid)","schema":{"type":"string"}},{"name":"virtual_account_id","in":"query","required":false,"description":"Limita a una cuenta virtual del cliente. (uuid)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Estado de la obligación. (texto)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/payins":{"get":{"operationId":"payins-list","tags":["Recaudos"],"summary":"Listar entradas (pay-ins)","description":"Transferencias entrantes a las cuentas virtuales de la empresa. Solo lectura: acreditar, redirigir, devolver o resolver una revisión son decisiones que se toman en el portal.","security":[{"bearerAuth":[]}],"x-scope":"payins:read","x-scopes":["payins:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Estado de la entrada. Los estados de devolución son aditivos: RETURN_REQUESTED y RETURN_PROCESSING no significan que el dinero ya salió. (COMPLETED | UNDER_REVIEW | REDIRECTED | REJECTED | RETURN_REQUESTED | RETURN_PROCESSING | RETURNED | RETURN_FAILED)","schema":{"type":"string"}},{"name":"financial_position","in":"query","required":false,"description":"Dónde está el dinero. Dimensión distinta del estado. (NONE | ACCOUNT | SUSPENSE | RETURN_IN_TRANSIT | EXITED)","schema":{"type":"string"}},{"name":"funds_nature","in":"query","required":false,"description":"Naturaleza económica del dinero recibido. (THIRD_PARTY | OWN_FUNDS | UNDETERMINED)","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Solo las entradas atribuidas a ese cliente. Cliente y cuenta son dimensiones separadas. (uuid)","schema":{"type":"string"}},{"name":"review_reason_code","in":"query","required":false,"description":"Motivo de revisión, en la taxonomía del motor. (texto)","schema":{"type":"string"}},{"name":"external_reference","in":"query","required":false,"description":"Referencia de la entrada en el sistema de la empresa. (texto)","schema":{"type":"string"}},{"name":"created_from","in":"query","required":false,"description":"Registradas desde ese momento (inclusive). (fecha ISO 8601)","schema":{"type":"string"}},{"name":"created_to","in":"query","required":false,"description":"Registradas hasta ese momento (inclusive). (fecha ISO 8601)","schema":{"type":"string"}},{"name":"account_id","in":"query","required":false,"description":"Solo las entradas de esa cuenta. (uuid)","schema":{"type":"string"}},{"name":"virtual_account_number","in":"query","required":false,"description":"Solo las entradas dirigidas a ese número de cuenta virtual. (texto)","schema":{"type":"string"}},{"name":"rail_code","in":"query","required":false,"description":"Riel por el que entró el dinero (hoy `t365`). (texto)","schema":{"type":"string"}},{"name":"received_from","in":"query","required":false,"description":"Recibidas desde ese momento (inclusive). (fecha ISO 8601)","schema":{"type":"string"}},{"name":"received_to","in":"query","required":false,"description":"Recibidas hasta ese momento (inclusive). (fecha ISO 8601)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"payin","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","conecta_transaction_id":"PI-2026-00018492","company_id":"a1111111-0000-4000-8000-000000000001","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","virtual_account_number":"01423100000174","status":"COMPLETED","amount":{"amount":"1500.00","currency":"USD"},"rail":"T365","rail_reference":"T365-20260118-4F7A21C9","origin":{"bank":"Banco Agrícola","account_number":"0011223344","holder_name":"Distribuidora La Ceiba, S.A. de C.V."},"customer_id":"3b8a1f60-92c4-4d0e-9a55-6f0c1d2e3a4b","financial_position":"ACCOUNT","funds_nature":"THIRD_PARTY","review_reason_code":null,"review_opened_at":null,"resolved_at":"2026-01-18T15:24:02.000Z","external_reference":"ERP-FAC-99120","return":null,"received_at":"2026-01-18T15:22:10.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/payins/{payin_id}":{"get":{"operationId":"payins-get","tags":["Recaudos"],"summary":"Consultar una entrada","description":"Acepta el identificador de la entrada o el número de transacción de Conecta (PI-2026-########).","security":[{"bearerAuth":[]}],"x-scope":"payins:read","x-scopes":["payins:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"payin_id","in":"path","required":true,"description":"Identificador de la entrada. (uuid o PI-####-########)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payin","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","conecta_transaction_id":"PI-2026-00018492","company_id":"a1111111-0000-4000-8000-000000000001","account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","virtual_account_number":"01423100000174","status":"COMPLETED","amount":{"amount":"1500.00","currency":"USD"},"rail":"T365","rail_reference":"T365-20260118-4F7A21C9","origin":{"bank":"Banco Agrícola","account_number":"0011223344","holder_name":"Distribuidora La Ceiba, S.A. de C.V."},"customer_id":"3b8a1f60-92c4-4d0e-9a55-6f0c1d2e3a4b","financial_position":"ACCOUNT","funds_nature":"THIRD_PARTY","review_reason_code":null,"review_opened_at":null,"resolved_at":"2026-01-18T15:24:02.000Z","external_reference":"ERP-FAC-99120","return":null,"received_at":"2026-01-18T15:22:10.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/payouts":{"get":{"operationId":"payouts-list","tags":["Salidas"],"summary":"Listar salidas (pay-outs) — Legacy / Historical","description":"Legacy / Historical — Deprecated for new integrations. Superficie de solo lectura sobre el modelo histórico previo a Block 6. No muestra los payouts creados con POST /v1/payouts: para esos usá GET /v2/payouts.","security":[{"bearerAuth":[]}],"x-scope":"payouts:read","x-scopes":["payouts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Estado de la salida. (PENDING_APPROVAL | PROCESSING | COMPLETED | FAILED)","schema":{"type":"string"}},{"name":"external_transaction_reference","in":"query","required":false,"description":"Referencia del pago en el sistema origen. (texto)","schema":{"type":"string"}},{"name":"rail_code","in":"query","required":false,"description":"Riel utilizado (hoy `t365`). (texto)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"payout","payout_id":"9a8b7c6d-5e4f-4031-9182-7364554a3b2c","conecta_transaction_id":"PO-2026-00004871","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","amount":{"amount":"2500.00","currency":"USD"},"fee":{"amount":"0.65","currency":"USD"},"beneficiary":{"name":"Ábaco Factoring, S.A. de C.V.","bank_code":"BAC","account_number":"1234567890"},"concept":"Retiro a cuenta propia","external_transaction_reference":"ERP-PAGO-77812","rail":"T365","rail_reference":"T365-20260118-9C11B4A2","executed_at":"2026-01-18T16:02:44.000Z","created_at":"2026-01-18T16:02:41.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"payouts-create","tags":["Salidas"],"summary":"Originar una salida","description":"Block 8: crea un pago saliente asíncrono hacia una cuenta destino registrada de un beneficiario (destination_account_id), usando el mismo dominio que el Portal: reserva de fondos, política de aprobación (la integración nunca aprueba; si la política lo exige queda pending_approval para aprobadores humanos), control de compliance y envío al riel. Requiere payouts:create y payouts:execute e Idempotency-Key. Respuestas: 201 submitted; 202 pending_funding / pending_approval / compliance. Fuera de sandbox responde 503 rail_integration_pending (riel Credicomer PRODUCTION BLOCKED).","security":[{"bearerAuth":[]}],"x-scope":"payouts:create","x-scopes":["payouts:create","payouts:execute"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Evita ejecutar dos veces el mismo pago ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination_account_id","amount"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"destination_account_id":{"description":"Cuenta destino registrada de un beneficiario activo de la empresa. El origen lo resuelve Tesorería (cuenta operativa + fondeo). (uuid)"},"amount":{"description":"Monto a transferir. También se valida contra el máximo por salida de la integración. (decimal > 0, máx. 10.000.000)"},"currency":{"description":"Moneda (USD). (USD)"},"concept":{"description":"Concepto de la transferencia. (texto (máx. 140))"},"external_transaction_reference":{"description":"Referencia del pago en el sistema origen. Única por empresa. (texto (máx. 80))"},"rail_code":{"description":"Riel; por defecto el de la cuenta destino. (texto)"}}},"example":{"destination_account_id":"7f7b8650-d9d0-4de6-8aeb-3186d8c06b4f","amount":2500,"concept":"Retiro a cuenta propia","external_transaction_reference":"ERP-PAGO-77812"}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payout","payout_id":"9a8b7c6d-5e4f-4031-9182-7364554a3b2c","conecta_transaction_id":"PO-2026-00004871","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","amount":{"amount":"2500.00","currency":"USD"},"fee":{"amount":"0.65","currency":"USD"},"beneficiary":{"name":"Ábaco Factoring, S.A. de C.V.","bank_code":"BAC","account_number":"1234567890"},"concept":"Retiro a cuenta propia","external_transaction_reference":"ERP-PAGO-77812","rail":"T365","rail_reference":"T365-20260118-9C11B4A2","executed_at":"2026-01-18T16:02:44.000Z","created_at":"2026-01-18T16:02:41.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/payouts/{payout_id}":{"get":{"operationId":"payouts-get","tags":["Salidas"],"summary":"Consultar una salida — Legacy / Historical","description":"Legacy / Historical — Deprecated for new integrations. Resuelve registros históricos previos a Block 6 por su identificador o número de transacción de Conecta (PO-2026-########). Para payouts actuales usá GET /v2/payouts/{payout_id}.","security":[{"bearerAuth":[]}],"x-scope":"payouts:read","x-scopes":["payouts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"payout_id","in":"path","required":true,"description":"Identificador de la salida. (uuid o PO-####-########)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payout","payout_id":"9a8b7c6d-5e4f-4031-9182-7364554a3b2c","conecta_transaction_id":"PO-2026-00004871","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","amount":{"amount":"2500.00","currency":"USD"},"fee":{"amount":"0.65","currency":"USD"},"beneficiary":{"name":"Ábaco Factoring, S.A. de C.V.","bank_code":"BAC","account_number":"1234567890"},"concept":"Retiro a cuenta propia","external_transaction_reference":"ERP-PAGO-77812","rail":"T365","rail_reference":"T365-20260118-9C11B4A2","executed_at":"2026-01-18T16:02:44.000Z","created_at":"2026-01-18T16:02:41.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v2/payouts":{"get":{"operationId":"payouts-v2-list","tags":["Salidas"],"summary":"Listar payouts (canónico)","description":"Current / Canonical. Payouts del dominio actual (Block 6), los mismos que crea POST /v1/payouts o el Portal. Estados canónicos en mayúsculas: DRAFT, PENDING_FUNDING, FUNDED, PENDING_APPROVAL, PROCESSING, SUBMITTED, SETTLED, FAILED, CANCELLED, RETURNED, REVERSED. No incluye registros legacy.","security":[{"bearerAuth":[]}],"x-scope":"payouts:read","x-scopes":["payouts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Estado del payout. (estado canónico (p. ej. SETTLED))","schema":{"type":"string"}},{"name":"external_transaction_reference","in":"query","required":false,"description":"Referencia del pago en el sistema origen. (texto)","schema":{"type":"string"}},{"name":"rail_code","in":"query","required":false,"description":"Riel utilizado. (texto)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"payout","payout_id":"3f2c1b0a-9e8d-4c7b-a6f5-1e2d3c4b5a69","conecta_transaction_id":"PO-2026-00000123","status":"SETTLED","amount":{"value":"1500.00","currency":"USD"},"fee":{"value":"1.25","currency":"USD"},"total_debit":{"value":"1501.25","currency":"USD"},"destination_account_id":"7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","concept":"Transferencia a cuenta propia","external_transaction_reference":"ERP-8841","rail_code":"t365","channel":"portal","requires_approval":true,"approval_request_id":"5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716","created_at":"2026-09-25T15:02:11Z","updated_at":"2026-09-25T15:09:40Z","beneficiary_amount":{"value":"1500.00","currency":"USD"},"fee_treatment":"added","approved_at":"2026-09-25T15:05:02Z","submitted_at":"2026-09-25T15:05:03Z","settled_at":"2026-09-25T15:09:40Z","failure_code":null,"failure_reason":null}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v2/payouts/{payout_id}":{"get":{"operationId":"payouts-v2-get","tags":["Salidas"],"summary":"Consultar un payout (canónico)","description":"Current / Canonical. Acepta el identificador canónico del payout o su número de transacción (PO-…).","security":[{"bearerAuth":[]}],"x-scope":"payouts:read","x-scopes":["payouts:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"payout_id","in":"path","required":true,"description":"Identificador del payout. (uuid o PO-…)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payout","payout_id":"3f2c1b0a-9e8d-4c7b-a6f5-1e2d3c4b5a69","conecta_transaction_id":"PO-2026-00000123","status":"SETTLED","amount":{"value":"1500.00","currency":"USD"},"fee":{"value":"1.25","currency":"USD"},"total_debit":{"value":"1501.25","currency":"USD"},"destination_account_id":"7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d","concept":"Transferencia a cuenta propia","external_transaction_reference":"ERP-8841","rail_code":"t365","channel":"portal","requires_approval":true,"approval_request_id":"5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716","created_at":"2026-09-25T15:02:11Z","updated_at":"2026-09-25T15:09:40Z","beneficiary_amount":{"value":"1500.00","currency":"USD"},"fee_treatment":"added","approved_at":"2026-09-25T15:05:02Z","submitted_at":"2026-09-25T15:05:03Z","settled_at":"2026-09-25T15:09:40Z","failure_code":null,"failure_reason":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/treasury-transfers":{"post":{"operationId":"treasury-transfers-create","tags":["Barridos"],"summary":"Movimiento interno de Tesorería hacia una cuenta propia elegible","description":"Block 8: movimiento interno sobre el mismo comando de Tesorería del Portal (Block 5). Orígenes: cuentas de terceros y/o propias de la empresa; destino: cuenta propia elegible (terceros → terceros no está permitido). Se respetan disponibilidad, composición e invariantes de Block 5. Se aplica la política de aprobación de la empresa; si la exige, responde 202 pending_approval y se ejecuta automáticamente cuando aprobadores humanos la completan. Un reintento con la misma intención reutiliza la misma solicitud.","security":[{"bearerAuth":[]}],"x-scope":"transfers:create","x-scopes":["transfers:create"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Clave de idempotencia. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sources","destination_account_id"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"sources":{"description":"Cuentas origen y montos. ([{account_id, amount}])"},"destination_account_id":{"description":"Cuenta destino de la misma empresa. (uuid)"},"composition_policy":{"description":"Política de composición. (proportional | third_party_first | own_funds_first)"},"note":{"description":"Nota. (texto (máx. 280))"}}},"example":{"sources":[{"account_id":"1efd4462-70a4-40e8-898c-b0b9a99e7235","amount":500}],"destination_account_id":"7f7b8650-d9d0-4de6-8aeb-3186d8c06b4f"}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"treasury_transfer","status":"COMPLETED","transfer_id":"…","approval_required":false,"approval_request_id":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/transfers":{"get":{"operationId":"transfers-list","tags":["Barridos"],"summary":"Listar barridos","description":"Transferencias internas de saldo desde cuentas de terceros hacia una cuenta operativa propia, creadas por API o desde el portal.","security":[{"bearerAuth":[]}],"x-scope":"transfers:read","x-scopes":["transfers:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"transfer","transfer_id":"2c9f5ad1-3d47-4b2a-8f33-0a71c9d55e10","transfer_code":"SW-2026-00000132","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","destination_account_id":"1efd4462-70a4-40e8-898c-b0b9a99e7235","amount":{"amount":"4200.00","currency":"USD"},"source_account_count":3,"note":"Barrido previo al retiro semanal","origin":"STANDALONE","executed_at":"2026-01-18T15:59:02.000Z","created_at":"2026-01-18T15:59:01.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"transfers-create","tags":["Barridos"],"summary":"Barrer saldo hacia una cuenta operativa","description":"DEPRECATED (Block 8): reemplazado por POST /v1/treasury-transfers. Responde 422 operation_not_available_via_api sin mover fondos.","security":[{"bearerAuth":[]}],"x-scope":"transfers:create","x-scopes":["transfers:create"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Evita ejecutar dos veces el mismo barrido ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination_account_id","note","sources"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"destination_account_id":{"description":"Cuenta operativa propia que recibe el dinero. (uuid)"},"note":{"description":"Nota que explica el barrido; queda en la bitácora. (texto (5 a 300))"},"sources":{"description":"Cuentas de origen: { account_id (uuid, obligatorio), amount (decimal > 0, opcional: si se omite se barre todo el saldo) }. (lista de 1 a 200)"}}},"example":{"destination_account_id":"1efd4462-70a4-40e8-898c-b0b9a99e7235","note":"Barrido previo al retiro semanal","sources":[{"account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","amount":1500},{"account_id":"b71ad3c8-92e4-4a19-88a0-41d6f5c72c33"}]}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"transfer","transfer_id":"2c9f5ad1-3d47-4b2a-8f33-0a71c9d55e10","transfer_code":"SW-2026-00000132","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","destination_account_id":"1efd4462-70a4-40e8-898c-b0b9a99e7235","amount":{"amount":"4200.00","currency":"USD"},"source_account_count":3,"note":"Barrido previo al retiro semanal","origin":"STANDALONE","executed_at":"2026-01-18T15:59:02.000Z","created_at":"2026-01-18T15:59:01.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/transfers/{transfer_id}":{"get":{"operationId":"transfers-get","tags":["Barridos"],"summary":"Consultar un barrido","description":"Acepta el identificador del barrido o su código de Conecta (SW-2026-########).","security":[{"bearerAuth":[]}],"x-scope":"transfers:read","x-scopes":["transfers:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"transfer_id","in":"path","required":true,"description":"Identificador del barrido. (uuid o SW-####-########)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"transfer","transfer_id":"2c9f5ad1-3d47-4b2a-8f33-0a71c9d55e10","transfer_code":"SW-2026-00000132","company_id":"a1111111-0000-4000-8000-000000000001","status":"COMPLETED","destination_account_id":"1efd4462-70a4-40e8-898c-b0b9a99e7235","amount":{"amount":"4200.00","currency":"USD"},"source_account_count":3,"note":"Barrido previo al retiro semanal","origin":"STANDALONE","executed_at":"2026-01-18T15:59:02.000Z","created_at":"2026-01-18T15:59:01.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/obligations":{"get":{"operationId":"obligations-list","tags":["Obligaciones"],"summary":"Listar obligaciones","description":"Devuelve las obligaciones de la empresa con sus totales esperados, aplicados y pendientes.","security":[{"bearerAuth":[]}],"x-scope":"obligations:read","x-scopes":["obligations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"virtual_account_id","in":"query","required":false,"description":"Solo las obligaciones de esa cuenta virtual. (uuid)","schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"description":"Solo las obligaciones de ese cliente. (uuid)","schema":{"type":"string"}},{"name":"external_reference","in":"query","required":false,"description":"Busca por la referencia del sistema del cliente. (texto)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filtra por estado. (ACTIVE | COMPLETED | CANCELLED | CLOSED)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"obligation","id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","type":"INSTALLMENT_PLAN","status":"ACTIVE","external_reference":"CONTRATO-2026-0441","description":"Plan de 6 cuotas","expected_total":{"amount":"7510.02","currency":"USD"},"allocated_total":{"amount":"1251.67","currency":"USD"},"outstanding_total":{"amount":"6258.35","currency":"USD"},"start_date":"2026-01-15","end_date":null,"closure_on_completion":true,"review_required":false,"recurrence":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"obligations-create","tags":["Obligaciones"],"summary":"Crear una obligación","description":"Crea la obligación sobre una cuenta virtual que ya tiene cliente asociado. ONE_TIME e INSTALLMENT_PLAN se crean con su calendario; RECURRING se crea con su regla y los períodos se generan por adelantado.","security":[{"bearerAuth":[]}],"x-scope":"obligations:write","x-scopes":["obligations:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Evita duplicar la obligación ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"virtual_account_id":{"description":"Cuenta virtual sobre la que vive la obligación. (uuid) Condicional: Si no se envía virtual_account_number."},"virtual_account_number":{"description":"Número de cuenta virtual. (texto) Condicional: Si no se envía virtual_account_id."},"type":{"description":"Tipo de obligación. (ONE_TIME | INSTALLMENT_PLAN | RECURRING)"},"periods":{"description":"Calendario: due_date, expected_amount y opcionalmente sequence, label y external_reference. (arreglo) Condicional: En ONE_TIME e INSTALLMENT_PLAN."},"recurrence":{"description":"periodicity (semanal | quincenal | mensual), amount, start y horizon_periods. (objeto) Condicional: En RECURRING."},"external_reference":{"description":"Referencia del contrato en el sistema del cliente. Debe ser única por empresa. (texto)"},"description":{"description":"Descripción de la obligación. (texto)"},"expected_total":{"description":"Total esperado; si se omite, se suma el calendario enviado. (decimal)"},"start_date":{"description":"Inicio de la obligación. (YYYY-MM-DD)"},"end_date":{"description":"Fin de la obligación. (YYYY-MM-DD)"},"closure_on_completion":{"description":"Cierra la obligación al quedar totalmente aplicada. No cierra la cuenta virtual. (booleano)"}}},"example":{"virtual_account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","type":"INSTALLMENT_PLAN","external_reference":"CONTRATO-2026-0441","description":"Plan de 6 cuotas","closure_on_completion":true,"periods":[{"sequence":1,"label":"Cuota 1/6","due_date":"2026-01-15","expected_amount":1251.67},{"sequence":2,"label":"Cuota 2/6","due_date":"2026-02-15","expected_amount":1251.67}]}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"obligation","id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","type":"INSTALLMENT_PLAN","status":"ACTIVE","external_reference":"CONTRATO-2026-0441","description":"Plan de 6 cuotas","expected_total":{"amount":"7510.02","currency":"USD"},"allocated_total":{"amount":"1251.67","currency":"USD"},"outstanding_total":{"amount":"6258.35","currency":"USD"},"start_date":"2026-01-15","end_date":null,"closure_on_completion":true,"review_required":false,"recurrence":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/obligations/{obligation_id}":{"get":{"operationId":"obligations-get","tags":["Obligaciones"],"summary":"Consultar una obligación","description":"Devuelve la obligación con sus totales. En obligaciones recurrentes, la consulta genera antes los períodos exigibles pendientes; la operación es idempotente y no modifica los períodos existentes.","security":[{"bearerAuth":[]}],"x-scope":"obligations:read","x-scopes":["obligations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"obligation_id","in":"path","required":true,"description":"Identificador de la obligación. (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"obligation","id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","type":"INSTALLMENT_PLAN","status":"ACTIVE","external_reference":"CONTRATO-2026-0441","description":"Plan de 6 cuotas","expected_total":{"amount":"7510.02","currency":"USD"},"allocated_total":{"amount":"1251.67","currency":"USD"},"outstanding_total":{"amount":"6258.35","currency":"USD"},"start_date":"2026-01-15","end_date":null,"closure_on_completion":true,"review_required":false,"recurrence":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"patch":{"operationId":"obligations-patch","tags":["Obligaciones"],"summary":"Actualizar una obligación","description":"Actualiza datos descriptivos, el total esperado, la fecha de fin, la política de cierre, el estado o la regla de recurrencia. Un cambio de regla rige solo para los períodos todavía no generados: los existentes no se modifican.","security":[{"bearerAuth":[]}],"x-scope":"obligations:write","x-scopes":["obligations:write"],"parameters":[{"name":"obligation_id","in":"path","required":true,"description":"Identificador de la obligación. (uuid)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"description":{"description":"Nueva descripción. (texto)"},"external_reference":{"description":"Nueva referencia externa. (texto)"},"expected_total":{"description":"Nuevo total esperado. (decimal)"},"end_date":{"description":"Nueva fecha de fin. (YYYY-MM-DD)"},"closure_on_completion":{"description":"Cierre automático al completarse. (booleano)"},"status":{"description":"Nuevo estado de la obligación. (ACTIVE | CANCELLED | CLOSED)"},"recurrence":{"description":"Nueva regla de recurrencia; aplica a períodos futuros. (objeto)"}}},"example":{"description":"Plan de 6 cuotas — renegociado","end_date":"2026-08-15"}}}},"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"obligation","id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","virtual_account_id":"8f1c0d2a-7c4e-4c1b-9b6e-1a2b3c4d5e6f","customer_id":"c3a9f1e2-0b44-4f6a-9a1c-6d2e7f8a9b01","type":"INSTALLMENT_PLAN","status":"ACTIVE","external_reference":"CONTRATO-2026-0441","description":"Plan de 6 cuotas","expected_total":{"amount":"7510.02","currency":"USD"},"allocated_total":{"amount":"1251.67","currency":"USD"},"outstanding_total":{"amount":"6258.35","currency":"USD"},"start_date":"2026-01-15","end_date":null,"closure_on_completion":true,"review_required":false,"recurrence":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/obligations/{obligation_id}/periods":{"get":{"operationId":"obligations-periods-list","tags":["Obligaciones"],"summary":"Listar períodos de una obligación","description":"Devuelve el calendario con lo esperado, lo aplicado y lo pendiente de cada período. En recurrentes genera antes los períodos exigibles faltantes, de forma idempotente.","security":[{"bearerAuth":[]}],"x-scope":"obligations:read","x-scopes":["obligations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"obligation_id","in":"path","required":true,"description":"Identificador de la obligación. (uuid)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"obligation_period","id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","sequence":2,"label":"Cuota 2/6","due_date":"2026-02-15","expected_amount":{"amount":"1251.67","currency":"USD"},"allocated_amount":{"amount":"0.00","currency":"USD"},"outstanding_amount":{"amount":"1251.67","currency":"USD"},"status":"PENDING","external_reference":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"obligations-periods-create","tags":["Obligaciones"],"summary":"Agregar períodos a una obligación","description":"Agrega cuotas o períodos al calendario existente. Cargar el calendario real cierra la marca de revisión de una obligación migrada.","security":[{"bearerAuth":[]}],"x-scope":"obligations:write","x-scopes":["obligations:write"],"parameters":[{"name":"obligation_id","in":"path","required":true,"description":"Identificador de la obligación. (uuid)","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Evita duplicar los períodos ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["periods"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"periods":{"description":"Períodos a agregar: due_date, expected_amount y opcionalmente sequence, label y external_reference. (arreglo)"}}},"example":{"periods":[{"sequence":3,"label":"Cuota 3/6","due_date":"2026-03-15","expected_amount":1251.67}]}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"obligation_period","id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","company_id":"a1111111-0000-4000-8000-000000000001","sequence":2,"label":"Cuota 2/6","due_date":"2026-02-15","expected_amount":{"amount":"1251.67","currency":"USD"},"allocated_amount":{"amount":"0.00","currency":"USD"},"outstanding_amount":{"amount":"1251.67","currency":"USD"},"status":"PENDING","external_reference":null,"source":"api","created_at":"2026-01-15T14:22:08.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/allocations":{"get":{"operationId":"allocations-list","tags":["Aplicaciones"],"summary":"Listar aplicaciones de pago","description":"Devuelve las aplicaciones económicas de la empresa. Una aplicación reversada se informa con status REVERSED y nunca desaparece del historial.","security":[{"bearerAuth":[]}],"x-scope":"allocations:read","x-scopes":["allocations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"obligation_id","in":"query","required":false,"description":"Solo las aplicaciones de esa obligación. (uuid)","schema":{"type":"string"}},{"name":"period_id","in":"query","required":false,"description":"Solo las aplicaciones de ese período. (uuid)","schema":{"type":"string"}},{"name":"payin_id","in":"query","required":false,"description":"Solo las aplicaciones de esa transacción entrante. (uuid)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Cantidad de resultados por página (50 por defecto). (entero 1-200)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor devuelto en `next_cursor` de la página anterior. (texto)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[{"object":"payment_allocation","id":"b91e4d02-7c15-4a63-92f8-3d5a6b7c8e90","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","period_id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","company_id":"a1111111-0000-4000-8000-000000000001","amount":{"amount":"1251.67","currency":"USD"},"status":"APPLIED","source":"API","channel":"API","actor":"ERP Contabilidad","allocated_at":"2026-02-14T16:03:11.000Z","created_at":"2026-02-14T16:03:11.000Z"}],"has_more":false,"next_cursor":null}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"allocations-create","tags":["Aplicaciones"],"summary":"Aplicar un pago a una obligación","description":"Aplica parte o todo un pago recibido a un período de una obligación de la misma cuenta virtual. Solo se aplican transacciones acreditadas de fondos de terceros. La aplicación no mueve dinero: no altera el saldo de la cuenta virtual ni el de la Cuenta Madre.","security":[{"bearerAuth":[]}],"x-scope":"allocations:write","x-scopes":["allocations:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Evita aplicar dos veces el mismo pago ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payin_id","obligation_id","amount"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"payin_id":{"description":"Transacción entrante que se aplica. (uuid)"},"obligation_id":{"description":"Obligación a la que se aplica. (uuid)"},"period_id":{"description":"Período específico; si se omite, se toma el más antiguo con saldo pendiente. (uuid)"},"amount":{"description":"Monto a aplicar. Nunca puede superar lo recibido sin aplicar ni lo exigible por el período. (decimal)"}}},"example":{"payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","period_id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","amount":1251.67}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payment_allocation","id":"b91e4d02-7c15-4a63-92f8-3d5a6b7c8e90","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","period_id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","company_id":"a1111111-0000-4000-8000-000000000001","amount":{"amount":"1251.67","currency":"USD"},"status":"APPLIED","source":"API","channel":"API","actor":"ERP Contabilidad","allocated_at":"2026-02-14T16:03:11.000Z","created_at":"2026-02-14T16:03:11.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/payins/{payin_id}/allocations":{"get":{"operationId":"payins-allocations","tags":["Aplicaciones"],"summary":"Aplicaciones de una transacción entrante","description":"Devuelve cuánto se recibió, cuánto se aplicó y cuánto queda sin aplicar, con el detalle de cada aplicación. El dinero recibido nunca cambia: lo que cambia es su destino económico.","security":[{"bearerAuth":[]}],"x-scope":"allocations:read","x-scopes":["allocations:read"],"parameters":[{"name":"company_id","in":"query","required":false,"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada.","schema":{"type":"string"}},{"name":"payin_id","in":"path","required":true,"description":"Identificador de la transacción entrante. (uuid)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"payin_allocations","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","received_amount":{"amount":"1500.00","currency":"USD"},"allocated_amount":{"amount":"1251.67","currency":"USD"},"unapplied_amount":{"amount":"248.33","currency":"USD"},"data":[{"object":"payment_allocation","id":"b91e4d02-7c15-4a63-92f8-3d5a6b7c8e90","payin_id":"1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071","obligation_id":"6b2f1d7c-92a4-4c88-9a1f-0e5c3b7a4d21","period_id":"0d44b2c1-6f3a-4a90-b7e2-51c8d9f0a3b4","company_id":"a1111111-0000-4000-8000-000000000001","amount":{"amount":"1251.67","currency":"USD"},"status":"APPLIED","source":"API","channel":"API","actor":"ERP Contabilidad","allocated_at":"2026-02-14T16:03:11.000Z","created_at":"2026-02-14T16:03:11.000Z"}]}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/allocations/{allocation_id}/reversals":{"post":{"operationId":"allocations-reverse","tags":["Aplicaciones"],"summary":"Reversar una aplicación","description":"Reversa explícitamente una aplicación con motivo obligatorio. Las aplicaciones no se editan ni se borran: la reversa es una operación propia y queda en el historial. No existe un DELETE de aplicaciones.","security":[{"bearerAuth":[]}],"x-scope":"allocations:reverse","x-scopes":["allocations:reverse"],"parameters":[{"name":"allocation_id","in":"path","required":true,"description":"Aplicación a reversar. (uuid)","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Evita reversar dos veces ante un reintento. (texto)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"reason":{"description":"Motivo de la reversa; queda en la auditoría. (texto (10-300))"}}},"example":{"reason":"Aplicada a la cuota equivocada del contrato 2026-0441"}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"allocation_reversal","id":"f4d3c2b1-0a98-4765-8432-1e0d9c8b7a65","allocation_id":"b91e4d02-7c15-4a63-92f8-3d5a6b7c8e90","company_id":"a1111111-0000-4000-8000-000000000001","amount":{"amount":"1251.67","currency":"USD"},"reason":"Aplicada a la cuota equivocada del contrato 2026-0441","actor":"ERP Contabilidad","channel":"API","created_at":"2026-02-15T10:41:02.000Z"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-endpoints":{"get":{"operationId":"webhook-endpoints-list","tags":["Webhooks"],"summary":"Listar destinos de avisos","description":"Destinos de webhooks de la empresa. El secreto nunca se devuelve en el listado.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:read","x-scopes":["webhooks:read"],"parameters":[],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[]}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}},"post":{"operationId":"webhook-endpoints-create","tags":["Webhooks"],"summary":"Registrar un destino de avisos","description":"Alta de un destino https. El secreto de firma se muestra una única vez. Los eventos se emiten solo desde transiciones canónicas del dominio.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:write","x-scopes":["webhooks:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"company_id":{"description":"Empresa sobre la que opera la llamada. (uuid) Condicional: Si la credencial tiene más de una empresa habilitada."},"url":{"description":"URL receptora. (https url)"},"events":{"description":"Eventos suscritos. ([texto])"},"description":{"description":"Descripción. (texto)"}}},"example":{"url":"https://example.com/hooks","events":["payin.credited"]}}}},"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"id":"…","url":"https://example.com/hooks","secret":"whsec_…"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-endpoints/{endpointId}":{"patch":{"operationId":"webhook-endpoints-update","tags":["Webhooks"],"summary":"Actualizar suscripciones","description":"Cambia los eventos suscritos y la descripción. Mismo servicio que el Portal.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:write","x-scopes":["webhooks:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"events":{"description":"Eventos suscritos. ([texto])"},"description":{"description":"Descripción. (texto)"}}},"example":{"events":["payin.credited"]}}}},"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"id":"…","events":["payin.credited"],"status":"activa"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-endpoints/{endpointId}/rotate-secret":{"post":{"operationId":"webhook-endpoints-rotate","tags":["Webhooks"],"summary":"Rotar el secreto de firma","description":"Genera un secreto nuevo, que se muestra una única vez; el anterior deja de firmar.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:write","x-scopes":["webhooks:write"],"parameters":[],"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"id":"…","secret":"whsec_…"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-endpoints/{endpointId}/disable":{"post":{"operationId":"webhook-endpoints-disable","tags":["Webhooks"],"summary":"Dar de baja un destino","description":"Deja el destino inactivo. El historial de entregas se conserva.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:write","x-scopes":["webhooks:write"],"parameters":[],"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"id":"…","status":"inactiva"}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-endpoints/{endpointId}/deliveries":{"get":{"operationId":"webhook-endpoints-deliveries","tags":["Webhooks"],"summary":"Registro de entregas","description":"Últimas entregas del destino con estado, código HTTP y error.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:read","x-scopes":["webhooks:read"],"parameters":[],"responses":{"200":{"description":"Operación exitosa","content":{"application/json":{"example":{"object":"list","data":[]}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}},"/api/public/v1/webhook-deliveries/{deliveryId}/replay":{"post":{"operationId":"webhook-deliveries-replay","tags":["Webhooks"],"summary":"Reenviar una entrega","description":"Reenvía ahora una entrega existente con el mismo evento y firma.","security":[{"bearerAuth":[]}],"x-scope":"webhooks:write","x-scopes":["webhooks:write"],"parameters":[],"responses":{"201":{"description":"Operación exitosa","content":{"application/json":{"example":{"delivered":true,"response_status_code":200}}}},"default":{"description":"Error","content":{"application/json":{"example":{"error":{"code":"invalid_parameter","message":"Descripción del problema.","field":"amount"},"request_id":"req_b02978aec3884109bb0ab0c9"}}}}}}}}}