# Integration Reference

Patterns for building integrations in OroCommerce.

## Oro IntegrationBundle Pattern

For managed integrations visible in System > Integrations:

1. **Transport** -- implements `TransportInterface`, handles connectivity
2. **Connector** -- implements `ConnectorInterface`, defines sync logic per entity
3. **Channel Type** -- defines the integration type shown in UI

### Transport

```php
class MyTransport implements TransportInterface
{
    public function init(Transport $transportEntity): void { }
    public function getLabel(): string { return 'My Integration'; }
    public function getSettingsFormType(): string { return MyTransportSettingsType::class; }
    public function getSettingsEntityFQCN(): string { return MyTransportSettings::class; }
}
```

Tag: `{ name: oro_integration.transport, type: my_integration, channel_type: my_channel }`

### Connector

```php
class MyConnector implements ConnectorInterface
{
    public function getLabel(): string { return 'My Connector'; }
    public function getType(): string { return 'my_entity'; }
    public function getImportEntityFQCN(): string { return MyEntity::class; }
    public function getImportJobName(): string { return 'my_import_job'; }
}
```

Tag: `{ name: oro_integration.connector, type: my_entity, channel_type: my_channel }`

## API-Based Integration (Middleware)

For external API integrations not using the IntegrationBundle:

1. Create an HTTP client service wrapping Symfony HttpClient
2. Store credentials in system configuration (see system-config pattern)
3. Use MQ processors for async data sync
4. Implement retry/backoff for resilience
5. Use notification alerts for failure reporting

## Import/Export Services

```yaml
services:
    acme.importexport.data_converter:
        parent: oro_importexport.data_converter.configurable

    acme.importexport.processor.export:
        parent: oro_importexport.processor.export_abstract
        calls:
            - [setDataConverter, ['@acme.importexport.data_converter']]
        tags:
            - { name: oro_importexport.processor, type: export,
                entity: 'Acme\Bundle\ExampleBundle\Entity\Example',
                alias: acme_example }

    acme.importexport.processor.import:
        parent: oro_importexport.processor.import_abstract
        calls:
            - [setDataConverter, ['@acme.importexport.data_converter']]
        tags:
            - { name: oro_importexport.processor, type: import,
                entity: 'Acme\Bundle\ExampleBundle\Entity\Example',
                alias: acme_example }
```

## Notification Alerts

Use `Oro\Bundle\NotificationAlertBundle` to surface integration failures:

```php
$this->notificationAlertManager->addNotificationAlert(
    NotificationAlert::createForIntegration($integration, 'Sync failed: ...')
);
```