Emitir un contra-CT-e

Parámetros, estructura de datos y respuestas del contrato versionado.

POST/fiscal/cte/contra

issueContraCteBase de Pruebas: https://api.fleetpay.site/v1

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Emite el CT-e de la transportista subcontratada contra el CT-e de la contratante, referenciando su clave en infDocAnt y designando a la contratante como tomadora del servicio.

tipo_servico define el ide/tpServ del contra-CT-e: 1 subcontratación (predeterminado), 2 redespacho, 3 redespacho intermedio. En el redespacho, la ruta es el tramo ejecutado, no el viaje completo de la contratante: 2 y 3 requieren origem y destino (400 validacao si faltan). Un tramo idéntico al viaje completo del CT-e original devuelve 422 contra_cte_invalido (redespacho_exige_rota); un CT-e original vinculado a transporte multimodal devuelve 422 contra_cte_invalido (origem_incompativel_com_tipo). La regla tributaria se determina según la ruta del tramo y el tipo de servicio.

El payload es reducido: indique la clave del CT-e original (que ya debe haber llegado a la bandeja del Monitor DFe), el conductor (por CPF), el vehículo (por matrícula) que ejecutan el tramo y el importe del flete, correspondiente a la transferencia al conductor. Remitente, destinatario, carga, ruta y tributación se leen del XML del CT-e original.

valor_frete es opcional: si se omite, la regla de precios de la transportista sugiere el importe del tramo. Una respuesta 202 requiere consultas periódicas a /cte/{cte_uuid}/consulta.

Autenticación

[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]

La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

No hay parámetros declarados para esta operación.

Cuerpo de la Solicitud

Obligatorio

`application/json`

ContraCteLoteRota ↗

chave_cte_originalstringObligatorio

Clave de acceso (44 dígitos) del CT-e de la empresa contratante.

minLength44

maxLength44

motoristaobjectObligatorio

placastringObligatorio

Matrícula del vehículo (formato brasileño, p. ej. ABC1D23 o ABC1234).

valor_fretenumber · doubleOpcional

Importe de la transferencia al conductor por el tramo. Opcional.

minimum0.01

tipo_servicointeger | nullOpcional

ide/tpServ del contra-CT-e: 1 subcontratación (predeterminado), 2 redespacho, 3 redespacho intermedio.

1 · 2 · 3 · null

origemobjectOpcional

ContraCteLoteRota ↗

destinoobjectOpcional

ContraCteLoteRota ↗

Respuestas

202 Respuesta HTTP

Emisión aceptada o resultado todavía inconcluso.

`application/json`

CteIssueEnvelope ↗

dataobjectObligatorio

CteIssueResult ↗

environmentobjectObligatorio

Environment ↗

Headers

X-Request-Id

Fallo interno sin detalles de las integraciones operativas.

`application/json`

ErrorEnvelope ↗

errorobjectObligatorio

ErrorBody ↗

Headers

X-Request-Id

Identificador de correlación de la llamada.

Definición Completa de la Operación

{
  "tags": [
    "CT-e"
  ],
  "summary": "Emitir contra-CT-e (subcontratação ou redespacho)",
  "description": "Emite o CT-e da transportadora **subcontratada** contra o CT-e da contratante, referenciando\na chave dele em `infDocAnt` e com a contratante como tomador.\n\n`tipo_servico` diz o `ide/tpServ` do contra-CT-e: `1` subcontratação (padrão), `2`\nredespacho, `3` redespacho intermediário. No redespacho a rota é o **trecho** executado,\nnão a viagem da contratante: `2` e `3` exigem `origem` e `destino` (`400` `validacao`\nsem eles); um trecho igual à viagem inteira do CT-e original responde `422`\n`contra_cte_invalido` (`redespacho_exige_rota`), e um CT-e original vinculado a\nmultimodal, `422` `contra_cte_invalido` (`origem_incompativel_com_tipo`). A regra de\ntributação é resolvida pela rota do trecho e pelo tipo.\n\nO payload é enxuto: informe a **chave do CT-e original** (que já precisa ter chegado pela\ncaixa do Monitor DFe), o **motorista** (por CPF) e o **veículo** (por placa) que executam o\ntrecho, e o **valor do frete** — o repasse ao motorista. Remetente, destinatário, carga,\nrota e tributação são lidos do XML do CT-e original.\n\n`valor_frete` é opcional: sem ele, a regra de precificação da transportadora sugere o valor\ndo trecho. Uma resposta 202 exige polling em `/cte/{cte_uuid}/consulta`.\n",
  "operationId": "issueContraCte",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "chave_cte_original",
            "motorista",
            "placa"
          ],
          "properties": {
            "chave_cte_original": {
              "type": "string",
              "minLength": 44,
              "maxLength": 44,
              "description": "Chave de acesso (44 dígitos) do CT-e da contratante."
            },
            "motorista": {
              "type": "object",
              "required": [
                "cpf"
              ],
              "properties": {
                "cpf": {
                  "type": "string",
                  "pattern": "^[0-9]{11}$",
                  "description": "CPF do motorista que executa o trecho (somente dígitos)."
                }
              }
            },
            "placa": {
              "type": "string",
              "description": "Placa do veículo (padrão brasileiro, ex. ABC1D23 ou ABC1234)."
            },
            "valor_frete": {
              "type": "number",
              "format": "double",
              "minimum": 0.01,
              "description": "Valor do repasse ao motorista pelo trecho. Opcional."
            },
            "tipo_servico": {
              "type": [
                "integer",
                "null"
              ],
              "enum": [
                1,
                2,
                3,
                null
              ],
              "description": "`ide/tpServ` do contra-CT-e: `1` subcontratação (padrão), `2` redespacho, `3` redespacho intermediário."
            },
            "origem": {
              "$ref": "#/components/schemas/ContraCteLoteRota"
            },
            "destino": {
              "$ref": "#/components/schemas/ContraCteLoteRota"
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Emissão aceita ou com resultado ainda não conclusivo.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CteIssueEnvelope"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "422": {
      "$ref": "#/components/responses/ValidationOrBusinessRuleFailed"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    }
  },
  "method": "POST",
  "path": "/fiscal/cte/contra",
  "parameters": []
}