A impressão normalmente é a última funcionalidade adicionada a um aplicativo e a primeira a apresentar problemas. Integrá-la por meio do ezeep fornece ao seu aplicativo renderização na nuvem, descoberta de impressoras e roteamento de trabalhos sem a necessidade de manter uma estrutura de drivers.

Esta página é destinada a desenvolvedores. Para usar o ezeep por meio de um assistente em vez de desenvolver diretamente com ele, comece com Conecte o ezeep MCP ao seu cliente de IA em três etapas.

Qual é a diferença entre tempo de desenvolvimento e tempo de execução?

Durante o desenvolvimento, uma ferramenta de IA lê a documentação do ezeep, gera o código de integração e executa uma impressão de teste enquanto você trabalha. Depois, seu aplicativo implantado chama diretamente a API REST do ezeep, sem a participação do MCP. Esse é o fluxo normal e o que a documentação do servidor considera como padrão.

Os frameworks de agentes são a exceção. Nesse caso, o MCP permanece como a interface permanente do agente para impressão.

Qual modelo de autenticação você precisa?

Escolha isso antes de escrever qualquer coisa, pois os dois modelos não são intercambiáveis e mudar posteriormente significa refazer a camada de autenticação.

Conta compartilhada. Uma única identidade do ezeep imprime para todo o aplicativo. Quiosques, ferramentas internas, automação no lado do servidor e integrações de API se encaixam nesse modelo. A configuração é feita pelo fluxo de emparelhamento integrado ao servidor MCP: solicite um código de emparelhamento, faça login na URL retornada e, em seguida, troque o código por tokens.

OAuth por usuário. Cada usuário final faz login com sua própria conta do ezeep, que é o que produtos multiusuário precisam. OAuth 2.0 Authorization Code padrão com PKCE. Reutilize um cliente PKCE público existente, caso tenha um, ou peça a um administrador da organização para registrar um cliente uma única vez.

Não substitua o OAuth por usuário pelo fluxo de emparelhamento. Cada usuário final teria que ser redirecionado para o ezeep, fazer login, gerar um token e colá-lo novamente no seu aplicativo, o que não oferece uma experiência adequada para um produto pronto para uso.

Regras que podem fazer sua integração falhar se forem ignoradas

Refresh tokens são de uso único. Cada troca retorna um novo refresh token e invalida o token que você utilizou.

Armazene os refresh tokens em uma linha de banco de dados que possa ser atualizada, nunca em variáveis de ambiente ou em um armazenamento de secrets da plataforma. Essa é a causa mais comum de falhas nessas integrações. Os armazenamentos de secrets não podem ser gravados pelo aplicativo em execução, portanto a primeira rotação faz com que a integração pare de funcionar permanentemente. Leia o token da linha, faça a troca e grave o novo token de volta na mesma linha.

O client ID deve estar em um cabeçalho Authorization, e não no corpo da requisição. Crie uma credencial Basic usando o client ID seguido por dois-pontos, sem secret.

Nunca peça a um usuário um client ID, client secret ou refresh token. O servidor MCP fornece um client ID padrão. Solicite-o ao servidor em vez de codificar um valor diretamente.

Não reutilize o próprio endpoint OAuth do servidor MCP dentro do seu aplicativo. Ele existe exclusivamente para clientes host do MCP.

Registre um único cliente OAuth por aplicativo, e não um por build. Um novo client ID altera a identidade do seu aplicativo e invalida os refresh tokens de todos os usuários existentes, pois cada refresh token está vinculado ao cliente que o emitiu. Novos clientes também contam para o limite da sua organização.

Escolha o modo de tenant com cuidado. Um cliente single-tenant permite apenas usuários da organização proprietária, enquanto um cliente multi-tenant permite usuários de qualquer organização ezeep. Essa escolha é definida quando o cliente é criado e não pode ser alterada posteriormente. Para a maioria dos aplicativos, single é a opção desejada.

Onde ficam os endpoints da API?

O ezeep funciona em três hosts e cada um possui um prefixo de caminho obrigatório. Não existe uma única URL base, e adicionar nomes de operações a um único host fará a solicitação falhar.

As operações de impressão do usuário final ficam em printapi.ezeep.com sob /sfapi/. A listagem das impressoras que um usuário pode visualizar, as propriedades das impressoras, a preparação de um upload, o envio de um trabalho, o status do trabalho e os tipos de arquivo compatíveis ficam todos aqui.

O gerenciamento de impressoras, grupos e conectores fica em api2.ezeep.com sob /printing/v1/, com paginação.

As operações de conta, usuário e OAuth ficam em account.ezeep.com sob /v1/, /oauth/ ou /auth/. O gerenciamento de usuários fica aqui e inclui a lista de usuários, os detalhes do usuário, o perfil do usuário conectado e os convites.

Três detalhes explicam a maioria das falhas iniciais. Todo caminho precisa da barra final. A chamada de preparação do upload aceita somente GET, com o nome do arquivo como parâmetro de consulta, portanto um POST ou um corpo JSON retorna um erro de método não permitido. Toda solicitação de impressão inclui o alias do arquivo e um tipo definido como auto.

Padrões a evitar

Evite a biblioteca JavaScript do ezeep, o componente web de impressão e o pacote CDN para uma integração construída dessa forma, pois o caminho compatível é usar REST diretamente a partir de uma função no lado do servidor. Não peça a um usuário para copiar um refresh token da página do gerador de tokens para a sua configuração, pois essa página existe para testes de desenvolvedores. Mantenha as credenciais fora do código do frontend.

Onde ficam as instruções atuais?

Dentro do servidor. Ele contém seu próprio guia de integração, referência da API e exemplos de código como ferramentas que podem ser chamadas, e essa saída é a fonte de verdade atual. Ao desenvolver usando um cliente de IA, faça com que ele leia esses recursos em vez de trabalhar com conhecimento geral sobre o ezeep, que envelhece mais rápido do que a plataforma.

Perguntas frequentes

Preciso do MCP no meu aplicativo implantado? Somente para frameworks de agentes. Um aplicativo convencional usa o MCP durante o desenvolvimento para gerar a integração e, em seguida, chama diretamente a API REST do ezeep durante a execução.

Por que minha integração parou de funcionar depois de um dia? Quase sempre por causa do refresh token. Os tokens são alternados a cada troca, e armazená-los em variáveis de ambiente ou em um armazenamento de secrets da plataforma significa que o novo token nunca é gravado de volta. Mova-os para uma linha de banco de dados que seu aplicativo possa sobrescrever.

Posso reutilizar um cliente OAuth em vários aplicativos? Reutilize-o para builds do mesmo aplicativo. Um aplicativo separado precisa de seu próprio cliente, pois os refresh tokens estão vinculados ao cliente que os emitiu e a rotação da identidade do cliente invalida os usuários existentes.

Qual scope devo solicitar? Printing cobre as operações de impressão e accounts cobre as operações administrativas. Solicite apenas o que o aplicativo realmente utiliza.

Existe um limite de taxa? As chamadas passam pela mesma plataforma da API REST e contam para a mesma cota, independentemente de chegarem por MCP ou diretamente.