Envia um manifesto novo (entrega, coleta ou transferência)

Cabeçalhos (header)

• X-Veltra-Api-Keytextoobrigatório

  Chave de API do TMS. Emitida na tela Chaves de API do portal; o valor completo aparece uma única vez.

• Idempotency-Keytextoobrigatório

  Chave de idempotência gerada pelo TMS (recomendado: UUID) por tentativa lógica de envio. Guardada por pelo menos 72 h, isolada por transportadora e ambiente. Repetir a mesma chave com o mesmo corpo devolve a resposta original; com corpo diferente = 409.

  de 1 a 255 caracteres

• Content-Typetextoobrigatório

  Sempre application/json.

Corpo (body) · application/json

• tipotexto (lista fixa)obrigatório

  Tipo do manifesto enviado pelo TMS. Use ROTA para o caminhão que sai com entregas e coletas juntas e TRANSFERENCIA para transferência entre filiais (sempre só transferência). ENTREGA e COLETA seguem aceitos por compatibilidade e são tratados como ROTA.

  Valores: ROTA, TRANSFERENCIA, ENTREGA, COLETA

• numeroExternotextoobrigatório

  Número do manifesto/relatório no TMS. Chave natural, única por transportadora e ambiente.

  de 1 a 60 caracteres

• motoristaobjetoobrigatório

  Motorista ou ajudante citado no manifesto.

• motorista.cpftextoobrigatório

  CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores.

• motorista.nometextoobrigatório

  até 200 caracteres

• veiculoobjetoobrigatório
• veiculo.placatextoobrigatório

  Placa de tração (padrão antigo ou Mercosul), com ou sem hífen. Chave de upsert do veículo.

• ajudanteslista de objetosopcional

  Até 2 ajudantes (nome + CPF). Não são usuários do app, só dados do manifesto.

  até 2 itens

• ajudantes[].cpftextoobrigatório

  CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores.

• ajudantes[].nometextoobrigatório

  até 200 caracteres

• filialOrigemSiglatextoopcional

  siglaExterna da filial de origem. Obrigatória quando tipo=TRANSFERENCIA; sigla desconhecida = 400.

• filialDestinoSiglatextoopcional

  siglaExterna da filial de destino. Obrigatória quando tipo=TRANSFERENCIA.

• chaveMdfetextoopcional

  Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos.

  de 44 a 44 caracteres; padrão ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$

• quantidadePaletesinteiroopcional

  Quantidade de paletes informada no manifesto.

  mínimo 0

• documentoslista de objetosobrigatório

  ao menos 1 item(ns)

• documentos[].modelotexto (lista fixa)obrigatório

  Modelo do documento fiscal: 55 = NF-e, 57 = CT-e, 58 = MDF-e. Nos documentos do manifesto o normal é 57 (CT-e) ou 55 (NF-e, ex.: coleta sem CT-e); a chave do MDF-e do próprio manifesto vai em chaveMdfe.

  Valores: 55, 57, 58

• documentos[].chavetextoopcional

  Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos.

  de 44 a 44 caracteres; padrão ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$

• documentos[].numerotextoobrigatório

  até 20 caracteres

• documentos[].serietextoopcional

  até 10 caracteres

• documentos[].cnpjTransportadoratextoopcional

  CNPJ da transportadora que emitiu o CT-e (só faz sentido em modelo=57). Opcional: ausente, o Veltra usa o CNPJ da chave (posições 7 a 20). Se vier, é usado como enviado, sem checar contra a chave. Com ou sem máscara.

• documentos[].cnpjEmbarcadortextoopcional

  CNPJ do embarcador, dono/emitente da NF (para modelo diferente de 57; obrigatório nesses casos). No CT-e não é usado: a chave já identifica o documento. Com ou sem máscara.

• documentos[].tomadorCnpjtextoopcional

  Opcional e aditivo (só modelo=57). CNPJ de quem paga o frete (tomador do CT-e), numérico ou alfanumérico, com ou sem máscara. Ausente, nenhum terceiro recebe PDF nem canhoto.

• documentos[].tarefatexto (lista fixa)opcional

  O que o motorista faz com o documento na parada. Coleta e entrega no mesmo cliente e no mesmo manifesto ficam na mesma parada, com as duas tarefas.

  Valores: ENTREGA, COLETA

• documentos[].embarcadorobjetoopcional

  Embarcador da mercadoria (opcional); quem embarca a mercadoria (cliente da transportadora).

