API de Faturas

49 min

atividades de certificação e validações necessáriasIntrodução

A API de Faturas faz parte da tríade de APIs relacionadas à gestão de pedidos de Peças, Acessórios e Vestuário (PA&A), sendo as outras duas a API de Pedido de Peças e a API de Entregas.

👉 Reserve um tempo para ler a seção Pedido, Fatura e Entrega: A História Completa para obter detalhes sobre pedidos de peças, entregas, faturamento e como usar as três APIs para conectá-los!

A API de Faturas permite que os concessionários recuperem uma fatura usando o número da fatura encontrado nas informações do pedido de peças, que também é exibido na fatura enviada pela BRP.

A API de Faturas também fornece um serviço para recuperar uma lista de faturas para um concessionário usando um filtro.

A API de Faturas pode ser usada para recuperar uma fatura de unidade.

🛑 As faturas de unidade retornadas são aquelas entre a BRP e o concessionário!

👉 São as faturas enviadas ao concessionário quando o concessionário compra unidades da BRP.

Por onde começar? Leia isto primeiro!

Antes de começar a trabalhar nesta API, você precisa ler as seguintes seções caso ainda não as tenha consultado:

Comece Aqui Com Leitura Obrigatória!
Informações Técnicas para informações técnicas gerais sobre a API e os ambientes.
Autenticação e Credenciais para detalhes sobre autenticação e credenciais.
Processo de Certificação para detalhes sobre o processo de certificação e o Jira.
Obtendo Suporte para detalhes sobre como obter ajuda e o Jira.
Pedido, Fatura e Entrega: A História Completa para obter uma visão geral do processo de pedido e entrega de peças.

Resumo do Negócio

Tópico	Descrição
Escopo	Unidade e PA&A (América do Norte)
Cenários	Módulo de Pedidos do DMS: fatura(s) de consultoria associadas a um pedido Módulo de Faturas do DMS: consultar/imprimir uma ou várias faturas Módulo de Contabilidade do DMS: associar faturas a contas a pagar
Funcionalidades principais	Fornecer informações de fatura
Processos de negócio suportados	Processo de recebimento de mercadorias na concessionária Reconciliação contábil
Benefícios para concessionárias	Facilitar o recebimento de mercadorias Facilitar a reconciliação contábil
Benefícios para a BRP	Maior satisfação das concessionárias Menos chamados de suporte

Informações Técnicas

Características

Tipo de API	Tipo de DSP	Versão DCP	Complexidade
Obter dados do BRP	DMS	V3 - Internacional	Baixa
Enviar dados ao BRP	CRM	V4 - América do Norte	Um pouco mais
Transação com BRP			Um pouco mais ainda

Autenticação

A API está usando Autenticação de Aplicação.

Você precisa de um token de acesso válido antes de chamar esta API ou deve chamar a API de Autenticação de Aplicativos para obter um.

O token de acesso é válido por 30 minutos! (1799 segundos)

URL Base

Teste	https://qa-cloud-api.brp.com/dcp/v4
Produção	https://cloud-api.brp.com/dcp/v4

Recurso: Fatura

Quando chamada para solicitar uma lista de faturas, a API de Faturas retorna um array de recursos Fatura Cada recurso Fatura mostrado abaixo contém todas as informações de uma fatura.

Quando você chama para recuperar uma fatura específica, a API de Faturas retorna um único recurso Fatura .

Representação JSON

