Submissão de Documentos
Visão Geral
A Submissão de Documentos é uma ferramenta do Partner's Portal para enviar payloads JSON diretamente às APIs públicas do ME, sem escrever código e sem depender do disparo pelo seu ERP. Funciona como um cliente de API embutido no portal: você escolhe o documento, cola o payload, a tela valida o JSON contra o schema publicado da API e, ao enviar, mostra a resposta real da API.
Use a Submissão de Documentos para:
- Testar o payload que o seu ERP vai gerar antes de terminar a integração;
- Reproduzir um erro de integração e ver a resposta completa da API;
- Enviar um documento pontual enquanto a integração automática não está pronta.
Você acessa a tela em Partner's Portal > Monitoramento > Submissão de Documentos, na barra lateral da área de monitoramento, junto de Tráfego e Eventos.
❗️ Atenção
Os envios feitos por esta tela são chamadas reais às APIs do ME, com o seu usuário. Em produção, eles gravam dados reais da sua empresa na plataforma, exatamente como uma chamada feita pelo seu ERP.
Documentos disponíveis
Nesta versão, a tela oferece a operação Criar para os documentos abaixo:
| Documento | Método e caminho | API |
|---|---|---|
| Produto | POST /v1/products | Products API |
| Requisição | POST /v1/requests | Requests API |
| Cotação | POST /v1/quotations | Quotations API |
| Contrato | POST /v1/contracts | Contracts API |
| Nota fiscal | POST /v1/invoices | Invoices API |
| Ordem de compra | POST /v1/orders | Orders API |
| Entrega de ordem de compra | POST /v1/orders/{orderId}/deliveries | Orders API |
O contrato completo de cada operação (campos, tipos e respostas) está na API Reference.
Como enviar um documento
1. Escolha o documento e a operação
Selecione o Documento e a Operação. A tela mostra a Chamada resolvida: o método HTTP e a URL completa (endereço do gateway + caminho) para onde o payload será enviado. Assim você sabe exatamente qual endpoint será chamado antes de enviar.
2. Preencha os IDs exigidos pelo caminho
Quando o caminho da operação tem parâmetros, a tela exibe um campo para cada um em IDs exigidos pelo caminho. Por exemplo, em Entrega de ordem de compra, o campo orderId recebe o ID da ordem de compra que vai receber a entrega. A chamada resolvida é atualizada conforme você digita.
Enquanto algum ID estiver vazio, o envio fica bloqueado.
3. Monte o payload
Cole ou digite o payload no editor Payload (JSON):
- Carregar exemplo: preenche o editor com um payload de exemplo do documento selecionado, que já passa na validação. Use-o como ponto de partida e troque os valores pelos dados reais (códigos do seu ERP, fornecedor, itens etc.).
- Formatar: reorganiza o JSON com indentação legível.
❗️ Atenção
O corpo precisa ser um objeto JSON (
{ ... }) de até 1 MB.Envios com payload muito grande podem não ficar registrados em Monitoramento › Tráfego. Para acompanhar um documento grande, guarde a resposta exibida no painel Resposta.
4. Confira a validação
Enquanto você edita, a tela valida o payload no navegador contra o schema publicado da API:
| Situação | O que aparece | Bloqueia o envio? |
|---|---|---|
| JSON com erro de sintaxe | JSON inválido, com a mensagem do parser. | Sim |
| Corpo que não é um objeto JSON (lista, texto, número) | Aviso pedindo um objeto JSON. | Sim |
| Campo obrigatório ausente | Aviso campo obrigatório não informado no campo correspondente. | Sim |
| Campo que não existe no documento | Aviso este campo não existe neste documento — confira o nome. Quando a diferença é só de maiúsculas e minúsculas, a tela indica o nome correto. | Não |
| Tipo, tamanho, formato ou valor fora do permitido | Aviso com a regra violada (por exemplo, deve ter no máximo 20 caracteres). | Não |
| Tudo certo | Payload válido para o schema de {documento}. | Não |
Cada aviso indica o campo no formato items[0].quantity. São exibidos até 20 avisos por vez; quando há mais, a tela mostra quantos ficaram de fora.
ℹ️ Nota
O schema usado na tela é uma cópia publicada da especificação da API e pode ficar defasado em relação a ela. Por isso, avisos de tipo, tamanho ou campo desconhecido não impedem o envio: a resposta da API é a palavra final. Se o schema não puder ser carregado, a validação fica indisponível, mas você continua podendo editar e enviar.
5. Envie
Clique em Enviar. Quando o portal está apontado para o ambiente de produção, a tela exibe um aviso de que a chamada afeta dados reais e pede uma confirmação extra (Confirmar envio?) antes de disparar a chamada. Em homologação, o envio é direto.
Resposta
Depois do envio, o painel Resposta mostra o status HTTP e o corpo devolvido pela API, com um botão para copiar. O resultado é classificado assim:
| Resultado | Status HTTP | O que significa | O que fazer |
|---|---|---|---|
| Documento recebido | 2xx | A API aceitou a requisição. | Acompanhe a chamada em Monitoramento › Tráfego e, nas integrações assíncronas, o resultado do processamento no Dashboard ou no webhook integration.result. |
| A API recusou o payload | 400, 409, 422 | Erro de negócio ou de contrato. | Corrija os campos listados no corpo da resposta e envie novamente. |
| Requisição não autorizada | 401, 403 | Sessão expirada ou sem permissão para o recurso. | Faça login novamente. Se persistir, peça a liberação do acesso. |
| Documento do caminho não encontrado | 404 em operação com ID no caminho | O ID informado no caminho não existe. | Corrija o ID e envie novamente. |
| Endpoint não encontrado | 404 em operação sem ID no caminho | A rota não existe no gateway. É um problema de configuração, não do payload. | Avise o suporte do ME. |
| O gateway devolveu um status inesperado | 5xx e outros | A requisição chegou à API, mas não foi processada. | Veja o corpo da resposta e tente novamente em instantes. |
| O gateway não respondeu | sem status | Não houve resposta dentro do tempo limite. | O envio pode ou não ter chegado à API. Confira em Monitoramento › Tráfego antes de enviar de novo, para não duplicar o documento. |
ℹ️ Nota
Algumas APIs do ME processam o documento de forma assíncrona. Nesses casos, a resposta
2xxconfirma apenas o recebimento; o resultado final (documento criado ou recusado) chega depois, pelo eventointegration.result.
Rastreio e auditoria
Os envios feitos pela Submissão de Documentos passam pelo mesmo gateway das chamadas do seu ERP e ficam registrados automaticamente em Monitoramento › Tráfego, com o seu tenant, o usuário que enviou, o método, o caminho, o status e os corpos da requisição e da resposta. Não é preciso salvar nada manualmente. A exceção são os envios com payload muito grande, que podem não ficar registrados (veja Monte o payload).
A tela não guarda histórico dos envios: para consultar um envio anterior, use o Tráfego.
Boas práticas
- Comece por "Carregar exemplo" e substitua os valores, em vez de montar o JSON do zero.
- Teste primeiro em homologação e só depois envie em produção.
- Leia o corpo da resposta de erro: ele indica o campo e a regra que a API recusou, com mais detalhe do que os avisos da tela.
- Depois de um timeout, confira o Tráfego antes de reenviar, para não criar o mesmo documento duas vezes.
- Use a tela para validar o contrato, não para carga em massa: para volumes recorrentes, integre o seu ERP diretamente às APIs.
Perguntas frequentes
Preciso de uma API Key para usar a tela? Não. O envio é autenticado com o seu login no Partner's Portal. As chamadas continuam sujeitas às mesmas permissões e regras das APIs.
Posso escolher o ambiente (homologação ou produção) na tela? Não. O envio vai sempre para o ambiente do portal que você está usando. A URL exibida na Chamada resolvida mostra para qual gateway a chamada vai.
Por que a tela deixou enviar e a API recusou? A validação da tela é uma ajuda antecipada, baseada em uma cópia do schema. A API aplica também regras de negócio (cadastros existentes, status, duplicidade etc.) que só ela conhece.
A tela permite atualizar ou excluir documentos? Não nesta versão. Estão disponíveis apenas as operações de criação listadas em Documentos disponíveis.