Recibir un CT-e de un tercero

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

POST/fiscal/cte-subcontratacao

receiveInboundCteBase 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.

Entrega a FleetPay el XML de un CT-e emitido por otra empresa, normalmente la transportista contratante, que origina tu contra-CT-e de subcontratación.

Finalidad

Los otros métodos de recepción dependen de un tercero entre tu empresa y la plataforma. Aquí tu sistema entrega el documento directamente y este queda disponible en FleetPay, incluso sin un servicio contratado de recepción automática.

También habilita POST /fiscal/cte/contra: ese endpoint necesita el XML del CT-e original para preparar el contra-CT-e y pasa a encontrarlo aquí.

Envío

Elige una de dos formas:

application/json con el campo xml: XML sin codificar o en base64. La codificación se detecta por el contenido; no requiere un indicador.
multipart/form-data con el campo arquivo.

Acepta cteProc (con protocolo) o CTe sin procesar. Límite: 2 MB.

Reenvío Seguro

La operación es idempotente por clave de acceso. El primer envío devuelve 201; los siguientes devuelven 200 con el mismo recurso y received_count incrementado. Los reintentos de red, el reprocesamiento nocturno y el doble clic no generan registros duplicados ni errores.

Si el reenvío incluye un XML distinto del archivado, como al enviar primero CTe y después cteProc con el protocolo, el contenido se sustituye por la versión más reciente y content_updated es true.

Recibir No Es Emitir

Registrar la recepción no genera ningún documento fiscal. El contra-CT-e sigue creándose mediante POST /fiscal/cte/contra, con conductor, vehículo y precio de tu tramo; ninguno de esos tres datos está en el XML del contratante.

Un CT-e que no admite contra-CT-e, por ejemplo uno emitido por tu propia empresa, se recibe igualmente: carrier_role identifica tu papel y allows_counter_cte indica la elegibilidad, sin que tengas que implementar de nuevo la regla.

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`

InboundCteInput ↗

xmlstringObligatorio

XML del CT-e, sin codificar o en base64. Acepta cteProc (con protocolo) o CTe.

maxLength2097152

`multipart/form-data`

arquivostring · binaryObligatorio

XML del CT-e, hasta 2 MB.

Respuestas

200 Respuesta HTTP

Documento ya conocido. La entrega es idempotente: se devuelve el mismo recurso, con received_count incrementado.

`application/json`

InboundCteReceiptEnvelope ↗

dataobjectObligatorio

InboundCteReceipt ↗

environmentobjectObligatorio

Environment ↗

Headers

X-Request-Id

Identificador de correlación de la llamada.

201 Respuesta HTTP

Primera recepción de este documento; se creó el recurso.

`application/json`

InboundCteReceiptEnvelope ↗

dataobjectObligatorio

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 de subcontratação"
  ],
  "summary": "Receber um CT-e de terceiro",
  "description": "Entrega à FleetPay o XML de um CT-e emitido por outra empresa — tipicamente o da\ntransportadora **contratante**, que dá origem ao seu contra-CT-e de subcontratação.\n\n## Por que existe\n\nAs demais formas de recepção dependem de um terceiro entre você e a plataforma. Aqui é o\nseu sistema que entrega o documento, e ele passa a existir na FleetPay sem intermediário\n— inclusive quando nenhuma recepção automática está contratada.\n\nÉ também o que destrava `POST /fiscal/cte/contra`: aquele endpoint precisa do XML do CT-e\noriginal para montar o contra-CT-e, e passa a encontrá-lo aqui.\n\n## Como enviar\n\nDuas formas, escolha uma:\n\n- `application/json` com o campo `xml` — o XML cru ou em **base64**. A codificação é\n  detectada pelo conteúdo; não há flag a acertar.\n- `multipart/form-data` com o campo `arquivo`.\n\nO documento pode ser o `cteProc` (com protocolo) ou o `CTe` cru. Limite de 2 MB.\n\n## Reenviar é seguro\n\nA operação é **idempotente pela chave de acesso**. O primeiro envio responde `201`; os\nseguintes respondem `200` com o mesmo recurso e `received_count` somado. Retry de rede,\nreprocessamento noturno e clique duplo não criam registro duplicado nem erro.\n\nSe o reenvio trouxer um XML diferente do arquivado — o caso comum é mandar o `CTe` e\ndepois o `cteProc` com o protocolo —, o conteúdo é substituído pelo mais recente e\n`content_updated` vem `true`.\n\n## Receber não é emitir\n\nRegistrar a chegada não gera documento fiscal nenhum. O contra-CT-e continua nascendo em\n`POST /fiscal/cte/contra`, com motorista, veículo e o preço do **seu** trecho — nenhum dos\ntrês está no XML da contratante.\n\nUm CT-e que não admite contra-CT-e (por exemplo, um que a sua própria empresa emitiu) é\nrecebido do mesmo jeito: o campo `carrier_role` nomeia o seu papel e `allows_counter_cte`\nresponde a pergunta prática, sem que você precise reimplementar a regra.\n",
  "operationId": "receiveInboundCte",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/InboundCteInput"
        }
      },
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "required": [
            "arquivo"
          ],
          "properties": {
            "arquivo": {
              "type": "string",
              "format": "binary",
              "description": "XML do CT-e, até 2 MB."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "$ref": "#/components/responses/InboundCteReceivedAgain"
    },
    "201": {
      "$ref": "#/components/responses/InboundCteReceived"
    },
    "400": {
      "$ref": "#/components/responses/ValidationFailed"
    },
    "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-subcontratacao",
  "parameters": []
}