API Reference

Eventos de Webhook

Lista de campos necessários por Estado

EstadoCampos obrigatórios
AcrePlaca e Renavam
AlagoasPlaca e Renavam
AmapáPlaca e Renavam
AmazonasPlaca e Renavam
BahiaPlaca e Renavam
CearáPlaca e Renavam
Distrito FederalPlaca, Renavam e CPF/CNPJ
Espírito SantoPlaca e Renavam
GoiásPlaca e Renavam
MaranhãoPlaca e Renavam
Mato GrossoPlaca e Renavam
Mato Grosso do SulPlaca e Renavam
Minas GeraisPlaca e Renavam
ParáPlaca e Renavam
ParaíbaPlaca e Renavam
ParanáPlaca e Renavam
PernambucoPlaca, Renavam e CPF/CNPJ
PiauíPlaca e Renavam
Rio de JaneiroPlaca, Renavam e CPF/CNPJ
Rio Grande do NortePlaca e Renavam
Rio Grande do SulPlaca e Renavam
RondôniaPlaca e Renavam
RoraimaPlaca e Renavam
Santa CatarinaPlaca e Renavam
São PauloPlaca, Renavam e CPF/CNPJ
TocantinsPlaca e Renavam

Uma chamada webhook contém em seu payload o resultado de um determinado evento (pesquisa de débito, pagamento, etc). Abaixo listamos detalhadamente os eventos e seus respectivos campos retornados:

Solicitação de consulta de débitos

curl --location 'https://api.b2b.usezapay.com.br/v2/vehicle/debts' \
--header 'Authorization: JWT TOKEN_JWT_VALIDO' \
--header 'Content-Type: application/json' \
--data '{
  "license_plate": "ABC1234"
}'

Resultado da solicitação de consulta de débitos

{
  "request_id": "653bde82b520d9659513988b"
}

Webhook informando que encontrou débitos para o veículo informado

{
  "id": "B1234",
  "event": "vehicle_debt_found",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {
    "debts": [
      {
        "id": "8J7SH08Q74Q0",
        "fine": null,
        "ipva": null,
        "type": "licensing",
        "year": "2023",
        "title": "LICENCIAMENTO",
        "amount": 160.23,
        "status": null,
        "distinct": [],
        "due_date": "2023-11-30",
        "interest": null,
        "required": null,
        "depends_on": [
          "MSIP7G9Z1G06"
        ],
        "is_expired": null,
        "description": "Licenciamento - 2023",
        "has_discount": null,
        "expiration_date": null,
        "discount_percentage": null,
        "value_without_discount": null
      },
      {
        "id": "MSIP7G9Z1G06",
        "fine": null,
        "ipva": null,
        "type": "ipva-unique",
        "year": "2023",
        "title": "IPVA",
        "amount": 1438.03,
        "status": null,
        "distinct": [],
        "due_date": "2023-02-10",
        "interest": null,
        "required": null,
        "depends_on": [
          "8J7SH08Q74Q0"
        ],
        "is_expired": null,
        "description": "IPVA Único 2023",
        "has_discount": null,
        "expiration_date": null,
        "discount_percentage": null,
        "value_without_discount": null
      }
    ],
    "protocol": "AAAAAZP",
    "request_id": "BBBBZP",
    "vehicle": {
        "license_plate": "ABC1234",
        "renavam": "11111111111"
    },
    "customer": {},
    "has_open_payment": false
  }
}

Webhook informando que o veículo não possui débitos

{
  "id": "B1234",
  "event": "vehicle_debt_not_found",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {
    "detail": "A requisição foi concluída e o veículo não possui débitos.",
    "code": "vehicle_debt_bureau_debts_not_found"
  }
}

Webhook de veículo não encontrado

{
  "id": "B1234",
  "event": "vehicle_not_found",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {
    "detail": "A requisição foi cancelada porque o veículo não foi encontrado.",
    "code": "vehicle_debt_bureau_vehicle_not_found"
  }
}

Webhook em caso de erro