{
    "dealer_no": "0000690885",
    "invoice_type": "ZF2P",
    "invoice_no": "9060858271",
    "invoice_date": "2024-03-20",
    "payer": "0000690885",
    "tax_amount_value": 0,
    "invoice_total": 302.97,
    "currency": "USD",
    "credit_indicator": false,
    "is_cancelled": false,
    "items": [
        {
            "item_no": "003202",
            "product_code": "705009190",
            "sales_order_no": "1030902201",
            "sales_order_item_no": "003202",
            "delivery_no": "8501841899",
            "delivery_item_no": "000010",
            "quantity": 12,
            "gross_value": 167.76,
            "discount_value": 0,
            "net_value": 167.94,
            "surcharge_value": 0,
            "handling_fees_value": 0.18,
            "freight_value": 0,
            "consignment_fees_value": 0,
            "other_fees_value": 0
        },
        {
            "item_no": "004101",
            "product_code": "705010334",
            "sales_order_no": "1030902201",
            "sales_order_item_no": "004101",
            "delivery_no": "8501841899",
            "delivery_item_no": "000020",
            "quantity": 6,
            "gross_value": 134.88,
            "discount_value": 0,
            "net_value": 135.03,
            "surcharge_value": 0,
            "handling_fees_value": 0.15,
            "freight_value": 0,
            "consignment_fees_value": 0,
            "other_fees_value": 0
        }
    ],
    "last_change_date": "2024-03-20T22:00:42Z"
}

Propriedades

Todos os campos numéricos com casas decimais usam o ponto (.) como separador decimal. A vírgula (,) NÃO é suportada como separador decimal.

Propriedade	Tipo	Definição	Notas
dealer_no	string	Código que representa o número do distribuidor ou outro número de entidade.	Comprimento:10
invoice_no	string	Número da fatura	Comprimento:10
invoice_type	string	Tipo de fatura. Os valores disponíveis estão listados na tabela Tipo de Fatura abaixo.
invoice_date	date	A data em que a transação de venda foi faturada no formato ISO 8601.	aaaa-mm-dd
payer	string	Número do Cliente (Pagador).	Comprimento:10
tax_amount_value	number	Valor total de impostos da fatura.	Precisão: 0.01
invoice_total	number	Valor líquido total do documento de faturamento.	Precisão: 0.01
currency	string	Moeda do documento. Os valores disponíveis estão listados na tabela Moeda abaixo.	Comprimento Máx.:3
credit_indicator	boolean	Indica se a fatura é um crédito. O valor pode ser verdadeiro ou falso.
is_cancelled	boolean	Indica se a fatura foi cancelada. O valor pode ser verdadeiro ou falso.
last_change_date	String	Data da última alteração realizada.	Formato: AAAA-MM-DDTHH:MM:SSZ
items	Lista de objetos
items.item_no	string	Número do item.
items.product_code	string	Código que identifica exclusivamente um produto.	Comprimento Máx.: 18
items.sales_order_no	string	O documento do pedido de venda ao qual o item se refere.	Comprimento Máx.:10
items.sales_order_item_no	string	O item no pedido de venda ao qual o item da fatura se refere.	Comprimento Máx.:10
items.delivery_no	string	O número da entrega para o item faturado.	Comprimento Máx.: 10
items.delivery_item_no	string	O documento do número de entrega ao qual o item se refere.	Comprimento Máx.: 10
items.quantity	number	Quantidade faturada na unidade de medida de vendas.	Precisão: 0.001
items.gross_value	number	O valor bruto do item faturado.	Precisão: 0.01
items.discount_value	number	Valor de desconto do item faturado.	Precisão: 0.01
items.net_value	number	Valor líquido do item faturado.	Precisão: 0.01
items.surcharge_value	number	Valor de sobretaxa.	Precisão: 0.01
items.handling_fees_value	number	Taxas de manuseio.	Precisão: 0.01
items.freight_value	number	Valor do frete.	Precisão: 0.01
items. consignment_fees_value	number	Valor das taxas de consignação.	Precisão: 0.01
items.other_fees_value	number	Valor de outras taxas.	Precisão: 0.01

Tipos de Fatura

