Integraciones de 1C con servicios externos: REST, SOAP, JSON y API: una guía completa para principiantes

Los procesos empresariales modernos rara vez funcionan de forma aislada. El sistema de contabilidad 1C debe intercambiar datos con sitios web, sistemas CRM, servicios de entrega, bancos y decenas de otros servicios. Para ello, se utilizan las API, interfaces de programación que permiten que los sistemas se comuniquen entre sí. Veamos cómo funciona y cómo empezar a crear integraciones en 1C.

¿Qué son las API y por qué son necesarias?

Una API (interfaz de programación de aplicaciones) es un conjunto de reglas mediante las cuales un programa puede solicitar datos o funciones a otro. Imagina que entras en un restaurante. No vas a la cocina a cocinar tú mismo, le dices al camarero lo que quieres pedir, él pasa el pedido a la cocina y luego te trae el plato preparado. La API funciona como este camarero: recibe solicitudes, las procesa y devuelve el resultado.

Tareas típicas de integración de 1C:

• Carga de pedidos de la tienda en línea

• Envío de documentos al banco

• Obtención de tipos de cambio

• Sincronización con sistemas CRM

• Envío de datos a los servicios de entrega

• Obtención de información sobre contrapartes de bases de datos externas

  

REST y SOAP: dos enfoques para crear una API

SOAP: el enfoque clásico

SOAP (Simple Object Access Protocol) es un protocolo de intercambio de datos que apareció a finales de los 90. Utiliza XML para transmitir mensajes y tiene una estructura estricta.

Ejemplo de solicitud SOAP:

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetClientInfo xmlns="http://example.com/">
      <ClientID>12345</ClientID>
    </GetClientInfo>
  </soap:Body>
</soap:Envelope>

Los servicios SOAP se describen utilizando WSDL (Web Services Description Language), un archivo especial que contiene toda la información sobre los métodos, parámetros y tipos de datos disponibles. Es como una guía detallada sobre cómo usar la API.

Ventajas de SOAP:

• Tipificación estricta y validación de datos

• Soporte de seguridad integrado

• Soporte para operaciones y transacciones complejas

• Gestión estandarizada de errores

Desventajas de SOAP:

• El XML voluminoso aumenta el tamaño de los datos transmitidos

• Más difícil de dominar y configurar

• Funciona más lento debido al procesamiento de XML

REST: un estándar moderno

REST (Representational State Transfer) es un estilo arquitectónico que utiliza métodos HTTP estándar. REST es más simple, más ligero y funciona más rápido que SOAP.

Métodos HTTP básicos en REST:

• GET — obtener datos

• POST — crear una nueva entrada

• PUT — actualizar la entrada existente

• DELETE — eliminar entrada

Ejemplo de solicitud REST (obtener información del cliente):

GET https://api.example.com/clients/12345

Ventajas de REST:

• Facilidad de uso

• Trabajo rápido

• Datos compactos (generalmente JSON)

• Fácil de probar a través del navegador o Postman

Desventajas de REST:

• Menos estandarización (cada API se puede organizar a su manera)

• No hay soporte integrado para operaciones complejas

JSON: lenguaje de intercambio de datos

JSON (JavaScript Object Notation) es un formato de texto para la transmisión de datos estructurados. Se ha convertido en el estándar para las API REST debido a su simplicidad y legibilidad.

Ejemplo de datos JSON:

{
  "clientId": "12345",
  "name": "Romashka LLC",
  "inn": "7701234567",
  "contacts": {
    "phone": "+7 495 123-45-67",
    "email": "info@romashka.ru"
  },
  "orders": [
    {
      "id": "ORD-001",
      "date": "2024-12-01",
      "amount": 45000
    }
  ]
}

JSON es fácil de leer para los humanos y fácil de procesar por software. 1C tiene herramientas integradas para trabajar con JSON.

Trabajar con solicitudes HTTP en 1C

Para enviar y recibir datos a través de la API en 1C, se utiliza el objeto HTTPСоединение y HTTPЗапрос.

Solicitud GET simple

// Estableciendo conexión con el servidor
Соединение = Новый HTTPСоединение(
    "api.example.com",  // dirección del servidor
    443,                // puerto (443 para HTTPS)
    ,                   // nombre de usuario
    ,                   // contraseña
    ,                   // proxy
    30,                 // tiempo de espera en segundos
    Новый ЗащищенноеСоединениеOpenSSL() // para HTTPS
);

