API de Entregas

39 min

Começando

A API de Entregas 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 Faturas.

👉 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 Entregas permite ao concessionário recuperar um documento de entrega com informações de envio usando um número de entrega encontrado na guia de remessa e as informações do pedido de peças quando o pedido tiver sido enviado.

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

❗ A API de Entrega NÃO PODE ser usada para recuperar um documento de entrega de unidade ❗

Por onde começar? Leia isto primeiro!

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

Comece Aqui Com Leitura Obrigatória!
Informações Técnicas para informações técnicas gerais sobre a API e 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 Jira.
Obtendo Suporte para detalhes sobre como obter ajuda e 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 de Negócios

Tópico	Descrição
Escopo	PA&A na América do Norte
Cenários	Módulo de Pedidos DMS: consultar entregas associadas a um pedido, gerenciar quantidades faltantes, obter informações de rastreamento Módulo de Serviço DMS: confirmar o recebimento de peças para uma manutenção/reparo agendado Acompanhamento de pedidos de clientes: facilitar o rastreamento de pedidos/reparos
Funcionalidades principais	Fornecer informações de rastreamento de envio de pedidos Fornecer informações da nota de embalagem do pedido
Processos de negócios suportados	Processo de recebimento de mercadorias na concessionária Gestão de inventário Acompanhamento de Vendas / Serviço
Benefícios para concessionários	Gestão de inventário de peças (em trânsito) Atualizações de rastreamento Facilitar o recebimento de mercadorias
Benefícios para a BRP	Aumento da satisfação dos concessionários Menos chamados de suporte Economia em despesas de devolução

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 para o BRP	CRM	V4 - América do Norte	Um pouco mais
Transação com o 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 você 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: Entrega

Quando chamada para solicitar uma lista de documentos de entrega, a API de Entregas retorna uma matriz de Entrega recursos. Cada recurso de Entrega mostrado abaixo contém todas as informações em um documento de entrega.

Quando chamado para obter um documento de entrega específico, a API de Entregas retorna um único recurso de Entrega ’

Representação JSON

{
    "delivery_no": "8502015519",
    "dealer_no": "0000690885",
    "customer_address": {
        "street": "109 THOMAS DRIVE",
        "city": "AMERICUS",
        "state": "GA",
        "country": "US",
        "postal_code": "31709-5533"
    },
    "shipping_condition": "S1",
    "ship_to_no": "0020000953",
    "ship_to_address": {
        "street": "1601 S SLAPPEY BLVD",
        "city": "ALBANY",
        "state": "GA",
        "country": "US",
        "postal_code": "31701-2645"
    },
    "last_change_date": "2024-05-07T00:00:00Z",
    "items": [
        {
            "delivery_item_no": "000010",
            "product_code": "420686602",
            "product_description": "GASKET SET",
            "order_qty": 1,
            "delivery_qty": 1,
            "package_qty": 1,
            "sales_order_no": "1030969589",
            "sales_order_item_no": "007001",
            "dealer_po_no": "ODN041123",
            "tracking_details": [
                {
                    "tracking_no": "1Z7F7W950301444225",
                    "tracking_url": "https://wwwapps.ups.com/WebTracking/track?loc=en_US&AgreeToTermsAndConditions=yes&track.x=26&track.y=5&trackNums=1Z7F7W950301444225"
                }
            ]
        }
    ]
}

Propriedades

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