Código	Descrição
ZCBR	Nota de crédito por devolução
ZF2F	Fatura de uma unidade
ZF2P	Fatura de um pedido PA&A
ZF2S	Fatura de serviço
ZF2W	Fatura de garantia estendida (BEST)
ZG2	Nota de crédito
ZG2R	Nota de crédito - devolução
ZG2W	Nota de crédito - garantia
ZL2	Nota de débito
ZL2W	Nota de débito - garantia
ZREP	Crédito por devoluções
ZREV	Devolução de veículo
ZS1	Cancelamento de fatura
ZS1C	Cancelamento de nota de débito
ZS1W	Cancelar fatura - garantia
ZS2	Cancelamento de nota de crédito
ZS2W	Cancelar nota de crédito - garantia
ZVG2	Nota de crédito - promoções
ZVL2	Nota de débito - promoções
ZVS1	Cancelamento de fatura - promoções
ZVS2	Cancelamento de nota de crédito - promoções

Limitações e Restrições

Formato de Número

Todos os campos numéricos com decimais usam o ponto(.) como separador decimal. A vírgula (,) NÃO é suportada como separador decimal.

Faturas para um Revendedor

Um revendedor pode recuperar apenas uma de suas faturas. O parâmetro de cabeçalho Dealer-Number deve identificar o revendedor que solicita as faturas, e a API retorna somente as faturas desse revendedor.

Tempo limite na Chamada de Obtenção

A API de Faturas fornece o serviço LISTA para recuperar faturas com base em um intervalo de datas.

❗ Em alguns casos, os critérios usados para a chamada do serviço LIST podem selecionar muitas faturas, e a API retorna um tempo limite (timeout) ❗

👉 O seu DMS deve lidar com o tempo limite e exibir uma mensagem de erro que peça ao concessionário para alterar o intervalo de datas para um menor.

Referência da API

Obter uma Fatura

Obtenha uma fatura usando o número da fatura.

GET

/invoice/{invoice_number}

curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9060858271' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Get an Invoice in PDF

Get an invoice PDF file using the invoice number.

GET

/invoice/{invoice_number}.pdf

curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338.pdf' 
--header 'Dealer-Number: 00006908855' \
--header 'Authorization: Bearer REPLACE_ME'

Obter Faturas

Obtenha uma lista de faturas usando um intervalo de datas.

GET

/invoices

curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2024-06-01'&limit=2 \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Como Fazer

Esta seção fornece informações sobre como obter resultados específicos com a API.

Obter uma Fatura para Encontrar um Pedido de Peças

Usando o número da fatura, obtenha uma fatura específica. Quando a fatura for encontrada, o concessionário pode usar o número do pedido de venda (sales_order_no) para encontrar o pedido de peças relacionado.

Obter a Fatura

curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obter o Pedido de Peças

👉 Este pedido de peças contém 116 itens, e um resumo é apresentado.

Get the Parts Order

curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'

curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'

Obter uma Fatura para Encontrar uma Entrega

Usando o número da fatura, obtenha uma fatura específica. Quando a fatura for encontrada, o revendedor pode usar o número da entrega (delivery_no) para encontrar a entrega relacionada.

👉 A partir do número de entrega, o pedido de peças correspondente pode ser encontrado, conforme descrito na seção Obter um Documento de Entrega para Encontrar um Pedido de Peças

Obter a Fatura

curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061023211' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obter a Entrega

Get the delivery

curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502015519' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obter a Fatura de uma Entrega

Obter uma fatura usando um número de entrega.

Obter a Fatura para um Número de Entrega

curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'

Obter Faturas por Números de Entrega

Obter uma lista de faturas usando uma lista de números de entrega.

Obter Faturas por Números de Entrega

curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312,8503004404,8503003809' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'

Obter as Faturas de um Período

Obter as faturas para um intervalo de datas.

Get the Invoices for a Period

curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-05-01&invoice_date_to=2025-05-10&limit=3' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obter uma fatura de uma unidade

A API de Faturas pode ser usada para obter faturas de unidades. A chamada também é feita utilizando o número da fatura.

👉 As faturas retornadas são enviadas pela BRP ao concessionário quando o concessionário compra unidades da BRP.

❗ Elas não são as faturas do cliente ❗

🚗 As faturas das unidades são identificadas com o tipo de fatura ZF2F.