// Creando una solicitud
Запрос = Новый HTTPЗапрос("/clients/12345");

// Enviamos la solicitud y recibimos la respuesta
Ответ = Соединение.Получить(Запрос);

// Comprobando el código de respuesta
Если Ответ.КодСостояния = 200 Тогда
    ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
    Сообщить(ТелоОтвета);
Иначе
    Сообщить("Error: " + Ответ.КодСостояния);
КонецЕсли;

Solicitud POST con datos JSON

// Preparando datos
ДанныеJSON = Новый Структура;
ДанныеJSON.Вставить("name", "Vasilyok LLC");
ДанныеJSON.Вставить("inn", "7702345678");

// Convertir a JSON
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, ДанныеJSON);
СтрокаJSON = ЗаписьJSON.Закрыть();

// Creando una solicitud
Запрос = Новый HTTPЗапрос("/clients");
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.УстановитьТелоИзСтроки(СтрокаJSON);

// Enviando
Соединение = Новый HTTPСоединение("api.example.com", 443, , , , 30,
    Новый ЗащищенноеСоединениеOpenSSL());
Ответ = Соединение.ОтправитьДляОбработки(Запрос);

// Procesando la respuesta
Если Ответ.КодСостояния = 201 Тогда
    Сообщить("Customer successfully created");
КонецЕсли;

Análisis de JSON en 1C

Para leer JSON se utiliza ЧтениеJSON:

СтрокаJSON = Ответ.ПолучитьТелоКакСтроку();

ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);

Данные = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();

// Ahora podemos acceder a los datos
Имя = Данные["name"];
ИНН = Данные["inn"];
Телефон = Данные["contacts"]["phone"];

Si la estructura JSON se conoce de antemano, se puede utilizar la deserialización en la estructura:

ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(СтрокаJSON);

Данные = ПрочитатьJSON(ЧтениеJSON, Истина); // Verdad = leer en la estructura
ЧтениеJSON.Закрыть();

Autenticación en la API

La mayoría de las API requieren autenticación. Métodos principales:

Basic Authentication

El nombre de usuario y la contraseña se transmiten en el encabezado:

Запрос = Новый HTTPЗапрос("/api/data");

Логин = "user";
Пароль = "password";
СтрокаАвторизации = Base64Строка(Логин + ":" + Пароль);

Запрос.Заголовки.Вставить("Authorization", "Basic " + СтрокаАвторизации);

API Key

La clave especial se transmite en el encabezado o parámetro:

Запрос = Новый HTTPЗапрос("/api/data");
Запрос.Заголовки.Вставить("X-API-Key", "your_secret_key");

Bearer Token (OAuth)

El token de acceso se obtiene mediante una solicitud separada:

Запрос = Новый HTTPЗапрос("/api/data");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);

Tratamiento de errores

Siempre es necesario prever el tratamiento de errores:

Попытка
    Ответ = Соединение.Получить(Запрос);
    
    Если Ответ.КодСостояния = 200 Тогда
        // Solicitud exitosa
        Данные = ПолучитьДанныеИзОтвета(Ответ);
    ИначеЕсли Ответ.КодСостояния = 404 Тогда
        ВызватьИсключение("Resource not found");
    ИначеЕсли Ответ.КодСостояния = 401 Тогда
        ВызватьИсключение("Authorization error");
    Иначе
        ВызватьИсключение("Server error: " + Ответ.КодСостояния);
    КонецЕсли;
    
Исключение
    Сообщить("Error while working with API: " + ОписаниеОшибки());
    ЗаписьЖурналаРегистрации("Integration.API", 
        УровеньЖурналаРегистрации.Ошибка,
        ,
        ,
        ПодробноеПредставлениеОшибки(ИнформацияОбОшибке())
    );
КонецПопытки;

Trabajar con SOAP en 1C

Para trabajar con servicios SOAP, 1C puede crear automáticamente un objeto basado en WSDL:

// Definimos el servicio SOAP mediante WSDL
Попытка
    WSОпределения = Новый WSОпределения(
        "http://example.com/service?wsdl",
        "Login",
        "Password"
    );
    
    // Creamos un proxy para trabajar con el servicio
    WSПрокси = Новый WSПрокси(WSОпределения, 
        "ServiceNamespace",
        "ServiceName");
    
    // Llamar al método de servicio
    Результат = WSПрокси.GetClientInfo("12345");
    