Property	Type	Definition	Notes
delivery_no	String	Delivery number	Length: 10
dealer_no	String	Code representing the dealer number or other entity number who placed the order.	Length:10
customer_address	object	Delivery address
customer_address .street	string	Street address (1st line)	Max Length:60
customer_address .city	string	City	Max Length:40
customer_address .state	string	Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format.	Max Length:3
customer_address .country	string	Code that uniquely identifies a country, in ISO 3166-1 format.	Max Length:2
customer_address .postal_code	string	Postal code.	Max Length:10
ship_to_no	string	Code representing the customer or other entity number to which the goods are delivered.	Length:10
ship_to_address	object	Delivery address
ship_to_address .street	string	street address (1st line)	Max Length:60
ship_to_address .city	string	City	Max Length:40
ship_to_address .state	string	Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format.	Max Length:3
ship_to_address .country	string	Code that uniquely identifies a country, in ISO 3166-1 format.	Max Length:2
ship_to_address .postal_code	string	Postal code.	Max Length:10
shipping_condition	string	BRP custom code that uniquely identifies the shipping method for which the order is delivered. One value from the Shipping Method table.	Max Length: 2
last_change_date	string	Last date and time at which this resource has changed, in ISO 8601 UTC format.	Format: YYYY-MM-DDTHH:MM:SSZ
items	List of objects
items. delivery_item_no	string	Delivery item number.	Max Length: 6
items. product_code	string	Code that uniquely identifies a product.	Max Length: 18
items. product_description	string	The product description.	Max Length: 40
items. order_qty	number	Ordered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped.	Precision:1.00
items. delivery_qty	number	Delivered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped.	Precision:1.00
items. package_qty	number	Quantity in a package.	Precision:1.00
items. sales_order_no	string	Sales order document the item refers to.	Length:10
items. sales_order_item_no	string	Sales order document item number the item refers to.	Max Length:6
items. dealer_po_no	string	The number that the customer uses to uniquely identify a purchasing document.	Max Length: 35
items. tracking_details	List of objects
items. tracking_details. tracking_no	String	Tracking number from the carrier.	Max Length: 30
items. tracking_details. tracking_url	String	URL tracking number from the carrier.	Max Length: 300 for each URL tracking number

Métodos de Envio - América do Norte

Código V3	Código V4	Descrição	Uso
01	S1	Envio Terrestre Expresso	Atualização de primeiro nível a partir do envio terrestre padrão doméstico: Serviço de Envio: envio terrestre padrão. Normalmente encomendas terrestres/LTL. Taxas de manuseio de frete são cobradas dos clientes.
02	S2	Veículo Imobilizado	Envio mais rápido disponível. Comumente usado quando atrasos na entrega são críticos (cenários de veículo imobilizado): Serviço de Envio: o mais rápido possível, frequentemente referido como Expresso (Purolator) ou Next Day Air (UPS). Opção de upgrade do Método de Envio 01/S1. Taxas de manuseio de frete são cobradas dos clientes.
03	S3	Veículo Imobilizado Sábado	Igual ao Veículo Imobilizado, com a possibilidade de ser recebido em um sábado.

Métodos de Envio - Internacional

Organização de Vendas	Código V3	Descrição
6030 - Escandinávia	50	itella
6030 - Escandinávia	51	posten_logistik
6030 - Escandinávia	52	terrestre
6030 - Escandinávia	53	aéreo
6030 - Escandinávia	54	terrestre
6030 - Escandinávia	55	aéreo
6030 - Escandinávia	59	terrestre
6030 - Escandinávia	60	aéreo
6050 - Europa (emea)	30	regular
6050 - Europa (emea)	33	urgente
7080 - Ásia-Pacífico (apac)	38	regular
7080 - Ásia-Pacífico (apac)	39	urgente
7080 - Ásia-Pacífico (apac)	40	regular
7080 - Ásia-Pacífico (apac)	82	estoque
7080 - Ásia-Pacífico (apac)	90	estoque
8070 - México	92	regular
8070 - México	93	aéreo
8070 - México	94	urgente
8075 - Brasil	63	aéreo_azul_cargo
8075 - Brasil	77	sedex_correios
8075 - Brasil	78	padrão_rodoviário

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.

Documento de Entrega para um Revendedor

Um revendedor só pode recuperar um de seus documentos de entrega. O parâmetro de cabeçalho Dealer-Number deve identificar o revendedor que está solicitando o documento, e a API retorna apenas o documento de entrega para este revendedor solicitante.

Timeout na Chamada para Obter

A API de Entregas oferece o serviço LISTA para recuperar entregas com base em alguns critérios, como um intervalo de datas.

❗ Em alguns casos, os critérios usados para a chamada do serviço LIST podem selecionar documentos de entrega demais, e a API retorna um timeout ❗

👉 Seu DMS deve tratar o timeout e exibir uma mensagem de erro solicitando ao concessionário que altere o intervalo de datas para um menor.

Quando a Quantidade do Pedido e a Quantidade da Entrega São 0

Em alguns casos, as propriedades order_qty e delivery_qty são 0. Isso ocorre quando uma entrega é criada, mas não está pronta para ser enviada.

Por exemplo, esta entrega tem as propriedades order_qty e delivery_qty em 0.