{
  "id": "B1234",
  "event": "vehicle_debt_search_error",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {
    "detail": "A requisição foi cancelada porque o veículo está bloqueado.",
    "code": "vehicle_debt_bureau_vehicle_blocked"
  }
}

Webhook em caso de falha na obtenção dos dados complementares

{
  "id": "B1234",
  "event": "vehicle_enriched_partially",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "data": {
    "detail": "A requisição não foi concluída por falta de dados adicionais.",
    "code": "vehicle_enriched_partially",
    "required_fields": [
      "state",
      "renavam",
      "document"
    ]
  }
}

Request para complementar a pesquisa com dados adicionais do veículo

curl --location 'https://api.b2b.usezapay.com.br/v2/vehicle/debts' \
--header 'Authorization: JWT TOKEN_JWT_VALIDO' \
--header 'Content-Type: application/json' \
--data '{
  "license_plate": "ABC1234",
  "renavam": "12345678901",
  "document": "12345678901",
  "state": "SP",
  "request_id": "653bde82b520d9659513988b"
}'

Request para listar o histórico de webhooks enviados

curl --location 'https://api.b2b.usezapay.com.br/v2/webhook/{hook_id}/events/' \
--header 'Authorization: JWT TOKEN_JWT_VALIDO' \
--header 'Content-Type: application/json' \
--data '{
    "events": [
        "vehicle_not_found"
    ],
    "created_at": "string",
    "status": "pending"
}'

Resultado da listagem de histórico de webhooks enviados

