Modelo M · Migração

Modelo M

O Modelo M reproduz o contrato de integração que o seu sistema já utiliza hoje, traduzindo-o para a plataforma Entregas Expressas. Na maioria dos casos a migração é uma troca de endereço base e de credencial — o restante do seu código permanece como está.

Endereço base

O protocolo usa dois endereços base — e o seu sistema provavelmente já tem os dois configurados hoje, cada um numa variável. Troque o valor delas por:

Base	Endereço	Usada por
Principal	https://entregasexpressas.com.br/api/m	Todos os endpoints, exceto o da linha abaixo
Secundária	https://entregasexpressas.com.br/api/m/v1	Apenas GET request/{id}

O que vem depois da base continua idêntico — {base}/abrirSolicitacao, {base}/solicitacao e assim por diante. Só o valor da variável muda; o código que monta as chamadas fica como está.

Por que são duas

A base secundária é uma geração mais nova do protocolo, que passou a conviver com a antiga em vez de substituí-la. Ela tem convenções próprias:

	Base principal	Base secundária
Campos	Português — id_mch, condutor, paradas	Inglês — request_id, driver, stops
Sucesso	{ "success": true, "response": … }	O objeto direto, sem envelope
Erro	{ "success": false, "errors": [ … ] }	{ "error": "…" }

Ou seja: GET request/{id} devolve os mesmos dados de GET solicitacao, com outros nomes e outro formato de erro. Use o que o seu sistema já consome — os dois continuam disponíveis.

Coleção do Postman

A coleção é gerada a partir dos endpoints publicados, então não fica desatualizada. Ela traz duas variáveis:

Variável	Valor
base_url	Já vem preenchida com https://entregasexpressas.com.br
api_key	Vazia — cole a chave fornecida pela central

A chave fica na variável e não escrita nos cabeçalhos: coleção exportada com credencial dentro acaba em repositório público.

Autenticação

Envie a sua chave no cabeçalho api-key em toda requisição. A chave é fornecida pela central e é ela que identifica de quem é a operação.

curl https://entregasexpressas.com.br/api/m/solicitacaoStatus?id_mch=1234 \
  --header 'api-key: SUA_CHAVE'

Se o seu sistema também envia autenticação HTTP Basic, pode continuar enviando: o cabeçalho é aceito e não precisa ser removido do seu código.

Escopo da chave

Existem dois tipos de chave, e é a central quem decide qual você recebe:

Tipo	Alcance
Central	Todos os recursos da praça — solicitações, empresas e entregadores.
Empresa	Apenas os dados da própria empresa: suas solicitações, seu cadastro, seu saldo e seus webhooks. Os demais endpoints respondem 403.

Respostas e erros

Todas as respostas são JSON. Sucesso:

{ "success": true, "response": { ... } }

Erro de negócio, com código para o seu sistema ramificar:

{ "success": false, "errors": [ { "code": 25, "message": "Solicitacao não encontrada." } ] }

Os códigos são os mesmos que o seu sistema já trata:

Código	Significado
1	Credencial inválida
2	Atributo obrigatório ausente
5 / 6	Tipo de identificação inválido / identificação não encontrada
24	Formato da entrada incorreto
25	Solicitação não encontrada
27	Solicitação não finalizada
56	Entregador não encontrado
75 / 76	Programada inexistente / não está aguardando disparo
97	Solicitação foi agrupada (traz solicitacao_agrupadora_id)
101 / 119	Webhook duplicado / id de webhook inválido

Solicitação

Método	Endpoint
POST	/abrirSolicitacao	Cria a solicitação. Com data e hora, cria programada.
GET	/estimarSolicitacao	Estimativa de valor, distância e tempo. Pontos na query, com sufixo _partida e _desejado.
GET	/solicitacao	Lista ou detalhe. Janela máxima de 30 dias.
GET	/solicitacaoStatus	Só a situação atual.
GET	/posicaoCondutor	Latitude e longitude do entregador.
GET	/reciboEntrega	Disponível com a solicitação finalizada.
GET	/obterLinkRastreio/{id}	Link de acompanhamento e código de confirmação.
GET	/consultarProgramada	Programadas aguardando disparo.
POST	/cancelar
POST	/cancelarProgramada	Só antes do disparo.
GET	/api/m/v1/request/{id}	Detalhes com campos em inglês.

Abrindo uma solicitação

