O seu sistema, agente ou ferramenta de desenvolvimento pode conversar com o MCP oficial da Omie, no mesmo endereço que o ChatGPT, o Claude e o Grok usam: https://api.omie.com.br/mcp. Para isso, ele precisa de um client ID da Omie e do login da pessoa, com as permissões dela.

💡 Dica Omie: Este login é do MCP. O token que ele entrega vale para o MCP e não serve direto nas APIs do Omie: quem faz a troca é o próprio servidor do MCP. Para integrar um sistema direto com as APIs, sem ninguém na frente, use uma integração com token próprio, como explicado na documentação da API.

Pedindo o client ID

Abra um chamado do tipo API no suporte com estas cinco informações. Faltando uma, o pedido volta.

Nome do sistema: aparece na tela de autorização que a pessoa vê. Não pode conter "Omie".
Empresa e aplicativo: razão social e o aplicativo Omie de quem pede.
Endereços de retorno: completos, com caminho, em https, e no ar quando formos validar.
Responsável técnico: nome, e-mail e telefone de quem cuida da integração.
O que o sistema faz: uma frase.

O client ID é um código de 32 caracteres e não é segredo: pode ficar no código e na configuração do seu sistema. Não existe client_secret: quem protege o fluxo é o PKCE.

💡 ChatGPT, Claude, Grok e Grok Bot já têm o próprio client ID. Para eles não é preciso pedir: siga o artigo do assistente.

O login, passo a passo

É o OAuth 2.0 com PKCE, o mesmo desenho do "Entrar com Google".

1) A cada login, o seu sistema sorteia três valores e guarda no servidor, com prazo curto e uso único:

code_verifier: de 43 a 128 caracteres, com letras, dígitos e os sinais - . _ ~
code_challenge: o base64url do SHA-256 do code_verifier, sem o = do final
state: um valor aleatório, de uso único

2) O sistema manda a pessoa para https://app.omie.com.br/login/oauth2/ com estes parâmetros:

response_type=code
client_id: o seu client ID
redirect_uri: o endereço de retorno cadastrado, idêntico
state e code_challenge, sorteados no passo 1
code_challenge_method=S256
resource=https://api.omie.com.br/mcp
scope: só se o seu cadastro tiver escopo, idêntico

3) A pessoa entra com a conta Omie e autoriza. O navegador volta para o seu endereço com code, state e iss. Confira que o state é o que você guardou e que o iss é https://app.omie.com.br.

4) Do seu servidor, troque o código pelo token: POST https://app.omie.com.br/login/oauth2/validate/, em formulário, com grant_type=authorization_code, code, code_verifier (o valor original, não o hash), client_id e redirect_uri. Sem client_secret. O código vale 10 minutos e só pode ser usado uma vez.

5) Chame o MCP em https://api.omie.com.br/mcp com Authorization: Bearer e o token recebido.

💡 Duas diferenças do que você conhece. O state é obrigatório: sem ele, o pedido é recusado. E redirect_uri e scope são comparados por igualdade exata: uma barra a mais ou um espaço e o pedido é recusado.

Renovando e revogando

Renovar: POST https://app.omie.com.br/login/oauth2/validate/, em formulário, com grant_type=refresh_token, refresh_token e client_id.
O token dura 2 dias. O refresh_token não expira por tempo e não muda a cada renovação: guarde o mesmo valor.
Pede um login novo quando o acesso é revogado ou a pessoa é desativada no Omie.
Revogar, quando a pessoa desconectar a Omie no seu sistema: POST https://app.omie.com.br/login/oauth2/revoke/, em formulário, com token e client_id. A resposta é sempre 200.

Alcance e cuidados com o token

O alcance é o de quem autoriza: o seu sistema faz o que a pessoa pode fazer no Omie, inclusive as restrições de IP, de horário e de duplo fator.
Guarde os tokens só no servidor, cifrados, nunca no navegador.
Nunca em log nem em endereço (URL).
O refresh_token merece o cuidado de uma senha: ele não expira por tempo, e quem o tiver mantém o acesso até alguém revogar.

O mesmo passo a passo está na documentação do MCP, em Sistema próprio.

Conectando um sistema próprio ao MCP da Omie (client ID)