---
title: "Solicitação De Consulta Em Lote"
method: POST
path: "/vehicle/debts/batch/"
tags: ["Consulta de Débitos Veiculares"]
---

# Solicitação De Consulta Em Lote

`POST /vehicle/debts/batch/`

A API de consulta de débitos veiculares permite que o cliente consulte os débitos de um veículo a partir de um fluxo assíncrono.

> Antes de realizar uma consulta, você deverá cadastrar uma URL para receber as atualizações de status da pesquisa via webhook através [deste endpoint](#tag/Webhook).
>
>
> [Neste link](https://docs-b2b.usezapay.com.br/docs/webhooks) você poderá encontrar um guia com maiores detalhes de como cadastrar um endpoint webhook para receber os resultados da sua pesquisa.

Ao realizar a requisição com sucesso, você receberá um código através do campo `id`. Segundos depois, você receberá um webhook com a url para consultar o resultado final.
Além disso, com o batch_id também é possível consultar o status da requisição de pesquisa. Através do endpoint [status](#tag/Consulta-de-Debitos-Veiculares/operation/Verificação_de_status_da_pesquisa_em_lote_de_veículos_vehicle_debts_batch__batch_id__status__get)

#### Eventos de Pesquisa de Débitos Veiculares que poderão aparecer nos eventos vinculados a aquele veículo são.

| Evento | Descrição |
| --- | --- |
| vehicle_debts_found | Foram encontrados débitos para o veículo pesquisado. |
| vehicle_debt_not_found | Não foram encontrados débitos para o veículo pesquisado. |
| vehicle_not_found | O veículo informado não foi encotrado. |
| vehicle_debt_search_error | Houve algum erro ao tentar realizar a pesquisa de débitos do veículo (Detalhes serão informados no corpo do evento) |
| vehicle_enriched_partially | A pesquisa não foi concluída porque não foi possível encontrar dados adicionais do veículo. |

Em [nosso guia de uso](https://docs-b2b.usezapay.com.br/docs/consulta-de-debitos#consultando-os-d%C3%A9bitos-de-um-ve%C3%ADculo), você poderá encontrar exemplos de payloads que seu endpoint receberá de acordo com cada um dos eventos listados acima.

Para testar o comportamento dessa API e diferentes tipos de retorno em ambiente sandbox, separamos um conjunto de placas de testes para você [neste link](https://docs-b2b.usezapay.com.br/docs/consulta-de-debitos#massa-de-testes).

## Request body

- SearchVehicleBatchRequestDTO
  - `vehicles` ZpyEnterpriseResourcesDomainDebtSchemasSearchDebtDtosVehicleDebtSearchDTO[], required
    - `license_plate` string, required — Placa do veículo em formato alfanumérico
    - `uf` string, nullable — Sigla do estado em que o veículo encontra-se emplacado. Ex: SP
    - `renavam` string, nullable — Renavam do veículo, é um número contendo até 11 dígitos
    - `chassis` string, nullable — Chassí do veículo
    - `request_id` string, nullable — Còdigo de uma solicitação de pesquisa anterior, informe quando a pesquisa original resultou na solicitação de dados adicionais
    - `customer` VehicleDebtCustomerDTO
      - `email` string, email, nullable
      - `phone` string, nullable
      - `document` string, nullable
      - `name` string, nullable
    - `extra_data` VehicleDebtSearchExtraDataDTO
      - `custom_field1` union — Campo de uso livre, com diferentes funções a depender do parceiro
        - string
        - object
      - `custom_data` VehicleDebtSearchExtraDataCustomDataDTO
        - `dealership` string, nullable — Concessionária
        - `dealership_document` string, nullable — CNPJ da concessionária
        - `customer_score` string, nullable — Score do cliente
        - `customer_age` string, nullable — Idade do cliente
        - `seller_age` string, nullable — Idade do vendedor
        - `active_customer` string, nullable — Flag para indicar se cliente está ativo
        - `defaulting_customer` string, nullable — Flag para indicar se cliente está inadimplente
      - `issue_ecrlv` boolean
      - `affiliates_params` VehicleDebtSearchExtraDataAffiliatesDataDTO
        - `coupon` string, nullable
        - `gclid` string, nullable
        - `utm_source` string, nullable
        - `utm_medium` string, nullable
        - `utm_keyword` string, nullable
        - `utm_campaign` string, nullable

## Response `201`

Sucesso

- SearchVehicleBatchRequestResponseDTOInput
  - `id` string, required — Id da requisição de pesquisa em lote
  - `webhook` WebhookShortModel, required
    - `id` string, required — Id único do webhook
    - `resource` 'vehicle_debt' | 'vehicle_debt_batch' | 'checkout' | 'autoradar' | 'payment_recurrence' | 'documents' | 'monitoring' | 'document_order'
    - `version` string — Versão do webhook
  - `fleet_id` string, nullable, required — Id da frota da requisição de pesquisa em lote
  - `created_at` string, date-time, required — Data e hora da criação da requisição de pesquisa em lote
  - `updated_at` string, date-time, required — Data e hora da atualização da requisição de pesquisa em lote
  - `status` 'created' | 'processing' | 'done' | 'failed'
  - `total_vehicles` integer, required — Quantidade de veículos dentro em lote
  - `processed_vehicles` integer, required — Quantidade de veículos pesquisados em lote

## Other responses

- `401` — Unauthorized
- `422` — Validation Error
- `503` — Serviço temporariamente indisponível

---

[API](https://skmtc.net/usezapay/apis/zapi.md) · [All operations](https://skmtc.net/usezapay/apis/zapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usezapay/zapi/revisions/50c96157fff4/schema)