• documentos[].embarcador.cnpjCpftextoobrigatório
• documentos[].embarcador.nometextoopcional
• documentos[].destinatarioobjetoobrigatório
• documentos[].destinatario.cnpjCpftextoobrigatório

  CNPJ (numérico ou alfanumérico) ou CPF do destinatário/recebedor, com ou sem máscara. Obrigatório: agrupa as paradas e identifica o link do destinatário.

• documentos[].destinatario.nometextoobrigatório

  até 200 caracteres

• documentos[].destinatario.enderecoobjetoobrigatório

  Endereço de entrega/coleta do destinatário. Junto com o CNPJ/CPF, define a parada.

• documentos[].destinatario.endereco.logradourotextoobrigatório
• documentos[].destinatario.endereco.numerotextoopcional
• documentos[].destinatario.endereco.complementotextoopcional
• documentos[].destinatario.endereco.bairrotextoopcional
• documentos[].destinatario.endereco.municipiotextoobrigatório
• documentos[].destinatario.endereco.uftextoobrigatório

  de 2 a 2 caracteres

• documentos[].destinatario.endereco.ceptextoopcional

  Só dígitos ou com hífen.

• documentos[].destinatario.emailtextoopcional

  Opcional. E-mail do destinatário para o aviso da entrega. Dado pessoal: não registrar em log. Ausente, o destinatário acompanha pelo link copiado no portal ou pela chave da NF.

  até 320 caracteres

• documentos[].nfVinculadaslista de objetosopcional

  NF transportadas quando o documento é um CT-e (1 ou mais). Vazio/omitido nos demais modelos.

• documentos[].nfVinculadas[].chavetextoopcional

  Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos.

  de 44 a 44 caracteres; padrão ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$

• documentos[].nfVinculadas[].numerotextoobrigatório

  até 20 caracteres

• documentos[].nfVinculadas[].serietextoopcional

  até 10 caracteres

• documentos[].nfVinculadas[].cnpjEmbarcadortextoobrigatório

  CNPJ do embarcador (emitente da NF), numérico ou alfanumérico, com ou sem máscara.

• documentos[].nfVinculadas[].valornúmeroopcional

  Valor da NF em reais, para exibição na torre; não é usado em cálculo (desde a 0.4.0).

  mínimo 0

• documentos[].nfVinculadas[].nfeEmitidoEmtexto (data e hora ISO 8601)opcional

  Opcional. Data e hora de emissão da NF-e. Sem a data base escolhida pela transportadora, o prazo conta da chegada do manifesto ao Veltra. prazoEntrega no documento continua aceito.

• documentos[].volumesinteiroopcional

  mínimo 0

• documentos[].pesonúmeroopcional

  Peso em kg.

  mínimo 0

• documentos[].valornúmeroopcional

  Valor do documento em reais, para exibição na torre; não é usado em cálculo (desde a 0.4.0).

  mínimo 0

• documentos[].prazoEntregatexto (data AAAA-MM-DD)opcional

  Prazo de entrega, quando houver. Continua aceito. Sem a data base escolhida pela transportadora (cteEmitidoEm, nfeEmitidoEm ou este campo), o prazo conta da chegada do manifesto ao Veltra.

• documentos[].cteEmitidoEmtexto (data e hora ISO 8601)opcional

  Opcional. Data e hora de emissão do CT-e. Sem a data base escolhida pela transportadora, o prazo conta da chegada do manifesto ao Veltra. prazoEntrega continua aceito.

• documentos[].latitudenúmeroopcional

  Opcional. Se vier junto com longitude, é usada direto na parada; senão o endereço é geocodificado em segundo plano.

  de -90 a 90

• documentos[].longitudenúmeroopcional

  de -180 a 180

• documentos[].protocoloAutorizacaotextoopcional

  Opcional e aditivo (só modelo=57). Protocolo de autorização do CT-e (nProt, 15 dígitos, do protCTe). Necessário ao perfil Comprovante Digital Homologado (evento 110180). Sem ele, o evento do CT-e fica PENDENTE_DE_DADOS no portal; a entrega continua sendo comprovada pelo comprovante interno do Veltra. Clientes que não enviam o campo seguem funcionando como antes.

  padrão ^[0-9]{15}$

• documentos[].tipoServicotexto (lista fixa)opcional

  Opcional e aditivo (só modelo=57). Tipo de serviço do CT-e (tpServ): NORMAL (0), SUBCONTRATACAO (1), REDESPACHO (2), REDESPACHO_INTERMEDIARIO (3), SERVICO_VINCULADO_MULTIMODAL (4). O evento 110180 só lista as NF-e entregues em CT-e NORMAL.

  Valores: NORMAL, SUBCONTRATACAO, REDESPACHO, REDESPACHO_INTERMEDIARIO, SERVICO_VINCULADO_MULTIMODAL