{
    "delivery_no": "8502072259",
    "dealer_no": "0000690885",
    "customer_address": {
        "street": "109 THOMAS DRIVE",
        "city": "AMERICUS",
        "state": "GA",
        "country": "US",
        "postal_code": "31709-5533"
    },
    "shipping_condition": "S1",
    "ship_to_no": "0020000953",
    "ship_to_address": {
        "street": "1601 S SLAPPEY BLVD",
        "city": "ALBANY",
        "state": "GA",
        "country": "US",
        "postal_code": "31701-2645"
    },
    "last_change_date": "2024-05-24T00:00:00Z",
    "items": [
        {
            "delivery_item_no": "000010",
            "product_code": "9779426",
            "product_description": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
            "order_qty": 0,
            "delivery_qty": 0,
            "package_qty": 3,
            "sales_order_no": "1030997804",
            "sales_order_item_no": "012208",
            "dealer_po_no": "ODN041256",
            "tracking_details": []
        }
    ]
}

O pedido de peças correspondente tem a propriedade deliveries indicando que o status da peça é allocated, o que significa que ela não foi enviada.

Essas entregas podem ser ignoradas porque o concessionário não as recebeu.

{
    "ordered_line": {
        "item_id": "5DCAC1B678131EEF84D74B96E2BBC46A",
        "item_no": "012200",
        "product_code": "9779426",
        "product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
        "order_qty": 3,
        "dealer_po_item_no": "",
        "dealer_product_code": "",
        "sales_uom": "PC",
        "min_order_qty": 1,
        "is_sales_bom": false,
        "product_line": "SNO",
        "product_type": "110",
        "texts": []
    },
    "shipping_lines": [
        {
            "item_no": "012216",
            "product_code": "9779426",
            "product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
            "ship_qty": 3,
            "sales_uom": "PC",
            "price_uom": "PC",
            "package_uom": "CS",
            "in_package": {
                "qty": 3,
                "uom": "PC"
            },
            "package_count": 3,
            "msrp_unit_price": 56.99,
            "wholesale_unit_price": 36.98,
            "net_unit_price": 37.02,
            "currency": "USD",
            "is_substitute_product": false,
            "substituted_product_code": null,
            "product_line": "SNO",
            "product_type": "110",
            "plant": {
                "name": "BRP - LAS VEGAS",
                "city": "LAS VEGAS",
                "state": "NV",
                "country": "US"
            },
            "pricings": [
                {
                    "condition_type": "gross_amt",
                    "total_amount": 110.94,
                    "currency": "USD"
                },
                {
                    "condition_type": "subtotal_amt",
                    "total_amount": 111.05,
                    "currency": "USD"
                },
                {
                    "condition_type": "tax_amt",
                    "total_amount": 8.88,
                    "currency": "USD"
                },
                {
                    "condition_type": "handling_fee",
                    "total_amount": 0.11,
                    "currency": "USD"
                }
            ],
            "deliveries": [
                {
                    "status_code": "allocated",
                    "status_date": "2024-07-06T20:20:34Z",
                    "status_descr": "",
                    "qty": 3,
                    "availability_date": "2024-07-15",
                    "no": "",
                    "item_no": "",
                    "delivery_qty": 0,
                    "creation_date": "",
                    "carrier_name": "",
                    "split_delivery_no": "",
                    "split_delivery_item_no": "",
                    "trackings": [],
                    "billings": []
                }
            ],
            "statuses": [
                {
                    "type": "success",
                    "code": "in_process",
                    "descr": "Your part is in process"
                }
            ]
        }
    ]
}

Referência da API

Get a Delivery Document

Get a delivery document using the delivery number.

GET

/delivery/{delivery_no}

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

Get Delivery Documents

Get a list of delivery documents.

GET

/deliveries

curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--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 um Documento de Entrega para Localizar um Pedido de Peças

Usando o número de entrega, você pode obter um documento de entrega específico. Por exemplo, ao receber um pacote, o revendedor insere o número de entrega encontrado na etiqueta de envio para localizar o documento de entrega.

Depois que o documento de entrega é encontrado, o revendedor pode usar o número do pedido de vendas (sales_order_no) para localizar o pedido de peças relacionado.

Obter o Documento de Entrega

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

Obter o Pedido de Peças

Get the Parts Order

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

Obter os Documentos de Entrega por um Período

