Publicación de deuda

Producto

La publicación de documentos de deuda es el proceso por el cual tu empresa informa a Frisvy los documentos a cobrar (facturas, notas de débito, notas de crédito, etc.). Se puede integrar mediante API REST o por archivo vía SFTP.

Dos modalidades de integración API REST para publicación programática e inmediata desde tus sistemas, y SFTP para cargas por archivo (lotes). Además, podés iniciar una Orden de Pago publicando documentos en el mismo paso (flujo de Botón de Pago).

1. Publicación mediante API REST

La Document Entry Manager API permite publicar documentos de deuda directamente en la plataforma de forma programática, sin intervención manual. Requiere un token generado con el scope ibcobros.debtdocuments.write.

Autenticación

Request — POST /auth/login

curl -X POST 'https://apim.{ambiente}.frisvy.com/auth/login' \
  --header 'Authorization: Basic {CREDENCIALES_BASE64}' \
  --header 'Scope: ibcobros.debtdocuments.write'

Endpoint

POST https://ibcobros.apim.{ambiente}.frisvy.com/document-entry-manager/v1/documents

Recibe uno o más documentos de deuda y los registra para su cobro posterior. Retorna el ID del lote creado (documentLotId).

Los headers collector-document-type y collector-document-number los completa internamente la infraestructura; no debés enviarlos.

Request body

Cada elemento de records[] admite los siguientes campos:

Ejemplo de request

curl --location 'https://ibcobros.apim.{ambiente}.frisvy.com/document-entry-manager/v1/documents' \
  --header 'Authorization: Bearer {SESSION_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "collector_document_number": "30501525327",
    "collector_document_type": "CUIT",
    "records": [
      {
        "id_1": "id1 custom",
        "publication_date": "2025-06-12",
        "first_expiration_date": "2025-06-12",
        "debit_credit": "D",
        "payer_document_type": "CUIT",
        "payer_document_number": "30211233567",
        "voucher_type": "FAC",
        "voucher_number": "99900000001",
        "doc_origin_date": "2023-07-21",
        "doc_currency_code": "ARS",
        "original_amount": 4000,
        "pending_amount": 4000,
        "custom_attributes": { "key1": "value" }
      }
    ]
  }'

Respuesta — 202 Accepted

Response 202

{
  "documentLotId": 12345
}

Un 202 no garantiza el procesamiento Si el lote completo es inválido se retorna igualmente el documentLotId, pero el lote queda en estado RECHAZADO (por ejemplo, si excede el límite de registros o hay inconsistencias de estado). Si solo algunos registros son inválidos, el lote se crea con los válidos y los inválidos quedan marcados con su error; el documentLotId permite consultar el detalle.

Códigos de error

El cuerpo de error es un JSON con timestamp, status, message y errors (arreglo de strings).

2. Publicación vía archivo (SFTP)

Alternativamente, podés publicar documentos cargando archivos CSV en el servidor SFTP de Frisvy, en la carpeta asignada a tu empresa. Requiere haber gestionado previamente el alta SFTP (ver sección 3).

Especificaciones del archivo

• Formato: CSV, valores separados por punto y coma (;).
• Nombre: <YYYYMMDDHHMISS>_DE_<nombre>.csv. Ej: 20251002164510_DE_pubdocs.csv.
• Exactamente 29 campos por registro. Los opcionales pueden ir vacíos, pero los separadores (;) deben mantenerse.
• Fechas en ISO 8601 (yyyy-MM-dd) y decimales con punto. El campo de atributos debe ser un JSON válido.

Estructura del registro (29 campos)

Ejemplo de registro válido

CCDE;100000012345;CUIT;30710148453;SR;1000002543;CDOC:100125;2024;1;2024-11-16;2023-11-03;2023-11-03;95300.00;2023-11-03;10000.00;2023-11-03;10000.00;ARS;ARS;0.00;D;VENTAS;000000000192394;000000000192394;Dato libre 2;example_file1.pdf;https://filelocation.com/12345.pdf;;{"test":"value"}

Partidas abiertas vs. cerradas Para partidas abiertas el campo 28 (estado) va vacío. Las partidas cerradas (documentos contabilizados, solo informativos, no vinculados a una orden de pago) llevan siempre estado = 4.

3. Conexión SFTP (alta de clientes)

Para integrarte por SFTP, tu empresa debe darse de alta en el API Manager indicando CUIT, flujos de negocio, usuario, email e IPs de origen (para UAT y producción). Recibirás un correo para establecer tu contraseña en el portal de autogestión; con eso, el usuario queda activo.

Servidor

El servidor SFTP se expone en sftp.frisvy.com. Ejemplo de conexión:

Conexión por línea de comandos

sftp {UserNameAPIM}@sftp.frisvy.com

Estructura de carpetas

Según los flujos habilitados verás distintos directorios. Cada uno puede tener subcarpetas input/ (subís archivos a procesar; al subirlos, Frisvy los toma y desaparecen) y output/ (descargás archivos generados por Frisvy).

Ejemplo de subida

# Subir publicación de deuda
put publicacion_deuda.csv /ibcobros-document-files/input/

4. Inicio de Orden de Pago (Botón de Pago)

Este endpoint permite a sistemas externos publicar documentos y preconfeccionar una Orden de Pago en un solo paso, para que el cliente la gestione en la interfaz de Frisvy. Forma parte del flujo de Botón de Pago.

POST https://{dominio-plataforma}/platform/v1/documents/publish/{token-key}

Path params

Request / Response

El body contiene una lista de documents (con voucher_type, voucher_number, id_custom_1, debit_credit, doc_currency_code, original_amount, document_legal_ref, first_expiration_date y doc_origin_date requeridos). La respuesta devuelve el payment_order_id y una callback_url a la que se debe redirigir al usuario para completar el pago.

Request

POST /platform/v1/documents/publish/abc123tokenkey

{
  "documents": [
    {
      "voucher_type": "FAC",
      "voucher_number": "0001-00004567",
      "id_custom_1": "REF-998877",
      "debit_credit": "D",
      "doc_currency_code": "ARS",
      "original_amount": 15500.50,
      "document_legal_ref": "CUIL-20-12345678-9",
      "first_expiration_date": "2026-03-15",
      "doc_origin_date": "2026-02-25",
      "custom_attributes": { "sector": "Administración", "intern_id": 5544 }
    }
  ]
}

Response 200

{
  "payment_order_id": 45012,
  "callback_url": "https://recaudaciones.frisvy.com?externalPlat=DCxLK1Q8...",
  "errors": []
}

Si errors trae elementos, callback_url será null: corregí los datos según los mensajes. Si el token-key es inválido o expiró, el servicio retorna 412 Precondition Failed (código interno 2513).