{
  "items": [
    {
      "id": "B1234",
      "event": "vehicle_debt_found",
      "webhook": {
        "id": "B1234",
        "resource": "vehicle_debt",
        "version": "v2"
      },
      "last_status": "sent",
      "data": {
        "debts": [
          {
            "id": "8J7SH08Q74Q0",
            "fine": null,
            "ipva": null,
            "type": "licensing",
            "year": "2023",
            "title": "LICENCIAMENTO",
            "amount": 160.23,
            "status": null,
            "distinct": [],
            "due_date": "2023-11-30",
            "interest": null,
            "required": null,
            "depends_on": [
              "MSIP7G9Z1G06"
            ],
            "is_expired": null,
            "description": "Licenciamento - 2023",
            "has_discount": null,
            "expiration_date": null,
            "discount_percentage": null,
            "value_without_discount": null
          },
          {
            "id": "MSIP7G9Z1G06",
            "fine": null,
            "ipva": null,
            "type": "ipva-unique",
            "year": "2023",
            "title": "IPVA",
            "amount": 1438.03,
            "status": null,
            "distinct": [],
            "due_date": "2023-02-10",
            "interest": null,
            "required": null,
            "depends_on": [
              "8J7SH08Q74Q0"
            ],
            "is_expired": null,
            "description": "IPVA Único 2023",
            "has_discount": null,
            "expiration_date": null,
            "discount_percentage": null,
            "value_without_discount": null
          }
        ],
        "protocol": "AAAAAZP",
        "request_id": "BBBBZP",
        "vehicle": {
            "license_plate": "ABC1234",
            "renavam": "11111111111"
        },
        "customer": {},
        "has_open_payment": false
      },
      "attempts": [
        {
          "attempt": 2,
          "created_at": "2023-10-24T15:44:04.506308",
          "status": "sent",
          "server_response": {
            "http_status_code": 200,
            "headers": {
              "Access-Control-Allow-Credentials": true,
              "Access-Control-Allow-Origin": "*",
              "Access-Control-Expose-Headers": "filename",
              "Content-Type": "application/json",
              "Date": "Fri, 24 Nov 2023 15:44:15 GMT",
              "Content-Length": "33",
              "Connection": "keep-alive"
            },
            "body": {
              "msg": "Ok"
            }
          }
        },
        {
          "attempt": 1,
          "created_at": "2023-10-24T15:44:04.506308",
          "status": "failed",
          "server_response": {
            "http_status_code": 500,
            "headers": {
              "Access-Control-Allow-Credentials": true,
              "Access-Control-Allow-Origin": "*",
              "Access-Control-Expose-Headers": "filename",
              "Content-Type": "application/json",
              "Date": "Fri, 24 Nov 2023 15:44:15 GMT",
              "Content-Length": "33",
              "Connection": "keep-alive"
            },
            "body": {
              "msg": "Error"
            }
          }
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 1,
  "pages": 1
}

Request para reenviar um determinado webhook

curl --location 'https://api.b2b.usezapay.com.br/v2/webhook/{hook_id}/events/retry' \
--header 'Authorization: JWT TOKEN_JWT_VALIDO' \
--header 'Content-Type: application/json' \
--data '{
  "event_id": "event_12345"
}'

Resultado da retentativa de envio de um webhook

{
  "id": "B1234",
  "event": "vehicle_debt_found",
  "webhook": {
    "id": "B1234",
    "resource": "vehicle_debt",
    "version": "v2"
  },
  "last_status": "sent",
  "data": {
    "debts": [
      {
        "id": "8J7SH08Q74Q0",
        "fine": null,
        "ipva": null,
        "type": "licensing",
        "year": "2023",
        "title": "LICENCIAMENTO",
        "amount": 160.23,
        "status": null,
        "distinct": [],
        "due_date": "2023-11-30",
        "interest": null,
        "required": null,
        "depends_on": [
          "MSIP7G9Z1G06"
        ],
        "is_expired": null,
        "description": "Licenciamento - 2023",
        "has_discount": null,
        "expiration_date": null,
        "discount_percentage": null,
        "value_without_discount": null
      },
      {
        "id": "MSIP7G9Z1G06",
        "fine": null,
        "ipva": null,
        "type": "ipva-unique",
        "year": "2023",
        "title": "IPVA",
        "amount": 1438.03,
        "status": null,
        "distinct": [],
        "due_date": "2023-02-10",
        "interest": null,
        "required": null,
        "depends_on": [
          "8J7SH08Q74Q0"
        ],
        "is_expired": null,
        "description": "IPVA Único 2023",
        "has_discount": null,
        "expiration_date": null,
        "discount_percentage": null,
        "value_without_discount": null
      }
    ],
    "protocol": "AAAAAZP",
    "request_id": "BBBBZP",
    "vehicle": {
        "license_plate": "ABC1234",
        "renavam": "11111111111"
    },
    "customer": {},
    "has_open_payment": false
  },
  "attempts": [
    {
      "attempt": 3,
      "created_at": "2023-12-06T13:55:02.301309",
      "status": "sent",
      "server_response": {
        "http_status_code": 200,
        "headers": {
          "Access-Control-Allow-Credentials": true,
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Expose-Headers": "filename",
          "Content-Type": "application/json",
          "Date": "Fri, 06 Dec 2023 13:55:03 GMT",
          "Content-Length": "33",
          "Connection": "keep-alive"
        },
        "body": {
          "msg": "Ok"
        }
      }
    },
    {
      "attempt": 2,
      "created_at": "2023-10-24T15:44:04.506308",
      "status": "sent",
      "server_response": {
        "http_status_code": 200,
        "headers": {
          "Access-Control-Allow-Credentials": true,
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Expose-Headers": "filename",
          "Content-Type": "application/json",
          "Date": "Fri, 24 Nov 2023 15:44:15 GMT",
          "Content-Length": "33",
          "Connection": "keep-alive"
        },
        "body": {
          "msg": "Ok"
        }
      }
    },
    {
      "attempt": 1,
      "created_at": "2023-10-24T15:44:04.506308",
      "status": "failed",
      "server_response": {
        "http_status_code": 500,
        "headers": {
          "Access-Control-Allow-Credentials": true,
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Expose-Headers": "filename",
          "Content-Type": "application/json",
          "Date": "Fri, 24 Nov 2023 15:44:15 GMT",
          "Content-Length": "33",
          "Connection": "keep-alive"
        },
        "body": {
          "msg": "Error"
        }
      }
    }
  ]
}