curl --request POST \
  https://entregasexpressas.com.br/api/m/abrirSolicitacao \
  --header 'api-key: SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "forma_pagamento": "F",
    "empresa_id": 845,
    "partida": {
      "endereco": "Rua Evandro Câmara, 717",
      "bairro": "Monte Carmelo",
      "cidade": "Montes Claros",
      "estado": "MG",
      "lat": "-16.7176723",
      "lng": "-43.8341584"
    },
    "paradas": [
      {
        "endereco_parada": "Aeroporto de Montes Claros",
        "bairro_parada": "Jaraguá",
        "cidade_parada": "Montes Claros",
        "estado_parada": "MG",
        "lat_parada": "-16.7049531",
        "lng_parada": "-43.8199862",
        "id_externo": "714",
        "nome_cliente_parada": "Ralph Wisozk",
        "telefone_cliente_parada": "(38) 99999-9999",
        "observacao_parada": "Entregar na portaria",
        "valor_cobrar": 104.18
      }
    ],
    "retorno": false
  }'

Resposta:

{ "success": true, "response": { "id_mch": "1234", "public_id": "A7K2" } }

Empresa

Método	Endpoint
GET	/empresa
POST	/cadastrarEmpresa
PUT	/atualizarEmpresa/{id}
PUT	/atualizarEmpresas
GET	/listarAreasAtuacaoEmpresa
POST	/saldoCreditosEmpresa
POST	/recarregarCreditosEmpresa
POST	/sacarCreditosEmpresa

Nos endpoints de crédito, a empresa é identificada pelo bloco empresa: id (I), CPF (F), CNPJ (J), telefone (T) ou número de contrato (C).

Condutor

Método	Endpoint
GET	/condutor
POST	/atualizarCondutor/{id}
PUT	/atualizarCondutores
POST	/obterDocumentosCadastroCondutor
POST	/obterDocumentosCondutor
POST	/documentoCondutor/{id}
POST	/saldoCreditosCondutor
POST	/recarregarCreditosCondutor
POST	/sacarCreditosCondutor

O envio de documento é multipart/form-data com os campos tipo e foto. Consulte os tipos aceitos em /obterDocumentosCadastroCondutor.

Webhook

Cadastre uma URL e receba um evento a cada mudança de situação da solicitação e a cada entrega confirmada.

Método	Endpoint
POST	/cadastrarWebhook
GET	/listarWebhook
PUT	/atualizarWebhook/{id}
DELETE	/deletarWebhook/{id}

Corpo enviado para a sua URL:

{
  "datetime": "2026-08-26T13:20:05Z",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_id": 1234,
  "status_code": "A",
  "status_label": "ACCEPTED",
  "stop_id": "abc123",
  "links": {
    "request": "https://entregasexpressas.com.br/api/m/v1/request/1234"
  }
}

stop_id aparece somente no evento de entrega confirmada (STOP_FINISHED). Use event_id para descartar reenvios: em caso de falha, a entrega é repetida.

Os cabeçalhos Signature-V2 e Signature trazem o HMAC-SHA-512 do corpo, assinado com a sua chave de API.

Situações da solicitação

Consulta	Webhook	Significado
R	WAITING_PAYMENT	Aguardando pagamento
L	WAITING_RELEASE	Programada ou em preparo
D	DISTRIBUTING	Buscando entregador
A	ACCEPTED	Aceita — inclui a caminho e no local de coleta
—	ARRIVED_AT_LOCATION	Entregador chegou ao local
E	IN_PROGRESS	Coletada, em andamento
—	STOP_FINISHED	Uma entrega foi confirmada
F	FINISHED	Finalizada
C	CANCELLED	Cancelada
N	NOT_SERVED	Não atendida

A chegada ao local não é uma situação própria na consulta: ela é uma etapa de A, e só o webhook a distingue.

Formas de pagamento

Código	Forma
F	Faturado
R	Carteira de créditos
X	Pix
C / B	Crédito / débito
D	Dinheiro
P / H	PicPay / WhatsApp

O que for pago na entrega é registrado na parada e informado ao entregador. Ao filtrar solicitações por dinheiro, débito ou crédito, o resultado traz todas as pagas na entrega, sem separar por forma.

Diferenças de comportamento

• Link de acompanhamento é por solicitação, não por entrega. O endpoint devolve uma linha por parada, e o link é o mesmo em todas.
• Solicitação programada usa o mesmo identificador da solicitação: id_mch_programada e id_mch são o mesmo número. A consulta sem identificador lista apenas as que ainda aguardam disparo.
• Solicitação agrupada responde o código 97 com o identificador da solicitação que absorveu as entregas — consulte por ela.
• Áreas de bloqueio e de permissão por entregador não existem. A área de atendimento é avaliada pela posição do entregador no momento, então esses endpoints respondem erro em vez de sucesso — assim você não fica achando que aplicou uma restrição que não existe.
• A exclusão de entregador não é permitida por esta API.
• Cupons, mensagens, dinâmicas e saque automático não fazem parte desta integração.