• documentos[].globalizadoverdadeiro/falsoopcional

  Opcional e aditivo (só modelo=57). CT-e globalizado (a SEFAZ admite mais de um comprovante para ele). Omitido = não globalizado.

  padrão: false

Exemplos de corpo

{
  "tipo": "ENTREGA",
  "numeroExterno": "REL-2026-000123",
  "motorista": {
    "cpf": "529.982.247-25",
    "nome": "Motorista Exemplo da Silva"
  },
  "veiculo": {
    "placa": "ABC1D23"
  },
  "ajudantes": [
    {
      "cpf": "111.444.777-35",
      "nome": "Ajudante Exemplo"
    }
  ],
  "chaveMdfe": "35260911222333000181580010000007891273645188",
  "quantidadePaletes": 4,
  "documentos": [
    {
      "modelo": 57,
      "chave": "35260911222333000181570010000123451482135762",
      "numero": "12345",
      "serie": "1",
      "cnpjTransportadora": "11222333000181",
      "embarcador": {
        "cnpjCpf": "12ABC34501DE35",
        "nome": "Indústria Exemplo S.A."
      },
      "destinatario": {
        "cnpjCpf": "11444777000161",
        "nome": "Mercado Exemplo Ltda",
        "endereco": {
          "logradouro": "Rua das Flores",
          "numero": "120",
          "bairro": "Centro",
          "municipio": "Campinas",
          "uf": "SP",
          "cep": "13010-000"
        }
      },
      "nfVinculadas": [
        {
          "chave": "35260912ABC34501DE35550010000456781555123454",
          "numero": "45678",
          "serie": "1",
          "cnpjEmbarcador": "12ABC34501DE35"
        }
      ],
      "volumes": 12,
      "peso": 350.5,
      "prazoEntrega": "2026-10-02"
    },
    {
      "modelo": 57,
      "chave": "35260911222333000181570010000123461918273641",
      "numero": "12346",
      "serie": "1",
      "cnpjTransportadora": "11222333000181",
      "destinatario": {
        "cnpjCpf": "11444777000161",
        "nome": "Mercado Exemplo Ltda",
        "endereco": {
          "logradouro": "Rua das Flores",
          "numero": "120",
          "bairro": "Centro",
          "municipio": "Campinas",
          "uf": "SP"
        }
      },
      "nfVinculadas": [
        {
          "numero": "45679",
          "serie": "1",
          "cnpjEmbarcador": "12ABC34501DE35"
        }
      ],
      "volumes": 3,
      "peso": 40
    }
  ]
}

{
  "tipo": "COLETA",
  "numeroExterno": "COL-2026-000045",
  "motorista": {
    "cpf": "52998224725",
    "nome": "Motorista Exemplo da Silva"
  },
  "veiculo": {
    "placa": "ABC1D23"
  },
  "documentos": [
    {
      "modelo": 55,
      "numero": "45679",
      "serie": "1",
      "cnpjEmbarcador": "12ABC34501DE35",
      "destinatario": {
        "cnpjCpf": "12ABC34501DE35",
        "nome": "Indústria Exemplo S.A.",
        "endereco": {
          "logradouro": "Avenida Industrial",
          "numero": "1000",
          "municipio": "Sumaré",
          "uf": "SP"
        }
      },
      "volumes": 20,
      "peso": 800
    }
  ]
}

{
  "tipo": "TRANSFERENCIA",
  "numeroExterno": "TRF-2026-000007",
  "motorista": {
    "cpf": "52998224725",
    "nome": "Motorista Exemplo da Silva"
  },
  "veiculo": {
    "placa": "XYZ9A87"
  },
  "filialOrigemSigla": "CPS",
  "filialDestinoSigla": "SJC",
  "documentos": [
    {
      "modelo": 57,
      "chave": "35260911222333000181570010000123451482135762",
      "numero": "12345",
      "serie": "1",
      "cnpjTransportadora": "11222333000181",
      "destinatario": {
        "cnpjCpf": "11222333000181",
        "nome": "Transportadora Exemplo - Filial SJC",
        "endereco": {
          "logradouro": "Rodovia Presidente Dutra",
          "numero": "km 150",
          "municipio": "São José dos Campos",
          "uf": "SP"
        }
      },
      "nfVinculadas": [
        {
          "numero": "45678",
          "serie": "1",
          "cnpjEmbarcador": "12ABC34501DE35"
        }
      ],
      "volumes": 12,
      "peso": 350.5
    }
  ]
}