Importación y exportación vía API

Podés importar y exportar datos de cuentas de forma programática a través de la API REST de Fynex. Esto es útil para sincronizar tu sistema de gestión (ERP, CRM) con la plataforma de cobranzas.

Autenticación

Todas las peticiones requieren una clave API con los scopes correspondientes. Consultá la guía de Claves API para crear una.

bash

# Incluí la clave en cada petición
-H "X-API-Key: fynex_pk_a1b2c3d4..."

Importar cuentas

Enviá un array de cuentas con sus datos de contacto. Fynex crea las cuentas y contactos automáticamente.

Endpoint

POST /api/v1/import/import

Scope requerido: import

Body

json

{
  "accounts": [
    {
      "external_id": "CTA-001",
      "contact": {
        "name": "María González",
        "email": "[email protected]",
        "phone": "+5491155551234",
        "document_ref": "27-12345678-9",
        "gender": "femenino"
      },
      "reference": "FAC-2026-001",
      "total_amount": 85000,
      "pending_balance": 85000,
      "currency": "ARS",
      "due_date": "2026-02-15",
      "language": "es",
      "notes": "Deuda de servicios"
    }
  ],
  "source_system": "mi-erp",
  "upsert_by_external_id": true
}

Campos de la cuenta

Campo	Tipo	Requerido	Descripción
`external_id`	string	No	ID de la cuenta en tu sistema (máx 255 caracteres)
`contact`	object	Sí	Datos del contacto (ver tabla siguiente)
`reference`	string	No	Número de referencia o factura (máx 255)
`total_amount`	number	Sí	Monto total de la deuda (debe ser positivo)
`pending_balance`	number	No	Saldo pendiente (por defecto = `total_amount`)
`currency`	string	No	Código ISO 4217 de 3 letras (por defecto: `ARS`)
`due_date`	string	No	Fecha de vencimiento original (`YYYY-MM-DD`)
`language`	string	No	Idioma del deudor (ej.: `es`, `en`, máx 5)
`source_system`	string	No	Nombre del sistema de origen (máx 100)
`notes`	string	No	Notas internas
`custom_fields`	object	No	Campos personalizados (pares clave-valor)

Campos del contacto

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre completo del contacto
`email`	string	No	Dirección de email
`phone`	string	No	Teléfono en formato E.164 (ej.: `+5491155551234`)
`whatsapp`	string	No	Número de WhatsApp en formato E.164
`document_ref`	string	No	Documento de identidad (DNI, CUIT, etc.)
`external_id`	string	No	ID del contacto en tu sistema (máx 255)
`gender`	string	No	`masculino` o `femenino` (para el agente de voz)

Parámetros del job

Campo	Tipo	Requerido	Descripción
`accounts`	array	Sí	Array de cuentas a importar (1 a 10,000)
`source_system`	string	No	Sistema de origen (aplica a todas las cuentas que no lo definan)
`upsert_by_external_id`	boolean	No	Si es `true` (por defecto), actualiza cuentas existentes con el mismo `external_id` en vez de crear duplicados

Respuesta

La importación se procesa de forma asincrónica. La respuesta inmediata incluye un job_id:

json

{
  "job_id": "uuid-del-job",
  "status": "processing"
}

Consultar estado de importación

GET /api/v1/import/import/:jobId

Scope requerido: import

Respuesta

json

{
  "id": "uuid-del-job",
  "status": "completed",
  "total_rows": 150,
  "processed_rows": 150,
  "created_rows": 142,
  "updated_rows": 5,
  "error_rows": 3,
  "errors": [
    { "index": 12, "error": "total_amount must be positive" },
    { "index": 87, "error": "contact.name is required" }
  ],
  "started_at": "2026-03-22T10:00:00Z",
  "completed_at": "2026-03-22T10:00:12Z"
}

Los valores posibles de status son processing, completed y failed.

Exportar cuentas

POST /api/v1/export/accounts

Scope requerido: export

Body

json

{
  "format": "json",
  "status": "active",
  "source_system": "mi-erp",
  "created_after": "2026-01-01T00:00:00Z",
  "created_before": "2026-03-22T23:59:59Z"
}

Filtros disponibles