Исключение
    Сообщить("Error while working with SOAP: " + ОписаниеОшибки());
КонецПопытки;

Consejos prácticos

Utilice constantes para direcciones y claves. No almacene las URL y las claves API directamente en el código, muévalas a constantes o configuraciones. Esto simplificará el cambio de los parámetros de conexión.

Registre todas las operaciones. Registre todas las llamadas a API externas: solicitudes, respuestas, errores. Esto ayudará con la depuración.

Gestiona los tiempos de espera. Los servicios externos pueden no estar disponibles o responder lentamente. Establezca tiempos de espera razonables y gestione correctamente las situaciones en las que el servicio no responde.

Prueba con Postman. Antes de escribir código en 1C, prueba la API a través de Postman o una herramienta similar. Esto ayudará a comprender la estructura de las solicitudes y respuestas.

Tenga en cuenta los límites de la API. Muchos servicios limitan el número de solicitudes por unidad de tiempo. Proporcione mecanismos para limitar la frecuencia de las llamadas.

Utiliza el procesamiento asíncrono. Para operaciones masivas, es mejor usar tareas en segundo plano para no bloquear el trabajo del usuario.

Ejemplo de integración real

Vamos a crear una integración sencilla para obtener el tipo de cambio de divisas del sitio web del Banco Central de la Federación Rusa:

Функция ПолучитьКурсВалюты(КодВалюты, Дата)
    
    СтрокаДаты = Формат(Дата, "DF=dd.MM.yyyy");
    
    Соединение = Новый HTTPСоединение("www.cbr.ru", 443, , , , 30,
        Новый ЗащищенноеСоединениеOpenSSL());
    
    Запрос = Новый HTTPЗапрос("/scripts/XML_daily.asp?date_req=" + СтрокаДаты);
    
    Попытка
        Ответ = Соединение.Получить(Запрос);
        
        Если Ответ.КодСостояния = 200 Тогда
            ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
            
            // Analizamos XML
            Чтение = Новый ЧтениеXML;
            Чтение.УстановитьСтроку(ТелоОтвета);
            
            Пока Чтение.Прочитать() Цикл
                Если Чтение.ТипУзла = ТипУзлаXML.НачалоЭлемента
                    И Чтение.Имя = "Valute" Тогда
                    
                    ТекКод = "";
                    ТекКурс = 0;
                    
                    Пока Чтение.ПрочитатьАтрибут() Цикл
                        Если Чтение.Имя = "ID" И Чтение.Значение = КодВалюты Тогда
                            // Encontramos la moneda que necesitamos, leemos el tipo de cambio
                            Пока Чтение.Прочитать() Цикл
                                Если Чтение.Имя = "Value" Тогда
                                    Чтение.Прочитать();
                                    СтрокаКурса = СтрЗаменить(Чтение.Значение, ",", ".");
                                    Возврат Число(СтрокаКурса);
                                КонецЕсли;
                            КонецЦикла;
                        КонецЕсли;
                    КонецЦикла;
                КонецЕсли;
            КонецЦикла;
            
            Чтение.Закрыть();
        КонецЕсли;
        
    Исключение
        Сообщить("Error getting the rate: " + ОписаниеОшибки());
        Возврат 0;
    КонецПопытки;
    
    Возврат 0;
    
КонецФункции

// Uso
Курс = ПолучитьКурсВалюты("R01235", ТекущаяДата()); // USD
Сообщить("Dollar exchange rate: " + Курс);

Conclusión

Las integraciones con servicios externos son una parte importante del desarrollo moderno en 1C. Las API REST con JSON se han convertido en el estándar debido a su simplicidad y eficiencia, aunque SOAP todavía se utiliza en los sistemas corporativos. Es mejor comenzar con solicitudes GET simples, pasando gradualmente a escenarios más complejos con POST, PUT, autenticación y manejo de errores.

Después de dominar los principios básicos de trabajar con HTTP, JSON y API, podrás conectar 1C a casi cualquier servicio moderno, desde tiendas en línea hasta sistemas bancarios.

¡Sigue aprendiendo!

Puedes estudiar este tema y mucho más en Codice — una plataforma para aprender programación con ejemplos prácticos y tareas reales.

Y también tenemos un genial Canal de Telegram con una comunidad de desarrolladores amigable donde puedes hacer preguntas, compartir experiencias y estar al tanto de los nuevos materiales.