> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useaira.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Omie

> Sincronize faturas, contratos, pagamentos e documentos fiscais com o ERP Omie.

> A integração com o Omie conecta a Aira ao seu ERP para sincronizar faturas, contratos, pagamentos e documentos fiscais automaticamente.

<h2 id="o-que-e-sincronizado">
  O que é sincronizado
</h2>

| Dados          | Direção     | Descrição                                                                |
| -------------- | ----------- | ------------------------------------------------------------------------ |
| **Faturas**    | Aira → Omie | Faturas emitidas são enviadas como ordens de serviço no Omie             |
| **Contratos**  | Aira ↔ Omie | Contratos sincronizados bidirecionalmente com número de contrato do Omie |
| **Pagamentos** | Omie → Aira | Confirmações de pagamento (baixas) atualizam o status na Aira            |
| **Boletos**    | Omie → Aira | Boletos gerados no Omie são armazenados e disponibilizados na Aira       |
| **NFSe**       | Omie → Aira | Notas fiscais emitidas no Omie são sincronizadas de volta para a Aira    |

<br />

<h2 id="webhooks-recebidos-do-omie">
  Webhooks recebidos do Omie
</h2>

A Aira recebe webhooks do Omie para manter os dados sincronizados. Os tópicos suportados são:

| Tópico Omie                             | O que acontece na Aira                   |
| --------------------------------------- | ---------------------------------------- |
| `Financas.ContaReceber.BaixaRealizada`  | Status do pagamento atualizado para Pago |
| `Financas.ContaReceber.Alterado`        | Pagamento criado ou atualizado           |
| `Financas.ContaReceber.BoletoGerado`    | Arquivo do boleto armazenado             |
| `Financas.ContaReceber.BoletoCancelado` | Boleto removido                          |
| `ContratoServico.Alterado`              | Número do contrato atualizado            |
| `NFSe.NotaAutorizada`                   | Documento fiscal criado e armazenado     |
| `OrdemServico.Faturada`                 | Ciclo de cobrança sincronizado           |

A validação é feita via `appKey` + `appHash` presentes no payload do webhook. Payloads com credenciais inválidas são rejeitados.

O Omie também envia payloads de ping (`{ "ping": "omie" }`) para verificar a disponibilidade do endpoint — a Aira responde com `{"message":"pong"}`.

<Note>
  Para ambientes que não são produção, use o mesmo caminho (`/v1/webhooks/omie`) e altere apenas o host.
</Note>

<br />

<h2 id="configuracao">
  Configuração
</h2>

<h3 id="habilitar-a-integracao">
  Habilitar a integração
</h3>

A integração com o Omie é provisionada pelo time da Aira. Entre em contato com o suporte em [contato@useaira.com](mailto:contato@useaira.com) informando as credenciais da sua conta Omie (`app_key` e `app_secret`) para ativação.

<h3 id="configurar-webhooks-no-omie">
  Configurar webhooks no Omie
</h3>

1. Acesse o [Portal de Desenvolvedor do Omie](https://developer.omie.com.br/my-apps/)
2. Clique em **Adicionar novo webhook**
3. Informe a URL do endpoint da Aira:
   ```
   https://api.useaira.com/v1/webhooks/omie
   ```
4. Selecione todos os tópicos suportados (listados acima)
5. Salve a configuração

<h3 id="modulos-de-sincronizacao">
  Módulos de sincronização
</h3>

Após habilitar, configure quais módulos deseja ativar:

* **Sincronização de pagamentos:** Receber confirmações de pagamento do Omie
* **Sincronização de documentos fiscais:** Receber NFSe emitidas pelo Omie

<h3 id="mapeamento-de-servicos">
  Mapeamento de serviços
</h3>

Para que as faturas sejam criadas corretamente no Omie, configure o mapeamento entre entidades da Aira e serviços do Omie:

* **Por produto:** Cada produto da Aira é mapeado para um serviço do Omie
* **Por recurso:** Cada recurso é mapeado individualmente
* **Por valor mínimo da fatura:** Itens de franquia mínima mapeados separadamente

O mapeamento é feito na aba de **Mapeamentos** dentro das configurações da integração Omie.

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Celcash](/integracoes/celcash) — processe cobranças via PIX e Boleto
* [Documentos fiscais](/faturas/documentos-fiscais) — entenda como NFSe são sincronizadas
* [Pagamentos](/pagamentos/metodos-de-pagamento) — métodos de pagamento disponíveis