Filtro	Tipo	Descripción
`format`	string	`json` (por defecto) o `csv`
`status`	string	Filtrar por estado de cobranza
`source_system`	string	Filtrar por sistema de origen
`created_after`	string	Solo cuentas creadas después de esta fecha (ISO 8601)
`created_before`	string	Solo cuentas creadas antes de esta fecha (ISO 8601)

Respuesta JSON

json

{
  "data": [
    {
      "id": "uuid",
      "external_id": "CTA-001",
      "total_amount": 85000,
      "pending_balance": 42500,
      "currency": "ARS",
      "collection_status": "active",
      "contacts": {
        "name": "María González",
        "email": "[email protected]",
        "phone": "+5491155551234"
      }
    }
  ],
  "total": 1
}

Si format es csv, la respuesta es un archivo CSV descargable con headers Content-Type: text/csv.

Mapeo de external_id

El campo external_id es la pieza clave para sincronización bidireccional. Te permite:

Importar sin duplicados — Con upsert_by_external_id: true, Fynex actualiza cuentas existentes que tengan el mismo external_id en tu organización.
Registrar pagos por referencia — El endpoint de pagos acepta account_external_id para identificar la cuenta sin necesidad del UUID interno de Fynex.
Consultar por ID externo — Los endpoints de listado aceptan external_id como filtro.

TIP

Asegurate de que external_id sea único dentro de tu organización. Si importás dos cuentas con el mismo external_id y upsert_by_external_id es true, la segunda va a actualizar la primera.

Ejemplos cURL

Importar cuentas

bash

curl -X POST https://api.fynex.solutions/api/v1/import/import \
  -H "X-API-Key: fynex_pk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "external_id": "CTA-001",
        "contact": {
          "name": "María González",
          "phone": "+5491155551234",
          "document_ref": "27-12345678-9"
        },
        "total_amount": 85000,
        "currency": "ARS",
        "due_date": "2026-02-15"
      },
      {
        "external_id": "CTA-002",
        "contact": {
          "name": "Juan Pérez",
          "email": "[email protected]",
          "phone": "+5491155559876"
        },
        "total_amount": 120000,
        "currency": "ARS"
      }
    ],
    "source_system": "mi-erp",
    "upsert_by_external_id": true
  }'

Consultar estado del job

bash

curl -X GET https://api.fynex.solutions/api/v1/import/import/uuid-del-job \
  -H "X-API-Key: fynex_pk_a1b2c3d4..."

Exportar cuentas en CSV

bash

curl -X POST https://api.fynex.solutions/api/v1/export/accounts \
  -H "X-API-Key: fynex_pk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{ "format": "csv", "status": "active" }' \
  -o cuentas-activas.csv

Exportar cuentas en JSON con filtros

bash

curl -X POST https://api.fynex.solutions/api/v1/export/accounts \
  -H "X-API-Key: fynex_pk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "source_system": "mi-erp",
    "created_after": "2026-01-01T00:00:00Z"
  }'

Guías relacionadas

Integraciones — Resumen general de capacidades de integración.
Claves API — Cómo crear y administrar claves.
Webhooks — Cómo recibir eventos en tiempo real.

Importación y exportación vía API ​

Autenticación ​

Importar cuentas ​

Endpoint ​

Body ​

Campos de la cuenta ​

Campos del contacto ​

Parámetros del job ​

Respuesta ​

Consultar estado de importación ​

Respuesta ​

Exportar cuentas ​

Body ​

Filtros disponibles ​

Respuesta JSON ​

Mapeo de external_id ​

Ejemplos cURL ​

Importar cuentas ​

Consultar estado del job ​

Exportar cuentas en CSV ​

Exportar cuentas en JSON con filtros ​

Guías relacionadas ​

Importación y exportación vía API

Autenticación

Importar cuentas

Endpoint

Body

Campos de la cuenta

Campos del contacto

Parámetros del job

Respuesta

Consultar estado de importación

Respuesta

Exportar cuentas

Body

Filtros disponibles

Respuesta JSON

Mapeo de external_id

Ejemplos cURL

Importar cuentas

Consultar estado del job

Exportar cuentas en CSV

Exportar cuentas en JSON con filtros

Guías relacionadas