Unit invoice

curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061034465' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obter Faturas de um Tipo Específico

Ao chamar o endpoint Obter Faturas , o parâmetro invoice_type pode ser usado para solicitar faturas de um tipo específico.

Os valores válidos são:

peças: retorna as faturas do tipo ZF2P.

unidades: retorna as faturas do tipo ZF2F.

serviço: retorna as faturas do tipo ZF2S.

❗ Ao usar o invoice_type filtro, APENAS as faturas listadas acima são retornadas.

O exemplo abaixo mostra uma chamada para obter apenas as faturas de peças.

Faturas para um tipo específico

curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-20&limit=2&invoice_type=parts' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'

Obter Faturas com uma Lista de Tipos

Ao chamar o Obter Faturas endpoint, o invoice_types parâmetro pode ser usado para solicitar faturas de tipos específicos.

O parâmetro recebe uma lista de tipos de fatura, separados por vírgula. A API de Faturas retorna as faturas com os tipos solicitados.

Obter Faturas com uma Lista de Tipos

curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-01&limit=3&invoice_types=ZCBR%2C%20ZF2F%2C%20ZF2P%2C%20ZF2S%2C%20ZF2W%2C%20ZG2%2C%20ZG2R%2C%20ZG2W%2C%20ZL2%2CZL2W%2CZREP%2C%20%20ZREV%2C%20ZS1%2C%20ZS1C%2C%20ZS1W%2C%20ZS2%2C%20ZS2W%2C%20ZVG2%2C%20ZVL2%2C%20ZVS1%2C%20ZVS2' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'

Tratamento de Erros

Esta seção apresenta vários cenários de chamadas inadequadas ou incorretas, que resultam em mensagens de erro e resultados impróprios.

400 Solicitação Inválida

O código de status 400 é normalmente encontrado durante o desenvolvimento e a integração, e não deve ser recebido durante operações normais. A resposta retornada contém as informações necessárias para corrigir o problema.

Muitos problemas podem causar um código de status 400; os mais comuns estão listados na tabela abaixo.

Resposta	Resolução
Retornado se o parâmetro de header Dealer-Number estiver ausente. { "status": "400", "id": "rrt-074faba1d0796ac77-c-ea-24396-616154-1", "title": "bad_request", "meta": { "service": "01", "detail": "falha na validação da requisição", "payload": { "details": [ { "message": "O parâmetro de header 'Dealer-Number' é obrigatório no caminho '/invoices', mas não foi encontrado na requisição." } ] } } }	Atualize sua chamada de API para adicionar o parâmetro Dealer-Number no header.
Retornado se o número da fatura estiver ausente na consulta. { "status": "400", "id": "rrt-074faba1d0796ac77-c-ea-24397-616812-1", "title": "bad_request", "meta": { "service": "00", "detail": "Caminho não encontrado." } }	Certifique-se de incluir um número de fatura no caminho da consulta.
✏Retornado se o número do concessionário for inválido. { "status": "400", "id": "rrt-023ba21d3844ea361-c-ea-4985-19207929-2.1", "title": "bad_request", "meta": { "service": "19", ln "detail": "Número de concessionário inválido" } }	Se o concessionário estiver usando seu DMS, pode ser que ele não seja mais um concessionário BRP. Verifique com ele e desative as atualizações de inventário de peças. Certifique-se de que o número do concessionário tenha 10 caracteres. Se você salvar o número sem os zeros à esquerda, adicione o zero à esquerda antes de chamar a API.

401 Não autorizado

O código de status de erro 401 Unauthorized é retornado quando você tenta chamar a API com um access_token.

Você precisa obter um novo access_token com uma chamada para a API de Autenticação de Aplicativos.

O código de status de erro 401 Unauthorized também é retornado se você não solicitou acesso à API criando um ticket no Jira do DCP.

Quando estiver pronto para começar a trabalhar em uma API, você deve criar um ticket de certificação no Jira, conforme descrito na seção Atividades de Certificação com o Jira.