Obter os documentos de entrega para um intervalo de datas.

Get the Delivery Documents for a Period

curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--header 'Dealer-Number: 0000690885' \
--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 indevidos.

400 Solicitação Inválida

O código de status 400 é geralmente observado 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 na tabela abaixo.

Resposta	Resolução
Retornado se o parâmetro de cabeçalho Dealer-Number estiver ausente. { "status": "400", "id": "rrt-00a574511a562afb5-b-ea-22208-1683284-1", "title": "bad_request", "meta": { "service": "01", "detail": "validação da requisição falhou", "payload": { "details": [ { "message": "O parâmetro de cabeçalho 'Dealer-Number' é obrigatório no caminho '/deliveries', mas não foi encontrado na requisição.: []" } ] } } }	Atualize sua chamada de API para adicionar o parâmetro Dealer-Number no cabeçalho.
Retornado se o número de entrega estiver ausente na consulta. { "status": "400", "id": "rrt-00a574511a562afb5-b-ea-22209-1683475-1", "title": "bad_request", "meta": { "service": "00", "detail": "Caminho não encontrado." } }	Certifique-se de incluir um número de entrega 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", "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 do concessionário sem o zero à 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 Não Autorizado também é retornado se você não solicitou acesso à API criando um ticket no Jira do DCP.

Quando você estiver pronto para começar a trabalhar em uma API, deve criar um ticket de certificação no Jira, conforme descrito na seção Atividades de Certificação com 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 Não Encontrado é retornado quando o número de entrega não é encontrado.

{
    "status": "404",
    "id": "rrt-00a574511a562afb5-b-ea-22209-1683823-1.1",
    "title": "not_found",
    "meta": {
        "service": "97",
        "detail": "Delivery 8500045713 not found."
    }
}

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

Requisitos de DSP

Requisitos Funcionais

ID	Tipo	Requisito
1	Obrigatório	O concessionário deve ser capaz de pesquisar um documento de entrega usando um número de entrega.
2	Obrigatório	O documento de entrega deve ser exibido ao 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 um documento de entrega.
4	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.
5	Opcional	O DMS recupera os documentos de entrega dos últimos 3 meses e os salva no banco de dados do DMS. O concessionário pode visualizar os documentos de entrega carregados.
6	Opcional	O concessionário pode encontrar um documento de entrega usando o número de rastreamento da transportadora.
7	Opcional	O serviço Get é usado diariamente para recuperar as entregas dos últimos 30 dias e salvá-las no banco de dados do DMS.

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 no ambiente de teste antes que você possa iniciar a fase piloto do revendedor.

Para esses testes, devemos usar o número de revendedor 0000690005

ID	Teste	Resultado Esperado
1	Obter o documento de entrega 8502067956	O documento de entrega é carregado e exibido.
2	Obter a lista de documentos de entrega com o intervalo de datas de 20/06/2023 a 25/09/2023	Uma lista de 15 documentos de entrega é carregada.
3	Encontrar o pedido de peças com o número do pedido de venda encontrado no documento de entrega 8502067956	O pedido de peças é encontrado e exibido.

Piloto do Revendedor

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ários	1 a 3
Duração	1 semana
Validação 1	Forneça uma lista de 10 a 20 números de entrega provenientes de entregas recebidas pelo concessionário. Forneça a captura de tela ou faça uma demonstração ao vivo para exibir pelo menos 10 documentos de entrega conforme visualizados pelo concessionário.
Validação 2	Forneça os números de pedidos de venda (pedidos de peças) obtidos nos documentos de entrega da Etapa 1. Forneça a captura de tela ou faça uma demonstração ao vivo para exibir o pedido de peças vinculado a pelo menos 10 documentos de entrega, conforme visualizado pelo concessionário.

Postman

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

Ambientes

Um ambiente Postman está disponível para testar a API de Entregas. Este ambiente Postman contém variáveis usadas pelas consultas e está configurado para se conectar ao ambiente de teste.

Teste - Ambiente DSP

Coleções

A coleção DMS - Deliveries contém exemplos de chamadas de API para recuperar documentos de entrega.

DMS - Entregas

Registro de Alterações

Revisão 1.1

Fixed

Renomeado o customer_po_no para dealer_po_no para alinhamento com outras APIs.

Revisão 1.0

Added

Primeiro lançamento