Se você já começou a trabalhar em uma API e perdeu o acesso, crie um ticket de suporte conforme descrito na seção Abrir um Ticket de Suporte.

404 Não Encontrado

O código de status 404 Not Found é retornado quando o número da fatura não é encontrado.

{
    "status": "404",
    "id": "rrt-074faba1d0796ac77-c-ea-24396-616988-1.1",
    "title": "not_found",
    "meta": {
        "service": "97",
        "detail": "Invoice 9060002826 not found."
    }
}

O concessionário pode ter cometido um erro ao inserir o número da fatura. Você deve informar o erro ao usuário para que ele possa tentar novamente.

Requisitos do DSP

Requisitos Funcionais

ID	Tipo	Requisito
1	Obrigatório	O concessionário deve ser capaz de pesquisar uma fatura usando um número de fatura.
2	Obrigatório	A fatura deve ser exibida para o concessionário.
3	Obrigatório	O concessionário deve ser capaz de abrir um pedido de peças usando o número do pedido de venda (sales_order_no) encontrado em uma fatura.
4	Obrigatório	O concessionário deve ser capaz de abrir um documento de entrega usando o número de entrega (delivery_no) encontrado em uma fatura.
5	Obrigatório	O parâmetro de cabeçalho Dealer-Number deve ser definido como o número BRP do concessionário, e o concessionário não pode modificá-lo.
6	Opcional	O DMS recupera as faturas dos últimos 3 meses e as salva no banco de dados do DMS. O concessionário pode visualizar as faturas carregadas.
7	Opcional	O concessionário pode solicitar a versão PDF de uma fatura usando um número de fatura.

Atividades de Certificação

Esta seção apresenta todas as atividades de certificação e validações que devem ser concluídas para certificar a API.

Garantia de Qualidade

Os testes listados na tabela abaixo devem ser concluídos com sucesso no ambiente de testes antes que você possa iniciar a fase piloto com o concessionário.

Para estes testes, devemos usar o número do revendedor 0000690005

ID	Teste	Resultado Esperado
1	Obter a fatura 9061863617	A fatura é carregada e exibida.
2	Obter a lista de faturas com o intervalo de datas 2053-01-01 a 2026-03-01	Uma lista de 21 faturas é carregada.
3	Encontrar o pedido de peças com o número do pedido de vendas presente na fatura 9061863617	O pedido de peças é encontrado e exibido.
4	Obter o arquivo PDF da fatura 9061860929 (Opcional)	O arquivo PDF da fatura é carregado.

Piloto do Concessionário

A tabela abaixo descreve os parâmetros e validações do piloto do concessionário.

Parâmetro	Valor
Ambiente	Produção
Número de concessionárias	1 a 3
Duração	1 semana
Validação 1	Forneça uma lista de 10 a 20 faturas dentre as faturas recebidas pela concessionária. Forneça a captura de tela ou realize uma demonstração ao vivo para exibir pelo menos 10 faturas conforme visualizadas pela concessionária.
Validação 2	Forneça os números de pedidos de venda (pedidos de peças) recuperados das faturas na Etapa 1. Forneça a captura de tela ou realize uma demonstração ao vivo para exibir o pedido de peças vinculado a pelo menos 10 faturas conforme visualizado pela concessionária.

Postman

Esta seção descreve o que está disponível no Postman para explorar a API.

Ambientes

Um ambiente do Postman está disponível para testar a API de Faturas. Este ambiente do Postman contém as variáveis que as consultas utilizam e está configurado para se conectar ao ambiente de teste.

Teste - Ambiente DSP

Coleções

A coleção DMS - Faturas contém exemplos de chamadas de API para recuperar faturas.

DMS - Faturas

Registro de Alterações

Revision 1.2

Fixed

Removed the cost_value property since it's not valid.

Revision 1.1

Added

Filter parameters invoice_type and invoice_types.

Revision 1.0

Added

First release